Класс CCmdTarget

Базовый класс для архитектуры сопоставления сообщений библиотеки классов Microsoft Foundation.

Синтаксис

class CCmdTarget : public CObject

Участники

Открытые конструкторы

Имя Описание
CCmdTarget::CCmdTarget Формирует объект CCmdTarget.

Открытые методы

Имя Описание
CCmdTarget::BeginWaitCursor Отображает курсор в виде курсора с часовой очками.
CCmdTarget::DoOleVerb Вызывает выполнение действия, указанного командой OLE.
CCmdTarget::EnableAutomation Разрешает автоматизацию CCmdTarget OLE для объекта.
CCmdTarget::EnableConnections Включает запуск событий по точкам подключения.
CCmdTarget::EnableTypeLib Включает библиотеку типов объекта.
CCmdTarget::EndWaitCursor Возвращается к предыдущему курсору.
CCmdTarget::EnumOleVerbs Перечисляет команды OLE объекта.
CCmdTarget::FromIDispatch Возвращает указатель на CCmdTarget объект, связанный с IDispatch указателем.
CCmdTarget::GetDispatchIID Возвращает идентификатор основного интерфейса диспетчера.
CCmdTarget::GetIDispatch Возвращает указатель на объект, IDispatch связанный с CCmdTarget объектом.
CCmdTarget::GetTypeInfoCount Извлекает количество интерфейсов сведений типа, которые предоставляет объект.
CCmdTarget::GetTypeInfoOfGuid Извлекает описание типа, соответствующее указанному GUID.
CCmdTarget::GetTypeLib Возвращает указатель на библиотеку типов.
CCmdTarget::GetTypeLibCache Возвращает кэш библиотеки типов.
CCmdTarget::IsInvokeAllowed Включает вызов метода автоматизации.
CCmdTarget::IsResultExpected Возвращает ненулевое значение, если функция автоматизации должна возвращать значение.
CCmdTarget::OnCmdMsg Маршрутизирует и отправляет сообщения команд.
CCmdTarget::OnFinalRelease Очищается после выпуска последней ссылки OLE.
CCmdTarget::RestoreWaitCursor Восстанавливает курсор почасовой очки.

Замечания

Сопоставление сообщений направляет команды или сообщения в функции-члены, которые вы записываете для их обработки. (Команда — это сообщение из пункта меню, кнопки команды или клавиши акселератора.)

Ключевые классы платформы, производные от CCmdTarget включения CView, CWinApp, CDocumentCWndи CFrameWnd. Если вы планируете использовать новый класс для обработки сообщений, наследуйте класс из одного из этих CCmdTargetпроизводных классов. Вы редко наследуете класс напрямую CCmdTarget .

Общие сведения о целевых объектах команд и OnCmdMsg маршрутизации см. в разделе "Целевые объекты команд", "Маршрутизация команд" и "Сообщения сопоставления".

CCmdTarget включает функции-члены, обрабатывающие отображение курсора часовой очки. Отображение курсора с часами при ожидании выполнения команды с заметным интервалом времени.

Карты отправки, аналогичные картам сообщений, используются для предоставления функций автоматизации IDispatch OLE. Предоставляя этот интерфейс, другие приложения (например, Visual Basic) могут вызываться в приложение.

Иерархия наследования

CObject

CCmdTarget

Требования

Заголовок.afxwin.h

CCmdTarget::BeginWaitCursor

Вызовите эту функцию, чтобы отобразить курсор в виде часовой очки, когда ожидается, что команда займет заметный интервал времени для выполнения.

void BeginWaitCursor();

Замечания

Платформа вызывает эту функцию, чтобы показать пользователю, что он занят, например, когда CDocument объект загружает или сохраняет себя в файле.

Действия BeginWaitCursor не всегда эффективны за пределами одного обработчика сообщений, так как другие действия, такие как OnSetCursor обработка, могут изменить курсор.

Вызов EndWaitCursor для восстановления предыдущего курсора.

Пример

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

Формирует объект CCmdTarget.

CCmdTarget();

CCmdTarget::DoOleVerb

Вызывает выполнение действия, указанного командой OLE.

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

Параметры

iVerb
Числовый идентификатор команды.

lpMsg
Указатель на MSG структуру, описывающую событие (например, дважды щелкните), вызвавшее команду.

hWndParent
Дескриптор окна документа, содержащего объект.

lpRect
Указатель на RECT структуру, содержащую координаты в пикселях, определяющий ограничивающий прямоугольник hWndParentобъекта.

Возвращаемое значение

TRUE Значение , если успешно выполнено, в противном случае FALSE.

Замечания

Эта функция-член в основном является реализацией IOleObject::DoVerb. Возможные действия перечисляются CCmdTarget::EnumOleVerbs.

CCmdTarget::EnableAutomation

Вызовите эту функцию, чтобы включить автоматизацию OLE для объекта.

void EnableAutomation();

Замечания

Эта функция обычно вызывается из конструктора объекта и должна вызываться только в том случае, если карта диспетчера объявлена для класса. Дополнительные сведения об автоматизации см. в статьях " Клиенты службы автоматизации" и "Серверы автоматизации".

CCmdTarget::EnableConnections

Включает запуск событий по точкам подключения.

void EnableConnections();

Замечания

Чтобы включить точки подключения, вызовите эту функцию-член в конструкторе производного класса.

CCmdTarget::EnableTypeLib

Включает библиотеку типов объекта.

void EnableTypeLib();

Замечания

Вызовите эту функцию-член в конструкторе производного CCmdTargetобъекта, если он предоставляет сведения о типе.

CCmdTarget::EndWaitCursor

Вызовите эту функцию после вызова BeginWaitCursor функции-члена, чтобы вернуться из курсора с часовой очки на предыдущий курсор.

void EndWaitCursor();

Замечания

Платформа также вызывает эту функцию-член после вызова курсора часовой очки.

Пример

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

Перечисляет команды OLE объекта.

BOOL EnumOleVerbs(LPENUMOLEVERB* ppenumOleVerb);

Параметры

ppenumOleVerb
Указатель на указатель на IEnumOLEVERB интерфейс.

Возвращаемое значение

TRUEЗначение , если объект поддерживает по крайней IEnumOLEVERB мере одну команду OLE (в этом случае *ppenumOleVerb указывает на интерфейс перечислителя), в противном случае FALSE.

Замечания

Эта функция-член в основном является реализацией IOleObject::EnumVerbs.

CCmdTarget::FromIDispatch

Вызовите эту функцию для сопоставления IDispatch указателя, полученного из функций члена службы автоматизации класса, в CCmdTarget объект, реализующий интерфейсы IDispatch объекта.

static CCmdTarget* PASCAL FromIDispatch(LPDISPATCH lpDispatch);

Параметры

lpDispatch
Указатель на объект IDispatch.

Возвращаемое значение

Указатель на объект, связанный CCmdTarget с lpDispatch. Эта функция возвращается, если IDispatch объект не распознается NULL как объект класса IDispatch Microsoft Foundation.

Замечания

Результатом этой функции является обратный вызов функции-члена GetIDispatch.

CCmdTarget::GetDispatchIID

Возвращает идентификатор основного интерфейса диспетчера.

virtual BOOL GetDispatchIID(IID* pIID);

Параметры

pIID
Указатель на идентификатор интерфейса ( GUID).

Возвращаемое значение

TRUE Значение , если успешно выполнено, в противном случае FALSE. В случае успешного выполнения *pIID задайте идентификатор основного интерфейса диспетчера.

Замечания

Производные классы должны переопределить эту функцию-член (если она не переопределена, GetDispatchIID возвращается FALSE). См. раздел COleControl.

CCmdTarget::GetIDispatch

Вызовите эту функцию-член, чтобы получить IDispatch указатель из метода автоматизации, который возвращает IDispatch указатель или принимает указатель по ссылке IDispatch .

LPDISPATCH GetIDispatch(BOOL bAddRef);

Параметры

bAddRef
Указывает, следует ли увеличивать число ссылок для объекта.

Возвращаемое значение

Указатель, IDispatch связанный с объектом.

Замечания

Для объектов, которые вызываются EnableAutomation в конструкторах, что позволяет включить автоматизацию, эта функция возвращает указатель на реализацию IDispatch класса Foundation, которая используется клиентами, взаимодействующими через IDispatch интерфейс. Вызов этой функции автоматически добавляет ссылку на указатель, поэтому не требуется выполнять вызов IUnknown::AddRef.

CCmdTarget::GetTypeInfoCount

Извлекает количество интерфейсов сведений типа, которые предоставляет объект.

virtual UINT GetTypeInfoCount();

Возвращаемое значение

Количество интерфейсов сведений о типе.

Замечания

Эта функция-член в основном реализует IDispatch::GetTypeInfoCount.

Производные классы должны переопределить эту функцию, чтобы вернуть число предоставленных интерфейсов сведений типа (0 или 1). Если параметр не переопределен, GetTypeInfoCount возвращает значение 0. Чтобы переопределить, используйте IMPLEMENT_OLETYPELIB макрос, который также реализует GetTypeLib и GetTypeLibCache.

CCmdTarget::GetTypeInfoOfGuid

Извлекает описание типа, соответствующее указанному GUID.

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

Параметры

lcid
Идентификатор языкового стандарта ( LCID).

guid
GUID описания типа.

ppTypeInfo
Указатель на указатель на ITypeInfo интерфейс.

Возвращаемое значение

Указывает HRESULT на успешность или сбой вызова. В случае успешного выполнения *ppTypeInfo указывает на интерфейс сведений о типе.

CCmdTarget::GetTypeLib

Возвращает указатель на библиотеку типов.

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

Параметры

lcid
Идентификатор языка (LCID).

ppTypeLib
Указатель на указатель на ITypeLib интерфейс.

Возвращаемое значение

Указывает HRESULT на успешность или сбой вызова. В случае успешного выполнения *ppTypeLib указывает на интерфейс библиотеки типов.

Замечания

Производные классы должны переопределить эту функцию-член (если она не переопределена, GetTypeLib возвращается TYPE_E_CANTLOADLIBRARY). IMPLEMENT_OLETYPELIB Используйте макрос, который также реализует GetTypeInfoCount и GetTypeLibCache.

CCmdTarget::GetTypeLibCache

Возвращает кэш библиотеки типов.

virtual CTypeLibCache* GetTypeLibCache();

Возвращаемое значение

Указатель на объект CTypeLibCache.

Замечания

Производные классы должны переопределить эту функцию-член (если она не переопределена, GetTypeLibCache возвращается NULL). IMPLEMENT_OLETYPELIB Используйте макрос, который также реализует GetTypeInfoCount и GetTypeLib.

CCmdTarget::IsInvokeAllowed

Эта функция вызывается реализацией IDispatch::Invoke MFC, чтобы определить, можно ли вызвать заданный метод автоматизации (идентифицируемый dispidпо).

virtual BOOL IsInvokeAllowed(DISPID dispid);

Параметры

dispid
Идентификатор диспетчера.

Возвращаемое значение

TRUE Значение , если метод можно вызвать, в противном случае FALSE.

Замечания

Если IsInvokeAllowed возвращается TRUE, Invoke выполняется вызов метода; в противном случае Invoke произойдет сбой, возврат E_UNEXPECTED.

Производные классы могут переопределить эту функцию для возврата соответствующих значений (если не переопределено, IsInvokeAllowed возвращается TRUE). См. в частности COleControl::IsInvokeAllowed.

CCmdTarget::IsResultExpected

Используется IsResultExpected для определения того, ожидает ли клиент возвращаемое значение от вызова функции автоматизации.

BOOL IsResultExpected();

Возвращаемое значение

Ненулевое значение, если функция автоматизации должна возвращать значение; в противном случае — 0.

Замечания

Интерфейс OLE предоставляет сведения MFC о том, использует ли клиент результат вызова функции или игнорирует его, и MFC, в свою очередь, использует эти сведения для определения результата вызова IsResultExpected. Если производство возвращаемого значения является временем или ресурсоемким, можно повысить эффективность, вызвав эту функцию перед вычислением возвращаемого значения.

Эта функция возвращает значение 0 только один раз, чтобы получить допустимые возвращаемые значения из других функций автоматизации при вызове их из функции автоматизации, вызываемой клиентом.

IsResultExpected возвращает ненулевое значение, если вызывается при выполнении вызова функции автоматизации.

CCmdTarget::OnCmdMsg

Вызывается платформой для маршрутизации и отправки сообщений команд и обработки обновления объектов пользовательского интерфейса команды.

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

Параметры

nID
Содержит идентификатор команды.

nCode
Определяет код уведомления команды. Дополнительные сведения о значениях см. в примечаниях.nCode

pExtra
Используется в соответствии со значением nCode. Дополнительные сведения смpExtra. в примечаниях.

pHandlerInfo
NULLOnCmdMsg В противном случае заполняет и pmf члены pTargetpHandlerInfo структуры вместо отправки команды. Как правило, этот параметр должен быть NULL.

Возвращаемое значение

Ненулевое значение, если сообщение обрабатывается; в противном случае — 0.

Замечания

Это основная подпрограмма реализации архитектуры команд платформы.

Во время OnCmdMsg выполнения отправляет команду другим объектам или обрабатывает саму команду, вызывая корневой класс CCmdTarget::OnCmdMsg, который выполняет фактический поиск карты сообщений. Полное описание маршрутизации команд по умолчанию см. в разделах об обработке и сопоставлении сообщений.

В редких случаях может потребоваться переопределить эту функцию-член, чтобы расширить стандартную маршрутизацию команд платформы. Дополнительные сведения об архитектуре маршрутизации команд см. в техническом примечание 21 .

При переопределении OnCmdMsgнеобходимо указать соответствующее значение для nCode, код уведомления команды и pExtra, который зависит от значения nCode. В следующей таблице перечислены соответствующие значения:

Значение nCode Значение pExtra
CN_COMMAND CCmdUI*
CN_EVENT AFX_EVENT*
CN_UPDATE_COMMAND_UI CCmdUI*
CN_OLECOMMAND COleCmdUI*
CN_OLE_UNREGISTER NULL

Пример

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

Вызывается платформой при выпуске последней ссылки OLE на объект или из нее.

virtual void OnFinalRelease();

Замечания

Переопределите эту функцию, чтобы обеспечить специальную обработку для этой ситуации. Реализация по умолчанию удаляет объект.

CCmdTarget::RestoreWaitCursor

Вызовите эту функцию, чтобы восстановить соответствующий курсор часовой очки после изменения системного курсора (например, после открытия и закрытия окна сообщения в середине длительной операции).

void RestoreWaitCursor();

Пример

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

См. также

Пример MFC ACDUAL
CObject Класса
Диаграмма иерархии
CCmdUI Класса
CDocument Класса
CDocTemplate Класса
CWinApp Класса
CWnd Класса
CView Класса
CFrameWnd Класса
COleDispatchDriver Класса