From ba5d5c3e5f829a7d1a8f25886e09881fbcf1fd95 Mon Sep 17 00:00:00 2001 From: dsiders Date: Wed, 4 Jan 2023 19:57:25 +0000 Subject: [PATCH] Docs: LCL/comctrls. Adds admonitions for macOS Carbon widgetset. Updates content for TStatusBar, TProgressBar, and TTrackBar topics. --- docs/xml/lcl/comctrls.xml | 335 +++++++++++++++++++++++++++++++++----- 1 file changed, 298 insertions(+), 37 deletions(-) diff --git a/docs/xml/lcl/comctrls.xml b/docs/xml/lcl/comctrls.xml index 373abf2d67..0b599ff527 100644 --- a/docs/xml/lcl/comctrls.xml +++ b/docs/xml/lcl/comctrls.xml @@ -1295,22 +1295,31 @@ The default value for the property is True in TStatusBar. -The background color of the control. + +The background color of the control. +

-The default value for the property is clDefault or clBtnFace (depending on -the UseCLDefault compiler define). If the color is clDefault , the result -will need to be passed through GetDefaultColor to resolve clDefault to an -actual TColor value. +Color is a published TColor property in +TStatusBar. The default value for the property is clDefault or +clBtnFace (depending on the UseCLDefault compiler define). If the color is +clDefault, the result will need to be passed through GetDefaultColor to +resolve clDefault to an actual TColor value.

Convenience routines which obtain the color by resolving clDefault and -ParentColor are provided in the TControl.GetColorResolvingParent and -TControl.GetRGBColorResolvingParent methods. +ParentColor are provided in the GetColorResolvingParent and +GetRGBColorResolvingParent methods in the TControl ancestor.

+ +For the macOS Carbon widgetset, the Color property is not supported in +TStatusBar. The status bar is always transparent on the platform. + TControl.Color +TControl.GetColorResolvingParent +TControl.GetRGBColorResolvingParent @@ -4180,7 +4189,7 @@ list. -Ordinal position in the page list for the return value. +Ordinal position in the page list for the return value. @@ -4301,7 +4310,7 @@ control. Ordinal position for the visible tab to convert to a physical page index. - + @@ -4502,6 +4511,9 @@ control. multiple tabs can be simultaneously selected on the tab control. When set to True, additional tabs can be selected by holding Shift or Ctrl when the mouse button is clicked.

+ +For the macOS Carbon widgetset, the MultiSelect property is not supported. + @@ -4720,7 +4732,7 @@ Ordinal position for the TCustomPage instance in the property value. Returns the number of page objects stored in the internal page list for the -tabbed control. +tabbed control.

@@ -4834,8 +4846,9 @@ Enables or disables justified text in the captions for tabs on the control.

-When set to False, captions are center-justified on the tabs. This property -requires support for the capability in the native tab control for the platform. +When set to False, captions are center-justified on the tabs. This +property requires support for the capability in the native tab control for the +platform.

@@ -4843,9 +4856,23 @@ requires support for the capability in the native tab control for the platform. -Introduced for use in descendent classes. +Indicates whether unused multi-line tabs are scrolled to the side opposite of +the tab position. - + +

+Set ScrollOpposite to True to force an unused row of tabs in +a multi-line tab control to be moved when a tab in a new row is selected. The +previous row of tabs is moved to edge opposite of the setting in TabPosition. +When set to False, a unused tab row is moved behind the current tab row. +

+

+The default value for the ScrollOpposite property is False. +

+

+ScrollOpposite is supported on the Windows widgetset only. It causes the TCS_SCROLLOPPOSITE flag to be included in the tab style flags for the widget when set to True. +

+ @@ -4859,16 +4886,23 @@ Enables display of tabs on the control when set to True (default). -Indicates the display style for the tabs on the tabbed control. +Indicates the appearance or display style used for the tabs on the control.

Style is a TTabStyle property which controls the visual appearance and behavior for the tabs on the control. The default value for the -property is tsTabs and causes convention tab appearance and behavior to be -used for the tab controls. See TTabStyle for the values for the property and -their meanings. +property is tsTabs and causes the conventional tab appearance and behavior to +be used for the tab controls.

+

+See for the other values for the property and their +meanings. +

+ +Use of the Style property to control tab appearance is a platform-spcific +feature, and is not supported for all of the LCL widgetsets. + @@ -5427,7 +5461,7 @@ updated in the Lazarus IDE.

- + TWinControl.ChildClassAllowed TControl.Parent TControl.CheckNewParent @@ -15132,7 +15166,9 @@ and indicator when a column header is clicked on the control. -Image list with the state images for the items on the control. + +Image list with the state images for the items on the control. +

StateImages is a TCustomImageList property which @@ -15153,8 +15189,16 @@ Use the OnChange, OnItemChecked, or OnDataStateChange event handlers to perform actions like setting the state image index for a list item when a list item is modified.

+ +For the macOS Carbon widgetset, the StateImages property is not supported. + - + + + + + + @@ -17876,7 +17920,24 @@ an animated marquee is used in the progress bar indicator. Increment applied to the value in Position in the StepIt method. - + +

+Step is an Integer property with the increment applied +to the value in Position in the StepIt method. The default value for the +property is 10, and represents 10% of the default range in Min and Max. +

+

+Changing the value for the property causes the ApplyChanges method to be +called to normalize the values in Min, Max, and Position. ApplyChanges also +updates the visual appearance and settings in the widgetset class instance. +

+

+Update Step when the range of values in Min and Max are changed. +

+ +For the macOS Carbon widgetset, the Step property is not supported. + + @@ -17896,7 +17957,7 @@ animated marquee-style progress bar to be displayed. -Indicates if status text is draw over the progress bar. +Indicates if status or progress text is draw over the progress bar.

@@ -24407,55 +24468,241 @@ Sets the position for the tick mark displayed on the track bar control. -Indicates the frequency of tick marks displayed for the control. +Indicates the frequency for the tick marks displayed on the control. + +

+Frequency is an Integer property which indicates the +interval between tick marks displayed on the track bar control. The default +value for the property is 1, and causes a tick mark to be drawn for +each value between Min and Max. When set to another value, tick marks are +drawn for each Position where the value modulus Frequency is 0 (zero). +

+

+Changing the value for the property causes the ApplyChanges method to be +called to update the settings and visual appearance for the widgetset control. +

+

+Use LineSize to specify the increment applied to Position when a cursor key is +pressed. +

+

+Use Min and Max to specify the range of values allowed in the Position +property. +

+ + + + + + + -Increment applied to the slider position when an arrow key is pressed. +Increment (or decrement) applied to the slider position when an arrow key is +pressed. + +

+LineSize is an Integer property used to change the +Position for the control when one of the arrow (cursor) keys is pressed. It +contains the increment (or decrement) applied to the Position property when +a cursor key is pressed. Use the Left or Up cursor keys to decrease the value +in Position. Use the Right or Down cursor keys to increase the value. The +default value for the property is 1. +

+

+Changing the value in LineSize causes the ApplyChanges method to be called to +update the visual appearance and settings for the widgetset class instance. +

+

+Use Min and Max to define the range of values allowed in the Position property. +

+ +For the macOS Carbon widgetset, the LineSize property is not supported. + + + + + + + + -Maximum value or position for the track bar slider. +Maximum value allowed in the Position for the track bar. + +

+Max is an Integer property which specifies the maximum +value allowed in the Position property. The default value for the property is +10. +

+

+Changing the value for the property causes Min, Max, and Position to be range +checked, normalized, and applied to the widgetset class instance using the +SetParams method. +

+ + + + + + -Minimum value or position for the track bar slider. +Minimum value allowed in the Position for the track bar. + +

+Min is an Integer property which specifies the minimum value allowed in the +Position property. The default value for the property is 0 (zero). +

+

+Changing the value for the property causes Min, Max, and Position to be range +checked, normalized, and applied to the widgetset class instance using the +SetParams method. +

+ + + + + + Event handler signalled when the Position in the control has been changed. + +

+OnChange is a TNotifyEvent property with the event +handler signalled when the value in the Position property is changed. The +Sender argument for the event is the TCustomTrackBar instance for the +notification. +

+

+OnChange is signalled from the Change method. It occurs after the new value +for Position has been stored and the OnEditingDone event handler has been +signalled (when assigned). +

+ + + + + + + +TControl.OnEditingDone + Indicates the horizontal or vertical orientation for the track bar control. + +

+Orientation is a TTrackBarOrientation property which +indicates whether the track bar is oriented horizontally or vertically. The +default value for the property is trHorizontal. +

+

+Changing the value for the property causes values in Width and Height to be +swapped to reflect the new orientation for the control. Left and Top +coordinates for the control are not changed. The Constraints are updated in +the LCL interface and the new property value is posted to the widgetset class +instance when its Handle has been allocated. +

+ + + +TControl.Width +TControl.Height +TControl.Constraints + -The increment for the slider position when PageUp or PageDown key is pressed. +The increment (or decrement) applied to the slider Position when the PageUp or +PageDown key is pressed. + +

+PageSize is an Integer property with the increment or +decrement applied to the Position property when the PageUp or PageDown key is +pressed while the control has focus. The default value for the property is 2. +

+

+For some platforms, modified cursor keys can be used for the same purpose. For example: Ctrl+Left, Ctrl+Right, Ctrl+Up, or Ctrl+Down. +

+

+Changing the value for the property causes the ApplyChanges method to be +called to update the settings in the widgetset class instance. +

+

+Use LineSize to control the increment applied to Position when an unmodified +cursor key is pressed while the control has focus. +

+ + + + + + Location of the slider on the track bar between the Min and Max values. + +

+Position is an Integer property with the current +location of the slider on the track bar control. Position contains a value in +the range specified by the Min and Max properties. +

+

+If Position is set to a value outside that range, it is set to the limit which +it exceeds. The new value for the property is applied to the widgetset class +instance when its Handle has been allocated. Position is used in the SetParams +method to determine if new property values needs to be applied to the widget. +

+

+The property value is updated in DoChange where its value is read from the +widget. It is also updated in FixParams if the property value is outside the +range allowed in Min and Max. +

+

+Changing the value for the property causes the OnChange event handler to be +signalled (when assigned). +

+ + + + + + + + + + + + -True if the values are displayed in ascending order from right-to-left. +True if the values on the track bar are displayed from right-to-left in +ascending order. @@ -24463,22 +24710,30 @@ Location of the slider on the track bar between the Min and Max values. -Position where the scale is displayed. +Position where the scale is displayed for the track bar control. -This is a GTK-specific property. + +ScalePos is a GTK-specific property. It is not implemented or supported for +other widgetsets. Use the TickMarks property on other platforms. + + + + -Ending value for the selection range in the track bar control. + +Ending value for the selection range on the track bar control. + -Starting value for the selection range in the track bar control. +Starting value for the selection range on the track bar control. @@ -24486,15 +24741,17 @@ Starting value for the selection range in the track bar control. -Displays a selection range and indicators using the values in SelStart and -SelEnd. +Enables or disables a highlighted selection range with tick marks using the +values in SelStart and SelEnd. -Enables or disables navigatiopn using the Tab key. + +Enables or disables navigation using the Tab key. +

The default value for the property is True in TCustomTrackBar. @@ -24512,7 +24769,7 @@ Position for the tick marks relative to the slider in the track bar.

Tickmarks indicates where the ticks appear relative to the slider -in the track bar control. +on the track bar control.

tmBottomRight
@@ -24530,6 +24787,9 @@ the left for the vertical orientation. Tick marks are displayed on both sides for the selected orientation.
+ +For the macOS Carbon widgetset, the TickMarks property is not supported. + @@ -24584,6 +24844,7 @@ associated TProgressBar.

+ How To Use Standard Controls