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 CCmdTargetCView, , CWinApp, CWndCDocument, et CFrameWnd. Si vous souhaitez qu’une nouvelle classe gère les messages, dérivez la classe de l’une de ces CCmdTargetclasses 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

CObject

CCmdTarget

Spécifications

En-têteafxwin.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 CCmdTargetobjet 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 GetIDispatchmembre.

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 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::GetTypeInfoCountessentiellement .

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 NULLle 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::OnCmdMsgracine, 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