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. |
| 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 Devolução
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 Devolução
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 Devolução
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 Devolução
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
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 Devolução
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 Devolução
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de