Controlo de Aplicação

OLE requer 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 atendem a esses requisitos. Além de serem chamadas pelas DLLs do sistema OLE, essas funções às vezes também devem ser chamadas por aplicativos.

Controlo de Aplicação

AfxOleCanExitApp

Indica se o aplicativo pode ser encerrado.

BOOL AFXAPI AfxOleCanExitApp();

Valor de retorno

Diferente de zero se o aplicativo puder sair; caso contrário, 0.

Observações

Um aplicativo não deve ser encerrado se houver referências pendentes a seus objetos. As funções AfxOleLockApp globais e AfxOleUnlockApp incremento e decréscimo, respectivamente, um contador de referências aos objetos do aplicativo. O aplicativo não deve ser encerrado quando esse contador for diferente de zero. Se o contador for diferente de zero, a janela principal do aplicativo ficará oculta (não destruída) quando o usuário escolher Fechar no menu do sistema ou Sair no 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;
   }
}

Requerimentos

Cabeçalho: afxdisp.h

AfxOleGetMessageFilter

Recupera o filtro de mensagens atual do aplicativo.

COleMessageFilter* AFXAPI AfxOleGetMessageFilter();

Valor de retorno

Um ponteiro para o filtro de mensagens atual.

Observações

Chame essa função para acessar o objeto derivado atual COleMessageFilter, 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();
   }
   //...
   //...
   //...
}

Requerimentos

Cabeçalho: afxwin.h

AfxOleGetUserCtrl

Recupera o sinalizador de controle de usuário atual.

BOOL AFXAPI AfxOleGetUserCtrl();

Valor de retorno

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

Observações

O usuário está no controle do aplicativo quando o usuário abriu ou criou explicitamente um novo documento. O usuário também está no controle se o aplicativo não foi iniciado pelas DLLs do sistema OLE — em outras palavras, se o usuário iniciou o aplicativo com o shell do sistema.

Requerimentos

Cabeçalho: afxdisp.h

AfxOleSetUserCtrl

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

void AFXAPI AfxOleSetUserCtrl(BOOL bUserCtrl);

Parâmetros

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

Observações

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 incorporado de um aplicativo contêiner.

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

Requerimentos

Cabeçalho: afxdisp.h

AfxOleLockApp

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

void AFXAPI AfxOleLockApp();

Observações

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

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

Chame AfxOleLockApp de qualquer objeto que exponha interfaces OLE, se for indesejável que esse objeto seja destruído enquanto ainda está sendo usado por um aplicativo cliente. Também chame AfxOleUnlockApp o destruidor de qualquer objeto que chama AfxOleLockApp o 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();
}

Requerimentos

Cabeçalho: afxdisp.h

AfxOleUnlockApp

Decrements a contagem de objetos ativos da estrutura no aplicativo.

void AFXAPI AfxOleUnlockApp();

Observações

Consulte AfxOleLockApp para mais informações.

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

Exemplo

Veja o exemplo de AfxOleLockApp.

Requerimentos

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 exclusivo do controle.

lpszProgID
O ID de programa exclusivo do controle.

Valor de retorno

Diferente de zero se a fábrica de classe do controle foi bloqueada com sucesso; caso contrário, 0.

Observações

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 precisa criá-lo e matá-lo novamente toda vez 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 pode melhorar significativamente o desempenho. Quando você estiver pronto para destruir o controle, ligue para 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"));

Requerimentos

Cabeçalho: afxwin.h

AfxOleRegisterServerClass

Esta função permite-lhe registar o seu servidor no registo 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 ao ID de classe OLE do servidor.

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

lpszShortTypeName
Ponteiro para uma cadeia de caracteres que contém o nome abreviado 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, retirado da enumeração OLE_APPTYPE, especificando o tipo de aplicativo OLE. Os valores possíveis são os seguintes:

• OAT_INPLACE_SERVER Server tem interface de usuário de servidor completo.

• OAT_SERVER Server suporta apenas incorporação.

• OAT_CONTAINER Container suporta links para incorporações.

• IDispatchOAT_DISPATCH_OBJECT objeto compatível.

rglpszRegistar
Matriz de ponteiros para cadeias de caracteres que representam as chaves e 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 valores a serem adicionados ao registro do sistema OLE se o registro contiver valores existentes para as chaves fornecidas.

Valor de retorno

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

Observações

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

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

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

Requerimentos

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

pCliente
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
O ID de comando que corresponde ao verbo primário.

nIDVerbMax
O ID do comando que corresponde ao último verbo.

nIDConvert
ID do item de menu Converter.

Observações

Se o servidor reconhecer apenas um verbo primário, o item de menu se tornará "verb typename Object" 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á " typename Object" e um submenu listando todos os verbos aparecerá quando o usuário escolher o comando. Quando o usuário escolhe um verbo no 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 COleDocument lida automaticamente com esse recurso.

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

<#include afxolecl.rc>

Requerimentos

Cabeçalho: afxole.h

AfxOleUnlockControl

Desbloqueia a classe factory do controle especificado.

Sintaxe

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

Parâmetros

CLSID
O ID de classe exclusivo do controle.

lpszProgID
O ID de programa exclusivo do controle.

Valor de retorno

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

Observações

Um controle é bloqueado com AfxOleLockControl, para 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 toda vez que é exibido. Quando você estiver pronto para destruir o controle, ligue para AfxOleUnlockControl.

Exemplo

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

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

Requerimentos

Cabeçalho: afxwin.h

Ver também

Macros e Globais