TRxPopupMenu Component

Unit
RxMenus

Description
Компонента TRxPopupMenu является наследником стандартного класса TPopupMenu и предназначена для создания owner-draw меню с возможностью отрисовки его пунктов в Вашем приложении.
При значении свойства Style = msStandard поведение меню ничем не отличается от стандартной компоненты — отрисовка пунктов меню выполняется системой Windows.
При установке свойства Style в значение, отличное от msStandard отрисовку пунктов меню выполняет компонента TRxPopupMenu. В этом случае Вы можете обработать событие OnGetItemParams для изменения шрифта или цвета пункта меню, а также для задания графического изображения, которое Вы хотите поместить в этот пункт меню. Вы можете также установить значение свойства LeftMargin для получения поля в левой части выпадающего меню.

Для более полного контроля за отрисовкой меню Вы можете воспользоваться также событиями OnMeasureItem, OnDrawItem, OnDrawMargin.

ВНИМАНИЕ
В 16-разрядной версии компоненты существует ограничение, вызванное поведением системы Windows. Сообщение WM_DRAWITEM не посылается 16-разрядным приложениям для тех пунктов меню, которые содержат в себе подменю. Следовательно, для таких пунктов меню не вызываются события OnGetItemParams, OnMeasureItem и OnDrawItem.


Declaration
property Style: TRxMenuStyle;

Description
Свойство Style определяет, будет ли отрисовка меню производиться стандартными средствами Windows, или же Вы можете использовать свой собственный код для отрисовки пунктов меню (owner-draw), например, для помещения в меню графических изображений.
Для создания owner-draw меню задайте значение свойству Style, отличное от msStandard. В этом случае Вы сможете обработать события OnMeasureItem, OnDrawItem и OnGetItemParams; а также задать значения свойствам ShowCheckMarks и LeftMargin.


Declaration
property OnGetItemParams: TItemParamsEvent;

Description
Событие происходит перед отрисовкой каждого пункта меню, если свойство Style установлено в значение, отличное от msStandard.
В обработчике события OnGetItemParams Вы можете изменить шрифт и фоновый цвет пункта меню, а также задать графическое изображение (битовое изображение, иконку, метафайл и т.д.) для отображения в левой части пункта меню. Параметр NumGlyphs определяет, сколько картинок содержит графическое изображение Graphic. Если он отличен от 1, то второе изображение используется при отрисовке запрещенного пункта меню, третье — при отрисовке выбранного пункта меню, четвертое — отмеченного (checked), остальные картинки не используются.

Событие не происходит, если свойство Style = msStandard.

Примечание
В 32-битной версии, если задано свойство Images и обработчик события OnGetImageIndex возвращает допустимое значение параметра ImageIndex, то для отрисовки пункта меню используется изображение из image-list'а, а параметры Graphic и NumGlyphs игнорируются.


Declaration
property OnMeasureItem: TMeasureMenuItemEvent;

Description
Событие OnMeasureItem происходит когда приложению необходимо перерисовать пункт меню, имеющего стиль owner-draw. Используйте это событие для изменения высоты и ширины пункта меню.
Событие OnMeasureItem имеет тип TMeasureMenuItemEvent и имеет 4 паратметра:
• Sender — меню, содержащее пункт, который надо перерисовать;

• Item — пункт меню;
• Width — ширина пункта меню;
• Height — высота пункта меню.
Параметры Width и Height являются var-параметрами, которые изначально имеют значения по-умолчанию, определенные в соответствии с высотой используемого шрифта, длины текста и, возможно, по результатам обработки события OnGetItemParams. Обработчик события OnMeasureItem может изменить эти значения.
После вызова события OnMeasureItem происходит вызов события OnDrawItem.

Событие OnMeasureItem не происходит, если свойство Style = msStandard.


Declaration
property OnDrawItem: TDrawMenuItemEvent;

Description
Событие OnDrawItem происходит при отрисовке каждого пункта меню, если значение свойства Style не равно msStandard.
В обработчике этого события Вы можете произвести необходимые действия по отрисовке пункта меню, заданного параметром Item. Отрисовку надо производить в прямоугольнике, заданном параметром Rect, пользуясь значением свойства Canvas.

Параметр State определяет состояние пункта меню (выбранный, запрещенный или помеченный).


Declaration
type
TRxMenuStyle = (msStandard, msOwnerDraw, msBtnLowered, msBtnRaised);
Description
Тип определяет возможные значения свойства Style компонент TRxMainMenu и TRxPopupMenu
. Значения msBtnLowered и msBtnRaised доступны только в 32-разрядной версии.


Declaration
property LeftMargin: Cardinal;

Description
Свойство определяет размер поля (в пикселях) в левой стороне меню, которое не будет занято пунктами меню и может быть использовано для рисования дополнительных изображений, текста и т.д.
Если свойство Sytle = msStandard, то значение свойства LeftMargin игнорируется.
По умолчанию, если не задан обработчик события OnDrawMargin, компонента TRxPopupMenu заполняет пространство, определенное LeftMargin, градиентной заливкой, используя метод DefaultDrawMargin. Вы можете также вызвать этот метод из Вашего обработчика события OnDrawMargin.


Declaration
property OnDrawMargin: TDrawMarginEvent;

Description
Событие OnDrawMargin происходит при перерисовке области в левой стороне меню, размер которой задан свойством LeftMargin. Событие не происходит для меню, имеющих свойство Style = msStandard или LeftMargin = 0.
Если обработчик этого события не задан, компонента TRxPopupMenu самостоятельно заполняет левое поле меню, используя метод DefaultDrawMargin.


Declaration
procedure DefaultDrawMargin(ARect: TRect; StartColor, EndColor: TColor);

Description
Метод DefaultDrawMargin предназначен для отрисовки поля в левой стороне popup-меню, когда значение свойства LeftMargin больше 0. Метод рисует прямоугольник Rect, цвет которого изменяется от StartColor до EndColor сверху вниз, используя процедуру GradientFillRect.

Вы можете вызвать метод DefaultDrawMargin из вашего обработчика события OnDrawMargin. Этот метод используется компонентой TRxPopupMenu для отрисовки левого поля, когда не задан пользовательсктй обработчик события OnDrawMargin.


Declaration
procedure GradientFillRect(Canvas: TCanvas; Rect: TRect; BeginColor, EndColor: TColor; Direction: TFillDirection; Colors: Byte);
Description
Процедура GradientFillRect рисует прямоугольник Rect на устройстве Canvas, цвет которого плавно изменяется от BeginColor до EndColor в направлении Direction. При рисовании используется число цветов, определенное параметром Colors (от 1 до 255).


Declaration
type
TFillDirection = (fdTopToBottom, fdBottomToTop, fdLeftToRight, fdRightToLeft);
Description
Тип определяет допустимые значения параметра Direction процедуры GradientFillRect.


Declaration
type
TDrawMenuItemEvent = procedure(Sender: TMenu; Item: TMenuItem; Rect: TRect; State: TMenuOwnerDrawState) of object;
Description
Тип TDrawMenuItemEvent определяет методы — обработчики события OnDrawItem компонент TRxMainMenu и TRxPopupMenu.

Параметр Item определяет пункт главного или popup- меню, Rect — прямоугольную область, в которой должен быть нарисован пункт меню, и State — текущее состояние пункта меню. Возможные значения параметра State:
• mdSelected — пункт меню является выбранным;
• mdDisabled — пункт меню запрещен;
• mdChecked — пункт меню помечен;
• mdDefault — пункт меню является пунктом меню "по умолчанию" (32-bit version only).


Declaration
type
TMenuOwnerDrawState = set of (mdSelected, mdGrayed, mdDisabled, mdChecked, mdFocused, mdDefault);
Description
Тип определяет возможные значения параметра State обработчика события OnDrawItem компонент TRxMainMenu и TRxPopupMenu.