Compartilhar via


Controle de Aplicativo

O OLE requer um controle substancial sobre aplicativos e seus objetos. As DLLs do sistema OLE devem ser capazes de iniciar e liberar aplicativos automaticamente, coordenar sua produção e modificação de objetos e assim por diante. As funções neste tópico cumprem esses requisitos. Além de serem chamadas pelas DLLs do sistema OLE, essas funções também devem ser chamadas por aplicativos.

Controle de Aplicativo

Nome Descrição
AfxOleCanExitApp Indica se o aplicativo pode ser encerrado.
AfxOleGetMessageFilter Recupera o filtro de mensagem atual do aplicativo.
AfxOleGetUserCtrl Recupera o sinalizador de controle de usuário atual.
AfxOleSetUserCtrl Define ou limpa o sinalizador de controle do usuário.
AfxOleLockApp Incrementa a contagem global da estrutura do número de objetos ativos em um aplicativo.
AfxOleLockControl Bloqueia a fábrica de classes do controle especificado.
AfxOleUnlockApp Diminui a contagem da estrutura do número de objetos ativos em um aplicativo.
AfxOleUnlockControl Desbloqueia a fábrica de classes do controle especificado.
Classe AfxOleRegisterServerClass Registra um servidor no Registro do sistema OLE.
AfxOleSetEditMenu Implementa a interface do usuário para o comando typename Object.

AfxOleCanExitApp

Indica se o aplicativo pode ser encerrado.

BOOL AFXAPI AfxOleCanExitApp();

Valor de retorno

Não zero se o aplicativo puder ser encerrado; caso contrário, 0.

Comentários

Um aplicativo não deverá ser encerrado se houver referências pendentes aos seus objetos. As funções globais AfxOleLockApp e AfxOleUnlockApp incrementam e decrementam, respectivamente, um contador de referências aos objetos do aplicativo. O aplicativo não deve ser encerrado quando esse contador não for zero. Se o contador não for zero, a janela principal do aplicativo ficará oculta (não destruída) quando o usuário escolher Fechar no menu de sistema ou Encerrar do menu Arquivo. A estrutura chama essa função em CFrameWnd::OnClose.

Exemplo

// Helper exit function for automation server
BOOL CMainFrame::CanExit()
{
   if (AfxOleCanExitApp())
   {
      // No outstanding object counts - go ahead and exit
      return TRUE;
   }
   else
   {
      // There are outstanding OLE object counts...
      // hide app to give user impression that application has exited.
      ShowWindow(SW_HIDE);
      // take user out of control of the app
      AfxOleSetUserCtrl(FALSE);
      return FALSE;
   }
}

Requisitos

Cabeçalho afxdisp.h

AfxOleGetMessageFilter

Recupera o filtro de mensagem atual do aplicativo.

COleMessageFilter* AFXAPI AfxOleGetMessageFilter();

Valor de retorno

Um ponteiro para o filtro de mensagem atual.

Comentários

Chame essa função para acessar o objeto derivado de COleMessageFilter atual, assim como você chamaria AfxGetApp para acessar o objeto de aplicativo atual.

Exemplo

COleMessageFilter *pFilter = AfxOleGetMessageFilter();
ASSERT_VALID(pFilter);
pFilter->BeginBusyState();
// do things requiring a busy state
pFilter->EndBusyState();

 

// Another example
//CWinApp-derived class
BOOL CCMFCAutomationApp::InitInstance()
{
   CWinApp::InitInstance();

   // Initialize OLE libraries
   if (!AfxOleInit())
   {
      AfxMessageBox(IDP_OLE_INIT_FAILED);
      return FALSE;
   }

   CWinThread *pThread = AfxGetThread();
   if (pThread != NULL)
   {
      // Destroy message filter, thereby unregistering it.
      delete pThread->m_pMessageFilter;
      pThread->m_pMessageFilter = NULL;

      // Create the new message filter object.
      //CMyMessageFilter is derived from COleMessageFilter
      pThread->m_pMessageFilter = new CMyMessageFilter;
      ASSERT(AfxOleGetMessageFilter() != NULL);

      // Register the new message filter object.
      AfxOleGetMessageFilter()->Register();
   }
   //...
   //...
   //...
}

Requisitos

Cabeçalho: afxwin.h

AfxOleGetUserCtrl

Recupera o sinalizador de controle de usuário atual.

BOOL AFXAPI AfxOleGetUserCtrl();

Valor de retorno

Não zero se o usuário estiver no controle do aplicativo; caso contrário, 0.

Comentários

O usuário está no controle do aplicativo quando o usuário abre ou cria explicitamente um documento. O usuário também estará no controle se o aplicativo não tiver sido iniciado pelas DLLs do sistema OLE. Em outras palavras, se o usuário tiver iniciado o aplicativo com o shell do sistema.

Requisitos

Cabeçalho afxdisp.h

AfxOleSetUserCtrl

Define ou limpa o sinalizador de controle do usuário, que é explicado na referência a AfxOleGetUserCtrl.

void AFXAPI AfxOleSetUserCtrl(BOOL bUserCtrl);

Parâmetros

bUserCtrl
Especifica se o sinalizador de controle do usuário deve ser definido ou desmarcado.

Comentários

A estrutura chama essa função quando o usuário cria ou carrega um documento, mas não quando um documento é carregado ou criado por meio de uma ação indireta, como carregar um objeto inserido de um aplicativo de contêiner.

Chame essa função se outras ações em seu aplicativo devem colocar o usuário no controle do aplicativo.

Requisitos

Cabeçalho afxdisp.h

AfxOleLockApp

Incrementa a contagem global da estrutura do número de objetos ativos no aplicativo.

void AFXAPI AfxOleLockApp();

Comentários

A estrutura mantém uma contagem do número de objetos ativos em um aplicativo. As funções AfxOleLockApp e AfxOleUnlockApp, respectivamente, incrementam e decrementam essa contagem.

Quando o usuário tenta fechar um aplicativo que tem objetos ativos, um aplicativo para o qual a contagem de objetos ativos não é zero, a estrutura oculta o aplicativo da exibição do usuário, em vez de encerrá-lo completamente. A função AfxOleCanExitApp indica se o aplicativo pode ser encerrado.

Chame AfxOleLockApp de qualquer objeto que exponha interfaces OLE, caso seja indesejável que esse objeto seja destruído enquanto ainda está sendo usado por um aplicativo cliente. Também chame o destruidor AfxOleUnlockApp de qualquer objeto que chame AfxOleLockApp no construtor. Por padrão, COleDocument (e classes derivadas) bloqueiam e desbloqueiam automaticamente o aplicativo.

Exemplo

// Below is a code sample from an  Application Wizard-generated SDI
// Application with Automation support. The Application Wizard adds a
// dispatch interface to the document class. AfxOleLockApp() and
// AfxOleUnlockApp() respectively increment and decrement the
// application's object count. When the object count is equal to
// zero and if the user has not taken control of the application,
// the server is terminated.

CCMFCAutomationDoc::CCMFCAutomationDoc()
{
   EnableAutomation();
   AfxOleLockApp();
}

CCMFCAutomationDoc::~CCMFCAutomationDoc()
{
   AfxOleUnlockApp();
}

Requisitos

Cabeçalho afxdisp.h

AfxOleUnlockApp

Diminui a contagem da estrutura de objetos ativos no aplicativo.

void AFXAPI AfxOleUnlockApp();

Comentários

Confira AfxOleLockApp para mais informações.

Quando o número de objetos ativos atinge zero, AfxOleOnReleaseAllObjects é chamado.

Exemplo

Veja o exemplo de AfxOleLockApp.

Requisitos

Cabeçalho afxdisp.h

AfxOleLockControl

Bloqueia a fábrica de classes do controle especificado para que os dados criados dinamicamente associados ao controle permaneçam na memória.

Sintaxe

BOOL AFXAPI AfxOleLockControl(  REFCLSID clsid  );
BOOL AFXAPI AfxOleLockControl( LPCTSTR lpszProgID );

Parâmetros

clsid
O ID de classe exclusiva do controle.

lpszProgID
A ID de programa exclusiva do controle.

Valor de retorno

Não zero se a fábrica de classes do controle foi bloqueada com êxito; caso contrário, 0.

Comentários

Isso pode acelerar significativamente a exibição dos controles. Por exemplo, depois de criar um controle em uma caixa de diálogo e bloquear o controle com AfxOleLockControl, você não precisará criá-lo e encerrá-lo novamente sempre que a caixa de diálogo for mostrada ou destruída. Se o usuário abrir e fechar uma caixa de diálogo repetidamente, bloquear seus controles poderá melhorar o desempenho de modo considerável. Quando estiver pronto para destruir o controle, chame AfxOleUnlockControl.

Exemplo

// Starts and locks control's (Microsoft Calendar) class factory.
// Control will remain in memory for lifetime of
// application or until AfxOleUnlockControl() is called.

AfxOleLockControl(_T("MSCAL.Calendar"));

Requisitos

Cabeçalho: afxwin.h

Classe AfxOleRegisterServerClass

Essa função permite que você registre seu servidor no Registro do sistema OLE.

BOOL AFXAPI AfxOleRegisterServerClass(
    REFCLSID clsid,
    LPCTSTR lpszClassName,
    LPCTSTR lpszShortTypeName,
    LPCTSTR lpszLongTypeName,
    OLE_APPTYPE nAppType = OAT_SERVER,
    LPCTSTR* rglpszRegister = NULL,
    LPCTSTR* rglpszOverwrite = NULL);

Parâmetros

clsid
Referência à ID da classe OLE do servidor.

lpszClassName
Ponteiro para uma cadeia de caracteres que contém o nome de classe dos objetos do servidor.

lpszShortTypeName
Ponteiro para uma cadeia de caracteres que contém o nome curto do tipo de objeto do servidor, como "Gráfico".

lpszLongTypeName
Ponteiro para uma cadeia de caracteres que contém o nome longo do tipo de objeto do servidor, como "Gráfico do Microsoft Excel 5.0".

nAppType
Um valor, obtido da enumeração OLE_APPTYPE, especificando o tipo de aplicativo OLE. Os valores possíveis são os seguintes:

  • OAT_INPLACE_SERVER O servidor tem interface de usuário completa do servidor.

  • OAT_SERVER O servidor dá suporte apenas à inserção.

  • OAT_CONTAINER Contêiner dá suporte a links para inserções.

  • Objeto compatível com IDispatchOAT_DISPATCH_OBJECT.

rglpszRegister
Matriz de ponteiros para cadeias de caracteres que representam as chaves e os valores a serem adicionados ao Registro do sistema OLE se nenhum valor existente para as chaves for encontrado.

rglpszOverwrite
Matriz de ponteiros para cadeias de caracteres que representam as chaves e os valores a serem adicionados ao Registro do sistema OLE se o registro contiver valores para as chaves fornecidas.

Valor de retorno

Não zero se a classe de servidor for registrada com êxito; caso contrário, 0.

Comentários

A maioria dos aplicativos pode usar COleTemplateServer::Register para registrar os tipos de documento do aplicativo. Se o formato de Registro do sistema do aplicativo não se ajustar ao padrão típico, você poderá usar AfxOleRegisterServerClass para obter mais controle.

O Registro consiste em um conjunto de chaves e valores. Os argumentos rglpszRegister e rglpszOverwrite são matrizes de ponteiros para cadeias de caracteres, cada uma consistindo em uma chave e um valor separado por um caractere NULL ('\0'). Cada uma dessas cadeias de caracteres pode ter parâmetros substituíveis cujos locais são marcados pelas sequências de caracteres %1 a %5.

Os símbolos são preenchidos da seguinte maneira:

Símbolo Valor
%1 ID da classe, formatada como uma cadeia de caracteres
%2 Nome da classe
%3 Caminho para o arquivo executável
4% Nome do tipo curto
5% Nome do tipo longo

Requisitos

Cabeçalho afxdisp.h

AfxOleSetEditMenu

Implementa a interface do usuário para o comando typename Object.

void AFXAPI AfxOleSetEditMenu(
    COleClientItem* pClient,
    CMenu* pMenu,
    UINT iMenuItem,
    UINT nIDVerbMin,
    UINT nIDVerbMax = 0,
    UINT nIDConvert = 0);

Parâmetros

pClient
Um ponteiro para o item OLE do cliente.

pMenu
Um ponteiro para o objeto de menu a ser atualizado.

iMenuItem
O índice do item de menu a ser atualizado.

nIDVerbMin
A ID de comando que corresponde ao verbo primário.

nIDVerbMax
A ID de comando que corresponde ao último verbo.

nIDConvert
ID do item de menu Converter.

Comentários

Se o servidor reconhecer apenas um verbo primário, o item de menu se tornará "Objeto typename de verbo" e o comando nIDVerbMin será enviado quando o usuário escolher o comando. Se o servidor reconhecer vários verbos, o item de menu se tornará "Objeto typename" e um submenu listando todos os verbos será exibido quando o usuário escolher o comando. Quando o usuário escolhe um verbo do submenu, nIDVerbMin é enviado se o primeiro verbo for escolhido, nIDVerbMin + 1 é enviado se o segundo verbo for escolhido e assim por diante. A implementação padrão de COleDocument manipula automaticamente esse recurso.

Você deve ter a seguinte instrução no arquivo (.RC) do script do recurso de aplicativo do cliente:

#include <afxolecl.rc>

Requisitos

Cabeçalho: afxole.h

AfxOleUnlockControl

Desbloqueia a fábrica de classes do controle especificado.

Sintaxe

BOOL AFXAPI AfxOleUnlockControl( REFCLSID clsid );
BOOL AFXAPI AfxOleUnlockControl( LPCTSTR lpszProgID );

Parâmetros

clsid
O ID de classe exclusiva do controle.

lpszProgID
A ID de programa exclusiva do controle.

Valor de retorno

Diferente de zero se a fábrica de classes do controle tiver sido desbloqueada com êxito; caso contrário, 0.

Comentários

Um controle é bloqueado com AfxOleLockControl, de modo que os dados criados dinamicamente associados ao controle permaneçam na memória. Isso pode acelerar significativamente a exibição do controle porque o controle não precisa ser criado e destruído sempre que é exibido. Quando estiver pronto para destruir o controle, chame AfxOleUnlockControl.

Exemplo

// Unlock control's (Microsoft Calendar Control) class factory.

AfxOleUnlockControl(_T("MSCAL.Calendar"));

Requisitos

Cabeçalho: afxwin.h

Confira também

Macros e Globais