Please enable JavaScript to view this site.

KOL/MCK - User Guide

type TMenuitemInfo = packed record

   cbSize: UINT;

   fMask: UINT;

   fType: UINT;             { used if MIIM_TYPE}

   fState: UINT;            { used if MIIM_STATE}

   wID: UINT;               { used if MIIM_ID}

   hSubMenu: HMENU;         { used if MIIM_SUBMENU}

   hbmpChecked: HBITMAP;    { used if MIIM_CHECKMARKS}

   hbmpUnchecked: HBITMAP;  { used if MIIM_CHECKMARKS}

   dwItemData: DWORD;       { used if MIIM_DATA}

   dwTypeData: PKOLChar;    { used if MIIM_TYPE}

   cch: UINT;               { used if MIIM_TYPE}

   hbmpItem: HBITMAP;       { used if MIIM_BITMAP }

 end;

 

const

  TPM_HORPOSANIMATION = $0400;

  TPM_HORNEGANIMATION = $0800;

  TPM_VERPOSANIMATION = $1000;

  TPM_VERNEGANIMATION = $2000;

  TPM_NOANIMATION     = $4000;

 

type PMenu = ^TMenu;

 

type TOnMenuItem = procedure( Sender: PMenu; Item: Integer ) of object;

Event type to define OnMenuItem event.

 

type TMenuAccelerator = packed Record

 

fVirt: Byte;

or-combination of FSHIFT, FCONTROL, FALT, FVIRTKEY, FNOINVERT

 

Key: Word;

character or virtual key code (FVIRTKEY flag is present above)

 

NotUsed: Byte;

not used

end;

Menu accelerator record. Use MakeAccelerator function to combine desired attributes into a record, describing the accelerator.

 

type TMenuOption =( moDefault, moDisabled, moChecked, moCheckMark, moRadioMark, moSeparator, moBitmap, moSubMenu, moBreak, moBarBreak );

Options to add menu items dynamically.

 

type TMenuOptions = set of TMenuOption;

Set of options for menu item to use it in TMenu.AddItem method.

 

type TMenuBreak =( mbrNone, mbrBreak, mbrBarBreak );

Possible menu item break types.

 

function MenuStructSize: Integer;

Returns 44 under Windows95, and 48 (=sizeof(TMenuItemInfo) under all other Windows versions.

 

 

Constructors:

 

function NewMenu( AParent: PControl; MaxCmdReserve: DWORD; const Template: array of PKOLChar; aOnMenuItem: TOnMenuItem ): PMenu;

Menu constructor. First created menu becomes main menu of form (if AParent is a form). All other menus becomes popup (can be activated using Popup method). To provide dynamic replacing of main menu, create all popup menus as children of any other control, not form itself. When Menu is created, pass FirstCmd integer value to set it as ID of first menu item (all other ID's obtained by incrementing this value), and Template, which is an array of PChar (usually array of string constants), containing list of menu item identifiers and/or formatting characters.

FirstCmd value is assigned to first menu item created as its ID, all follow menu items are assigned to ID's obtained from FirstCmd incrementing it by 1. It is desirable to provide not intersected ranges of ID's for different menus in the applet.

 

Following formatting characters can be used in menu template strings:

& (in identifier) - to underline next character and use it as a shortcut character when possible;

+ (in front of identifier) - to make item checked. If also ! is used before & than radioitem is defined;

- (in front of identifier) - item not checked;

- (separate) - separator (between two items);

( (separate) - start of submenu;

) (separate) - end of submenu;

 

To get access to menu items, use constants 0, 1, etc. It is a good idea to create special enumerated type to index correspondent menu items using Ord( ) operator. Note in that case, that it is necessary only to define constants correspondent to identifiers (positions, correspondent to separators or submenu brackets are not identified by numbers).

 

function NewMenuEx( AParent: PControl; FirstCmd: Integer; const Template: array of PKOLChar; aOnMenuItems: array of TOnMenuItem ): PMenu;

Creates menu, assigning its own event handler for every (enough) menu item.

 

Properties, Methods and Events

 

property Handle : HMenu;

Handle of Windows menu object.

 

 

property MenuId: Integer;

Id of the menu item object. If menu item has subitems, it has also submenu Handle. Top parent menu object itself has no Id. Id-s areassigned automatically starting from 4096. Do not (re)create menu items instantly, because such values are not reused, and maximum possible Id value must not exceed 65535.

 

property Parent: PMenu;

Parent menu item (or parent menu).

 

property TopParent: PMenu;

Top parent menu, owning all nested subitems.

 

property Owner: PControl;

Parent control or form.

 

property Caption: KOLString;

Menu item caption text (including '&' indicating mnemonic characters, and keyboard accelerator representation string, usually following tabulation character).

 

property Items[ Id: HMenu ]: PMenu;

Returns menu item object by its index or by menu id. Since menu id values are starting from 4096, values from 0 to 4095 are interpreted as absolute index of menu item. Be careful accessing menu items or submenus by index, if you dynamically insert or delete items or submenus. In this version, separators are enumerating too, like all other items. Use index -1 to access object itself. The first item of a menu (or the first subitem of submenu item) has index 0.

Children are enumerating before all siblings. The maximum available index is (Count - 1), when accessing menu items by index.

 

property Count: Integer;

Count of items together with all its nested subitems.

 

function IndexOf( Item: PMenu ): Integer;

Returns index of an item. This index can be used to access menu item. Value -2 is returned, if the Item is not a child for menu or menu item, and has no parents, which are children for it, etc.

Menu object itself always has index -1.

 

property OnMenuItem : TOnMenuItem;

Is called when menu item is clicked. Absolute index of menu item clicked is passed as the second parameter. TopParent always is passed as a Sender parameter.

 

property ByAccel: Boolean;

True, when OnMenuItem is called not by mouse, but by accelerator key. Check this flag for entire menu (TopParent), not for item itself.

(Note, that Sender in OnMenuItem always is TopParent menu object).

 

property IsSeparator: Boolean;

TRUE, if a separator menu item.

 

property MenuBreak: TMenuBreak;

Menu item break type.

 

property OnUncheckRadioItem : TOnMenuItem;

Is called when radio item becomes unchecked in menu in result of checking another radio item of the same radio group.

 

property RadioGroup: Integer;

Radio group index. Several neighbor items with the same radio group index form radio group. Only single item from the same group can be checked at a time.

 

property IsCheckItem: Boolean;

If menu item is defined as check item, it is checked automatically when clicked.

 

procedure RadioCheckItem;

Call this method to check radio item. (Calling this method for an item, which is not belonging to a radio group, just sets its Checked state to TRUE).

 

property Checked: Boolean;

Checked state of the item.

 

property Enabled: Boolean;

Enabled state of the item. When assigned, Grayed state also is set to arbitrary value (i.e., when Enabled is set to true, Grayed is set to FALSE. )

 

property DefaultItem: Boolean;

Set this property to TRUE to make menu item default. Default item is drawn with bold. If you change DefaultItem at run-time and want to provide changing its visual state, recreate the item first resetting Visible property, then set it again.

 

property Highlight: Boolean;

Highlight state of the item.

 

property Visible: Boolean;

Visibility of menu item.

 

property Data: Pointer;

Data pointer, associated with the menu item.

 

property Bitmap: HBitmap;

Bitmap used for unchecked state of the menu item.

 

property BitmapChecked: HBitmap;

Bitmap used for checked state of the menu item.

 

property BitmapItem: HBitmap;

Bitmap used for item itself. In addition, following special values are possible: HBMMENU_CALLBACK, HBMMENU_MBAR_CLOSE, HBMMENU_MBAR_CLOSE_D, HBMMENU_MBAR_MINIMIZE, HBMMENU_MBAR_MINIMIZE_D, HBMMENU_MBAR_RESTORE, HBMMENU_POPUP_CLOSE,  HBMMENU_POPUP_MAXIMIZE, HBMMENU_POPUP_MINIMIZE, HBMMENU_POPUP_RESTORE, HBMMENU_SYSTEM.

 

property Accelerator: TMenuAccelerator;

Accelerator for menu item.

 

property HelpContext: Integer;

Help context for entire menu (help context can not be assigned to individual menu items).

 

procedure AssignEvents( StartIdx: Integer; const Events: array of TOnMenuItem );

It is possible to assign its own event handler to every menu item using this call. This procedure also is called automatically in a constructor NewMenuEx.

 

function MakeAccelerator( fVirt: Byte; Key: Word ): TMenuAccelerator;

Creates accelerator item to assign it to TMenu.ItemAccelerator[ ] property easy.

 

function GetAcceleratorText( const Accelerator: TMenuAccelerator ): KOLString;

Returns text representation of accelerator.

 

function Insert(InsertBefore: Integer; ACaption: PKOLChar; Event: TOnMenuItem; Options: TMenuOptions): PMenu;

Inserts new menu item before item, given by Id (>=4096) or index value InsertBefore. Pointer to an object created is returned.

 

property SubMenu: HMenu read FHandle; // write SetSubMenu;

Submenu associated with the menu item. The same as Handle. It was possible in earlier versions to change this value, replacing (removing, assigning) entire popup menu as a submenu for menu item.

But in modern version of TMenu, this is not possible. Instead, entire menu object should be added or removed using InsertSubmenu or RemoveSubmenu methods.

 

procedure InsertSubMenu( SubMenuToInsert: PMenu; InsertBefore: Integer );

Inserts existing menu item (together with its subitems if any present) into given position. See also RemoveSubMenu.

 

function RemoveSubMenu( ItemToRemove: Integer ): PMenu;

Removes menu item from the menu, returning TMenu object, representing it, if submenu item, having its own children, detached. If an individual menu item is removed, nil is returned.

 

function AddItem(ACaption: PKOLChar; Event: TOnMenuItem; Options: TMenuOptions): Integer;

Adds menu item dynamically. Returns ID of the added item.

 

function InsertItem(InsertBefore: Integer; ACaption: PKOLChar; Event: TOnMenuItem; Options: TMenuOptions): Integer;

Inserts menu item before an item with ID, given by InsertBefore parameter.

 

function InsertItemEx(InsertBefore: Integer; ACaption: PKOLChar; Event: TOnMenuItem; Options: TMenuOptions; ByPosition: Boolean): Integer;

Inserts menu item by command or by position, dependant on ByPosition parameter

 

procedure AssignBitmaps( StartIdx: Integer; Bitmaps: array of HBitmap );

Can be used to assign bitmaps to several menu items during one call.

 

function GetMenuItemHandle( Idx : Integer ): DWORD;

Returns Id of menu item with given index.

 

property ItemHandle[ Idx: Integer ]: DWORD;

Returns handle for item given by index.

 

property ItemChecked[ Idx : Integer ] : Boolean;

True, if correspondent menu item is checked.

 

procedure RadioCheck( Idx : Integer );

Call this method to check radio item. For radio items, do not use assignment to ItemChecked or Checked properties.

 

property ItemBitmap[ Idx: Integer ]: HBitmap read GetItemBitmap write SetItemBitmap;

This property allows to assign bitmap to menu item (for unchecked state only - for checked menu items default checkmark bitmap is used).

 

property ItemText[ Idx: Integer ]: KOLString;

This property allows to get / modify menu item text at run time.

 

property ItemEnabled[ Idx: Integer ]: Boolean;

Controls enabling / disabling menu items. Disabled menu items are displayed (grayed) but inaccessible to click.

 

property ItemVisible[ Idx: Integer ]: Boolean;

This property allows to simulate visibility of menu items (implementing it by removing or inserting again if needed. For items of submenu, which is made invisible, True is returned. If such item made Visible, entire submenu with all its parent menu items becomes visible. To release menu properly it is necessary to make before all its items visible again.

This does not matter, if menu is released at the end of execution, but can be sensible if owner form is destroyed and re-created at run time dynamically.

 

property ItemHelpContext[ Idx: Integer ]: Integer;

The context of the help system

 

property ItemAccelerator[ Idx: Integer ]: TMenuAccelerator;

Allows to get / change accelerator key codes assigned to menu items. Has no effect unless SupportMnemonics called for a form.

 

property ItemSubmenu[ Idx: Integer ]: HMenu; // write SetItemSubmenu;

Retrieves submenu item dynamically. See also SubMenu property.

 

procedure RedrawFormMenuBar;

for the main menu, this call provides an update of the image of the main menu bar after making any modifications in it. If such a call is not made, then the menu itself is not updated.

 

property OnMeasureItem: TOnMeasureItem;

This event is called for owner-drawn menu items. Event handler should return menu item height in lower word of a result and item width (for menu) in high word of result. If either for height or for width returned value is 0, a default one is used.

 

property OnDrawItem: TOnDrawItem;

This event is called for owner-drawn menu items.

 

property OwnerDraw: Boolean;

Set this property to true for some items to make it owner-draw.

 

function Popup( X, Y : Integer ): Integer;  

Only for popup menu - to popup it at the given position on screen.

Return: If you specify TPM_RETURNCMD in the uFlags parameter, the return value is the menu-item identifier of the item that the user selected.

If the user cancels the menu without making a selection, or if an error occurs, then the return value is zero.

If you do not specify TPM_RETURNCMD in the uFlags parameter, the return value is nonzero if the function succeeds and zero if it fails.

 

function PopupEx( X, Y: Integer ): Integer;

This version of popup command is very useful, when popup menu is activated when its parent window is not visible (e.g., for a kind of applications, which always are invisible, and can be activated only using tray icon).

PopupEx method provides correct tracking of menu disappearing when mouse is clicked anywhere else on screen, fixing strange menu behavior in some Windows versions (NT).

Actually, when PopupEx used, parent form is shown but below of visible screen, and when menu is disappearing, previous state of the form (visibility and position) are restored. If such solution is not satisfying You, You can do something else (e.g., use region clipping, etc.)

 

property OnPopup: TOnEvent;

This event occurs before the popup menu is shown.

 

property NotPopup: Boolean;

Set this property to true to prevent popup of popup menu, e.g. in OnPopup event handler.

 

property Flags: DWORD;

Pop-up flags, which are used to call TrackPopupMenuEx, when Popup or PopupEx method is called. Can be a combination of following values:

 

TPM_CENTERALIGN or TPM_LEFTALIGN or TPM_RIGHTALIGN

TPM_BOTTOMALIGN or TPM_TOPALIGN or TPM_VCENTERALIGN

TPM_NONOTIFY or TPM_RETURNCMD

TPM_LEFTBUTTON or TPM_RIGHTBUTTON

TPM_HORNEGANIMATION or TPM_HORPOSANIMATION or TPM_NOANIMATION or

TPM_VERNEGANIMATION or TPM_VERPOSANIMATION

TPM_HORIZONTAL or TPM_VERTICAL.

 

By default, a combination TPM_LEFTALIGN or TPM_LEFTBUTTON is used.

 

property CurCtl: PControl;

By Alexander Pravdin. This property is assigned to a control which were initiated a pop-up, for popup menu.

See also conditional compilation symbol: USE_MENU_CURCTL

 

KOL / MCK User Guide - Created by Carl Peeraer - Diamant Soft, based on the work of Vladimir Kladov - Artwerp.be

  

Keyboard Navigation

F7 for caret browsing
Hold ALT and press letter

This Info: ALT+q
Nav Header: ALT+n
Page Header: ALT+h
Topic Header: ALT+t
Topic Body: ALT+b
Exit Menu/Up: ESC