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
, CWnd
y 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
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)