Implements menus used in forms created with the Lazarus IDE.

menus.pp contains classes, types, and routines used to implement menus used on TForm instances in the Lazarus Component Library (LCL).

Authors: Shane Miller and Marc Weustink

The following components are added to the Lazarus IDE component palette:

Standard Tab

TMainMenu
TPopupMenu

Registered but not displayed:

TMenuItem

Exception raised when an error occurs while accessing a menu item. TGlyphShowMode indicates if the glyph image of a menu or button should shown or not and in which circumstances. TApplication.ShowMenuGlyphs TApplicationShowGlyphs TCustomBitBtn.GlyphShowMode Always show the glyph image. Never show the glyph image. Uses the setting in the Application.ShowMenuGlyphs property. Uses the theme element setting in ThemeServices. Specifies an event handler signalled when a menu or menu item is changed.

TMenuChangeEvent defines an event handler signalled when a menu or a menu item has been changed.

TMenuChangeEvent is the type used for the OnChange property in both TMenu and TMenuItem, and implemented in the TMenu.MenuChanged method.

Object for the event notification. Menu or menu item where the change occurred. True to rebuild the menu item hierarchy. TMenuActionLink: defines the link between a selected menu item and its corresponding action.

TMenuActionLink defines the link between a selected menu item and its corresponding action. Properties are protected and not readily accessible by application programmers.

Stored a reference to the menu item for the link.

Overridden in TMenuActionLink to ensure that the value in AClient is cast to the TMenuItem type used for the internal client.

Determines if the menu item and action have the same value in their AutoCheck properties. True when AutoCheck is the same in the menu item and the action. Indicates if the OnExecute event handler in the action is linked to a menu item.

IsOnExecuteLinked always returns true in TBasicActionLink. Descendent classes can override this method to provide a different result.

TBasicActionLink SetAutoCheck - specifies whether AutoCheck is to apply. SetCaption - specifies the caption for the linked MenuItem. SetChecked - specifies whether the Item is checked. SetEnabled - specifies whether the action is enabled. SetHelpContext - specifies the Help context. Sets the Hint text for the linked menu action. Sets the index for the image associated with the linked menu action. Sets the ShortCut or accelerator key for the linked menu action. Sets the value in Visible for the menu item when the client and the action are linked. New value for the Visible property in the menu item. Not used in the current LCL implementation.

In previous LCL versions, this method changed the OnClick event handler. That action is not needed because TMenuItem.Click executes the Action. The current version has an empty implementation.

TMenuActionLinkClass - class of TMenuActionLink. Implements an enumerator for child menu items in the specified TMenuItem instance.

TMenuItemEnumerator is a class which implements an enumerator for child menu items for a specified TMenuItem instance. The menu item examined is passed as an argument to the constructor, and the reference is stored in an internal member variable.

TMenuItemEnumerator provides the MoveNext method used to advance the position for the enumerator, and the Current property which returns the TMenuItem instance in the child menu Items at the current enumerator position.

TMenuItemEnumerator is the type returned from the TMenuItem.GetEnumerator method.

Constructor for the class instance.

Create is the constructor for the class instance. Create stores the menu item in the AMenuItem argument to an internal member, and sets the internal position for the enumerator to -1.

Use MoveNext to advance to the first and subsequent child menu items for the enumerator. Use Current to retrieve the TMenuItem instance at the current position for the enumerator.

Menu item with the child menu items accessed in the class instance. Moves to the next position for the enumerator. True if another value is available for the enumerator. Returns the TMenuItem instance at the current position for the enumerator. TMenuItemHandlerType - enumerated type for menu item handlers. Currently has only one member - mihtDestroy Specifies an event handler signalled to draw a menu item to a canvas. Object for the event notification. Canvas used to render the menu item. Display rectangle for the menu item. Owner-drawn state for the menu item. Specifies an event handler signalled to get the width and height for a menu item.

TMenuMeasureItemEvent is an object procedure type which specifies an event handler signalled to get the width and height for a menu item.

Cast the value in Sender (when assigned) to a TMenuItem type to access properties and methods for the menu item.

Use ACanvas to access values for the TCanvas instance where the menu item is drawn.

AWidth and AHeight are variable arguments updated in the event handler with the dimensions for the menu item.

TMenuMeasureItemEvent is the type used to implement the OnMeasureItem property in TMenu and TMenuItem.

Object (TMenuItem) for the event notification. Canvas where the menu item is drawn. Width needed for the menu item. Height needed for the menu item. Implements a container for menu items merged into a parent menu or menu item.

TMergedMenuItems provides an internal array for visible and hidden menu items stored in the container. The array has two (2) elements; one for visible menu items, the other for hidden menu items. Each element is a TList instance where the corresponding TMenuItem instances are stored.

Use the indexed VisibleItems and InvisibleItems properties to access values stored in the container.

TMergedMenuItems is the type used for the MergedItems property in TMenuItem.

Constructor for the class instance.

Create is the constructor for the class instance, and calls the inherited method on entry. Create allocates resources needed for the internal storage in the container.

AParent is the TMenuItem instance that is the parent for the merged menu items. Values in its Merged property are added or updated in the visible or hidden sections for the container based on the Visible property for the menu items.

Menu item with the merged menu items for the container. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that menu items in the internal storage are freed. It calls the inherited destructor prior to exiting from the method.

Implements the default sort routine for merged menu items. Pointer to the first menu item for the sort comparison. Pointer to the second menu item for the sort comparison. Pointer to the Parent menu item for the compared values. Number of visible menu items in the storage for the container. Provides indexed access to the visible menu items in the list of merged menu items. Ordinal position for a visible menu item in the container. Number of invisible (hidden) menu items in the storage for the container. Provides indexed access to the invisible (hidden) menu items in the list of merged menu items. Ordinal position for an invisible (hidden) menu item in the container. Implements a list used to store TMenuItem instances with a given parent. Notifies the parent and the merged menu item that a child menu item has been added, extracted, or deleted.

The parent menu item calls its InvalidateMergedItems method to free the merged items. If the parent has an assigned MergeWith menu item, its InvalidateMergedItems is called as well. The CheckChildHandles method in the MergeWith menu item is called to free or re-create handles for the child menu items as needed.

Not used in the current implementation. Not used in the current implementation. Constructor for the class instance.

Create is the constructor for the class instance, and calls the inherited method on entry. Create stores the value in AMenuItem to the member variable used for the parent menu item.

Menu item that is the parent for the menu items in the list. Represents a menu item displayed in a menu.

TMenuItem is a TLCLComponent descendant which represent a menu item displayed on a TMenu instance, or one of its derived classes like TMainMenu and TPopUpMenu.

TMenuItem has properties which define the display attributes for the menu item, and allows accelerator keys to be defined in the Caption for the item. Event handlers are also provided which perform actions needed when the menu item is measured, drawn, or clicked.

TMenuItem is the type added and maintained in the TMenu.Items property.

Stores the numeric command in the widgetset class for the menu item. Changes the action for the menu item using the value specified in Sender.

ActionChange- changes the action associated with this menu item to a new action, provided Sender is of type TCustomAction. No actions are performed in the method when Sender is not derived from TCustomAction.

ActionChange updates property values in the current class instance to reflect the values in Sender when CheckDefaults has not been enabled. The following properties are updated from the values in the action:

AutoCheck
Caption
Checked
Enabled
HelpContext
Hint
GroupIndex
ImageIndex
ShortCut
Visible

ActionChange is called when a new value is assigned to the Action property for the menu item or when changes occur in the linked menu action.

TCustomAction examined and applied to the menu item. Copies property values from the current class instance to the specified destination.

AssignTo is an overridden method in TMenuItem used to copy property values from the current class instance to the destination specified in Dest. Dest can be either a TCustomAction instance or a TMenuItem instance.

When Dest is a TCustomAction descendant, the following properties are copied into the destination:

Caption
Enabled
HelpContext
Hint
ImageIndex
Visible

When Dest is a TMenuItem descendant, an implementation routine is called to transfer values between the TMenuItem instances.

If Dest is not a TMenuItem or a TCustomAction instance, the inherited AssignTo method is called.

TPersistent.Assign Action or menu item where values are stored in the method. Updates the image associated with the menu item when it has been changed.

BitmapChange is a method used to updates the image associated with the menu item when it has been changed. BitmapChange calls the UpdateImage method retrieve the Images or SubMenuImages for the item, its ancestor items, or the parent menu.

If an image is already assigned to the Bitmap property, it is freed. The value in ImageIndex is used to access the relevant bitmap in the image list. -1 indicates that a bitmap image has not been assigned for the menu item.

If the Handle for the control has been allocated, the widget set class is notified of the change to the property value.

BitmapChange is used as the OnChange event handler for the Bitmap property.

Performs actions needed to draw the menu item to the specified Canvas.

DoDrawItem is a Boolean function which performs actions needed to draw the menu item to the specified canvas with the given owner-drawn state.

DoDrawItem signals the OnDrawItem event handler (when assigned) to render the menu item to the canvas specified in ACanvas using the arguments passed to the method. The return value is set to True when the drawing operation is completed.

If OnDrawItem has not been assigned in the menu item, the GetParentMenu method is called to get the TMenu instance where the menu item is located. Its OnDrawItem event handler is signalled (when assigned) to render the menu item to the canvas specified in ACanvas using the arguments passed to the method. The return value is set to True when the drawing operation is completed.

If neither OnDrawItem event handler has been assigned, no actions are performed in the method and the return value is set to False.

True if the menu item was rendered using an OnDrawItem event handler. Canvas where the menu item is drawn. Display rectangle for the menu item. Owner-draw state for the menu item. Performs actions needed to get the width and height for the menu item.

DoMeasureItem is a method used to perform actions needed to get the width and height for the menu item. DoMeasureItem signals the OnMeasureItem event handler (when assigned) to calculate the values in AWidth and AHeight. The TCanvas instance in ACanvas is used to get the text metrics for the Caption.

If the OnMeasureItem event handler has not been for the menu item, the OnMeasureItem event handler in the Parent menu is used.

The return value is set to True after the selected event handler is successfully executed.

DoMeasureItem is called from the MeasureItem method in the TMenuItemHelper class helper. This class helper is implemented for the Windows platform only.

True if the size was calculated using an OnMeasureItem event handler. Canvas used to get size information for the menu item. Calculated width for the menu item. Calculated height for the menu item. Gets the value for the Action property.

The value for the property is read from the ActionLink property (when assigned). The property value is Nil when a TMenuActionLink instance has not been assigned to ActionLink.

Value for the property. Gets the class reference used to create an action link for the class. Returns TMenuActionLink in TMenuItem. Gets the value for the Handle property.

GetHandle calls HandleNeeded to ensure that a valid handle is available for the menu item. If the handle has not already been allocated, CreateHandle is called to create the handle in the widgetset class.

Value for the property. DoClicked- process the system message signifying that a click has occurred over this menu item.

At run-time, DoClicked calls InitiateAction to update the actions for each of the Items in the class instance, and calls Click to execute the menu item.

At design-time, the Click event is intercepted by the design surface for the IDE.

Message handled in the method. Verifies the handles for child menu items on the menu.

CheckChildrenHandles recursively checks menu items to ensure that handles for merged menu items are freed when they are hidden, or not owned by a menu item on the menu. No actions are performed in the method when Items has not been assigned.

Creates the Handle for the menu item.

CreateHandle is a method used to create the Handle for the control using the widgetset class instance. CreateHandle calls CheckChildrenHandles to ensure that handles for hidden menu Items are freed, and handles for MergedItems are re-created.

CreateHandle raises a catchable exception if the method is called when the menu item is not Visible.

Frees the Handle for the control and any handles allocated for its Items.

Handles for menu items in Merged are also freed. Calls the corresponding method in the widgetset class to destroy the handle, and sets the Handle property to 0 to indicate that it is unassigned.

Performs actions needed after the component is loaded using LCL streaming.

Loaded is overridden in TMenuItem, and calls the inherited method on entry. It calls the ActionChange method if Action has been assigned for the class instance.

TComponent Performs a notification when the menu item is added or removed.

Notification is an overridden method in TMenuItem, and calls the inherited method on entry. Notification ensures that the class instances in Action and SubMenuImages are set to Nil when the remove Operation is received for either member.

TComponent.Notification Component for the notification. Operation for the notification. Performs an operation for a component instance and its Items.

GetChildren is an overridden method in TMenuItem, and implements the dynamic method defined in the ancestor class. It does not call the inherited method.

GetChildren calls the object procedure in Proc for the component instance in Root and each of the component instances in its Items property.

No actions are performed in the method when Items has not been assigned (contains Nil).

TComponent Object procedure called for the component. Component examined in the object procedure. Updates Actions in child menu items.

InitiateActions is a method used to update the actions for child menu items in the Items property. InitiateActions visits each of the TMenuItem instances in Items and calls its InitiateAction method. This allows the ActionLink in the menu item to call its Update method for the associated TBasicAction instance.

InitiateActions is called from the DoClicked method prior to executing the Click method for the menu item. It is called from the TMenu class when shortcut (accelerator) keys are handled for the menu. It is also called from the TPopupMenu.PopUp method when the menu is displayed.

Signals the OnChange event handler (when assigned) and optionally rebuilds child menu items.

MenuChanged is a method used to perform actions needed when values in a menu item have been changed.

MenuChanged signals the OnChange event handler (when assigned) and optionally rebuilds the child menu items list. Arguments passed to the event handler identify the menu item for the notification, the menu item that owns the changed item or Nil when it is a TMenu instance, and the value in the Rebuild parameter.

MenuChanged is called from methods which modify property values like: Enabled, Bitmap, and ImageIndex. It is also called from methods that modify the values in in the Items property, including: Insert and Delete.

True to rebuild the child menu items. Sets the value for the Action property.

Maintains the ActionLink for the class instance.

New value for the property. Moves a menu item to the specified position in a menu.

Stores the value in the Order parameter to the MenuIndex property in the Child menu item.

TComponent Menu item affected in the method. Value assigned to the MenuIndex for the menu item. Sets the value for the GroupIndex property. New value for the property. Sets the value for the ImageIndex property.

Calls GetImageList to get the Images for the TMenu instance that owns the menu item, or the SubImages from the Parent menu item. AValue indicates the position in the image list used as the property value.

If an image list could not be located, no additional actions are performed in the method. Otherwise, an existing value in Bitmap is freed and the UpdateWSIcon method is called to notify the widgetset class of the change to the property value. MenuChanged is called to signal the OnChange event handler (when assigned). The menu item hierarchy is not rebuilt.

New value for the property. Ensures that the menu item is parented by the specified menu or menu item.

SetParentComponent is an overridden method used to ensure that the menu item is parented by the menu or menu item specified in AValue. SetParentComponent re-implements the method introduced in the ancestor class, and does not call the inherited method.

When Parent has been assigned, its Remove method is called to delete the current class instance from its Items.

When AValue has been assigned, the value is examined to determine if the new parent is a TMenu or a TMenuItem instance. If it is a TMenu instance, the current class instance is added to its Items property. If it is a TMenuItem instance, its Add method is called to append the current class instance to its Items property.

An Exception is raised if AValue is derived from any class type other than TMenu or TMenuItem. The current class instance is not re-parented when AValue contains Nil.

TComponent Menu or menu item used as the parent for the current class instance. Sets the value for the ShortCut property. New value for the property. Sets the value for the SetShortCutKey2 property. New value for the property. Sets the value for the Visible property.

When the new property value is True, a valid Handle is needed for both the menu item and its Parent (when assigned). HandleNeeded is called to allocate a handle if it does not already exist.

The widgetset class is notified of a change to the property value.

When the new property value is False, the Handle is freed by calling the DestroyHandle method.

When MergedParent has been assigned, its InvalidateMergedItems method is called to free the MergedItems for the menu item.

New value for the property. Updates the widgetset class with the values in HasIcon and Bitmap.

UpdateWSIcon is a method used to update the widgetset class to reflect the values from HasIcon and the Bitmap property. HasIcon returns True when a bitmap is available and in use for the menu item. Bitmap contains the image displayed for the menu item, and may be Nil when HasIcon returns False.

UpdateWSIcon requires a valid Handle for the menu item. No actions are performed in the method when Handle has not been allocated for the menu item.

UpdateWSIcon is called when a value is assigned to the Bitmap or ImageIndex property, and from the UpdateImage method.

ImageListChange - change the image list if commanded by the Sender. Object for the event notification. Maintains a link to the action for the menu item. Member used to store style flags for the component. Constructor for the class instance.

Create is the overridden constructor for TMenuItem, and calls the inherited method on entry. Create sets the default values for properties, and allocates resources needed for the internal TChangeLink instance used in the class instance.

TComponent.Create Owner of the class instance. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that resources allocated for the class instance are freed. This includes freeing the Bitmap, Handle, and any Items or Merged items for the menu item. It also removes itself from the Items for the Parent menu or menu item. Destroy calls the inherited destructor prior to exit.

TComponent.Destroy Find the identity given menu item (named in ACaption).

Find is a TMenuItem function used to locate the menu item in Items with the caption specified in the ACaption argument. Find calls IndexOfCaption to get the ordinal position in Items for the specified menu item. If a menu item with the given caption is not found, the return value is Nil.

Caption for the menu item to locate in the method. Gets an enumerator for the child menu Items in the class instance. TMenuItemEnumerator instance for the Items in the class. Gets an image list with the available bitmaps for the menu item.

GetImageList is an overloaded method used to get the list of available images for the menu item. The images are retrieved from an ancestor menu item or the menu which contains the menu item.

AImages is an output variable with the TCustomImageList which contains the available images.

AImagesWidth is an output variable with the width for the bitmaps in the AImages argument.

When Parent has been assigned, the SubMenuImages property in an ancestor menu item is copied into the image list. The Width in the image list is used in the aImagesWidth argument.

When Parent has not been assigned, GetParentMenu is called to get the menu which contains the menu item. Its Images property is copied into the image list. The Width in the image list is used in the aImagesWidth argument.

The TCustomImageList instance is Nil (unassigned) if neither SubMenuImages nor Images can be retrieved for the menu item.

Use the ImageIndex property to specify which image is used for the menu item. Use Bitmap to access the image displayed for the menu item.

GetImageList is called when the value for the Bitmap property is read. The image list provides an image resolution with the image for the Bitmap property. It is also called from the HasIcon and GetIconSize methods.

TCustomImageList with the bitmaps available for the menu item. Output variable with the images available for the menu item. Output variable with the width for the images in AImages. Gets the menu for the Parent component when available.

Overridden to ensure that the TMenu instance for the Parent menu item is used (when assigned). If not assigned, the value in Parent is returned. GetParentComponent does not call the inherited method.

TComponent.GetParentComponent Parent menu item or menu for the current class instance. Gets the parent menu to which this menu item belongs.

GetParentMenu is a TMenu function used to get the menu where the menu item or its Parent menu item is located. GetParentMenu visits each of the Parent menu items. When an item is located without an assigned Parent, its Menu property is used as the return value for the method. The return value is Nil if all menu items in the hierarchy have a Parent menu item.

GetParentMenu is used in methods like GetIsRightToLeft, GetImageList, DoDrawItem, and DoMeasureItem.

Gets the parent menu to which this menu item belongs taking a merged menu into account. Determines whether right-to-left display is enabled for the menu item.

Calls GetParentMenu to get the menu which contains the menu item. The return value is False if a parent menu is not found for the menu item, or the BiDiMode in the menu is set to bdLeftToRight.

True when the menu item has a parent menu with a BiDiMode other than bdLeftToRight. Indicates whether a Handle has been allocated for the menu item. True when Handle has a non-zero value. True when a bitmap is configured and available for the menu item.

HasIcon is a Boolean function which indicates if a Bitmap is configured and available for the menu item. The menu item is configured to display a bitmap using the GlyphShowMode and ImageIndex properties, or by assigning a TBitmap value to the Bitmap property.

The return value is False for the following conditions:

GlyphShowMode is set to gsmNever.
GlyphShowMode is set to gsmApplication and TApplication.ShowMenuGlyphs is set to sbgNever.
GlyphShowMode is set to gsmSystem and SystemShowGlyphMenus returns False.
An image list is not available or ImageIndex contains an invalid index.
Bitmap has an empty image.

TApplication.ShowMenuGlyphs True when a bitmap is configured and available for the menu item. Indicates if the menu item has a parent menu item.

Returns True if the menu item has a parent responsible for streaming. Overridden to check for an assigned value in the Parent property. Does not call the inherited method.

TComponent.HasParent True when a Parent menu item has been assigned for the menu item. Updates the Action in the ActionLink for the menu item.

Calls the Update method in ActionLink (when assigned).

TBasicAction.Update IntfDoSelect - perform the selection using the interface.

Forces the Application to display the Hint for the menu item.

Gets the ordinal position in Items for the specified menu item.

Calls the IndexOf method in Items to locate the menu item specified in Item. The return value is -1 if Items has not been assigned in the class instance.

Ordinal position for the specified menu item, or -1 when not found. Menu item to locate in the Items property. Gets the ordinal position in Items for the menu item with the specified Caption.

IndexOfCaption visits the TMenuItem instances in the Items property to locate the menu item with the Caption specified in ACaption. Case is significant when comparing the value in ACaption to the menu item(s).

The return value contains the ordinal position in Items for the menu item with the specified caption, or -1 when a menu item is not found.

Ordinal position for the menu item with the given caption, or -1 when not found. Caption text to locate in the child Items for the menu item. Frees the MergedItems property for the menu item. Gets the ordinal position for the specified menu item in the list of visible menu items.

VisibleIndexOf is an Integer function used to get the ordinal position for the specified menu item in the list of visible menu items.

Item contains the TMenuItem instance to locate in the MergedItems property. No actions are performed in the method if the Visible property in Item is set to False, and the return value is set to -1.

VisibleIndexOf visits each of the visible items in MergedItems to locate the value specified in Item. The return value is set to the position in VisibleItems where the menu item was found. The return value is -1 if Item is not found in the VisibleItems for the MergedItems property.

Ordinal position in the visible Mergeditems for the specified menu item. Menu item to locate in the visible MergedItems. Adds item(s) to the menu item.

Add is an overloaded method used to add one or more items to the menu. Variants are provided that allow a single TMenuItem instance to be added, or an array of TMenuItem instances.

The single menu item variant calls Insert to store the value in Item at the position in the Count property. Insert will increment the value in Count.

The array variant iterates over each of the elements in the array, and calls Add to store the menu instances in Items.

Be aware that adding an child menu item that is a Separator may crash the application on non-Windows platforms. Use the AddSeparator method instead.

Does this admonition still apply today? By non-Windows do we actually mean Mac OS Carbon? Menu item added to the child Items. Array of menu items added to the child Items. Adds a separator line to the child menu items.

AddSeparator is a method used to add a separator line to the child menu Items. AddSeparator creates a new TMenuItem instance, and sets its Caption to the value in the cLineCaption constant. The Add method is called to append the menu item to the Items property.

Performs actions needed when the menu item is clicked.

Click is method used to perform actions needed when the menu item is clicked, or when the DoClick method is called. No actions are performed in the method if the menu item is not Enabled.

Click signals the OnMenuPopupHandler event handler variable (when assigned).

Properties in the TMenuItem instance are examined to determine whether an Action is used to execute the menu item, or if its OnClick event handler is signalled for the purpose. An action is used when the ActionLink property has been assigned for the class instance. The action is not executed if the menu item is clicked at design-time.

Otherwise, the OnClick event handler is used. When AutoCheck is enabled, the value for the Checked property is toggled when the menu item has not been configured as a RadioItem. AutoCheck is not performed at design-time. The OnClick event handler is signalled to perform the menu item.

Deletes the child menu item at the specified position in Items.

Delete is a method used to delete the menu item in Items at the position specified in Index. Index must be in the range 0..Count-1. An EMenuError exception is raised when Index is not in the required range, when Items has not been assigned for the class instance, or when the menu item has already been freed.

Delete calls the DestroyHandle method for the TMenuItem instance to free the Handle for the menu item, and sets its Parent property to Nil. The Delete method in Items is called to free the menu item. The MenuChanged method is called to signal the OnChange event handler (when assigned) and to optionally rebuild the child menu items.

Ordinal position for the menu item removed in the method. Ensures that a valid Handle exists for the menu item.

Checks the value in Handle to ensure that a handle has been allocated for the menu item. Calls CreateHandle when Handle is set to 0 (unassigned).

Insert a new item at the location marked by Index. Ordinal position in Items where the menu item is inserted. Menu item inserted in Items. Re-creates the Handle for the menu item.

RecreateHandle is a method used to destroy and re-create the Handle for the menu item. It is called when the type or the context for a TMenuItem instance is changed.

Removes the specified menu item from its Parent.

Remove is a method used to locate and delete the menu item specified in Item. Remove call IndexOf to get the position in Items where the menu item is stored. An EMenuError exception is raised if the menu item in Item is not found in the Items property.

Remove calls the Delete method to free the handle and the menu item instance at the required position.

Menu item removed in the method. Updates the image associated with the menu item, particularly if it has changed. Update the images for the menu item and its child items. Indicates if the menu item is configured as a check box or a radio button item. True if the menu item is configured as a separator line. True if the menu item has a main menu bar as its parent. True if the menu item has a main menu bar as its parent. Removes all child menu Items in the class instance.

Clear visits each of the TMenuItem instances in Items (in reverse order) and calls their Free method. Clear does not change other property values in the class instance.

Indicates whether a TBitmap instance has been assigned to the Bitmap property. True if a TBitmap instance has been assigned to the Bitmap property. Gets the size for the icon (glyph) used on the menu item.

The return value is a TPoint instance with the Width and Height for the glyph displayed on the menu item.

Calls HasIcon to determine if GlyphShowMode allows (or requires) a glyph to be displayed for the menu item, and whether image(s) are available. When HasIcon returns True, the images available for the menu item are retrieved to get the Width and Height required for the device context in ADC. If an image list is not available, the Width and Height in Bitmap are used in the return value.

TPoint instance with the width and height for the glyph displayed on the menu item. Device context used to get the display density (PPI) for the glyph images. Adds an OnDestroy event handler to the handlers for the menu item. Routine added to the handlers for the menu item. True if the handler is the first in the list of OnDestroy handlers. Removes the specified OnDestroy event handler from the list of handlers for the menu item. Routine removed from the list of handlers in the menu item. Adds an event handler routine of the specified type to the menu item. Identifies the type of handler added in the method. Event handler routine added to the list of handlers. True if the handler is the first for the given type. Removes the event handler routine from the specified handler type. Contains a menu item and its children merged into the current class instance.

Merged is a read-only TMenuItem property with the menu item merged into the Items for the current class instance.

Menu item where the current class instance was merged.

MergedWith is a read-only TMenuItem property with the menu item where the current class instance was merged.

Number of child menu items stored in the Items property.

Count is a read-only Integer property with the number of child menu items stored in the Items property. The property value is redirected to the Count property in Items. The property value is 0 when Items has not been assigned (contains Nil).

TList.Count Handle for the menu item allocated in the widgetset class.

Handle is a HMenu property with the handle for the menu item. Reading the value for the property causes the HandleNeeded method to be called to ensure that a valid handle exists for the menu item. The Handle value is assigned when the CreateHandle method in the widgetset class is called. Handle is set 0 when it has not been allocated using the widgetset class.

Provides indexed access to the child menu items for the current class instance.

Items is a read-only TMenuItem property which provides indexed access to the child menu items for the current class instance. An internal TList member is used to store the TMenuItem property values.

Index contains the ordinal position in the list for the TMenuItem instance returned as the property value.

An EMenuError is raised when accessing a value in the property and the Items list has not been assigned. The exception message reports an "Index Out of Bounds" condition.

TMenuItem instances are added and removed from the internal list using the Add, AddSeparator, Delete, Clear, and Remove methods.

Use the IndexOf, IndexOfCaption, and Find methods to locate a particular menu item in the Items property.

Ordinal position in the list for the property value. Returns the visible and invisible child items taking the merged menu into account. Ordinal position for the menu item in its Parent.

MenuIndex is an Integer property with the ordinal position for the menu item in its Parent.

The property value is retrieved by calling the IndexOf method in Parent using the current class instance as an argument. The property value is -1 if Parent has not been assigned. Changing the value for the property causes the menu item to be relocated in Parent to the position indicated in the new property value.

Menu where the menu item is displayed.

Menu is a read-only TMenu property with the menu which owns the menu item or its ancestors.

The parent menu item for the class instance. The parent menu item for the class instance taking the merged menu into account. Numeric command for the menu item as assigned in the widgetset class. MenuVisibleIndex - the index value of the visible menu. Generates information about the menu item and its child Items for use in the debugger. Action - the default action associated with this Menu Item. Indicates whether a check mark is automatically drawn when the menu item is selected. The caption text displayed for the menu item.

Caption is a TTranslateString property which contains the text displayed for the menu item. Caption can include a prefixed character which is used as the accelerator key for the menu item. Use the value in cHotkeyPrefix to identify the character used as the ShortCut key for the menu item.

Changing the value in the property causes the widgetset class to be notified when the Handle has been allocated and the Parent property is assigned.

Indicates whether a check mark is displayed beside the menu item. Indicates if the menu item is the default selection. When Default is set to True, the menu item is normally displayed in boldface and can be executed by pressing the Enter key. Indicates if the menu item can be selected and executed. When Enabled is set to False, the menu item is normally displayed using a "greyed" style. Bitmap image (glyph) displayed for the menu item.

Bitmap is a TBitmap property which contains the bitmap image displayed as a glyph for the menu item.

The value in Bitmap can be set by assigning a TBitmap instance to the property. It may also be retrieved from images in the parent menu (or an Action list) using the ImageIndex property. The assignment mechanisms are not used at the same time. A value assigned directly to the Bitmap property overrides the setting in ImageIndex.

Changing the value in Bitmap causes the UpdateWSIcon method to be called to post the change to the widgetset class. The MenuChanged method is called to signal the OnChange event handler (when assigned).

Use GlyphShowMode to control use the visibility of the glyph image for the menu item.

GroupIndex: the sequence number in a group of mutually exclusive RadioItem choices.

GroupIndex is a Byte property which indicates a group for related menu items. GroupIndex is used in menu items displayed as radio buttons. The menu items with their RadioItem property set and the same value in GroupIndex are in the same mutually exclusive radio button display; only one radio button item can be Checked at any given time.

Changing the value for the property causes other radio button menu items with the same GroupIndex to be un-checked when the current item is Checked. If the Handle has been allocated for the menu item, the RegroupMenuItem routine in the LCL interface is called.

The default value for the property is 0, and indicates that a group index value has not been assigned.

Indicates the display behavior for the glyph (or Bitmap) on the menu item.

GlyphShowMode is a TGlyphShowMode property which indicates the display behavior for the glyph (or Bitmap) on the menu item. The default value for the property is gsmApplication, and causes the value in Application.ShowMenuGlyphs to be used to determine the visibility for a glyph on the menu item.

See TGlyphShowMode for more information about values for the property and their meanings.

Index to the context-sensitive help string used for the menu item (context ID). Hint: shown in a statusbar if the main window has one and if the statusbar has AutoHint = True. Ordinal position in the list of images for the glyph displayed on the menu item. Indicates if the menu item is displayed as a radio button. Indicates if the menu item caption is displayed with right-justification.

The default value for the property is False, and causes the menu item caption to use left-justification.

Accelerator key sequence to be used in selecting this menu item.

ShortCut - the quick key sequence to be used in selecting this menu item

If you select this property in the Object Inspector, a list-box will appear with choices for various key-combinations to be used. The chosen key-sequence will be displayed, at run-time, on the menu drop-down next to the caption for the menu item.

Secondary shortcut (accelerator) key for the menu item. ShowAlwaysCheckable - if True, Item is always shown as checkable. SubMenuImages - will images be shown for sub-menu items as well as the main item? Width for the bitmaps in the SubMenuImages property.

SubMenuImagesWidth is an Integer property with the width for the bitmaps in the SubMenuImages property. The default value for the property is 0 (zero), and indicates that an explicit value has not been assigned for the property. This causes the width from the SubMenuImages image list to be used.

Indicates whether the menu item is visible (or hidden). Event handler signalled to perform the actions needed when the menu item is selected. TBasicAction Event handler signalled to draw the menu item.

OnDrawItem is a TMenuDrawItemEvent property with the event handler signalled to draw the menu item.

Event handler signalled to get the Width and Height for the menu item.

OnMeasureItem is a TMenuMeasureItemEvent property with the event handler signalled to calculate the width and height for the menu item on the specified Canvas.

Does the rectangle argument encompass the entire menu item or just its caption? TMenuItemClass - class of TMenuItem. TFindItemKind - enumerated type for kind of item in search operation: a command, a handle or a shortcut.

TFindItemKind is an enumeration type with values that indicate the property examined to find a menu item with a specified value. A value from the enumeration is passed as an argument to the TMenu.FindItem method.

Checks the Command property in a menu item. Checks the Handle property in a menu item. Checks the ShortCut property in a menu item. TMenu - a menu appearing in a form. Base class for TMainMenu or TPopupMenu.

TMenu is the base class for all menus.

The class definition contains very few public or published properties or methods accessible to the application programmer, but contains the entry Items which points to the Menu Items that appear in the menu displays.

How To Use Menus Handles the CM_PARENTBIDIMODECHANGED control message.

See TCustomForm.CMBiDiModeChanged for more information.

Control message examined in the method. Handles the CM_APPSHOWMENUGLYPHCHANGED message for the menu. Control message examined in the method. Implements the storage specifier for the BiDiMode property. True when BiDiMode contains a value other than the default. Implements the OnChange event handler used in the Images property. Object for the event notification. Sets the value for the BiDiMode property. New value for the property. Sets the value for the Images property. New value for the property. Sets the value for the ImagesWidth property. New value for the property. Sets the value for the Parent property. New value for the property. Sets the value for the Parent BiDiMode property. New value for the property. Performs actions needed when the value in BiDiMode has been changed.

BidiModeChanged is a method used to performs actions needed when the value in the BiDiMode property has been changed. If the Handle has been allocated for the menu, the widgetset class is notified of the new property values.

Creates the Handle for the menu.

CreateHandle calls the corresponding method in the widgetset class. It also calls CheckChildHandles to validate and update handles for merged menu Items. CreateHandle is used in the implementation of the HandleNeeded method.

Performs actions needed when the specified menu item has been changed.

DoChange is a method used to perform actions need when the menu item in Source has been changed. The Rebuild parameter indicates that the hierarchy of child menu items in Source should be reconstructed.

DoChange signals the OnChange event handler (when assigned) using the menu instance, Source, and Rebuild as arguments.

DoChange is called from the MenuChanged method.

Menu item where the change occurred. True to rebuild the child menu items. Gets the value for the Handle property.

Calls HandleNeeded to create the handle if it has not been allocated in the widgetset class.

Value for the property. Calls the specified process for the Items in the menu control.

Calls the processing routine in Proc for each of the Items in the control. This is a helper function used during LCL component streaming.

TComponent Process called for the child items. Not used in the method. Implements the OnChange event handler assigned to menu items in the menu.

Calls the DoChange method using Source and Rebuild as arguments. No actions are performed in the method during LCL component streaming, or when the component is being freed.

Object for the event notification. Menu item for the change notification. True to rebuild the visible child menu items in Source. Copies property values from the class instance to the specified persistent object.

AssignTo is an overridden method in TMenu which re-implements the method from the ancestor class. AssignTo copies property values from the current class instance to the persistent object in the Dest argument.

When Dest is a TMenu instance, an implementation routine is called to copy the property value. If Dest is not derived from TMenu (or Nil), the inherited method (which raises an EConvertError exception) is called.

TPersistent.Assign Persistent object where the property values are stored. Handles a notification when a component is added to or removed from the control.

Notification is an overridden method in TMenu. It calls the inherited method on entry, and sets the member for the Images property to Nil when it is removed from the control. An exception is raised if the Items property is removed from the control.

TComponent.Notification Performs action when ParentBiDiMode has been changed.

Performs actions needed when the value in ParentBiDiMode has been changed. When Parent BiDiMode is set to True, ParentBidiModeChanged ensures the BiDiMode from the TCustomForm instance in AOwner is used in the menu.

ParentBidiModeChanged is called from the Create constructor, and when a new value is assigned to the ParentBiDiMode property.

Owner of the menu instance with the BiDiMode value applied to the menu. Sets the order for the menu item specified in Child.

SetChildOrder is an overridden method used to set the order for the specified child in the menu instance. It ensures that the value in Child is cast to a TMenuItem instance before assigning the value in Order to its MenuIndex property.

TComponent UpdateItems has an empty implementation in the current LCL version. Event handler signalled when a menu item in Items has been changed. Stores component style flags. Constructor for the class instance.

Create is the constructor for TMenu, and creates menu items and links, sets some defaults then calls inherited Create.

TComponent.Create Owner of the class instance. Destructor for the class instance.

Destroy is the destructor for TMenu, and frees items and links, then calls inherited Destroy.

TComponent.Destroy Frees the Handles for the items on the menu.

DestroyHandle calls the DestroyHandle method in Items to free all of the handles for the menu items.

Gets the menu item with the specified value in a given property.

FindItem is a TMenuItem function used to locate a menu item which has the value specified in AValue in a given property. The property examined for the value is specified in the Kind argument.

FindItem searches the menu items stored in the Items property to locate the specified value. The return value is Nil when a menu item is not found with the required value, or a Nil value is found in Items.

FindItem is used to implement methods like GetHelpContext, IsShortcut, and DispatchCommand.

Menu item which matches the find criteria, or Nil when not found. Value to locate in the property indicated by Kind. Identifies the property examined for the specified value. Gets the numeric help context for the menu item with the specified handle or command. Menu item with the specified value, or Nil when not found. Command or Handle to locate in the menu items for the menu. True to search Command values, False to search Handle values. Indicates if the specified control message contains a shortcut (accelerator) key used in the menu.

Is Shortcut is a Boolean function used to determine if the control message in Message contains a shortcut (accelerator) key used in the menu. It converts the CharCode and KeyData in Message to a shortcut value by calling the ShortCut routine.

The FindItem method is called to locate the menu item with the value in its Shortcut property. The ShortCutHandled property is updated to indicate whether the shortcut value exists in Items.

IsShortCut checks the Parent for the menu item to determine if the shortcut key is handled in the parent menu item. The InitiateAction and Click methods for the menu item are called if the parent handles the shortcut value.

True when the message matches a menu item shortcut in Items. Control message examined in the method. Returns True if a Handle has been allocated for the menu. True if a Handle has been allocated for the menu. Indicates if Right-to-Left text display is used in the menu.

IsRightToLeft is a Boolean function which indicates if Right-to-Left text display is used in the menu. The return value is True when the BiDiMode property contains a value other than bdLeftToRight.

UseRightToLeftAlignment - returns True if Right-Left alignment is being used. Indicates if right-to-left reading is used for the menu.

UseRightToLeftReading is a Boolean function which indicates if the menu uses Right-to-Left reading for its values. UseRightToLeftReading is used in the widgetset class to enable bi-directional text display for languages like Arabic and Hebrew.

The return value is True when the BiDiMode property is set to a value other than bdLeftToRight.

Use the UseRightToLeftAlignment property to set the alignment for text values in the menu.

TBiDiMode Ensures that a Handle has been allocated for the menu.

Calls CreateHandle if the Handle has not been allocated for the menu.

Executes the menu item with the specified numeric Command value. True if a menu item with the specified command was found and executed. Numeric command value to locate in the menu items for the menu. Handle for the menu allocated in the widgetset class.

Handle is a read-only HMenu property with the handle for the menu. The Handle value is allocated by the widgetset class when the CreateHandle method is called. Use DestroyHandle to free the Handle for the menu.

Parent component for the menu.

Parent is a TComponent property with the component associated with the menu instance. Setting Parent to Nil when a handle has been assigned for Items in the menu causes the DestroyHandle method to be called.

Indicates whether the shortcut key for a menu item is used in the menu. Indicates whether Bi-directional text mode is implemented allowing use with languages like Arabic or Hebrew. The BiDiMode value for the parent component. Contains the menu items displayed on the menu.

Items is a read-only TMenuItem property with the menu items included in the menu. Values in Items can be maintained at design-time using the menu editor in the Lazarus IDE, or created and configured at run-time.

The image list with bitmaps used as glyphs for the menu items.

Images is a TCustomImageList property which contains the bitmap images displayed as glyphs for the Items on the menu. Populate an image list and assign it to the property prior to setting the ImageIndex and GlyphShowMode for the individual TMenuItem instances on the menu. As an alternative, glyphs can assigned directly to the Bitmap property in each TMenuItem instance.

Setting a new value for the property causes the image change link and free notification to be removed and/or added as needed. The UpdateImages method in Items is called to validate the image(s) and to notify the widgetset class of change(s) to the property value(s).

TCustomImageList Width for the bitmaps in the Images property.

ImagesWidth is an Integer property with the width needed for bitmaps in the Images property. The default value for the property is 0 (zero), and indicates that the width in the Images property is used.

Setting a new value for the property causes the UpdateImages method in Items to be called.

Indicates if the menu items are drawn using the OnDrawItem event handler.

OwnerDraw is a Boolean property which indicates if the menu items are drawn using the OnDrawItem event handler. The default value for the property is False.

OwnerDraw is used when the widgetset class renders the menu. If OwnerDraw is False, the default drawing routines for the platform are used to draw the menu control. Otherwise, the OnMeasureItem and OnDrawItem event handlers are signalled for the purpose.

Event handler signalled to draw a menu item on the menu. Event handler signalled to get the width and height for a menu item on the menu. TMainMenu - the Main Menu that appears at the top of most windows.

TMainMenu - the Main Menu that appears at the top of most windows; form designers can customize by choosing various menu items.

To see the Menu Editor, right-click on the Main Menu icon on your Form.

How To Use Menus Performs actions needed when a menu item has been changed.

Calls MenuChanged when a menu item has been changed in the widgetset class.

Implements the OnChange event handler used for menu items in the class instance.

MenuChanged is an overridden method in TMainMenu. It ensures that the CM_MENUCHANGED control message is forwarded to the WindowHandle (when assigned) where the menu is displayed. MenuChanged calls the inherited method prior to exit to signal the OnChange event handler (when assigned).

Object of the change notification. Menu item for the change notification. True to rebuild the child menu items for the menu. Constructor for the class instance.

Create is the overridden constructor in TMainMenu.

Create ensures that the internal component style flags are set for the main menu instance. It also sets the WindowHandle to 0 (zero) to indicate that the display window has not been assigned for the menu instance.

Create calls the inherited constructor prior to exiting from the method.

TMenu.Create Merges menu items from the specified main menu instance.

Merge is a method used to merge the menu items from the specified Menu into the Items for the current class instance. When Menu contains a non-Nil value, the MergeWith method in Items is called using the Items in the current class instance as the target. When Menu has not been assigned, the MergeWith method in Items is called using Nil as the target.

Use Unmerge to remove merge menu items from a specified menu instance.

Main menu merged into the current class instance. Removes merged menu items for the specified menu. Menu instance with the merged items removed in the method. Height for the menu. Handle for the window where the menu is displayed. Event handler signalled when a menu item has been changed. TPopupAlignment - enumerated type to describe the position of pop-up menu relative to the pop-up coordinates.

paLeft: Positions the pop-up menu so its left corner is at the pop-up coordinate
paRight: Positions the pop-up menu menu so its right corner is at the pop-up coordinate
paCenter: Centers the pop-up menu around the pop-up coordinate

TTrackButton - enumerated type described which mouse buttons can be used to activate (click) menu items.

tbRightButton: Both left and right buttons are used to activate a menu item
tbLeftButton: Only the left button is used to activate a menu item

TPopupMenu - a menu panel that pops up on the desktop when the right mouse button is clicked.

TPopupMenu : a menu panel that pops up on the desktop when the right mouse button is clicked.

Inherits all the properties of TMenu (including the properties of TMenuItem), but has some new properties (procedure PopUp and procedure Close) that define its behavior when actually invoked.

PopupPoint defines the position of the pop-up menu, usually at the current cursor position.

To use a pop-up menu, first create it with the MenuEditor. Then with the Object Inspector for the control that needs to use the Pop-up, select the property named PopupMenu, and a list box will appear with the names of the available Menus - choose the Pop-up name you want.

How To Use Menus Performs actions needed to display the pop-up menu. Object for the event notification. Performs actions needed when the pop-up menu is closed. Constructor for the class instance.

Create is the constructor for TPopupMenu, and calls the inherited Create, sets style to PopupMenu, sets AutoPopup to True.

TMenu.Create Owner of the class instance. Destructor for the class instance.

Destroy is the destructor for TPopupMenu. It closes the display window for the pop-up menu and calls the inherited Destroy method.

TMenu.Destroy Displays the pop-up menu.

PopUp is an overloaded method used to display the pop-up menu. An overloaded variant is provided which includes X and Y coordinates where the pop-up menu is displayed. The parameterless version calls the overloaded variant using the current position for the mouse pointer in the X and Y arguments.

No actions are performed in the method if a value has already been assigned to the ActivePopupMenu variable. DoPopUp is called to signal the OnPopup event handler (when assigned). No additional actions are performed in the method if menu items have not been defined in the Items property.

PopUp sets the value in ActivePopupMenu to the current class instance. The InitiateActions method is called for the menu Items to ensure that the ActionLink for the component is updated. The handles for the menu and its sub-items are recreated, and the OnMenuPopupHandler event handler is signalled (when assigned).

PopUpMenu calls the corresponding method in the widgetset class prior to exiting from the method.

Horizontal coordinate where the pop-up menu is displayed. Vertical coordinate where the pop-up menu is displayed. Component to which the pop-up menu is attached.

PopupComponent is a TComponent property which contains a reference to the component which implements the pop-up menu. It allows properties and methods in the implementor to be accessed from the menu items for the pop-up menu. Its value is must be assigned in code where the pop-up menu is created and configured.

TPoint instance with the coordinates where the pop-up menu is displayed.

PopupPoint is a read-only TPoint property which contains the coordinates where the pop-up menu is displayed. The value in PopupPoint is updated when the PopUp method is called.

Closes the pop-up menu when it is active.

Close is a method used to close the pop-up menu when it is active. When ActivePopupMenu contains the current class instance, the DoClose method is called to signal the OnClose event handler (when assigned). ActivePopupMenu is set to Nil to indicate that the pop-up menu is no longer active.

No actions are performed in the method if ActivePopupMenu does not refer to the current class instance.

Determines the position of pop-up menu relative to the pop-up coordinate.

Alignment is a TPopupAlignment property which indicates the alignment of the pop-up menu relative to the mouse coordinates in PopupPoint. The default value for the property is paLeft and causes the menu to be displayed to the left of the mouse coordinates passed to the PopUp method.

Indicates if the pop-up is displayed when the mouse hovers over the component for the pop-up menu.

AutoPopUp determines whether the pop-menu is automatically displayed when the mouse is hovered over the PopupComponent for the menu. Its value can be used in the implementing component to determine whether the PopUp method should be called. The default value for the property is True.

Help context for the pop-up menu. Identifies the mouse button which activated the pop-up menu.

TrackButton is a TTrackButton property which contains the mouse button which can be used to activate the pop-up menu. The default value for the property is tbRightButton.

TrackButton is used in widgetset classes when they are notified of the mouse event for the menu and perform the actions needed for the platform.

Event handler signalled to display the pop-up menu.

OnPopUp is signalled from DoPopUp when the PopUp method is executed. The Sender argument contains the TPopUpMenu instance for the notification, and occurs before the handles for menu items are recreated and the widgetset class is used to display the pop-up menu. It can be used to alter the menu items for the pop-up menu based on context.

Event handler signalled when the pop-up menu is closed.

You can delete menu items here. But if you delete the clicked menu item on OnClose the OnClick will not follow under Windows.

Converts a virtual key code and modifier to a shortcut value.

Calls the KeyToShortCut routine in LCLType get the return value for the function.

KeyToShortCut TShortCut type with the value for the key and modifier. Virtual key code for the shortcut value. Shift, Alt, or Ctrl modifier for the shortcut value. Converts a shortcut value to a virtual key code and modifier. Shortcut value converted to a Key code and Shift modifier. Virtual key code for the shortcut value. Shift, Ctrl or Alt modifier for the shortcut value. Unit global variable with the event handler signalled when a menu item is clicked at design-time. Unit global variable which represents the active pop-up menu.

The value for the variable is updated when the PopUp or Close methods are called for a TPopUpMenu instance. It is set to the TPopUpMenu instance in the Popup method if an existing pop-up menu is not already active. It is set to Nil when the Close method is called for the pop-up menu.

Unit global variable with the event handler signalled when a pop-up menu is displayed.

OnMenuPopupHandler is a TNotifyEvent variable which contains the global routine executed when when a pop-up menu is displayed. It is signalled (when assigned) from the Popup method in a TPopUpMenu instance, or from the Click method in a TMenuItem instance. The MenuPopupHandler method in Application is assigned to the variable (by default) during application start up. It is set to Nil when an application is shut down.

TApplication.MenuPopupHandler Creates and configures a new menu instance with the specified menu items.

NewMenu is a TMainMenu function used to create and configure a new menu instance using the values passed in the arguments to the routine. The return value is a TMainMenu instance created using the component in Owner as the owner for the class instance. The value in AName is used in the Name property for the new menu instance.

NewMenu calls an implementation routine to add the menu Items to the new menu instance. It ensures that the Owner for the menu items are updated to reflect the Owner for the new menu instance, and that they are inserted into the Owner component.

TMainMenu instance created in the routine. Component which owns the new menu instance. Name for the new menu instance. Array with the menu items for the new menu instance. Creates and configures a new pop-up menu with the specified menu items.

NewPopupMenu is a TPopUpMenu function used to create and configure a new pop-menu with the values specified in the arguments to the routine. The return value is created using the component in Owner as the owner of the class instance. The value in AName is used in the Name property for the new menu instance. AutoPopUp and Alignment are assigned to the corresponding properties in the new pop-up menu instance.

NewPopupMenu calls an implementation routine to add the menu Items to the new menu instance. It ensures that the Owner for the menu items are updated to reflect the Owner for the new menu instance, and that they are inserted into the Owner component.

TPopUpMenu instance created in the routine. Component which owns the new pop-up menu instance. Name for the new pop-up menu instance. Alignment relative to the mouse pointer for the pop-up menu instance. True if the pop-up menu is automatically displayed when the mouse is hovered over the component. Array with the menu items for the new pop-up menu instance. Creates and configures a new sub-menu with the specified child menu items.

NewSubMenu is a TMenuItem function used to create a sub-menu using the values specified in the arguments to the routine. The return value contains the TMenuItem instance created to represent the sub-menu. It uses the value in aCaption as the caption text for the menu item, and AName contains the name for the sub-menu.

The menu item is created using Nil as the owner of the class instance; it must be added or inserted into the Items for the desired menu instance. Each of the menu Items is added to the class instance, and the remaining arguments are assigned to the corresponding properties for the sub-menu (menu item).

TMenuItem with the sub-menu created in the routine. Caption text displayed for the sub-menu. Help context for the sub-menu. Name for the menu item representing the sub-menu. Array of menu items for the new sub-menu. True if the menu item for the sub-menu is enabled. Creates and configures a new menu item instance.

NewItem is a TMenuItem function used to create and configure a new menu item instance using the values passed in the arguments to the routine. The TMenuItem instance is created with its Owner property set to Nil. Values passed in the parameters are assigned to the corresponding properties in the TMenuItem instance in the return value.

Other property values for the menu item can be assigned in the calling routine. Use the Add or Insert method in the desired menu or sub menu to store the new menu item instance.

Menu item instance created in the routine. Caption text for the new menu item. Short cut for the new menu item. True if the new menu item is checked. True if the new menu item is enabled. OnClick handler for the new menu item. Help context for the new menu item. Name assigned for the new menu item. Creates and configures a menu item displayed as a separator line.

Uses the value in cLineCaption as the caption text for the menu item.

TMenuItem instance created in the routine. Removes the hot key (accelerator) prefix from the specified text. Text value after removing the hotkey prefix. Text examined and updated in the routine. Registers components for use in the Lazarus IDE.

The following components are added to the Lazarus IDE component palette:

Standard Tab

TMainMenu
TPopupMenu

Registered but not displayed:

TMenuItem

Prefix used in a menu item caption to identify a hot key (accelerator). Caption used for a menu item displayed as a separator line. Not used in the current LCL implementation. Contains characters that can be used as accelerator keys in menus and menu items.

Not used in the current LCL implementation.

HowToUseMenus - hints for creating Menus for your Forms.

TMainMenu is the Main Menu that appears at the top of most forms; form designers can customize by choosing various menu items. TPopupMenu is a menu window that pops up with pertinent, usually context-sensitive, details and choices when the right mouse button is clicked near a control.

Main Menu is a non-visible component : that is, if the icon is selected from the Component Palette and placed on the Form, it will not appear at Run-time. Instead, a Menu bar with a structure defined by the Menu Editor will appear. Pop-up menus, placed on the form by selecting the icon from the Component Palette, do not appear at all unless the right mouse button is clicked on a control that owns such a menu.

To see the Menu Editor, right-click on the Main Menu or Pop-up Menu icon on your Form. A pop-up box appears, that invites you to enter items into the Menu bar.

An Edit box is displayed, containing a Button labeled New Item1. If you right-click on that box, a pop-up menu is displayed that allows you to add a new item before or after (along the same level) or create a sub-menu with the opportunity to add further items below (or above) the new item in a downward column.

Any or all of the MenuItems that you add can be configured using the Object Inspector.

At the least you should give each item a Caption which will appear on the Menu Bar (you may also wish to give it a more meaningful Name). The caption should indicate the activity to be selected, such as "File Open" or "Close", "Run" or "Quit"

If you want a particular letter in the Caption to be associated with a shortcut key, that letter should be preceded by an ampersand. The Menu item at run-time will appear with the shortcut letter underlined, and hitting that letter key will have the same effect as selecting the menu item. Alternatively you can choose a shortcut key sequence (such as Ctrl-C for Copy or Ctrl-V for Paste - the standard Keyboard shortcuts) with the ShortCut property of the MenuItem.

It is often helpful to use the Menu controls in conjunction with an ActionList which contains a series of standard or customized Actions. Menu Items can be linked in the Object Inspector to Actions on the list, and the same actions can be linked to Buttons, ToolBar Buttons, SpeedButtons etc. It is obviously economic of effort to re-use the same code to respond to the various events, rather than writing separate OnClick event handlers for each individual control.

By default a number of standard actions are pre-loaded from StdActns or, if DataAware controls are being used, from DBActns, and these can be chosen using the ActionList editor which appears when you right-click on the ActionList icon on the Form Designer.