Поделиться через

Глобальные функции составных элементов управления

  • Статья

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

Важно!

Функции, перечисленные в следующей таблице, нельзя использовать в приложениях, которые выполняются в среда выполнения Windows.

Function Description
AtlAxDialogBox Создает модальное диалоговое окно на основе шаблона диалогового окна, предоставленного пользователем. Результирующее диалоговое окно может содержать элементы ActiveX.
AtlAxCreateDialog Создает немодальное диалоговое окно на основе шаблона диалогового окна, предоставленного пользователем. Результирующее диалоговое окно может содержать элементы ActiveX.
AtlAxCreateControl Создает элемент управления ActiveX, инициализирует его и размещает в указанном окне.
AtlAxCreateControlEx Создает элемент ActiveX, инициализирует его, размещает его в указанном окне и извлекает указатель интерфейса (или указатели) из элемента управления.
AtlAxCreateControlLic Создает лицензированный элемент управления ActiveX, инициализирует его и размещает в указанном окне.
AtlAxCreateControlLicEx Создает лицензированный элемент activeX, инициализирует его, размещает его в указанном окне и извлекает указатель интерфейса (или указатели) из элемента управления.
AtlAxAttachControl Присоединяет ранее созданный элемент управления к указанному окну.
AtlAxGetHost Используется для получения прямого указателя интерфейса на контейнер для указанного окна (если таковые есть), учитывая его дескриптор.
AtlAxGetControl Используется для получения прямого указателя интерфейса на элемент управления, содержащийся в указанном окне (если таковые есть), учитывая его дескриптор.
AtlSetChildSite Инициализирует IUnknown дочерний сайт.
AtlAxWinInit Инициализирует код размещения для объектов AxWin.
AtlAxWinTerm Неинициализирует код размещения для объектов AxWin.
AtlGetObjectSourceInterface Возвращает сведения о исходном интерфейсе по умолчанию объекта.

Требования

Заголовок: atlhost.h

AtlAxDialogBox

Создает модальное диалоговое окно на основе шаблона диалогового окна, предоставленного пользователем.

ATLAPI_(int) AtlAxDialogBox(
    HINSTANCE hInstance,
    LPCWSTR lpTemplateName,
    HWND hWndParent,
    DLGPROC lpDialogProc,
    LPARAM dwInitParam);

Параметры

hInstance
[in] Определяет экземпляр модуля, исполняемый файл которого содержит шаблон диалогового окна.

lpTemplateName
[in] Определяет шаблон диалогового окна. Этот параметр является указателем на строку символов, завершающую значение NULL, указывающее имя шаблона диалогового окна или целочисленное значение, указывающее идентификатор ресурса шаблона диалогового окна. Если параметр задает идентификатор ресурса, его слово высокого порядка должно быть равно нулю, а его слово с низким порядком должно содержать идентификатор. Для создания этого значения можно использовать макрос MAKEINTRESOURCE .

hWndParent
[in] Определяет окно, которое владеет диалоговым окном.

lpDialogProc
[in] Указывает на процедуру диалогового окна. Дополнительные сведения о процедуре диалогового окна см . в разделе DialogProc.

dwInitParam
[in] Указывает значение, которое нужно передать в диалоговое окно в параметре lParam сообщения WM_INITDIALOG.

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

Одно из стандартных значений HRESULT.

Замечания

Чтобы использовать AtlAxDialogBox шаблон диалогового окна, содержащий элемент activeX, укажите допустимую строку CLSID, APPID или URL-адреса в качестве текстового поля раздела CONTROL ресурса диалогового окна, а также "AtlAxWin80" в качестве поля имени класса в том же разделе. Ниже показано, как выглядит допустимый раздел CONTROL :

CONTROL    "{04FE35E9-ADBC-4f1d-83FE-8FA4D1F71C7F}", IDC_TEST,
    "AtlAxWin80", WS_GROUP | WS_TABSTOP, 0, 0, 100, 100

Дополнительные сведения об изменении скриптов ресурсов см. в статье "Практическое руководство. Создание ресурсов". Дополнительные сведения об инструкциях определения ресурсов см. в разделе "Общие параметры управления" в пакете SDK для Windows: средства SDK.

Дополнительные сведения о диалоговых окнах, как правило, см . в диалоговом окне иCreateDialogParam в пакете SDK для Windows.

AtlAxCreateDialog

Создает немодальное диалоговое окно на основе шаблона диалогового окна, предоставленного пользователем.

ATLAPI_(HWND) AtlAxCreateDialog(
    HINSTANCE hInstance,
    LPCWSTR lpTemplateName,
    HWND hWndParent,
    DLGPROC lpDialogProc,
    LPARAM dwInitParam);

Параметры

hInstance
[in] Определяет экземпляр модуля, исполняемый файл которого содержит шаблон диалогового окна.

lpTemplateName
[in] Определяет шаблон диалогового окна. Этот параметр является указателем на строку символов, завершающую значение NULL, указывающее имя шаблона диалогового окна или целочисленное значение, указывающее идентификатор ресурса шаблона диалогового окна. Если параметр задает идентификатор ресурса, его слово высокого порядка должно быть равно нулю, а его слово с низким порядком должно содержать идентификатор. Для создания этого значения можно использовать макрос MAKEINTRESOURCE .

hWndParent
[in] Определяет окно, которое владеет диалоговым окном.

lpDialogProc
[in] Указывает на процедуру диалогового окна. Дополнительные сведения о процедуре диалогового окна см . в разделе DialogProc.

dwInitParam
[in] Указывает значение, которое нужно передать в диалоговое окно в параметре lParam сообщения WM_INITDIALOG.

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

Одно из стандартных значений HRESULT.

Замечания

Результирующее диалоговое окно может содержать элементы ActiveX.

См. статью CreateDialog и CreateDialogParam в пакете SDK для Windows.

AtlAxCreateControl

Создает элемент управления ActiveX, инициализирует его и размещает в указанном окне.

ATLAPI AtlAxCreateControl(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer);

Параметры

lpszName
Указатель на строку, передаваемую элементу управления. Должен быть отформатирован одним из следующих способов:

  • Идентификатор progID, например "MSCAL.Calendar.7"

  • CLSID, например "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • URL-адрес, например "<https://www.microsoft.com>"

  • Ссылка на активный документ, например "file://\\\Documents\MyDoc.doc"

  • Фрагмент HTML, например "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Примечание.

    "MSHTML:" должен предшествовать фрагменту HTML, чтобы он был назначен как поток MSHTML.

hWnd
[in] Обработайте окно, к которому будет присоединен элемент управления.

pStream
[in] Указатель на поток, используемый для инициализации свойств элемента управления. Может иметь значение NULL.

ppUnkContainer
[out] Адрес указателя, который получит IUnknown контейнер. Может иметь значение NULL.

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

Одно из стандартных значений HRESULT.

Замечания

Эта глобальная функция дает тот же результат, что и вызов AtlAxCreateControlEx(lpszName, hWnd, pStream, NULL, NULL, NULL, NULL);

Сведения о создании лицензированного элемента activeX см. в статье AtlAxCreateControlLic.

AtlAxCreateControlEx

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

ATLAPI AtlAxCreateControlEx(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer,
    IUnknown** ppUnkControl,
    REFIID iidSink = IID_NULL,
    IUnknown* punkSink = NULL);

Параметры

lpszName
Указатель на строку, передаваемую элементу управления. Должен быть отформатирован одним из следующих способов:

  • Идентификатор progID, например "MSCAL.Calendar.7"

  • CLSID, например "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • URL-адрес, например "<https://www.microsoft.com>"

  • Ссылка на активный документ, например "file://\\\Documents\MyDoc.doc"

  • Фрагмент HTML, например "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Примечание.

    "MSHTML:" должен предшествовать фрагменту HTML, чтобы он был назначен как поток MSHTML.

hWnd
[in] Обработайте окно, к которому будет присоединен элемент управления.

pStream
[in] Указатель на поток, используемый для инициализации свойств элемента управления. Может иметь значение NULL.

ppUnkContainer
[out] Адрес указателя, который получит IUnknown контейнер. Может иметь значение NULL.

ppUnkControl
[out] Адрес указателя, который получит IUnknown созданный элемент управления. Может иметь значение NULL.

iidSink
Идентификатор интерфейса исходящего интерфейса в содержащемся объекте.

punkSink
Указатель на IUnknown интерфейс объекта приемника, который должен быть подключен к точке подключения, указанной iidSink на автономном объекте после успешного создания содержащегося объекта.

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

Одно из стандартных значений HRESULT.

Замечания

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

Сведения о создании лицензированного элемента activeX см. в статье AtlAxCreateControlLicEx.

AtlAxCreateControlLic

Создает лицензированный элемент управления ActiveX, инициализирует его и размещает в указанном окне.

ATLAPI AtlAxCreateControlLic(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer,
    BSTR bstrLic = NULL);

Параметры

lpszName
Указатель на строку, передаваемую элементу управления. Должен быть отформатирован одним из следующих способов:

  • Идентификатор progID, например "MSCAL.Calendar.7"

  • CLSID, например "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • URL-адрес, например "<https://www.microsoft.com>"

  • Ссылка на активный документ, например "file://\\\Documents\MyDoc.doc"

  • Фрагмент HTML, например "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Примечание.

    "MSHTML:" должен предшествовать фрагменту HTML, чтобы он был назначен как поток MSHTML.

hWnd
Обработайте окно, к которому будет присоединен элемент управления.

pStream
Указатель на поток, используемый для инициализации свойств элемента управления. Может иметь значение NULL.

ppUnkContainer
Адрес указателя, который получит IUnknown контейнер. Может иметь значение NULL.

bstrLic
BSTR, содержащий лицензию для элемента управления.

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

Одно из стандартных значений HRESULT.

Пример

Пример использования AtlAxCreateControlLicэлементов ActiveX см. в разделе "Размещение элементов ActiveX Controls с помощью ATL AXHost".

AtlAxCreateControlLicEx

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

ATLAPI AtlAxCreateControlLicEx(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer,
    IUnknown** ppUnkControl,
    REFIID iidSink = IID_NULL,
    IUnknown* punkSink = NULL,
    BSTR bstrLic = NULL);

Параметры

lpszName
Указатель на строку, передаваемую элементу управления. Должен быть отформатирован одним из следующих способов:

  • Идентификатор progID, например "MSCAL.Calendar.7"

  • CLSID, например "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • URL-адрес, например "<https://www.microsoft.com>"

  • Ссылка на активный документ, например "file://\\\Documents\MyDoc.doc"

  • Фрагмент HTML, например "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Примечание.

    "MSHTML:" должен предшествовать фрагменту HTML, чтобы он был назначен как поток MSHTML.

hWnd
Обработайте окно, к которому будет присоединен элемент управления.

pStream
Указатель на поток, используемый для инициализации свойств элемента управления. Может иметь значение NULL.

ppUnkContainer
Адрес указателя, который получит IUnknown контейнер. Может иметь значение NULL.

ppUnkControl
[out] Адрес указателя, который получит IUnknown созданный элемент управления. Может иметь значение NULL.

iidSink
Идентификатор интерфейса исходящего интерфейса в содержащемся объекте.

punkSink
Указатель на IUnknown интерфейс объекта приемника, который должен быть подключен к точке подключения, указанной iidSink на автономном объекте после успешного создания содержащегося объекта.

bstrLic
BSTR, содержащий лицензию для элемента управления.

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

Одно из стандартных значений HRESULT.

Замечания

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

Пример

Пример использования AtlAxCreateControlLicExэлементов ActiveX см. в разделе "Размещение элементов ActiveX Controls с помощью ATL AXHost".

AtlAxAttachControl

Присоединяет ранее созданный элемент управления к указанному окну.

ATLAPI AtlAxAttachControl(
    IUnknown* pControl,
    HWND hWnd,
    IUnknown** ppUnkContainer);

Параметры

pControl
[in] Указатель на IUnknown элемент управления.

hWnd
[in] Обработайте окно, в котором будет размещаться элемент управления.

ppUnkContainer
[out] Указатель на указатель IUnknown на объект контейнера.

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

Одно из стандартных значений HRESULT.

Замечания

Используйте AtlAxCreateControlEx и AtlAxCreateControl , чтобы одновременно создавать и присоединять элемент управления.

Примечание.

Перед вызовом AtlAxAttachControlприсоединенный объект элемента управления должен быть правильно инициализирован.

AtlAxGetHost

Получает прямой указатель интерфейса на контейнер для указанного окна (если имеется) по его указателю.

ATLAPI AtlAxGetHost(HWND h, IUnknown** pp);

Параметры

ч
[in] Дескриптор окна, в котором размещается элемент управления.

Pp
[out] Контейнер IUnknown элемента управления.

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

Одно из стандартных значений HRESULT.

AtlAxGetControl

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

ATLAPI AtlAxGetControl(HWND h, IUnknown** pp);

Параметры

ч
[in] Дескриптор окна, в котором размещается элемент управления.

Pp
[out] Размещенный IUnknown элемент управления.

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

Одно из стандартных значений HRESULT.

AtlSetChildSite

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

HRESULT AtlSetChildSite(IUnknown* punkChild, IUnknown* punkParent);

Параметры

punkChild
[in] Указатель на IUnknown интерфейс дочернего элемента.

punkParent
[in] Указатель на IUnknown интерфейс родительского элемента.

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

Стандартное значение HRESULT.

AtlAxWinInit

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

ATLAPI_(BOOL) AtlAxWinInit();

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

Ненулевое значение, если инициализация кода размещения элемента управления прошла успешно; в противном случае ЗНАЧЕНИЕ FALSE.

Замечания

Эта функция должна вызываться перед использованием API размещения элементов управления ATL. После вызова этой функции класс окна AtlAxWin можно использовать в вызовах CreateWindow или CreateWindowEx, как описано в пакете SDK для Windows.

AtlAxWinTerm

Эта функция неинициализирует код размещения элемента управления ATL, отменив регистрацию классов окон AtlAxWin80 и AtlAxWinLic80 .

inline BOOL AtlAxWinTerm();

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

Всегда возвращает значение TRUE.

Замечания

Эта функция просто вызывает UnregisterClass , как описано в пакете SDK для Windows.

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

AtlGetObjectSourceInterface

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

ATLAPI AtlGetObjectSourceInterface(
    IUnknown* punkObj,
    GUID* plibid,
    IID* piid,
    unsigned short* pdwMajor,
    unsigned short* pdwMinor);

Параметры

punkObj
[in] Указатель на объект, для которого возвращаются сведения.

plibid
[out] Указатель на LIBID библиотеки типов, содержащую определение исходного интерфейса.

piid
[out] Указатель на идентификатор интерфейса исходного интерфейса объекта по умолчанию.

pdwMajor
[out] Указатель на основной номер версии библиотеки типов, содержащий определение исходного интерфейса.

pdwMinor
[out] Указатель на дополнительный номер версии библиотеки типов, содержащей определение исходного интерфейса.

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

Стандартное значение HRESULT.

Замечания

AtlGetObjectSourceInterface можно предоставить идентификатор интерфейса исходного интерфейса по умолчанию, а также номера основных и дополнительных версий библиотеки типов, описывающих этот интерфейс.

Примечание.

Чтобы эта функция успешно извлекла запрошенные сведения, объект, представленный punkObj, должен реализовывать IDispatch (и возвращать сведения о типе с помощьюIDispatch::GetTypeInfo) плюс также должен реализовывать либоIProvideClassInfo2.IPersist Сведения о типе исходного интерфейса должны находиться в той же библиотеке типов, что и сведения о IDispatchтипе.

Пример

В приведенном ниже примере показано, как определить класс приемника событий, CEasySinkчто сокращает количество аргументов шаблона, которые можно передать IDispEventImpl в основные компоненты. EasyAdviseиспользуйте AtlGetObjectSourceInterfaceEasyUnadvise для инициализации членов IDispEventImpl перед вызовом DispEventAdvise или DispEventUnadvise.

template <UINT nID, class T>
class CEasySink : public IDispEventImpl<nID, T>
{
public:
   HRESULT EasyAdvise(IUnknown* pUnk) 
   { 
      AtlGetObjectSourceInterface(pUnk,
         &m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum);
      return DispEventAdvise(pUnk, &m_iid);
   }
   HRESULT EasyUnadvise(IUnknown* pUnk) 
   {
      AtlGetObjectSourceInterface(pUnk,
         &m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum);
      return DispEventUnadvise(pUnk, &m_iid);
   }
};

См. также

Функции
Макросы для работы с составными элементами управления