From d07428b8d10ebb331a924b143ed752811aef377c Mon Sep 17 00:00:00 2001 From: dsiders Date: Tue, 8 Feb 2022 02:44:12 +0000 Subject: [PATCH] Docs: LCL/buttons. Adds topic for TCustomSpeedButton.Alignment added in 1f92d4fd. * Contains topic updates which depend on 4cb682f0, 0bbdfcf5, 6e245453. --- docs/xml/lcl/buttons.xml | 345 +++++++++++++++++++++++++++++++++------ 1 file changed, 293 insertions(+), 52 deletions(-) diff --git a/docs/xml/lcl/buttons.xml b/docs/xml/lcl/buttons.xml index edc56cfa72..b00e284088 100644 --- a/docs/xml/lcl/buttons.xml +++ b/docs/xml/lcl/buttons.xml @@ -585,7 +585,7 @@ GetImageIndexAndEffect is a procedure used to get the ordinal position for the image used to render the Glyph for the class instance. In addition, it returns the image resolution for the specified display density and the drawing effect for the button State.

- GetImageIndexAndEffect uses ThemeServiecs to determine if drawing effects are automatically applied to glyph images, and captures the effect in the AEffect output argument. + GetImageIndexAndEffect uses ThemeServices to determine if drawing effects are automatically applied to glyph images, and captures the effect in the AEffect output argument.

GetImageIndexAndEffect determines the image source and the ordinal position for the image used for the button glyph. ExternalImages and ExternalImageIndex are used (when assigned). The next available source is the resource name specified in LCLGlyphResourceName (when specified). Finally, the Images property is used (when assigned). When the image source has been determined, the correct image resolution for the value in APPI is selected and stored in AImageResolution. ImageIndexes is used to get the position for the image with the specified button State. @@ -2119,6 +2119,7 @@ + Gets the value for the Glyph property. @@ -2174,6 +2175,24 @@ + + Gets the value for the Transparent property. + + + + + Value for the Transparent property. + + + + Sets the value for the Alignment property. + + + + + New value for the Alignment property. + + Sets the value for the AllowAllUp property. @@ -2230,16 +2249,23 @@ - Control message passed when the button is pressed. - + Handles the Control message passed when the button is pressed. + +

+ CMButtonPressed is a method used to handle a CM_BUTTONPRESSED control message received for the control. CMButtonPressed ensures that the Down property is set to False when another speed button with the same GroupIndex is pressed. AllowAllUp is updated and the control is redrawn. +

+

+ No actions are performed in the method when the control in Message does not have the same GroupIndex value. +

+ - + TLMessage instance examined in the method. - Control message passed when the control is enabled. + Handles the Control message passed when the control is enabled. @@ -2249,7 +2275,7 @@ - Performs actions needed when the Mouse Up message is received for the control. + Performs actions needed when a Mouse Up message is received for the control. @@ -2409,7 +2435,7 @@ - Calculates the Width and Height for the speed button, and optionally renders the control. + Calculates the Width, Height, and layout for the speed button and optionally renders the control.

@@ -2434,43 +2460,83 @@ - + + + Performs actions needed for a mouse down event on the control. + + +

+ MouseDown is an overridden method in TCustomSpeedButton. It calls the inherited MouseDown method on entry to signal the OnEditingDone event for the active control on the Parent form. It also updates the DragManager coordinates when a drag operation is already active. +

+

+ No additional actions are performed in the method at design-time. +

+

+ If the Left mouse button was pressed when the control is Enabled, Down is set to True (when needed) and the Action for the control is unchecked. An internal flag for a pending drag operation in MouseMove is set prior to exiting from the method. +

+ + + TControl.MouseDown + + - + Button for the mouse event. - + Shift, Ctrl, or Alt modifier for the mouse event. - + Horizontal coordinate for the mouse pointer. - + Vertical coordinate for the mouse pointer. - + + + Performs actions needed for a mouse move message received for the control. + + +

+ MouseMove calls the inherited method on entry to update the pointer position for the DragManager (when active) and to signal the OnMouseMove event handler (when assigned). +

+

+ No additional actions are performed in the method at design-time. +

+

+ if a drag operation has been started in MouseDown, the internal TButtonState for the control is updated to reflect the values in AllowAllUp and Down. When the button state has changed, the control is redrawn. +

+ + + + + TControl.OnMouseMove + TControl.MouseMove + TControl.WMMouseMove + + - + Shift, Ctrl, or Alt modifier for the mouse move event. - + Horizontal coordinate where the mouse pointer was moved. - + Vertical coordinate where the mouse pointer was moved. - + Button for the mouse event. - + Shift, Ctrl, or Alt modifier for the mouse up event. - + Horizontal coordinate for the mouse pointer. - + Vertical coordinate for the mouse pointer. @@ -2510,8 +2576,25 @@ Paints the background for the control to the specified rectangle. - - + +

+ PaintBackground is a method used to draw the background for the speed button control on its Canvas. When Transparent is True and the theme element has transparent areas, the value in Color is used to fill the drawing area in PaintRect. +

+

+ The DrawElement method in ThemeServices is called to render the drawing area to the Canvas for the control. PaintRect is updated following the drawing operation with the reduced content rectangle (the button surface without borders/edges) needed for the control. +

+

+ PaintBackground is called when the MeasureDraw method is used to render the control. The adjusted rectangle is later used in the method to calculate the drawing areas for the glyph bitmap and caption text. +

+ + + + + + + ThemeServices + TGraphicControl.Canvas + Rectangle where the control is drawn. @@ -2623,18 +2706,63 @@ - GetDrawDetails - returns the structured details for drawing. + Gets the theme element details used to draw the control. + +

+ Called from the MeasureDraw method. The return value can be an enumeration value from either TThemedToolBar or TThemedButton depending on the value in the Flat property. +

+

+ When Flat is True, one of the following TThemedToolBar values is returned: +

+
+
ttbButtonDisabled
+
Used when IsEnabled is False.
+
ttbButtonChecked
+
Used when Down is True and the mouse pointer is not over the control.
+
ttbButtonCheckedHot
+
Used when Down is True and the mouse pointer is hovered over the control.
+
ttbButtonPressed
+
Used when Down is False and the mouse is hovered over a grouped button control.
+
ttbButtonHot
+
Used when Down is False and the mouse is hovered over a non-grouped button control.
+
ttbButtonNormal
+
Default state for the control.
+
+

+ When Flat is False, one of the following TThemedButton values is returned: +

+
+
tbPushButtonDisabled
+
Used when IsEnabled is False.
+
tbPushButtonPressed
+
Used when a grouped button control is Down.
+
tbPushButtonHot
+
Used when a grouped button control is under the mouse pointer.
+
tbPushButtonNormal
+
Default state for the control.
+
+ - + Theme element detail used to draw the control in its current state. - MouseInControl - returns True if the mouse cursor is in the control. - - + Returns True if the mouse pointer is in the display area for the control. + + +

+ The property value is updated in the MouseEnter and MouseLeave methods when the mouse pointer enters or leaves the control area. The property value is used in the UpdateState method to determine if the button control is drawn using the "up" or "hot" states. It is used in the GetDrawDetails method to selected the theme element detail needed to draw the control in its current state. +

+ + + + + + + @@ -2643,7 +2771,7 @@

- ActionChange is overridden in TCustomSpeedButton to ensure that values from the new action instance in Sender are stored to properties in the control. ActionChange is the routine which implements the OnChange event handler for the ActionLink in the control. It is signalled (from TControl) when a new value is assigned to the Action property, or when the control is loaded using LCL component streaming. + ActionChange is overridden in TCustomSpeedButton to ensure that values from the new action instance in Sender are stored to properties in the control. ActionChange is the routine which implements the OnChange event handler for the ActionLink in the control. It is signalled (from TControl) when a new value is assigned to the Action property, or when the control is loaded using LCL component streaming.

Sender is the new action instance for the event, or Nil when the value in Action has been removed (set to Nil). @@ -2684,8 +2812,7 @@ Loaded is called by the LCL streaming system when a root component was completely read from a stream and all properties and references to other objects have been resolved. Descendents of TComponent should override this method to perform additional processing when all published properties have been set from values obtained from the LCL component stream.

- Application programmers should never call Loaded directly; this - is done automatically by the LCL streaming system. + Application programmers should never call Loaded directly; this is done automatically by the LCL streaming system.

@@ -2728,28 +2855,53 @@ Gets the size of the text within the specified PaintRect. - - + +

+ GetTextSize is a TSize function used to get the dimensions for the Caption text for the control. +

+

+ GetTextSize removes Ampersand (&) characters in Caption prior to calculating the dimensions for the text using the TextStyle for the control Canvas. The value in PaintRect is updated with the calculated dimensions. The X and Y members in the return value contain the width and the height for the text using the Font for the control. Both member values are set to 0 when ShowCaption is False or Caption contains an empty string (''). +

+

+ GetTextSize is called from the MeasureDraw method. +

+ + + + + TGraphicControl.Canvas + TControl.Caption + TControl.Font + - + TSize instance with the dimensions for the caption text. - + Not used in the current implementation. - + + Display rectangle for the control; updated in the method with the calculated text dimensions. + - Draws the glyph on the canvas in the specified rectangle at a given offset. + Draws the glyph image on the canvas at a given offset in the specified client rectangle. - + +

+ Uses the internal TButtonGlyph instance for the control (when assigned) to access its Draw method. The PixelsPerInch setting in Font and the Canvas scaling factor for the control are used to scale the image. +

+

+ The return value is a TRect instance with are needed to draw the glyph image on the the specified canvas. Its member values are set to 0 (zero) when a TButtonGlyph instance has not been assigned by setting a Glyph bitmap for the control. +

+ - + TRect instance used to draw the glyph bitmap. Canvas where the control is glyph is drawn. @@ -2764,10 +2916,10 @@ Button state drawn for the control. - + True if the glyph image is drawn with transparency. - + Not used in the current implementation. @@ -2851,12 +3003,59 @@ + + Horizontal alignment for the text displayed on the button control. + +

+ Alignment is a TAlignment property with the horizontal alignment for the Caption displayed on the button control. Alignment is used (along with UseRightToLeftReading) in the MeasureDraw method to set the text flags needed to measure / draw the Caption> for the control. +

+

+ The default value for the property is taCenter, and causes the Caption to be centered in the text area on the control. Use taLeft to left-align the Caption in the text area. Use taRight to right-align the Caption for the control. Changing the value for the property causes the control to be redrawn. +

+

+ Set the value in ShowCaption to True to display the Caption for the control. +

+

+ Use the Layout property to control the placement of the image relative to the text value displayed on the control. +

+

+ Use the Align property to specify the side on the parent control to which the speed button is aligned, or to specify that custom Anchors are used for positioning and sizing. +

+ + + + + + TControl.Align + TControl.Anchors + TControl.Caption + TControl.UseRightToLeftReading + TAlignment + + + Indicates if all buttons in a group can be in an up state. - - + +

+ AllowAllUp is a Boolean property which indicates whether all speed buttons with the same GroupIndex value can be in the "up" state. The default value for the property is False, and means that one of the grouped speed buttons must have its Down property set to True when GroupIndex has a non-zero value. +

+

+ Changing the value for the property causes a button pressed event to be sent to the Parent control (when assigned) and the Down property is toggled and updated for the new property value. +

+

+ Set GroupIndex to a value other than 0 (zero) to use AllowAllUp when a mouse button or an accelerator key is handled for the control. +

+ + + + + + + TControl.Parent + @@ -2868,7 +3067,7 @@ The default value for the property is clBtnFace in TCustomSpeedButton.

- If the color is clDefault , the result will need to be passed through GetDefaultColor to resolve clDefault to a TColor value. Convenience routines which obtain the color by resolving clDefault and ParentColor are also provided in the GetColorResolvingParent and GetRGBColorResolvingParent methods. + If the color is clDefault, the result will need to be passed through GetDefaultColor to resolve clDefault to a TColor value. Convenience routines which obtain the color by resolving clDefault and ParentColor are also provided in the GetColorResolvingParent and GetRGBColorResolvingParent methods.

@@ -2922,26 +3121,59 @@ Indicates whether the button is displayed with a Flat (non-relief) appearance. - - + +

+ Set Flat to True to draw the control without relief, elevation, or a three-dimensional appearance. The default value for the property is False. Changing the value for the property causes the control to be redrawn. +

+

+ Flat is used in the GetDrawDetails method to select the theme element details applied to the control for its current state. When set to False, TThemedButton element details are used. When set to True, TThemedToolBar element details are used. See GetDrawDetails for more information about the values used for specific button states. +

+ + + + + - The bitmap with the glyph image(s) displayed the button states. - - + The bitmap with the glyph image(s) displayed for button states. + +

+ Glyph is a TBitmap property with the image drawn for the button control. Read and write access to the property value are redirected to an internal TButtonGlyph instance for the control. This allows a single image to be specified for Glyph, or multiple bitmaps for various button states using the Images property. +

+

+ Changing the value for the property cause the control to be redrawn. +

+ + + + + + + + + + - Identifies the group of related speed buttons for the control. + Identifies the group to which the speed button control belongs.

- GroupIndex is used with AllowAllUp and Down to determine if the button state can be changed within the related group of controls. The default value for the property is 0 (zero). + GroupIndex is used with AllowAllUp and Down to determine if the button state can be changed within the related group of controls. All buttons on the Parent control with the same value in GroupIndex are treated as a single group. The default value for the property is 0 (zero), and indicates that an explicit value has not been assigned for the property. +

+

+ Set GroupIndex to a positive non-zero value to enable AllowAllUp checking when a mouse button event or an accelerator key is handled for the control.

- + + + + + + @@ -2977,6 +3209,12 @@

Provides an alternate way to specify images (individually) as opposed to multiple adjacent bitmaps in Glyph.

+

+ Use ImageIndex to specify the ordinal position in Images for the glyph bitmap displayed on the control. +

+

+ Use Glyph to access an image in the TButtonGlyph assigned to the control. +

@@ -3023,7 +3261,9 @@ Space around the Glyph bitmap and Caption for the control. - A value of -1 centers the content. If Spacing is -1 too then there is the same space on the left, between the glyph and caption, and on the right. +

+ A value of -1 centers the content. If Spacing is -1 too then there is the same space on the left, between the glyph and caption, and on the right. +

@@ -3151,6 +3391,7 @@ +