La classe CCmdTarget
Classe de base pour l’architecture de carte de messages de la bibliothèque de classes Microsoft Foundation.
Syntaxe
class CCmdTarget : public CObject
Membres
Constructeurs publics
Nom | Description |
---|---|
CCmdTarget::CCmdTarget |
Construit un objet CCmdTarget . |
Méthodes publiques
Nom | Description |
---|---|
CCmdTarget::BeginWaitCursor |
Affiche le curseur en tant que curseur de sablier. |
CCmdTarget::DoOleVerb |
Provoque l’exécution d’une action spécifiée par un verbe OLE. |
CCmdTarget::EnableAutomation |
Autorise l’automatisation OLE pour l’objet CCmdTarget . |
CCmdTarget::EnableConnections |
Active le déclenchement d’événements sur les points de connexion. |
CCmdTarget::EnableTypeLib |
Active la bibliothèque de types d’un objet. |
CCmdTarget::EndWaitCursor |
Retourne au curseur précédent. |
CCmdTarget::EnumOleVerbs |
Énumère les verbes OLE d’un objet. |
CCmdTarget::FromIDispatch |
Retourne un pointeur vers l’objet CCmdTarget associé au IDispatch pointeur. |
CCmdTarget::GetDispatchIID |
Obtient l’ID d’interface de répartition principale. |
CCmdTarget::GetIDispatch |
Retourne un pointeur vers l’objet IDispatch associé à l’objet CCmdTarget . |
CCmdTarget::GetTypeInfoCount |
Récupère le nombre d’interfaces d’informations de type fournies par un objet. |
CCmdTarget::GetTypeInfoOfGuid |
Récupère la description de type qui correspond au GUID spécifié. |
CCmdTarget::GetTypeLib |
Obtient un pointeur vers une bibliothèque de types. |
CCmdTarget::GetTypeLibCache |
Obtient le cache de bibliothèque de types. |
CCmdTarget::IsInvokeAllowed |
Active l’appel de méthode Automation. |
CCmdTarget::IsResultExpected |
Retourne une valeur différente de zéro si une fonction Automation doit retourner une valeur. |
CCmdTarget::OnCmdMsg |
Route et répartit les messages de commande. |
CCmdTarget::OnFinalRelease |
Nettoie une fois la dernière référence OLE publiée. |
CCmdTarget::RestoreWaitCursor |
Restaure le curseur de sablier. |
Notes
Un mappage de messages achemine les commandes ou les messages vers les fonctions membres que vous écrivez pour les gérer. (Une commande est un message à partir d’un élément de menu, d’un bouton de commande ou d’une touche accélérateur.)
Classes de framework clés dérivées d’include CCmdTarget
CView
, , CWinApp
, CWnd
CDocument
, et CFrameWnd
. Si vous souhaitez qu’une nouvelle classe gère les messages, dérivez la classe de l’une de ces CCmdTarget
classes dérivées. Vous dériverez rarement une classe directement CCmdTarget
.
Pour obtenir une vue d’ensemble des cibles de commande et OnCmdMsg
du routage, consultez Cibles de commande, Routage des commandes et Messages de mappage.
CCmdTarget
inclut des fonctions membres qui gèrent l’affichage d’un curseur de sablier. Affichez le curseur de sablier lorsque vous vous attendez à ce qu’une commande prenne un intervalle de temps notable à exécuter.
Les mappages de répartition, similaires aux mappages de messages, sont utilisés pour exposer les fonctionnalités d’automatisation IDispatch
OLE. En exposant cette interface, d’autres applications (telles que Visual Basic) peuvent appeler votre application.
Hiérarchie d'héritage
CCmdTarget
Spécifications
En-tête : afxwin.h
CCmdTarget::BeginWaitCursor
Appelez cette fonction pour afficher le curseur sous forme de sablier lorsque vous attendez qu’une commande prenne un intervalle de temps notable à exécuter.
void BeginWaitCursor();
Notes
L’infrastructure appelle cette fonction pour montrer à l’utilisateur qu’il est occupé, par exemple lorsqu’un CDocument
objet charge ou s’enregistre dans un fichier.
Les actions de BeginWaitCursor
ne sont pas toujours efficaces en dehors d’un seul gestionnaire de messages, comme d’autres actions, telles que OnSetCursor
la gestion, peuvent modifier le curseur.
Appelez EndWaitCursor
pour restaurer le curseur précédent.
Exemple
// 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
Construit un objet CCmdTarget
.
CCmdTarget();
CCmdTarget::DoOleVerb
Provoque l’exécution d’une action spécifiée par un verbe OLE.
BOOL DoOleVerb(
LONG iVerb,
LPMSG lpMsg,
HWND hWndParent,
LPCRECT lpRect);
Paramètres
iVerb
Identificateur numérique du verbe.
lpMsg
Pointeur vers la MSG
structure décrivant l’événement (par exemple, un double-clic) qui a appelé le verbe.
hWndParent
Handle de la fenêtre de document contenant l'objet.
lpRect
Pointeur vers la RECT
structure contenant les coordonnées, en pixels, qui définissent le rectangle englobant d’un objet en hWndParent
.
Valeur de retour
TRUE
si elle réussit, sinon FALSE
.
Notes
Cette fonction membre est essentiellement une implémentation de IOleObject::DoVerb
. Les actions possibles sont énumérées par CCmdTarget::EnumOleVerbs
.
CCmdTarget::EnableAutomation
Appelez cette fonction pour activer l’automatisation OLE pour un objet.
void EnableAutomation();
Notes
Cette fonction est généralement appelée à partir du constructeur de votre objet et ne doit être appelée que si une carte de répartition a été déclarée pour la classe. Pour plus d’informations sur l’automatisation, consultez les articles Automation Clients et Serveurs Automation.
CCmdTarget::EnableConnections
Active le déclenchement d’événements sur les points de connexion.
void EnableConnections();
Notes
Pour activer les points de connexion, appelez cette fonction membre dans le constructeur de votre classe dérivée.
CCmdTarget::EnableTypeLib
Active la bibliothèque de types d’un objet.
void EnableTypeLib();
Notes
Appelez cette fonction membre dans le constructeur de votre CCmdTarget
objet dérivé si elle fournit des informations de type.
CCmdTarget::EndWaitCursor
Appelez cette fonction une fois que vous avez appelé la BeginWaitCursor
fonction membre pour revenir du curseur de sablier au curseur précédent.
void EndWaitCursor();
Notes
L’infrastructure appelle également cette fonction membre une fois qu’elle a appelé le curseur de sablier.
Exemple
// 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
Énumère les verbes OLE d’un objet.
BOOL EnumOleVerbs(LPENUMOLEVERB* ppenumOleVerb);
Paramètres
ppenumOleVerb
Pointeur vers un pointeur vers une IEnumOLEVERB
interface.
Valeur de retour
TRUE
si l’objet prend en charge au moins un verbe OLE (auquel cas *ppenumOleVerb
pointe vers une interface d’énumérateur IEnumOLEVERB
), sinon FALSE
.
Notes
Cette fonction membre est essentiellement une implémentation de IOleObject::EnumVerbs
.
CCmdTarget::FromIDispatch
Appelez cette fonction pour mapper un IDispatch
pointeur, reçu des fonctions membres automation d’une classe, dans l’objet CCmdTarget
qui implémente les interfaces de l’objet IDispatch
.
static CCmdTarget* PASCAL FromIDispatch(LPDISPATCH lpDispatch);
Paramètres
lpDispatch
Pointeur vers un objet IDispatch
.
Valeur de retour
Pointeur vers l’objet CCmdTarget
associé à lpDispatch
. Cette fonction retourne NULL
si l’objet IDispatch
n’est pas reconnu en tant qu’objet Microsoft Foundation Class IDispatch
.
Notes
Le résultat de cette fonction est l’inverse d’un appel à la fonction GetIDispatch
membre.
CCmdTarget::GetDispatchIID
Obtient l’ID d’interface de répartition principale.
virtual BOOL GetDispatchIID(IID* pIID);
Paramètres
pIID
Pointeur vers un ID d’interface (GUID).
Valeur de retour
TRUE
si elle réussit, sinon FALSE
. En cas de réussite, *pIID
est défini sur l’ID d’interface de distribution principal.
Notes
Les classes dérivées doivent remplacer cette fonction membre (si elle n’est pas substituée, GetDispatchIID
retourne FALSE
). Consultez l’article COleControl
.
CCmdTarget::GetIDispatch
Appelez cette fonction membre pour récupérer le IDispatch
pointeur à partir d’une méthode Automation qui retourne un IDispatch
pointeur ou prend un IDispatch
pointeur par référence.
LPDISPATCH GetIDispatch(BOOL bAddRef);
Paramètres
bAddRef
Spécifie s’il faut incrémenter le nombre de références pour l’objet.
Valeur de retour
Pointeur IDispatch
associé à l’objet.
Notes
Pour les objets qui appellent EnableAutomation
leurs constructeurs, ce qui les rend activés pour l’automatisation, cette fonction retourne un pointeur vers l’implémentation de la classe Foundation utilisée IDispatch
par les clients qui communiquent via l’interface IDispatch
. L’appel de cette fonction ajoute automatiquement une référence au pointeur. Il n’est donc pas nécessaire d’effectuer un appel à IUnknown::AddRef
.
CCmdTarget::GetTypeInfoCount
Récupère le nombre d’interfaces d’informations de type fournies par un objet.
virtual UINT GetTypeInfoCount();
Valeur de retour
Nombre d’interfaces d’informations de type.
Notes
Cette fonction membre implémente IDispatch::GetTypeInfoCount
essentiellement .
Les classes dérivées doivent remplacer cette fonction pour retourner le nombre d’interfaces d’informations de type fournies (0 ou 1). Si elle n’est pas remplacée, GetTypeInfoCount
retourne 0. Pour remplacer, utilisez la IMPLEMENT_OLETYPELIB
macro, qui implémente GetTypeLib
et GetTypeLibCache
.
CCmdTarget::GetTypeInfoOfGuid
Récupère la description de type qui correspond au GUID spécifié.
HRESULT GetTypeInfoOfGuid(
LCID lcid,
const GUID& guid,
LPTYPEINFO* ppTypeInfo);
Paramètres
lcid
Identificateur de paramètres régionaux ( LCID
).
guid
GUID de la description de type.
ppTypeInfo
Pointeur vers un pointeur vers l’interface ITypeInfo
.
Valeur de retour
Indiquant HRESULT
la réussite ou l’échec de l’appel. Si elle réussit, *ppTypeInfo
pointe vers l’interface d’informations de type.
CCmdTarget::GetTypeLib
Obtient un pointeur vers une bibliothèque de types.
virtual HRESULT GetTypeLib(
LCID lcid,
LPTYPELIB* ppTypeLib);
Paramètres
lcid
Identificateur de paramètres régionaux (LCID).
ppTypeLib
Pointeur vers un pointeur vers l’interface ITypeLib
.
Valeur de retour
Indiquant HRESULT
la réussite ou l’échec de l’appel. Si elle réussit, *ppTypeLib
pointe vers l’interface de bibliothèque de types.
Notes
Les classes dérivées doivent remplacer cette fonction membre (si elle n’est pas substituée, GetTypeLib
retourne TYPE_E_CANTLOADLIBRARY
). Utilisez la IMPLEMENT_OLETYPELIB
macro, qui implémente GetTypeInfoCount
également et GetTypeLibCache
.
CCmdTarget::GetTypeLibCache
Obtient le cache de bibliothèque de types.
virtual CTypeLibCache* GetTypeLibCache();
Valeur de retour
Pointeur vers un objet CTypeLibCache
.
Notes
Les classes dérivées doivent remplacer cette fonction membre (si elle n’est pas substituée, GetTypeLibCache
retourne NULL
). Utilisez la IMPLEMENT_OLETYPELIB
macro, qui implémente GetTypeInfoCount
également et GetTypeLib
.
CCmdTarget::IsInvokeAllowed
Cette fonction est appelée par l’implémentation de MFC pour IDispatch::Invoke
déterminer si une méthode d’automatisation donnée (identifiée par dispid
) peut être appelée.
virtual BOOL IsInvokeAllowed(DISPID dispid);
Paramètres
dispid
ID de répartition.
Valeur de retour
TRUE
si la méthode peut être appelée, sinon FALSE
.
Notes
Si IsInvokeAllowed
cette propriété est retournée TRUE
, Invoke
passe à l’appel de la méthode ; sinon, Invoke
échouera, en retournant E_UNEXPECTED
.
Les classes dérivées peuvent remplacer cette fonction pour retourner les valeurs appropriées (si elles ne sont pas remplacées, IsInvokeAllowed
retourne TRUE
). Voir en particulier COleControl::IsInvokeAllowed
.
CCmdTarget ::IsResultExpected
Permet IsResultExpected
de déterminer si un client attend une valeur de retour de son appel à une fonction Automation.
BOOL IsResultExpected();
Valeur de retour
Différent de zéro si une fonction Automation doit retourner une valeur ; sinon 0.
Notes
L’interface OLE fournit des informations à MFC sur l’utilisation ou l’ignorance du résultat d’un appel de fonction, et MFC utilise à son tour ces informations pour déterminer le résultat d’un appel à IsResultExpected
. Si la production d’une valeur de retour est gourmande en temps ou en ressources, vous pouvez augmenter l’efficacité en appelant cette fonction avant de calculer la valeur de retour.
Cette fonction ne retourne 0 qu’une seule fois afin que vous obteniez des valeurs de retour valides à partir d’autres fonctions d’automatisation si vous les appelez à partir de la fonction Automation que le client a appelée.
IsResultExpected
retourne une valeur différente de zéro si elle est appelée lorsqu’un appel de fonction Automation n’est pas en cours.
CCmdTarget::OnCmdMsg
Appelé par l’infrastructure pour acheminer et distribuer des messages de commande et gérer la mise à jour des objets d’interface utilisateur de commande.
virtual BOOL OnCmdMsg(
UINT nID,
int nCode,
void* pExtra,
AFX_CMDHANDLERINFO* pHandlerInfo);
Paramètres
nID
Contient l’ID de commande.
nCode
Identifie le code de notification de commande. Pour plus d’informations sur les valeurs pour nCode
.
pExtra
Utilisé en fonction de la valeur de nCode
. Pour plus d’informations sur pExtra
.
pHandlerInfo
Si ce n’est pas NULL
le cas, OnCmdMsg
renseigne les membres et pmf
les pTarget
membres de la pHandlerInfo
structure au lieu de distribuer la commande. En règle générale, ce paramètre doit être NULL
.
Valeur de retour
Différent de zéro si le message est géré ; sinon 0.
Notes
Il s’agit de la routine d’implémentation principale de l’architecture de commande du framework.
Au moment de l’exécution, OnCmdMsg
distribue une commande à d’autres objets ou gère la commande elle-même en appelant la classe CCmdTarget::OnCmdMsg
racine, qui effectue la recherche réelle de la carte de messages. Pour obtenir une description complète du routage des commandes par défaut, consultez Rubriques relatives à la gestion des messages et au mappage.
Dans de rares cas, vous pouvez remplacer cette fonction membre pour étendre le routage des commandes standard du framework. Pour plus d’informations sur l’architecture de routage des commandes, reportez-vous à la note technique 21 .
Si vous remplacez OnCmdMsg
, vous devez fournir la valeur appropriée pour nCode
, le code de notification de commande et pExtra
, qui dépend de la valeur de nCode
. Le tableau suivant répertorie leurs valeurs correspondantes :
Valeur nCode |
Valeur pExtra |
---|---|
CN_COMMAND |
CCmdUI * |
CN_EVENT |
AFX_EVENT * |
CN_UPDATE_COMMAND_UI |
CCmdUI * |
CN_OLECOMMAND |
COleCmdUI * |
CN_OLE_UNREGISTER |
NULL |
Exemple
// 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
Appelé par l’infrastructure lorsque la dernière référence OLE vers ou à partir de l’objet est publiée.
virtual void OnFinalRelease();
Notes
Remplacez cette fonction pour fournir une gestion spéciale pour cette situation. L’implémentation par défaut supprime l’objet.
CCmdTarget::RestoreWaitCursor
Appelez cette fonction pour restaurer le curseur de sablier approprié une fois que le curseur système a changé (par exemple, une fois qu’une boîte de message a ouvert, puis fermée au milieu d’une longue opération).
void RestoreWaitCursor();
Exemple
// 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
}
Voir aussi
Exemple MFC ACDUAL
CObject
Classe
Graphique hiérarchique
CCmdUI
Classe
CDocument
Classe
CDocTemplate
Classe
CWinApp
Classe
CWnd
Classe
CView
Classe
CFrameWnd
Classe
COleDispatchDriver
Classe