Classe CCmdTarget

Classe di base per l'architettura della mappa messaggi della libreria di classi Microsoft Foundation.

Sintassi

class CCmdTarget : public CObject

Membri

Costruttori pubblici

Nome	Descrizione
CCmdTarget::CCmdTarget	Costruisce un oggetto CCmdTarget.

Metodi pubblici

Nome	Descrizione
CCmdTarget::BeginWaitCursor	Visualizza il cursore come cursore di clessidra.
CCmdTarget::DoOleVerb	Determina l'esecuzione di un'azione specificata da un verbo OLE.
CCmdTarget::EnableAutomation	Consente l'automazione OLE per l'oggetto CCmdTarget .
CCmdTarget::EnableConnections	Abilita la generazione di eventi sui punti di connessione.
CCmdTarget::EnableTypeLib	Abilita la libreria dei tipi di un oggetto.
CCmdTarget::EndWaitCursor	Restituisce al cursore precedente.
CCmdTarget::EnumOleVerbs	Enumera i verbi OLE di un oggetto.
CCmdTarget::FromIDispatch	Restituisce un puntatore all'oggetto CCmdTarget associato al IDispatch puntatore.
CCmdTarget::GetDispatchIID	Ottiene l'ID dell'interfaccia dispatch principale.
CCmdTarget::GetIDispatch	Restituisce un puntatore all'oggetto IDispatch associato all'oggetto CCmdTarget .
CCmdTarget::GetTypeInfoCount	Recupera il numero di interfacce di informazioni sul tipo fornite da un oggetto .
CCmdTarget::GetTypeInfoOfGuid	Recupera la descrizione del tipo corrispondente al GUID specificato.
CCmdTarget::GetTypeLib	Ottiene un puntatore a una libreria dei tipi.
CCmdTarget::GetTypeLibCache	Ottiene la cache della libreria dei tipi.
CCmdTarget::IsInvokeAllowed	Abilita la chiamata al metodo di automazione.
CCmdTarget::IsResultExpected	Restituisce un valore diverso da zero se una funzione di automazione deve restituire un valore.
CCmdTarget::OnCmdMsg	Instrada e invia messaggi di comando.
CCmdTarget::OnFinalRelease	Pulisce dopo il rilascio dell'ultimo riferimento OLE.
CCmdTarget::RestoreWaitCursor	Ripristina il cursore di clessidra.

Osservazioni:

Una mappa dei messaggi instrada i comandi o i messaggi alle funzioni membro scritte per gestirli. Un comando è un messaggio da una voce di menu, un pulsante di comando o un tasto di scelta rapida.

Le classi del framework chiave derivate da CCmdTarget includono CView, CWinApp, CDocument, CWnde CFrameWnd. Se si prevede che una nuova classe gestisca i messaggi, derivare la classe da una di queste CCmdTargetclassi derivate. Raramente si deriva direttamente una classe CCmdTarget .

Per una panoramica delle destinazioni e OnCmdMsg del routing dei comandi, vedere Destinazioni dei comandi, Routing dei comandi e Mapping dei messaggi.

CCmdTarget include funzioni membro che gestiscono la visualizzazione di un cursore di clessidra. Visualizzare il cursore di clessidra quando si prevede che un comando prenda un intervallo di tempo notevole per l'esecuzione.

Le mappe dispatch, simili alle mappe messaggi, vengono usate per esporre la funzionalità di automazione IDispatch OLE. Esponendo questa interfaccia, altre applicazioni (ad esempio Visual Basic) possono chiamare nell'applicazione.

Gerarchia di ereditarietà

CObject

CCmdTarget

Requisiti

Intestazione:afxwin.h

CCmdTarget::BeginWaitCursor

Chiamare questa funzione per visualizzare il cursore come clessidra quando si prevede che un comando prenda un intervallo di tempo notevole per l'esecuzione.

void BeginWaitCursor();

Osservazioni:

Il framework chiama questa funzione per mostrare all'utente che è occupato, ad esempio quando un CDocument oggetto carica o salva se stesso in un file.

Le azioni di BeginWaitCursor non sono sempre efficaci al di fuori di un singolo gestore di messaggi come altre azioni, ad esempio OnSetCursor la gestione, potrebbero modificare il cursore.

Chiamare EndWaitCursor per ripristinare il cursore precedente.

Esempio

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

Costruisce un oggetto CCmdTarget.

CCmdTarget();

CCmdTarget::DoOleVerb

Determina l'esecuzione di un'azione specificata da un verbo OLE.

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

Parametri

iVerb
Identificatore numerico del verbo.

lpMsg
Puntatore alla MSG struttura che descrive l'evento ,ad esempio un doppio clic, che ha richiamato il verbo.

hWndParent
Punto di controllo della finestra del documento contenente l'oggetto.

lpRect
Puntatore alla RECT struttura contenente le coordinate, in pixel, che definiscono il rettangolo di delimitazione di un oggetto in hWndParent.

Valore restituito

TRUE se ha esito positivo; in caso contrario FALSE, .

Osservazioni:

Questa funzione membro è fondamentalmente un'implementazione di IOleObject::DoVerb. Le azioni possibili vengono enumerate da CCmdTarget::EnumOleVerbs.

CCmdTarget::EnableAutomation

Chiamare questa funzione per abilitare l'automazione OLE per un oggetto .

void EnableAutomation();

Osservazioni:

Questa funzione viene in genere chiamata dal costruttore dell'oggetto e deve essere chiamata solo se una mappa dispatch è stata dichiarata per la classe . Per altre informazioni sull'automazione, vedere gli articoli Client di automazione e server di automazione.

CCmdTarget::EnableConnections

Abilita la generazione di eventi sui punti di connessione.

void EnableConnections();

Osservazioni:

Per abilitare i punti di connessione, chiamare questa funzione membro nel costruttore della classe derivata.

CCmdTarget::EnableTypeLib

Abilita la libreria dei tipi di un oggetto.

void EnableTypeLib();

Osservazioni:

Chiamare questa funzione membro nel costruttore dell'oggetto CCmdTargetderivato da se fornisce informazioni sul tipo.

CCmdTarget::EndWaitCursor

Chiamare questa funzione dopo aver chiamato la BeginWaitCursor funzione membro per tornare dal cursore di clessidra al cursore precedente.

void EndWaitCursor();

Osservazioni:

Il framework chiama anche questa funzione membro dopo aver chiamato il cursore di clessidra.

Esempio

// 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 i verbi OLE di un oggetto.

BOOL EnumOleVerbs(LPENUMOLEVERB* ppenumOleVerb);

Parametri

ppenumOleVerb
Puntatore a un puntatore a un'interfaccia IEnumOLEVERB .

Valore restituito

TRUE se l'oggetto supporta almeno un verbo OLE (nel qual caso *ppenumOleVerb punta a un'interfaccia dell'enumeratore IEnumOLEVERB ), in caso contrario FALSE.

Osservazioni:

Questa funzione membro è fondamentalmente un'implementazione di IOleObject::EnumVerbs.

CCmdTarget::FromIDispatch

Chiamare questa funzione per eseguire il mapping di un IDispatch puntatore, ricevuto dalle funzioni membro di automazione di una classe, nell'oggetto CCmdTarget che implementa le interfacce dell'oggetto IDispatch .

static CCmdTarget* PASCAL FromIDispatch(LPDISPATCH lpDispatch);

Parametri

lpDispatch
Puntatore a un oggetto IDispatch.

Valore restituito

Puntatore all'oggetto CCmdTarget associato a lpDispatch. Questa funzione restituisce NULL se l'oggetto IDispatch non viene riconosciuto come oggetto Microsoft Foundation Class IDispatch .

Osservazioni:

Il risultato di questa funzione è l'inverso di una chiamata alla funzione GetIDispatchmembro .

CCmdTarget::GetDispatchIID

Ottiene l'ID dell'interfaccia dispatch principale.

virtual BOOL GetDispatchIID(IID* pIID);

Parametri

pIID
Puntatore a un ID interfaccia (GUID).

Valore restituito

TRUE se ha esito positivo; in caso contrario FALSE, . In caso di esito positivo, *pIID viene impostato sull'ID dell'interfaccia dispatch principale.

Osservazioni:

Le classi derivate devono eseguire l'override di questa funzione membro (se non sottoposto a override, GetDispatchIID restituisce FALSE). Vedere COleControl.

CCmdTarget::GetIDispatch

Chiamare questa funzione membro per recuperare il IDispatch puntatore da un metodo di automazione che restituisce un IDispatch puntatore o accetta un IDispatch puntatore per riferimento.

LPDISPATCH GetIDispatch(BOOL bAddRef);

Parametri

bAddRef
Specifica se incrementare il conteggio dei riferimenti per l'oggetto .

Valore restituito

Puntatore IDispatch associato all'oggetto .

Osservazioni:

Per gli oggetti che chiamano EnableAutomation nei costruttori, rendendoli abilitati per l'automazione, questa funzione restituisce un puntatore all'implementazione Foundation Class di IDispatch che viene usata dai client che comunicano tramite l'interfaccia IDispatch . La chiamata a questa funzione aggiunge automaticamente un riferimento al puntatore, quindi non è necessario effettuare una chiamata a IUnknown::AddRef.

CCmdTarget::GetTypeInfoCount

Recupera il numero di interfacce di informazioni sul tipo fornite da un oggetto .

virtual UINT GetTypeInfoCount();

Valore restituito

Numero di interfacce di informazioni sul tipo.

Osservazioni:

Questa funzione membro implementa IDispatch::GetTypeInfoCountfondamentalmente .

Le classi derivate devono eseguire l'override di questa funzione per restituire il numero di interfacce di informazioni sul tipo fornite (0 o 1). Se non ne viene eseguito l'override, GetTypeInfoCount restituisce 0. Per eseguire l'override, utilizzare la IMPLEMENT_OLETYPELIB macro , che implementa GetTypeLib anche e GetTypeLibCache.

CCmdTarget::GetTypeInfoOfGuid

Recupera la descrizione del tipo corrispondente al GUID specificato.

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

Parametri

lcid
Identificatore delle impostazioni locali ( LCID).

guid
GUID della descrizione del tipo.

ppTypeInfo
Puntatore a un puntatore all'interfaccia ITypeInfo .

Valore restituito

Oggetto HRESULT che indica l'esito positivo o negativo della chiamata. In caso di esito positivo, *ppTypeInfo punta all'interfaccia delle informazioni sul tipo.

CCmdTarget::GetTypeLib

Ottiene un puntatore a una libreria dei tipi.

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

Parametri

lcid
Identificatore delle impostazioni locali (LCID).

ppTypeLib
Puntatore a un puntatore all'interfaccia ITypeLib .

Valore restituito

Oggetto HRESULT che indica l'esito positivo o negativo della chiamata. In caso di esito positivo, *ppTypeLib punta all'interfaccia della libreria dei tipi.

Osservazioni:

Le classi derivate devono eseguire l'override di questa funzione membro (se non sottoposto a override, GetTypeLib restituisce TYPE_E_CANTLOADLIBRARY). Utilizzare la IMPLEMENT_OLETYPELIB macro , che implementa GetTypeInfoCount anche e GetTypeLibCache.

CCmdTarget::GetTypeLibCache

Ottiene la cache della libreria dei tipi.

virtual CTypeLibCache* GetTypeLibCache();

Valore restituito

Puntatore a un oggetto CTypeLibCache.

Osservazioni:

Le classi derivate devono eseguire l'override di questa funzione membro (se non sottoposto a override, GetTypeLibCache restituisce NULL). Utilizzare la IMPLEMENT_OLETYPELIB macro , che implementa GetTypeInfoCount anche e GetTypeLib.

CCmdTarget::IsInvokeAllowed

Questa funzione viene chiamata dall'implementazione di MFC di per determinare se un determinato metodo di IDispatch::Invoke automazione (identificato da dispid) può essere richiamato.

virtual BOOL IsInvokeAllowed(DISPID dispid);

Parametri

dispid
ID di invio.

Valore restituito

TRUE se il metodo può essere richiamato; in caso contrario FALSE, .

Osservazioni:

Se IsInvokeAllowed restituisce TRUE, Invoke continua a chiamare il metodo; in caso contrario, Invoke restituisce E_UNEXPECTED.

Le classi derivate possono eseguire l'override di questa funzione per restituire valori appropriati (se non sottoposto a override, IsInvokeAllowed restituisce TRUE). Vedere in particolare COleControl::IsInvokeAllowed.

CCmdTarget::IsResultExpected

Usare IsResultExpected per verificare se un client prevede un valore restituito dalla chiamata a una funzione di automazione.

BOOL IsResultExpected();

Valore restituito

Diverso da zero se una funzione di automazione deve restituire un valore; in caso contrario, 0.

Osservazioni:

L'interfaccia OLE fornisce informazioni a MFC sul fatto che il client usi o ignori il risultato di una chiamata di funzione e MFC a sua volta usa queste informazioni per determinare il risultato di una chiamata a IsResultExpected. Se la produzione di un valore restituito è a elevato utilizzo di tempo o di risorse, è possibile aumentare l'efficienza chiamando questa funzione prima di calcolare il valore restituito.

Questa funzione restituisce 0 una sola volta in modo da ottenere valori restituiti validi da altre funzioni di automazione se vengono chiamate dalla funzione di automazione chiamata dal client.

IsResultExpected restituisce un valore diverso da zero se viene chiamato quando una chiamata di funzione di automazione non è in corso.

CCmdTarget::OnCmdMsg

Chiamato dal framework per instradare e inviare messaggi di comando e per gestire l'aggiornamento degli oggetti dell'interfaccia utente del comando.

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

Parametri

nID
Contiene l'ID comando.

nCode
Identifica il codice di notifica del comando. Per altre informazioni sui valori per nCode.

pExtra
Usato in base al valore di nCode. Per altre informazioni su , vedere la sezione Note.pExtra

pHandlerInfo
Se non è NULL, OnCmdMsg compila i pTarget membri e pmf della pHandlerInfo struttura invece di inviare il comando. In genere, questo parametro deve essere NULL.

Valore restituito

Diverso da zero se il messaggio viene gestito; in caso contrario, 0.

Osservazioni:

Questa è la routine di implementazione principale dell'architettura dei comandi del framework.

In fase di esecuzione, OnCmdMsg invia un comando ad altri oggetti o gestisce il comando stesso chiamando la classe CCmdTarget::OnCmdMsgradice , che esegue la ricerca effettiva della mappa messaggi. Per una descrizione completa del routing dei comandi predefinito, vedere Argomenti relativi alla gestione e al mapping dei messaggi.

In rari casi, è possibile eseguire l'override di questa funzione membro per estendere il routing dei comandi standard del framework. Per informazioni dettagliate sull'architettura di routing dei comandi, vedere la Nota tecnica 21.

Se si esegue l'override OnCmdMsgdi , è necessario specificare il valore appropriato per nCode, il codice di notifica del comando e pExtra, che dipende dal valore di nCode. Nella tabella seguente sono elencati i valori corrispondenti:

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

Esempio

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

Chiamato dal framework quando viene rilasciato l'ultimo riferimento OLE a o dall'oggetto .

virtual void OnFinalRelease();

Osservazioni:

Eseguire l'override di questa funzione per fornire una gestione speciale per questa situazione. L'implementazione predefinita elimina l'oggetto .

CCmdTarget::RestoreWaitCursor

Chiamare questa funzione per ripristinare il cursore di clessidra appropriato dopo la modifica del cursore di sistema, ad esempio dopo l'apertura e la chiusura di una finestra di messaggio durante un'operazione lunga.

void RestoreWaitCursor();

Esempio

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

Vedi anche

Esempio MFC ACDUAL
CObject Classe
Grafico della gerarchia
CCmdUI Classe
CDocument Classe
CDocTemplate Classe
CWinApp Classe
CWnd Classe
CView Classe
CFrameWnd Classe
COleDispatchDriver Classe