From 9ced00b2eea9a8ee46f1e91456bdcaffd6ca4e9b Mon Sep 17 00:00:00 2001 From: dsiders Date: Mon, 11 Oct 2021 21:35:40 +0100 Subject: [PATCH] Docs: LCL/menus. Adds missing topic content. (cherry picked from commit a058e53864a3b30efcd877be31de8cfef6db5074) --- docs/xml/lcl/menus.xml | 218 +++++++++++++++++++++++++++++++---------- 1 file changed, 168 insertions(+), 50 deletions(-) diff --git a/docs/xml/lcl/menus.xml b/docs/xml/lcl/menus.xml index 74863f7147..d899680475 100644 --- a/docs/xml/lcl/menus.xml +++ b/docs/xml/lcl/menus.xml @@ -3112,7 +3112,7 @@ - ItemChanged - method to deal with a changed Item. + Performs actions needed when a menu item has been changed.

@@ -3341,8 +3341,28 @@ 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. @@ -3352,8 +3372,12 @@ - Component to which the pop-up menu is attached - + 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. +

+ @@ -3361,7 +3385,11 @@ 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. +

+ @@ -3369,26 +3397,53 @@ - Closes the display window for the pop-up menu. + 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. +

+ + + + + + @@ -3401,7 +3456,14 @@ 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. +

+ @@ -3409,7 +3471,11 @@ 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. +

+ @@ -3418,7 +3484,7 @@ - OnClose - event handler for closing down the pop-up. + Event handler signalled when the pop-up menu is closed.

@@ -3474,7 +3540,11 @@ 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. +

+ @@ -3482,109 +3552,157 @@ 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. - + + 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. +

+