Листы свойств и страницы свойств
Свойства объекта предоставляются клиентам так же, как методы через com-интерфейсы или реализацию IDispatch объекта, что позволяет изменять свойства программами, вызывающими эти методы. Технология OLE страниц свойств предоставляет средства для создания пользовательского интерфейса для свойств объекта в соответствии со стандартами пользовательского интерфейса Windows. Таким образом, свойства предоставляются конечным пользователям. Лист свойств объекта — это диалоговое окно с вкладками, где каждая вкладка соответствует определенной странице свойств. Модель OLE для работы со страницами свойств состоит из следующих функций:
- Каждая страница свойств управляется внутрипроцессным объектом, реализующим IPropertyPage или IPropertyPage2. Каждая страница идентифицируется с собственным уникальным CLSID.
- Объект указывает поддержку страниц свойств путем реализации ISpecifyPropertyPages. Через этот интерфейс вызывающий объект может получить список CLSID, определяющий определенные страницы свойств, поддерживаемые объектом. Если объект указывает clSID страницы свойств, объект должен иметь возможность получать изменения свойств на странице свойств.
- Любой фрагмент кода (клиент или объект), который хочет отобразить лист свойств объекта, передает указатель IUnknown объекта (или массив, если требуется затронуть несколько объектов) вместе с массивом страниц CLSID в OleCreatePropertyFrame или OleCreatePropertyFrameIndirect, который создает диалоговое окно табуляции.
- Диалоговое окно кадра свойств создает экземпляр одного экземпляра каждой страницы свойств с помощью CoCreateInstance для каждого CLSID. Кадр свойств получает по крайней мере указатель IPropertyPage для каждой страницы. Кроме того, кадр создает объект сайта страницы свойств для каждой страницы. Каждый сайт реализует IPropertyPageSite , и этот указатель передается на каждую страницу. Затем страница взаимодействует с сайтом с помощью этого указателя интерфейса.
- Каждая страница также учитывает объект или объекты, для которых он был вызван; То есть кадр свойств передает указатели IUnknownобъектов на каждую страницу. При указании применить изменения к объектам каждую страницу запрашивает соответствующий указатель интерфейса и передает новые значения свойств объектам в любом случае. Нет никаких условий о том, как такое общение должно произойти.
- Объект также может поддерживать для каждого свойства, просматривая интерфейс IPerPropertyBrowsing , разрешая объекту указывать, какое свойство должно получать начальное фокусирование при отображении страницы свойств, а также указывать строки и значения, которые могут отображаться клиентом в собственном пользовательском интерфейсе.
Эти функции показаны на следующей схеме:
Эти интерфейсы определены следующим образом:
interface ISpecifyPropertyPages : IUnknown
{
HRESULT GetPages([out] CAUUID *pPages);
};
interface IPropertyPage : IUnknown
{
HRESULT SetPageSite([in] IPropertyPageSite *pPageSite);
HRESULT Activate([in] HWND hWndParent, [in] LPCRECT prc
, [in] BOOL bModal);
HRESULT Deactivate(void);
HRESULT GetPageInfo([out] PROPPAGEINFO *pPageInfo);
HRESULT SetObjects([in] ULONG cObjects
, [in, max_is(cObjects)] IUnknown **ppunk);
HRESULT Show([in] UINT nCmdShow);
HRESULT Move([in] LPCRECT prc);
HRESULT IsPageDirty(void);
HRESULT Apply(void);
HRESULT Help([in] LPCOLESTR pszHelpDir);
HRESULT TranslateAccelerator([in] LPMSG pMsg);
}
interface IPropertyPageSite : IUnknown
{
HRESULT OnStatusChange([in] DWORD dwFlags);
HRESULT GetLocaleID([out] LCID *pLocaleID);
HRESULT GetPageContainer([out] IUnknown **ppUnk);
HRESULT TranslateAccelerator([in] LPMSG pMsg);
}
Метод ISpecifyPropertyPages::GetPages возвращает подсчитанный массив значений UUID (GUID), каждый из которых описывает CLSID страницы свойств, отображаемой объектом. Кто ever вызывает лист свойств с помощью OleCreatePropertyFrame или OleCreatePropertyFrameIndirect передает этот массив функции. Обратите внимание, что если вызывающий объект хочет отображать страницы свойств для нескольких объектов, он должен передавать только пересечение списков CLSID всех объектов этим функциям. Другими словами, вызывающий объект должен вызывать только страницы свойств, которые являются общими для всех объектов.
Кроме того, вызывающий объект передает указатели IUnknown затронутым объектам в функции API. Обе функции API создают диалоговое окно фрейма свойств и создают экземпляр сайта страницы с IPropertyPageSite для каждой страницы, для нее будет загружена. С помощью этого интерфейса страница свойств может:
- Получите текущий язык, используемый на листе свойств, с помощью GetLocaleID.
- Попросите кадр обрабатывать нажатия клавиш с помощью TranslateAccelerator.
- Уведомите кадр изменений на странице через OnStatusChange.
- Получите указатель интерфейса для самого кадра с помощью GetPageContainer, хотя в настоящее время для этой функции нет интерфейсов, которые всегда возвращаются E_NOTIMPL.
Кадр свойств создает экземпляр каждого объекта страницы свойств и получает интерфейс IPropertyPage каждой страницы. В этом интерфейсе фрейм сообщает странице своего сайта страницы (SetPageSite), извлекает измерения страницы и строки (GetPageInfo), передает указатели интерфейса на затронутые объекты (SetObjects), сообщает странице, когда нужно создавать и уничтожать его элементы управления (активировать и деактивировать), предписывает странице отображать или изменять положение страницы (Показать и перемещаться)), указывает странице применять текущие значения к затронутым объектам (применить), проверка на грязное страницы состояния (IsPageDirty), вызывает справку (справка) и передает нажатия клавиш на страницу (TranslateAccelerator).
Объект также может поддерживать просмотр свойств для каждого свойства, который предоставляет следующие возможности:
- Способ (через IPerPropertyBrowsing и IPropertyPage2), чтобы указать, какое свойство на странице свойств должно быть задано начальное фокус при первом отображении листа свойств.
- Способ (через IPerPropertyBrowsing) для объекта для указания предопределенных значений и соответствующих описательных строк, которые могут отображаться в собственном пользовательском интерфейсе клиента для свойств.
Объект может выбрать поддержку (2) без поддержки (1), например, если объект не имеет листа свойств.
Интерфейсы IPropertyPage2 и IPerPropertyBrowsing определяются следующим образом:
interface IPerPropertyBrowsing : IUnknown
{
HRESULT GetDisplayString([in] DISPID dispID, [out] BSTR *pbstr);
HRESULT MapPropertyToPage([in] DISPID dispID, [out] CLSID *pclsid);
HRESULT GetPredefinedStrings([in] DISPID dispID, [out] CALPOLESTR *pcaStringsOut, [out] CADWORD *pcaCookiesOut);
HRESULT GetPredefinedValue([in] DISPID dispID, [in] DWORD dwCookie, [out] VARIANT *pvarOut);
}
interface IPropertyPage2 : IPropertyPage
{
HRESULT EditProperty([in] DISPID dispID);
}
Чтобы указать поддержку таких возможностей, объект реализует IPerPropertyBrowsing. Через этот интерфейс вызывающий объект может запрашивать сведения, необходимые для просмотра, например предопределенные строки (GetPredefinedStrings) и значения (GetPredefinedValue), а также отображаемую строку для заданного свойства (GetDisplayString).
Кроме того, клиент может получить CLSID страницы свойств, которая позволяет пользователю изменять заданное свойство, определяемое с DISPID (MapPropertyToPage). Затем клиент указывает кадру свойств активировать ее изначально путем передачи CLSID и DISPID в OleCreatePropertyFrameIndirect. Кадр активирует первую страницу и передает DISPID на страницу через IPropertyPage2::EditProperty. Затем страница задает фокус в поле редактирования этого свойства. Таким образом, клиент может перейти с имени свойства в собственном пользовательском интерфейсе на страницу свойств, которая может управлять этим свойством.
См. также