Класс 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
, CDocument
CWnd
и CFrameWnd
. Если вы планируете использовать новый класс для обработки сообщений, наследуйте класс из одного из этих CCmdTarget
производных классов. Вы редко наследуете класс напрямую CCmdTarget
.
Общие сведения о целевых объектах команд и OnCmdMsg
маршрутизации см. в разделе "Целевые объекты команд", "Маршрутизация команд" и "Сообщения сопоставления".
CCmdTarget
включает функции-члены, обрабатывающие отображение курсора часовой очки. Отображение курсора с часами при ожидании выполнения команды с заметным интервалом времени.
Карты отправки, аналогичные картам сообщений, используются для предоставления функций автоматизации IDispatch
OLE. Предоставляя этот интерфейс, другие приложения (например, Visual Basic) могут вызываться в приложение.
Иерархия наследования
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
NULL
OnCmdMsg
В противном случае заполняет и pmf
члены pTarget
pHandlerInfo
структуры вместо отправки команды. Как правило, этот параметр должен быть 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
Класс