Добавление страницы свойств (учебник ATL, часть 6)

  • Статья

Примечание.

Мастер поставщика OLE DB в ATL недоступен в Visual Studio 2019 и более поздних версиях.

Страницы свойств реализуются в качестве отдельных COM-объектов, которые при необходимости позволяют предоставлять к ним общий доступ. В рамках этой части вы добавите страницу свойств в элемент управления, выполнив следующие задачи:

  • Создание ресурса страницы свойств

  • Добавление кода для создания страницы свойств и управления ею.

  • Добавление страницы свойств в элемент управления

Создание ресурса страницы свойств

Чтобы добавить страницу свойств в свой элемент управления, используйте шаблон страницы свойств ATL.

Добавление страницы свойств

  1. В обозревателе решений щелкните Polygon правой кнопкой мыши.

  2. В контекстном меню выберите Добавить>Новый элемент.

  3. В списке шаблонов выберитеБиблиотека ATL>Страница свойств ATL и щелкните Добавить.

  4. После открытия мастера страницы свойств ATL введите PolyProp в поле Краткое имя.

  5. Щелкните Строки, чтобы открыть страницу Строки и введите &Polygon в поле Заголовок.

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

  6. Щелкните Готово и объект страницы свойств будет создан.

Будут созданы следующие три файла:

Файл Description
PolyProp.h Содержит класс C++ CPolyProp, который реализует страницу свойств.
PolyProp.cpp Включает файл PolyProp.h.
PolyProp.rgs Сценарий для реестра, который регистрирует объект страницы свойств.

Кроме того, в код будут внесены следующие изменения:

  • В файле Polygon.cpp в карту записи объекта добавляется новая страница свойств.

  • В файл Polygon.idl добавляется класс PolyProp.

  • В ресурс проекта добавляется новый файл сценария для реестра PolyProp.rgs.

  • В ресурс проекта для страницы свойств добавляется шаблон диалогового окна.

  • В таблицу строк ресурсов добавляются указанные вами строки свойств.

Теперь добавьте поля, которые должны отображаться на странице свойств.

Добавление полей на страницу свойств

  1. В обозревателе решений дважды щелкните файл ресурсов Polygon.rc. Откроется представление ресурсов.

  2. В представлении ресурсов разверните узел Dialog и дважды щелкните IDD_POLYPROP. Обратите внимание, что открывшееся диалоговое окно пустое. В нем находится лишь метка, указывающая, что сюда необходимо вставить элементы управления.

  3. Щелкните эту метку и измените ее на значение Sides:, изменив текст заголовка в окне свойств.

  4. Измените размер поля метки, чтобы оно соответствовало размеру текста.

  5. Перетащите элемент управления "Поле ввода" с панели инструментов, расположенной справа от метки.

  6. Наконец, в окне Свойства измените идентификатор элемента управления "Поле ввода" на IDC_SIDES.

На этом процесс создания ресурса страницы свойств завершается.

Добавление кода для создания страницы свойств и управления ею.

Теперь, после создания ресурса страницы свойств, вам нужно написать код реализации.

Сначала включите класс CPolyProp, чтобы задать количество сторон в вашем объекте при нажатии кнопки Применить.

Изменение функции Apply для установки количества сторон

  1. Замените функцию Apply в файле PolyProp.h следующим кодом:

    STDMETHOD(Apply)(void)
{
   USES_CONVERSION;
   ATLTRACE(_T("CPolyProp::Apply\n"));
   for (UINT i = 0; i < m_nObjects; i++)
   {
      CComQIPtr<IPolyCtl, &IID_IPolyCtl> pPoly(m_ppUnk[i]);
      short nSides = (short)GetDlgItemInt(IDC_SIDES);
      if FAILED(pPoly->put_Sides(nSides))
      {
         CComPtr<IErrorInfo> pError;
         CComBSTR strError;
         GetErrorInfo(0, &pError);
         pError->GetDescription(&strError);
         MessageBox(OLE2T(strError), _T("Error"), MB_ICONEXCLAMATION);
         return E_FAIL;
      }
   }
   m_bDirty = FALSE;
   return S_OK;
}

К странице свойств можно подключить несколько клиентов одновременно, поэтому функция Apply выполняет циклические запросы put_Sides для каждого клиента со значением, извлеченным из поля редактирования. Вы используете класс CComQIPtr, который выполняет запрос QueryInterface для каждого объекта, чтобы получить интерфейс IPolyCtl из интерфейса IUnknown, который хранится в массиве m_ppUnk.

Теперь код проверяет, действительно ли выполняется настройка свойства Sides. Если происходит сбой, код отображает окно сообщения с подробными сведениями об ошибке из интерфейса IErrorInfo. Как правило, контейнер запрашивает у объекта интерфейс ISupportErrorInfo и для начала вызывает InterfaceSupportsErrorInfo, чтобы определить, поддерживает ли объект сведения об ошибках настройки. Этот этап можно пропустить.

CComPtr помогает автоматически обрабатывать подсчет ссылок, поэтому нет необходимости вызывать Release в интерфейсе. CComBSTR помогает в обработке BSTR, поэтому вам не нужно выполнять последний вызов SysFreeString. Кроме того, вы используете один из множества классов преобразования строк, поэтому при необходимости можете преобразовать BSTR (именно поэтому в начале функции находится макрос USES_CONVERSION).

Вам также нужно установить флаг наличия несохраненных изменений на странице свойств, чтобы указать необходимость включения кнопки Применить. Это происходит, когда пользователь изменяет значение в поле редактирования Sides (Стороны).

Обработка кнопки "Применить"

  1. В представлении классов щелкните правой кнопкой мыши CPolyProp и выберите Свойства в контекстном меню.

  2. В окне Свойства щелкните значок События.

  3. Разверните узел IDC_SIDES в списке событий.

  4. Выберите EN_CHANGEи в раскрывающемся меню справа нажмите кнопку <"Добавить> OnEnChangeSides". Объявление обработчика OnEnChangeSides будет добавлено в файл Polyprop.h, а реализация обработчика — в файл Polyprop.cpp.

После этого вам необходимо изменить обработчик.

Изменение метода OnEnChangeSides

  1. В файле Polyprop.cpp добавьте следующий код в метод OnEnChangeSides (удалив код, который там поместил мастер):

    LRESULT CPolyProp::OnEnChangeSides(WORD /*wNotifyCode*/, WORD /*wID*/, 
   HWND /*hWndCtl*/, BOOL& /*bHandled*/)
{
   SetDirty(TRUE);

   return 0;
}

OnEnChangeSides вызывается при отправке сообщения WM_COMMAND с уведомлением EN_CHANGE для элемента управления IDC_SIDES. Затем OnEnChangeSides вызывает SetDirty и передает значение TRUE, чтобы указать, что страница свойств теперь является черновиком, а кнопка Применить должна быть включена.

Добавление страницы свойств в элемент управления

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

Добавление страницы свойств

  1. Откройте файл PolyCtl.h и добавьте приведенные ниже строки в карту свойств:

    PROP_ENTRY_TYPE("Sides", 1, CLSID_PolyProp, VT_INT)
PROP_PAGE(CLSID_PolyProp)

Карта свойств элемента управления должна выглядеть следующим образом:

BEGIN_PROP_MAP(CPolyCtl)
   PROP_DATA_ENTRY("_cx", m_sizeExtent.cx, VT_UI4)
   PROP_DATA_ENTRY("_cy", m_sizeExtent.cy, VT_UI4)
#ifndef _WIN32_WCE
   PROP_ENTRY_TYPE("FillColor", DISPID_FILLCOLOR, CLSID_StockColorPage, VT_UI4)
#endif
   PROP_ENTRY_TYPE("Sides", 1, CLSID_PolyProp, VT_INT)
   PROP_PAGE(CLSID_PolyProp)
   // Example entries
   // PROP_ENTRY("Property Description", dispid, clsid)
   // PROP_PAGE(CLSID_StockColorPage)
END_PROP_MAP()

Вы могли бы добавить макрос PROP_PAGE с CLSID вашей страницы свойств, но при использовании макроса PROP_ENTRY, как показано выше, значение свойства Sides также сохраняется при сохранении элемента управления.

К трем параметрам макроса относится описание свойства, DISPID свойства и CLSID страницы свойств, которая содержит свойство. Это удобно если, к примеру, вы загружаете элемент управления в Visual Basic и задаете количество сторон во время разработки. Так как количество сторон сохранено, при перезагрузке проекта Visual Basic оно будет восстановлено.

Сборка и тестирование элемента управления

Теперь выполните сборку этого элемента управления и вставьте его в контейнер для проверки элементов ActiveX. В контейнере для проверки в меню Правка щелкните PolyCtl Class Object (Объект класса PolyCtl). Откроется страница свойств с добавленными сведениями.

Кнопка Применить изначально отключена. Начните вводить значение в поле Sides (Стороны) и кнопка Применить станет активной. После ввода значения нажмите кнопку Применить. Отображение элемента управления изменится и кнопка Применить снова отключится. Попробуйте ввести недопустимое значение. Отобразится окно сообщения с описанием ошибки, которое вы настроили с помощью функции put_Sides.

После этого необходимо разместить элемент управления на странице.

Вернуться к шагу 5 | На шаге 7

См. также

Руководство