Clase CCmdTarget

La clase base para la arquitectura de mapa de mensajes de la biblioteca MFC (Microsoft Foundation Class).

Sintaxis

class CCmdTarget : public CObject

Miembros

Constructores públicos

Nombre	Descripción
CCmdTarget::CCmdTarget	Construye un objeto CCmdTarget.

Métodos públicos

Nombre	Descripción
CCmdTarget::BeginWaitCursor	Muestra el cursor como un cursor de reloj de arena.
CCmdTarget::DoOleVerb	Hace que se realice una acción especificada por un verbo OLE.
CCmdTarget::EnableAutomation	Permite la automatización OLE para el objeto CCmdTarget.
CCmdTarget::EnableConnections	Habilita la activación de eventos a través de puntos de conexión.
CCmdTarget::EnableTypeLib	Habilita la biblioteca de tipos de un objeto.
CCmdTarget::EndWaitCursor	Devuelve al cursor anterior.
CCmdTarget::EnumOleVerbs	Enumera los verbos OLE de un objeto.
CCmdTarget::FromIDispatch	Devuelve un puntero al objeto CCmdTarget asociado al puntero IDispatch.
CCmdTarget::GetDispatchIID	Obtiene el identificador de la interfaz de distribución principal.
CCmdTarget::GetIDispatch	Devuelve un puntero al objeto IDispatch asociado al puntero CCmdTarget.
CCmdTarget::GetTypeInfoCount	Recupera el número de interfaces de información de tipo que proporciona un objeto (0 ó 1).
CCmdTarget::GetTypeInfoOfGuid	Recupera la descripción del tipo que corresponde al GUID especificado.
CCmdTarget::GetTypeLib	Obtiene un puntero a una biblioteca de tipos.
CCmdTarget::GetTypeLibCache	Obtiene la memoria caché de la biblioteca de tipos.
CCmdTarget::IsInvokeAllowed	Habilita la invocación de métodos de automatización.
CCmdTarget::IsResultExpected	Devuelve un valor distinto de cero si una función de automatización debe devolver un valor.
CCmdTarget::OnCmdMsg	Enruta y envía mensajes de comando.
CCmdTarget::OnFinalRelease	Limpia después de que se libere la última referencia OLE.
CCmdTarget::RestoreWaitCursor	Restaura el cursor de reloj de arena.

Comentarios

Un mapa de mensajes enruta los comandos o mensajes a las funciones miembro que escribe para controlarlos. (Un comando es un mensaje de un elemento de menú, un botón de comando o una tecla de aceleración).

Las clases de marco de trabajo clave derivadas de CCmdTarget incluyen CView, CWinApp, CDocument, CWndy CFrameWnd. Si tiene previsto que una nueva clase controle los mensajes, derive la clase de una de estas clases derivadas CCmdTarget. Rara vez se derivará una clase directamente de CCmdTarget.

Para obtener información general sobre los destinos de comandos y OnCmdMsg enrutamiento v, vea Destinos de comandos, Enrutamiento de comandos y Mensajes de asignación.

CCmdTarget incluye funciones miembro que controlan la visualización de un cursor de reloj de arena. Muestra el cursor de reloj de arena cuando se espera que un comando tarde un intervalo de tiempo notable en ejecutarse.

Los mapas de distribución, similares a los mapas de mensajes, se usan para exponer la funcionalidad IDispatch de automatización OLE. Al exponer esta interfaz, otras aplicaciones (como Visual Basic) pueden llamar a la aplicación.

Jerarquía de herencia

CObject

CCmdTarget

Requisitos

Encabezado: afxwin.h

CCmdTarget::BeginWaitCursor

Llame a esta función para mostrar el cursor como un reloj de arena cuando se espera que un comando tarde un intervalo de tiempo notable en ejecutarse.

void BeginWaitCursor();

Comentarios

El marco llama a esta función para mostrar al usuario que está ocupado, como cuando un objeto CDocument se carga o se guarda en un archivo.

Las acciones de BeginWaitCursor no siempre son eficaces fuera de un único controlador de mensajes, como otras acciones, como el control OnSetCursor, podrían cambiar el cursor.

Llame a EndWaitCursor para restaurar el cursor anterior.

Ejemplo

// 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

Construye un objeto CCmdTarget.

CCmdTarget();

CCmdTarget::DoOleVerb

Hace que se realice una acción especificada por un verbo OLE.

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

Parámetros

iVerb
Identificador numérico del verbo.

lpMsg
Puntero a la estructura MSG que describe el evento que invocó el verbo (como doble clic).

hWndParent
Identificador de la ventana de documento que contiene el objeto.

lpRect
Puntero a la estructura RECT que contiene las coordenadas, en píxeles, que definen el rectángulo delimitador de un objeto en hWndParent.

Valor devuelto

TRUE es si se ejecuta correctamente; de lo contrario FALSE, es .

Comentarios

Esta función miembro es básicamente una implementación de IOleObject::DoVerb. Las posibles acciones se enumeran mediante CCmdTarget::EnumOleVerbs.

CCmdTarget::EnableAutomation

Llame a esta función para habilitar la automatización OLE para un objeto.

void EnableAutomation();

Comentarios

Normalmente, se llama a esta función desde el constructor del objeto y solo se debe llamar si se ha declarado una asignación de distribución para la clase. Para obtener más información sobre la automatización, consulta los artículos Clientes de Automation y Servidores de automatización.

CCmdTarget::EnableConnections

Habilita la activación de eventos a través de puntos de conexión.

void EnableConnections();

Comentarios

Para habilitar los puntos de conexión, llame a esta función miembro en el constructor de la clase derivada.

CCmdTarget::EnableTypeLib

Habilita la biblioteca de tipos de un objeto.

void EnableTypeLib();

Comentarios

Llame a esta función miembro en el constructor del objeto derivado CCmdTarget de si proporciona información de tipo.

CCmdTarget::EndWaitCursor

Llame a esta función después de llamar a la función miembro BeginWaitCursor para volver del cursor de reloj de arena al cursor anterior.

void EndWaitCursor();

Comentarios

El marco también llama a esta función miembro después de llamar al cursor de reloj de arena.

Ejemplo

// 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 los verbos OLE de un objeto.

BOOL EnumOleVerbs(LPENUMOLEVERB* ppenumOleVerb);

Parámetros

ppenumOleVerb
IEnumOLEVERB es un puntero a un puntero a un entero.

Valor devuelto

TRUE si el objeto admite al menos un verbo OLE (en cuyo caso *ppenumOleVerb apunta a una interfaz de enumerador IEnumOLEVERB), en caso contrario FALSE.

Comentarios

Esta función miembro es básicamente una implementación de IOleObject::EnumVerbs.

CCmdTarget::FromIDispatch

Llame a esta función para asignar un puntero IDispatch, recibido de las funciones miembro de automatización de una clase, en el objeto CCmdTarget que implementa las interfaces del objeto IDispatch.

static CCmdTarget* PASCAL FromIDispatch(LPDISPATCH lpDispatch);

Parámetros

lpDispatch
Puntero a un objeto IDispatch .

Valor devuelto

Puntero al objeto CCmdTarget asociado a la vista lpDispatch. Esta función devuelve NULL si el objeto IDispatch no se reconoce como un objeto IDispatch de Microsoft Foundation Class.

Comentarios

El resultado de esta función es el inverso de una llamada a la función miembro GetIDispatch.

CCmdTarget::GetDispatchIID

Obtiene el identificador de la interfaz de distribución principal.

virtual BOOL GetDispatchIID(IID* pIID);

Parámetros

pIID
Puntero a un identificador de interfaz (un GUID).

Valor devuelto

TRUE es si se ejecuta correctamente; de lo contrario FALSE, es . Si se ejecuta correctamente, *pIID se establece en el identificador de la interfaz de distribución principal.

Comentarios

Las clases derivadas deben invalidar esta función miembro (si no se invalida, GetDispatchIID devuelve FALSE). Vea COleControl.

CCmdTarget::GetIDispatch

Llame a esta función miembro para recuperar el puntero IDispatch de un método de automatización que devuelve un puntero IDispatch o toma un puntero IDispatch por referencia.

LPDISPATCH GetIDispatch(BOOL bAddRef);

Parámetros

bAddRef
Especifica si se debe incrementar el recuento de referencias para el objeto.

Valor devuelto

Puntero IDispatch asociado al objeto.

Comentarios

En el caso de los objetos que llaman a EnableAutomation en sus constructores, lo que hace que la automatización esté habilitada, esta función devuelve un puntero a la implementación de Foundation Class de IDispatch que usan los clientes que se comunican a través de la interfaz IDispatch. Al llamar a esta función, se agrega automáticamente una referencia al puntero, por lo que no es necesario realizar una llamada a IUnknown::AddRef.

CCmdTarget::GetTypeInfoCount

Recupera el número de interfaces de información de tipo que proporciona un objeto (0 ó 1).

virtual UINT GetTypeInfoCount();

Valor devuelto

Recupera el número de interfaces de información de tipo.

Comentarios

Esta función miembro implementa IDispatch::GetTypeInfoCount básicamente.

Las clases derivadas deben invalidar esta función para devolver el número de interfaces de información de tipo proporcionadas (ya sea 0 o 1). Si no se reemplaza, GetTypeInfoCount devuelve 0. Para invalidar, use la macro IMPLEMENT_OLETYPELIB, que también implementa GetTypeLib y GetTypeLibCache.

CCmdTarget::GetTypeInfoOfGuid

Recupera la descripción del tipo que corresponde al GUID especificado.

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

Parámetros

lcid
Un identificador de configuración regional (LCID).

guid
GUID de la descripción de tipo.

ppTypeInfo
Puntero un puntero a la interfaz ITypeInfo.

Valor devuelto

Un HRESULT que indica si la llamada se realizó correctamente o no. Si se ejecuta correctamente, *ppTypeInfo apunta a la interfaz de información de tipo.

CCmdTarget::GetTypeLib

Obtiene un puntero a una biblioteca de tipos.

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

Parámetros

lcid
Identificador de configuración regional (LCID).

ppTypeLib
Un puntero a un puntero a la interfaz ITypeLib.

Valor devuelto

Un HRESULT que indica si la llamada se realizó correctamente o no. Si se ejecuta correctamente, *ppTypeLib apunta a la interfaz de la biblioteca de tipos.

Comentarios

Las clases derivadas deben invalidar esta función miembro (si no se invalida, GetTypeLib devuelve TYPE_E_CANTLOADLIBRARY). Use la macro IMPLEMENT_OLETYPELIB, que también implementa GetTypeInfoCount y GetTypeLibCache.

CCmdTarget::GetTypeLibCache

Obtiene la memoria caché de la biblioteca de tipos.

virtual CTypeLibCache* GetTypeLibCache();

Valor devuelto

Puntero a un objeto CTypeLibCache .

Comentarios

Las clases derivadas deben invalidar esta función miembro (si no se invalida, GetTypeLibCache devuelve NULL). Use la macro IMPLEMENT_OLETYPELIB, que también implementa GetTypeInfoCount y GetTypeLib.

CCmdTarget::IsInvokeAllowed

La implementación de IDispatch::Invoke por MFC llama a esta función para determinar si se puede invocar un método de automatización determinado (identificado por dispid).

virtual BOOL IsInvokeAllowed(DISPID dispid);

Parámetros

dispid
Identificador de envío.

Valor devuelto

TRUE es si se puede invocar el método ; en caso contrario, es FALSE.

Comentarios

Si IsInvokeAllowed devuelve TRUE, Invoke continúa llamando al método ; de lo contrario, Invoke producirá un error y devolverá E_UNEXPECTED.

Las clases derivadas pueden invalidar esta función para devolver los valores adecuados (si no se invalidan, IsInvokeAllowed devuelve TRUE). En concreto, vea COleControl::IsInvokeAllowed.

CCmdTarget::IsResultExpected

Use IsResultExpected para determinar si un cliente espera un valor devuelto de su llamada a una función de automatización.

BOOL IsResultExpected();

Valor devuelto

Distinto de cero si una función de automatización debe devolver un valor; de lo contrario, 0.

Comentarios

La interfaz OLE proporciona información a MFC sobre si el cliente usa o ignora el resultado de una llamada de función y, a su vez, MFC usa esta información para determinar el resultado de una llamada a IsResultExpected. Si la producción de un valor devuelto consume mucho tiempo o recursos, puede aumentar la eficacia llamando a esta función antes de calcular el valor devuelto.

Esta función devuelve 0 solo una vez para que obtenga valores devueltos válidos de otras funciones de automatización si los llama desde la función de automatización a la que ha llamado el cliente.

IsResultExpected devuelve un valor distinto de cero si se llama cuando una llamada de función de automatización no está en curso.

CCmdTarget::OnCmdMsg

Lo llama el marco para enrutar y enviar mensajes de comandos y controlar la actualización de objetos de interfaz de usuario de comandos.

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

Parámetros

nID
Contiene el identificador de comando.

nCode
Identifica el código de notificación del comando. Vea Comentarios para obtener más información sobre los valores de nCode.

pExtra
Se usa según el valor de nCode. Consulte Comentarios para más información sobre pExtra.

pHandlerInfo
Si no es NULL, OnCmdMsg rellena los miembros pTarget y pmf de la estructura pHandlerInfo en lugar de enviar el comando. Normalmente, este parámetro debería ser NULL.

Valor devuelto

Distinto de cero si se controla el mensaje; en caso contrario, es 0.

Comentarios

Esta es la rutina de implementación principal de la arquitectura de comandos del marco.

En tiempo de ejecución, OnCmdMsg envía un comando a otros objetos o controla el propio comando mediante una llamada a la clase raíz CCmdTarget::OnCmdMsg, que realiza la búsqueda real de mapa de mensajes. Para obtener una descripción completa del enrutamiento de comandos predeterminado, vea Temas de control y asignación de mensajes.

En raras ocasiones, es posible que desee invalidar esta función miembro para ampliar el enrutamiento de comandos estándar del marco. Consulte la nota técnica 21 para obtener detalles avanzados de la arquitectura de enrutamiento de comandos.

Si invalida OnCmdMsg, debe proporcionar el valor adecuado para nCode, el código de notificación del comando y pExtra, que depende del valor de nCode. En la siguiente tabla se indican los valores correspondientes:

Valor de nCode	Valor de pExtra
CN_COMMAND	CCmdUI*
CN_EVENT	AFX_EVENT*
CN_UPDATE_COMMAND_UI	CCmdUI*
CN_OLECOMMAND	COleCmdUI*
CN_OLE_UNREGISTER	NULL

Ejemplo

// 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

Lo llama el marco cuando se libera la última referencia OLE a o desde el objeto.

virtual void OnFinalRelease();

Comentarios

Invalide esta función para proporcionar un control especial para esta situación. La implementación predeterminada elimina el objeto.

CCmdTarget::RestoreWaitCursor

Llame a esta función para restaurar el cursor de reloj de arena adecuado después de que el cursor del sistema haya cambiado (por ejemplo, después de que se haya abierto un cuadro de mensaje y luego se haya cerrado mientras se encuentra en medio de una operación larga).

void RestoreWaitCursor();

Ejemplo

// 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
}

Vea también

Ejemplo de MFCACDUAL
CObject (clase)
Gráfico de jerarquías
CCmdUI (clase)
CDocument (clase)
CDocTemplate (clase)
CWinApp (clase)
CWnd (clase)
CView (clase)
CFrameWnd (clase)
COleDispatchDriver (clase)