CCmdTarget Classe

A classe base para a arquitetura de mapa de mensagens da Microsoft Foundation Class Library.

Sintaxe

class CCmdTarget : public CObject

Membros

Construtores Públicos

Métodos Públicos

Observações

Um mapa de mensagens encaminha comandos ou mensagens para as funções de membro que você escreve para manipulá-los. (Um comando é uma mensagem de um item de menu, botão de comando ou tecla aceleradora.)

Principais classes de estrutura derivadas de CCmdTarget include CView, CWinApp, CDocument, CWnd, e CFrameWnd. Se você pretende que uma nova classe manipule mensagens, derive a classe de uma dessas CCmdTargetclasses derivadas. Você raramente derivará uma classe diretamente CCmdTarget .

Para obter uma visão geral dos destinos de comando e OnCmdMsg roteamento, consulte Command Targets, Command Routing e Mapping Messages.

CCmdTarget Inclui funções de membro que lidam com a exibição de um cursor de ampulheta. Exiba o cursor de ampulheta quando você espera que um comando tenha um intervalo de tempo percetível para ser executado.

Os mapas de expedição, semelhantes aos mapas de mensagens, são usados para expor a funcionalidade de automação IDispatch OLE. Ao expor essa interface, outros aplicativos (como o Visual Basic) podem chamar seu aplicativo.

Hierarquia de herança

CObject

CCmdTarget

Requerimentos

Cabeçalho:afxwin.h

CCmdTarget::BeginWaitCursor

Chame essa função para exibir o cursor como uma ampulheta quando você espera que um comando leve um intervalo de tempo percetível para ser executado.

void BeginWaitCursor();

Observações

A estrutura chama essa função para mostrar ao usuário que ela está ocupada, como quando um CDocument objeto é carregado ou salva em um arquivo.

As ações de nem sempre são eficazes fora de um único manipulador de BeginWaitCursor mensagens, pois outras ações, como OnSetCursor o manuseio, podem alterar o cursor.

Chamada EndWaitCursor para restaurar o cursor anterior.

Exemplo

// The following example illustrates the most common case
// of displaying the hourglass cursor during some lengthy
// processing of a command handler implemented in some
// CCmdTarget-derived class, such as a document or view.
void CMyView::OnBeginSleepEnd()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// The next example illustrates RestoreWaitCursor.
void CMyView::OnBeginDlgRestore()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   // The dialog box will normally change the cursor to
   // the standard arrow cursor, and leave the cursor in
   // as the standard arrow cursor when the dialog box is
   // closed.
   CFileDialog dlg(TRUE);
   dlg.DoModal();

   // It is necessary to call RestoreWaitCursor here in order
   // to change the cursor back to the hourglass cursor.
   RestoreWaitCursor();
   // do some more lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// In the above example, the dialog was clearly invoked between
// the pair of calls to BeginWaitCursor and EndWaitCursor.
// Sometimes it may not be clear whether the dialog is invoked
// in between a pair of calls to BeginWaitCursor and EndWaitCursor.
// It is permissible to call RestoreWaitCursor, even if
// BeginWaitCursor was not previously called.  This case is
// illustrated below, where CMyView::AnotherFunction does not
// need to know whether it was called in the context of an
// hourglass cursor.
void CMyView::OnDlgRestore()
{
   // some processing ...
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   RestoreWaitCursor();

   // some more processing ...
}

// If the dialog is invoked from a member function of
// some non-CCmdTarget, then you can call CWinApp::DoWaitCursor
// with a 0 parameter value to restore the hourglass cursor.
void CMyObject::OnDlgDoWait()
{
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   AfxGetApp()->DoWaitCursor(0); // same as CCmdTarget::RestoreWaitCursor
}

CCmdTarget::CCmdTarget

Constrói um objeto CCmdTarget.

CCmdTarget();

CCmdTarget::DoOleVerb

Faz com que uma ação especificada por um verbo OLE seja executada.

BOOL DoOleVerb(
    LONG iVerb,
    LPMSG lpMsg,
    HWND hWndParent,
    LPCRECT lpRect);

Parâmetros

iVerb
Identificador numérico do verbo.

lpMsg
Ponteiro para a MSG estrutura que descreve o evento (como um clique duplo) que invocou o verbo.

hWndParent
Identificador da janela do documento que contém o objeto.

lpRect
Ponteiro para a RECT estrutura que contém as coordenadas, em pixels, que definem o retângulo delimitador de um objeto em hWndParent.

Valor de retorno

TRUE se bem sucedido, caso contrário FALSE.

Observações

Esta função de membro é basicamente uma implementação do IOleObject::DoVerb. As ações possíveis são enumeradas por CCmdTarget::EnumOleVerbs.

CCmdTarget::EnableAutomation

Chame essa função para habilitar a automação OLE para um objeto.

void EnableAutomation();

Observações

Essa função é normalmente chamada a partir do construtor do seu objeto e só deve ser chamada se um mapa de despacho tiver sido declarado para a classe. Para obter mais informações sobre automação, consulte os artigos Clientes de automação e servidores de automação.

CCmdTarget::EnableConnections

Permite o disparo de eventos em pontos de conexão.

void EnableConnections();

Observações

Para habilitar pontos de conexão, chame essa função de membro no construtor de sua classe derivada.

CCmdTarget::EnableTypeLib

Habilita a biblioteca de tipos de um objeto.

void EnableTypeLib();

Observações

Chame essa função de membro no construtor de seu CCmdTargetobjeto derivado se ele fornecer informações de tipo.

CCmdTarget::EndWaitCursor

Chame essa função depois de chamar a BeginWaitCursor função de membro para retornar do cursor da ampulheta para o cursor anterior.

void EndWaitCursor();

Observações

A estrutura também chama essa função de membro depois de ter chamado o cursor de ampulheta.

Exemplo

// The following example illustrates the most common case
// of displaying the hourglass cursor during some lengthy
// processing of a command handler implemented in some
// CCmdTarget-derived class, such as a document or view.
void CMyView::OnBeginSleepEnd()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// The next example illustrates RestoreWaitCursor.
void CMyView::OnBeginDlgRestore()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   // The dialog box will normally change the cursor to
   // the standard arrow cursor, and leave the cursor in
   // as the standard arrow cursor when the dialog box is
   // closed.
   CFileDialog dlg(TRUE);
   dlg.DoModal();

   // It is necessary to call RestoreWaitCursor here in order
   // to change the cursor back to the hourglass cursor.
   RestoreWaitCursor();
   // do some more lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// In the above example, the dialog was clearly invoked between
// the pair of calls to BeginWaitCursor and EndWaitCursor.
// Sometimes it may not be clear whether the dialog is invoked
// in between a pair of calls to BeginWaitCursor and EndWaitCursor.
// It is permissible to call RestoreWaitCursor, even if
// BeginWaitCursor was not previously called.  This case is
// illustrated below, where CMyView::AnotherFunction does not
// need to know whether it was called in the context of an
// hourglass cursor.
void CMyView::OnDlgRestore()
{
   // some processing ...
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   RestoreWaitCursor();

   // some more processing ...
}

// If the dialog is invoked from a member function of
// some non-CCmdTarget, then you can call CWinApp::DoWaitCursor
// with a 0 parameter value to restore the hourglass cursor.
void CMyObject::OnDlgDoWait()
{
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   AfxGetApp()->DoWaitCursor(0); // same as CCmdTarget::RestoreWaitCursor
}

CCmdTarget::EnumOleVerbs

Enumera os verbos OLE de um objeto.

BOOL EnumOleVerbs(LPENUMOLEVERB* ppenumOleVerb);

Parâmetros

ppenumOleVerb
Um ponteiro para um ponteiro para uma IEnumOLEVERB interface.

Valor de retorno

TRUE se o objeto suportar pelo menos um verbo OLE (nesse caso *ppenumOleVerb , aponta para uma IEnumOLEVERB interface de enumerador), caso contrário FALSE.

Observações

Esta função de membro é basicamente uma implementação do IOleObject::EnumVerbs.

CCmdTarget::FromIDispatch

Chame essa função para mapear um IDispatch ponteiro, recebido de funções de membro de automação de uma classe, para o CCmdTarget objeto que implementa as interfaces do IDispatch objeto.

static CCmdTarget* PASCAL FromIDispatch(LPDISPATCH lpDispatch);

Parâmetros

lpDispatch
Um ponteiro para um IDispatch objeto.

Valor de retorno

Um ponteiro para o objeto associado ao CCmdTargetlpDispatch. Essa função retornará NULL se o IDispatch objeto não for reconhecido como um objeto Microsoft Foundation Class IDispatch .

Observações

O resultado desta função é o inverso de uma chamada para a função GetIDispatchde membro.

CCmdTarget::GetDispatchIID

Obtém o ID da interface de despacho principal.

virtual BOOL GetDispatchIID(IID* pIID);

Parâmetros

pIID
Um ponteiro para um ID de interface (um GUID).

Valor de retorno

TRUE se bem sucedido, caso contrário FALSE. Se for bem-sucedido, *pIID é definido como o ID da interface de despacho primária.

Observações

As classes derivadas devem substituir essa função de membro (se não forem substituídas, GetDispatchIID retornarão FALSE). Consulte COleControl.

CCmdTarget::GetIDispatch

Chame essa função de membro para recuperar o IDispatch ponteiro de um método de automação que retorna um IDispatch ponteiro ou usa um IDispatch ponteiro por referência.

LPDISPATCH GetIDispatch(BOOL bAddRef);

Parâmetros

bAddRef
Especifica se a contagem de referência para o objeto deve ser incrementada.

Valor de retorno

O IDispatch ponteiro associado ao objeto.

Observações

Para objetos que chamam EnableAutomation seus construtores, tornando-os habilitados para automação, essa função retorna um ponteiro para a implementação de classe básica que é usada por clientes que se comunicam por meio da IDispatchIDispatch interface. Chamar essa função adiciona automaticamente uma referência ao ponteiro, portanto, não é necessário fazer uma chamada para IUnknown::AddRef.

CCmdTarget::GetTypeInfoCount

Recupera o número de interfaces de informações de tipo que um objeto fornece.

virtual UINT GetTypeInfoCount();

Valor de retorno

O número de interfaces de informação de tipo.

Observações

Esta função de membro basicamente implementa IDispatch::GetTypeInfoCount.

As classes derivadas devem substituir esta função para retornar o número de interfaces de informação de tipo fornecidas (0 ou 1). Se não for substituído, GetTypeInfoCount retorna 0. Para substituir, use a IMPLEMENT_OLETYPELIB macro, que também implementa GetTypeLib e GetTypeLibCache.

CCmdTarget::GetTypeInfoOfGuid

Recupera a descrição do tipo que corresponde ao GUID especificado.

HRESULT GetTypeInfoOfGuid(
    LCID lcid,
    const GUID& guid,
    LPTYPEINFO* ppTypeInfo);

Parâmetros

lcid
Um identificador de localidade (LCID).

guid
O GUID da descrição do tipo.

ppTypeInfo
Ponteiro para um ponteiro para a ITypeInfo interface.

Valor de retorno

Um HRESULT que indica o sucesso ou fracasso da chamada. Se for bem-sucedido, *ppTypeInfo aponta para a interface de informações de tipo.

CCmdTarget::GetTypeLib

Obtém um ponteiro para uma biblioteca de tipos.

virtual HRESULT GetTypeLib(
    LCID lcid,
    LPTYPELIB* ppTypeLib);

Parâmetros

lcid
Um identificador de localidade (LCID).

ppTypeLib
Um ponteiro para um ponteiro para a ITypeLib interface.

Valor de retorno

Um HRESULT que indica o sucesso ou fracasso da chamada. Se for bem-sucedido, *ppTypeLib aponta para a interface da biblioteca de tipos.

Observações

As classes derivadas devem substituir essa função de membro (se não forem substituídas, GetTypeLib retornarão TYPE_E_CANTLOADLIBRARY). Use a IMPLEMENT_OLETYPELIB macro, que também implementa GetTypeInfoCount e GetTypeLibCache.

CCmdTarget::GetTypeLibCache

Obtém o cache da biblioteca de tipos.

virtual CTypeLibCache* GetTypeLibCache();

Valor de retorno

Um ponteiro para um CTypeLibCache objeto.

Observações

As classes derivadas devem substituir essa função de membro (se não forem substituídas, GetTypeLibCache retornarão NULL). Use a IMPLEMENT_OLETYPELIB macro, que também implementa GetTypeInfoCount e GetTypeLib.

CCmdTarget::IsInvokeAllowed

Esta função é chamada pela implementação do MFC de para determinar se um determinado método de IDispatch::Invoke automação (identificado por dispid) pode ser invocado.

virtual BOOL IsInvokeAllowed(DISPID dispid);

Parâmetros

dispid
Um ID de expedição.

Valor de retorno

TRUE se o método pode ser invocado, caso contrário FALSE.

Observações

Se IsInvokeAllowed retornar TRUE, Invoke passa a chamar o método, caso contrário, Invoke falhará, retornando E_UNEXPECTED.

Classes derivadas podem substituir essa função para retornar valores apropriados (se não substituídos, IsInvokeAllowed retorna TRUE). Ver, em especial COleControl::IsInvokeAllowed, .

CCmdTarget::IsResultExpected

Use IsResultExpected para verificar se um cliente espera um valor de retorno de sua chamada para uma função de automação.

BOOL IsResultExpected();

Valor de retorno

Diferente de zero se uma função de automação deve retornar um valor; caso contrário, 0.

Observações

A interface OLE fornece informações ao MFC sobre se o cliente está usando ou ignorando o resultado de uma chamada de função, e o MFC, por sua vez, usa essas informações para determinar o resultado de uma chamada para IsResultExpected. Se a produção de um valor de retorno consome muito tempo ou recursos, você pode aumentar a eficiência chamando essa função antes de calcular o valor de retorno.

Essa função retorna 0 apenas uma vez para que você obtenha valores de retorno válidos de outras funções de automação se você chamá-las da função de automação que o cliente chamou.

IsResultExpected Retorna um valor diferente de zero se chamado quando uma chamada de função de automação não está em andamento.

CCmdTarget::OnCmdMsg

Chamado pela estrutura para rotear e despachar mensagens de comando e para lidar com a atualização de objetos de interface do usuário de comando.

virtual BOOL OnCmdMsg(
    UINT nID,
    int nCode,
    void* pExtra,
    AFX_CMDHANDLERINFO* pHandlerInfo);

Parâmetros

nID
Contém o ID do comando.

nCode
Identifica o código de notificação de comando. Consulte Comentários para obter mais informações sobre valores para nCode.

pExtra
Usado de acordo com o valor de nCode. Consulte Comentários para obter mais informações sobre pExtrao .

pHandlerInfo
Se não NULL, OnCmdMsg preenche os pTarget e pmf membros da pHandlerInfo estrutura em vez de despachar o comando. Normalmente, esse parâmetro deve ser NULL.

Valor de retorno

Diferente de zero se a mensagem for tratada; caso contrário, 0.

Observações

Esta é a principal rotina de implementação da arquitetura de comando do framework.

Em tempo de execução, OnCmdMsg despacha um comando para outros objetos ou manipula o próprio comando chamando a classe CCmdTarget::OnCmdMsgraiz , que faz a pesquisa real do mapa de mensagens. Para obter uma descrição completa do roteamento de comando padrão, consulte Tópicos de manipulação e mapeamento de mensagens.

Em raras ocasiões, você pode querer substituir essa função de membro para estender o roteamento de comando padrão da estrutura. Consulte a Nota Técnica 21 para obter detalhes avançados da arquitetura de roteamento de comandos.

Se você substituir OnCmdMsg, deverá fornecer o valor apropriado para nCode, o código de notificação de comando e pExtra, que depende do valor de nCode. A tabela a seguir lista seus valores correspondentes:

Exemplo

// This example illustrates extending the framework's standard command
// route from the view to objects managed by the view.  This example
// is from an object-oriented drawing application, similar to the
// DRAWCLI sample application, which draws and edits "shapes".
BOOL CMyView::OnCmdMsg(UINT nID,
                       int nCode,
                       void *pExtra,
                       AFX_CMDHANDLERINFO *pHandlerInfo)
{
   // Extend the framework's command route from the view to
   // the application-specific CMyShape that is currently selected
   // in the view. m_pActiveShape is NULL if no shape object
   // is currently selected in the view.
   if ((m_pActiveShape != NULL) &&
       m_pActiveShape->OnCmdMsg(nID, nCode, pExtra, pHandlerInfo))
      return TRUE;

   // If the object(s) in the extended command route don't handle
   // the command, then let the base class OnCmdMsg handle it.
   return CView::OnCmdMsg(nID, nCode, pExtra, pHandlerInfo);
}

// The command handler for ID_SHAPE_COLOR (menu command to change
// the color of the currently selected shape) was added to the message
// map of CMyShape (note, not CMyView) using the Properties window.
// The menu item will be automatically enabled or disabled, depending
// on whether a CMyShape is currently selected in the view, that is,
// depending on whether CMyView::m_pActiveView is NULL.  It is not
// necessary to implement an ON_UPDATE_COMMAND_UI handler to enable
// or disable the menu item.
BEGIN_MESSAGE_MAP(CMyShape, CCmdTarget)
ON_COMMAND(ID_SHAPE_COLOR, &CMyShape::OnShapeColor)
END_MESSAGE_MAP()

CCmdTarget::OnFinalRelease

Chamado pela estrutura quando a última referência OLE para ou do objeto é liberada.

virtual void OnFinalRelease();

Observações

Substitua essa função para fornecer tratamento especial para essa situação. A implementação padrão exclui o objeto.

CCmdTarget::RestoreWaitCursor

Chame essa função para restaurar o cursor de ampulheta apropriado depois que o cursor do sistema for alterado (por exemplo, depois que uma caixa de mensagem for aberta e fechada no meio de uma operação demorada).

void RestoreWaitCursor();

Exemplo

// The following example illustrates the most common case
// of displaying the hourglass cursor during some lengthy
// processing of a command handler implemented in some
// CCmdTarget-derived class, such as a document or view.
void CMyView::OnBeginSleepEnd()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// The next example illustrates RestoreWaitCursor.
void CMyView::OnBeginDlgRestore()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   // The dialog box will normally change the cursor to
   // the standard arrow cursor, and leave the cursor in
   // as the standard arrow cursor when the dialog box is
   // closed.
   CFileDialog dlg(TRUE);
   dlg.DoModal();

   // It is necessary to call RestoreWaitCursor here in order
   // to change the cursor back to the hourglass cursor.
   RestoreWaitCursor();
   // do some more lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// In the above example, the dialog was clearly invoked between
// the pair of calls to BeginWaitCursor and EndWaitCursor.
// Sometimes it may not be clear whether the dialog is invoked
// in between a pair of calls to BeginWaitCursor and EndWaitCursor.
// It is permissible to call RestoreWaitCursor, even if
// BeginWaitCursor was not previously called.  This case is
// illustrated below, where CMyView::AnotherFunction does not
// need to know whether it was called in the context of an
// hourglass cursor.
void CMyView::OnDlgRestore()
{
   // some processing ...
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   RestoreWaitCursor();

   // some more processing ...
}

// If the dialog is invoked from a member function of
// some non-CCmdTarget, then you can call CWinApp::DoWaitCursor
// with a 0 parameter value to restore the hourglass cursor.
void CMyObject::OnDlgDoWait()
{
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   AfxGetApp()->DoWaitCursor(0); // same as CCmdTarget::RestoreWaitCursor
}

Ver também

Exemplo de MFC ACDUAL
CObject Classe
Gráfico de Hierarquia
CCmdUI Classe
CDocument Classe
CDocTemplate Classe
CWinApp Classe
CWnd Classe
CView Classe
CFrameWnd Classe
COleDispatchDriver Classe