Приложения

Приложение А. Функции, константы и структуры RDS

А.5. Сервисные функции и макросы RDS

А.5.2. Управление работой RDS и функции общего назначения

А.5.2.37. rdsRegisterWindow – регистрация немодального окна

Функция rdsRegisterWindow добавляет указанное немодальное окно в меню «окна» и на панель с кнопками окон, чтобы пользователь мог активировать это окно, выбрав его название в меню или нажав соответствующую ему кнопку панели.

  BOOL RDSCALL rdsRegisterWindowA(
    HWND Handle,     // Дескриптор окна
    RDSCSTR Title,   // Название окна (UTF8)
    HBITMAP HBmp,    // Дескриптор картинки окна
    HINSTANCE HInst, // Дескриптор модуля с картинкой
    RDSCSTR ResName  // Имя ресурса с картинкой (UTF8)
  );
  BOOL RDSCALL rdsRegisterWindowW(
    HWND Handle,     // Дескриптор окна
    RDSWCSTR Title,  // Название окна (UTF16)
    HBITMAP HBmp,    // Дескриптор картинки окна
    HINSTANCE HInst, // Дескриптор модуля с картинкой
    RDSWCSTR ResName // Имя ресурса с картинкой (UTF16)
  );
  // Функция-псевдоним
  BOOL RDSCALL rdsRegisterWindow(
    HWND Handle,     // Дескриптор окна
    RDSXCSTR Title,  // Название окна (кодировка по умолчанию)
    HBITMAP HBmp,    // Дескриптор картинки окна
    HINSTANCE HInst, // Дескриптор модуля с картинкой
    RDSXCSTR ResName // Имя ресурса с картинкой (кодировка по умолчанию)
  );

Тип указателя на эту функцию

RDS_BHwSHbHiS (для UTF8) или RDS_BHwWsHbHiWs (для UTF16)

Параметры

Handle (HWND)

Дескриптор регистрируемого немодального окна. Именно это окно RDS будет помещать на передний план при выборе пользователем его названия в меню «окна» или нажатии кнопки на панели окон.

Title (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку с названием окна. Это название будет добавлено в меню «окна» и на панель кнопок окон RDS.

HBmp (HBITMAP)

Дескриптор растрового рисунка, который должен быть помещен на кнопку окна слева от названия. Может иметь значение NULL, тогда растровый рисунок задается параметрами HInst и ResName.

HInst (HINSTANCE)

Дескриптор модуля, из ресурсов которого должен быть загружен растровый рисунок для кнопки окна. Значение этого параметра используется только тогда, когда параметр HBmp равен NULL, в противном случае значение HInst может быть любым (можно передавать NULL). Понятие ресурсов и их использования рассматривается в описании Windows API.

ResName (RDSCSTR, RDSWCSTR, RDSXCSTR)

Имя ресурса, в котором находится растровый рисунок для кнопки окна. Значение этого параметра используется только тогда, когда параметр HBmp равен NULL, а параметр HInst не равен NULL. В противном случае значение ResName может быть любым (можно передавать NULL).

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

TRUE, если окно успешно зарегистрировано, FALSE в противном случае. Как правило, результат возврата этой функции можно не проверять – отказ в регистрации окна обычно связан с недопустимыми параметрами функции (например, если параметр Handle равен NULL), что легко обнаруживается и исправляется на этапе разработки программы.

Примечания

Если модель блока или модуль автоматической компиляции открывает немодальные окна (то есть окна, разрешающие пользователю переключаться в другие окна), желательно регистрировать их в RDS функцией rdsRegisterWindow, чтобы пользователю проще было вызывать их на передний план. При регистрации обязательно указывается дескриптор окна Handle, используемый RDS для перемещения окна на передний план, и название окна Title, по которому пользователь будет его опознавать в меню и на панели кнопок окон (обычно название окна делают одинаковым с его заголовком, чтобы пользователю было проще сопоставить их). Кроме того, при регистрации может быть задан растровый рисунок, который будет изображаться на кнопке этого окна слева от названия. Рисунок должен иметь размеры 16×16 точек, причем цвет его левой нижней точки будет считаться прозрачным, то есть этот цвет при изображении рисунка будет заменен на цвет фона кнопки. Сам рисунок задается тремя параметрами функции: HBmp, HInst и ResName. Возможны следующие сочетания параметров:

Как правило, при загрузке рисунка из ресурса этот ресурс размещают в одной DLL с моделью блока или модулем автокомпиляции, и в качестве дескриптора модуля HInst указывают дескриптор той библиотеки, из которой вызвана функция rdsRegisterWindow. Однако, это не является обязательным требованием: в HInst можно передать дескриптор любого модуля, загруженного в память на момент вызова. После регистрации окна этот модуль можно, при желании, немедленно выгрузить – для дальнейшей работы он не нужен.

После регистрации окна функцией rdsRegisterWindow процедура этого окна обязательно должна сообщать RDS об активации этого окна вызовом rdsRegWinActivateNotify, иначе кнопка этого окна не будет переходить в нажатое состояние, а его название в меню «окна» не будет помечаться. При закрытии окна его необходимо убрать из меню и с панели вызовом rdsUnregisterWindow.

См. также

rdsUnregisterWindow, rdsChangeRegWinTitle, rdsRegWinActivateNotify.