From c2c075c78f8b20d9002ba9ba9af34a6dbc85770d Mon Sep 17 00:00:00 2001 From: dsiders Date: Wed, 27 Apr 2022 01:58:38 +0100 Subject: [PATCH] Docs: LCL/forms. Adds, updates topic content. --- docs/xml/lcl/forms.xml | 914 +++++++++++++++++++++++++++++++++-------- 1 file changed, 745 insertions(+), 169 deletions(-) diff --git a/docs/xml/lcl/forms.xml b/docs/xml/lcl/forms.xml index 77475cc053..e21dbdee3b 100644 --- a/docs/xml/lcl/forms.xml +++ b/docs/xml/lcl/forms.xml @@ -12,7 +12,7 @@

- forms.pp contains classes, types, and routines used to implement forms, which are used as the basis a graphical user interface in the Lazarus Component Library (LCL). + forms.pp contains classes, types, and routines used to implement forms, which are the basis for the graphical user interface in the Lazarus Component Library (LCL).

The following components are added to the Lazarus IDE component palette: @@ -3126,10 +3126,10 @@ Handles the CM_BIDIMODECHANGED control message for the form.

- Re-implements the method from the ancestor class. Calls the inherited method on entry using the value in Message to set the BiDi and adjust the size for the control. + Re-implements the method from the ancestor class. Calls the inherited method on entry using the value in Message to set the BiDiMode and adjust the size for the control.

- Ensures that all components owned by the form are notified of the change to the BiDiMode property. This is needed for menus on the form. A TLMessage instance is constructed with the CM_PARENTBIDIMODECHANGED message and displatched to all of the Components on the form not derived from TWinControl. TWinControl handles the notification for its descendants. Alignment is temporarily disabled during the process, and re-enabled prior to exiting from the method. + Ensures that all components owned by the form are notified of the change to the BiDiMode property. This is needed for menus on the form. A TLMessage instance is constructed with the CM_PARENTBIDIMODECHANGED message and dispatched to all of the Components on the form not derived from TWinControl. TWinControl handles the notification for its descendants. Alignment is temporarily disabled during the process, and re-enabled prior to exiting from the method.

@@ -3719,7 +3719,9 @@ - Here: clip width and height of a top-level form to the monitor WorkArea. + + Here: clip width and height of a top-level form to the monitor WorkArea. + @@ -4545,7 +4547,9 @@ - The role(s) for the control in a modal form (default or cancel button). + + The role(s) for the control in a modal form (default or cancel button). + @@ -5299,14 +5303,10 @@ Use BorderStyle to get or set the appearance of the form's border.

- By default it is a sizeable window, but it could, for example, be a dialog form - or a tool window, or could be non-sizeable. + By default it is a sizeable window, but it could, for example, be a dialog form or a tool window, or could be non-sizeable.

- This property is slightly different (has a different base type) from the - TCustomControl.BorderStyle property. When the form is put into - another control the window borders depend on the widgetset. There are no - borders under GTK. + This property is slightly different (has a different base type) from the TCustomControl.BorderStyle property. When the form is put into another control the window borders depend on the widgetset. There are no borders under GTK.

@@ -5395,7 +5395,7 @@ - Value from ShowInTaskBar adjusted for the default taskbar behavior in the application. + Value from ShowInTaskBar adjusted for the default task bar behavior in the application. @@ -5430,10 +5430,13 @@
fsNormal
Usual style.
fsStayOnTop
-
Form is positioned above all application's forms, except those which have - fsStayOnTop style.
+
+ Form is positioned above all application's forms, except those which have fsStayOnTop style. +
fsSystemStayOnTop
-
Form is positioned above all OS windows, except other OS top-level windows.
+
+ Form is positioned above all OS windows, except other OS top-level windows. +
fsSplash
Form is border-less.
fsMDIForm
@@ -6298,7 +6301,41 @@ - + + + + Delimited list of form and / or component properties saved to and restored from an external storage mechanism. + + +

+ SessionProperties is a String property with the names of properties, in the form instance or its child components. It allows published property values to be saved to and restored from an external storage mechanism like: TIniPropStorage, TXMLPropStorage, or TJSONPropStorage. +

+

+ Values in the property are delimited using the ';' (SemiColon) character. Component properties require both the component and property names using dotted notation like 'Image1.Visible'. The values can be assigned at design-time using a dialog in the Lazarus IDE, or by setting the property value at run-time. +

+

+ For example: +

+ +// var AForm: TForm; +AForm.SessionProperties := 'Top;Left;WindowState;Image1.Visible;Image1.Transparent'; + +

+ At design-time, the selection dialog is limited to published properties since RTTI is used to display and access the property values. Use the event handlers in the storage mechanism, or its StoredValues property, to save or restore properties with lesser visibility. Use the Save and Restore methods in the storage mechanism to read and write the property values. +

+

+ TForm sets the visibility for SessionProperties, introduced in TControl, to published. +

+ + + + TCustomPropertyStorage + TIniPropStorage + TXMLPropStorage + TJSONPropStorage + + + @@ -6315,17 +6352,25 @@ - + - - Class of TForm. - - + + + Class type used to create new TForm instances. + + +

+ Class type used to create new TForm instances. Used in the CustomForm package to register a custom form type, unit, or package. +

+ + + + - A floating DockSite, usable to make TControls float. + A floating DockSite used to make TControls float. @@ -6336,7 +6381,7 @@

- DoAddDockClient is an overridden method used to add the control in Client to the docked form. It calls the inherited method on entry to set the Parent in Client to the current class instance. It sets the Align property in Client to alAlign to align the control to the bounds for the docked form. Values in the BorderSpacing property in Client are reset to 0; the current class instance provides the BorderSpacing values for the docked control. At run-time, the Visible property is set to True to display the docked form after the Client has been added. + DoAddDockClient is an overridden method used to add the control in Client to the docked form. It calls the inherited method on entry to set the Parent in Client to the current class instance. It sets the Align property in Client to alAlign to align the control to the bounds for the docked form. Values in the BorderSpacing property in Client are reset to 0; the current class instance provides the BorderSpacing values for the docked control. At run-time, the Visible property is set to True to display the docked form after the Client has been added.

@@ -6381,8 +6426,7 @@ - Tries to make all child controls dockclients. This is of little use in practice, - a floating hostdocksite should have no child controls. + Tries to make all child controls dockclients. This is of little use in practice, a floating host docksite should have no child controls. @@ -6414,14 +6458,14 @@ - Indicates if the form can automatically show or hide scroll bars. + Indicates if the form can automatically show or hide its scroll bars.

- AutoScroll is a Boolean property which indicates if the form can automatically show or hide its scroll bars. The default valule for the property is False in TCustomDockForm. + AutoScroll is a Boolean property which indicates if the form can automatically show or hide its scroll bars. The default value for the property is False in TCustomDockForm.

- AutoScroll can only be True when the BorderStyle for the form is bsSizeable or bsSizeToolWin , and may be changed to False at run-time when BorderStyle is changed to another value. + AutoScroll can only be True when the BorderStyle for the form is bsSizeable or bsSizeToolWin, and may be changed to False at run-time when BorderStyle is changed to another value.

@@ -6588,7 +6632,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Handles the WM_NCHITTEST window message for the hint window. + + Handles the WM_NCHITTEST window message for the hint window. +

Sets the result in Message to HTTRANSPARENT. This forces the message to be forwarded to other windowed controls in the Z-Order until a value other than HTTRANSPARENT is returned. @@ -6601,7 +6647,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Sets the bounds for the hint window and configures the auto-hide timer. + + Sets the bounds for the hint window and configures the auto-hide timer. +

Sets the bounds for the hint window to the values in the HintRect property, and makes the window Visible. The internal auto-hide timer is enabled when AutoHide contains True. @@ -6854,16 +6902,22 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - TPoint with the horizontal and vertical offsets for the hint display. + + TPoint with the horizontal and vertical offsets for the hint display. + Additional vertical offset applied to the hint rectangle. - Indicates the width for the hint rectangle must be maintained. + + Indicates the width for the hint rectangle must be maintained. + - Indicates the height for the hint rectangle must be maintained. + + Indicates the height for the hint rectangle must be maintained. + @@ -6904,7 +6958,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Applies the argument values to the bounds for the control. + + Applies the argument values to the bounds for the control. +

SetBounds is an overridden method in THintWindow. It calls the inherited method on entry to apply the argument values to the bounds for the class instance. It calls the UpdateRegion method to set the window region, or apply a background theme when enabled. @@ -6983,8 +7039,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Does the hint disappear (get hidden) after a while? - If AutoHide is TRUE, the hint disappears after an interval specified by - HideInterval. +

+ If AutoHide is TRUE, the hint disappears after an interval specified by HideInterval. +

@@ -7008,7 +7065,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - For a rendered hint with a child control added by an external provider. + + For a rendered hint with a child control added by an external provider. + @@ -7028,7 +7087,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Shows hint contents are rendered by a provider on child control. + + Shows hint contents are rendered by a provider on child control. + @@ -7084,9 +7145,19 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Value for the property. - + + + Gets the value for the Height property. + + + + + + - + + Value for the Height property. + @@ -7100,29 +7171,79 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Value for the property. - + + + Gets the value for the Top property. + + + + + + - + + Value for the Top property. + - + + + Gets the value for the Width property. + + + + + + - + + Value for the Width property. + - + + + Gets the value for the BoundsRect property. + + + + + + - + + Value for the BoundsRect property. + - + + + Gets the value for the WorkareaRect property. + + + + + + - + + Value for the WorkareaRect property. + - + + + Gets the value for the Primary property. + + + + + + - + + Value for the Primary property. + @@ -7130,44 +7251,157 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Index of the monitor in the list. + + Index of the monitor in the list. + + +

+ MonitorNum is a read-only Integer property with the ordinal position where the class instance is stored in a list of Monitors. The value for the property is assigned in the UpdateMonitors method in TScreen when the monitor class instance is created and stored. +

+ + + + + - The leftmost screen coordinate of the display. + The left-most screen coordinate for the display. + +

+ Left is a read-only Integer property with the coordinate for the left edge of the monitor. It contains the value from the Left member in BoundsRect. +

+ + + + TRect + - The height of the display. + + The height for the display. + + +

+ Height is a read-only Integer property with the height for the monitor in pixels. The property value is calculated as the difference between the Bottom and Top members in BoundsRect. +

+ + + + TRect + - The top-most screen coordinate of the display. + + The top-most screen coordinate for the display. + + +

+ Top is a read-only Integer property with the top coordinate for the monitor. It contains the value from the Top member in BoundsRect. +

+ + + + TRect + - The width of the display. + + The width for the display. + + +

+ Width is a read-only Integer property with the width for the monitor. It is calculated as the difference between the Right and Left members in BoundsRect. +

+ + + + TRect + - The logical dimensions of the monitor, within the desktop. + + Rectangle with the dimensions for the monitor. + +

+ BoundsRect is a read-only TRect property which contains the bounds for the display device. The property value is assigned from TMonitorInfo information retrieved using the platform-specific GetMonitorInfo routine. The rectangle can be empty (where all members have the value 0) if monitor information was not successfully retrieved from the widgetset. +

+ + + GetMonitorInfo + TMonitorInfo + TRect + - The usable display area, excluding a taskbar etc. + + The usable display area on the monitor excluding the system task bar. + + +

+ WorkareaRect is a read-only TRect property with the bounds for the usable display area on the monitor. This does not include any space covered by the system task bar. +

+

+ The property value is assigned from TMonitorInfo information retrieved using the platform-specific GetMonitorInfo routine. The rectangle can be empty (where all members have the value 0) if monitor information was not successfully retrieved from the widgetset. +

+ + + GetMonitorInfo + TMonitorInfo + TRect + - True if this is the primary monitor of the system. + + Contains True if this is the primary monitor for the system. + + +

+ Primary is a read-only Boolean property which indicates if the monitor is the primary display in a list of monitors. The property value is determined using flag values in the TMonitorInfo retrieved using GetMonitorInfo for the platform or operating system. It is set to True when the monitor information contains MONITORINFOF_PRIMARY in its flags. +

+

+ Primary is used when the value for the PrimaryMonitor property is retrieved in the TScreen class. It indicates which TMonitor instance is used as the value for the PrimaryMonitor property. +

+ + + + GetMonitorInfo + TMonitorInfo + - Contains the Pixels Per Inch or display density for the monitor. + + Contains the Pixels Per Inch (or display density) for the monitor. + + +

+ PixelsPerInch is a read-only Integer property with the display density for the monitor. The property value is determined by calling the GetDpiForMonitor routine for the widgetset to retrieve the effective dots-per-inch for both horizontal and vertical dimensions. The horizontal density is used in the property value. +

+

+ If the GetDpiForMonitor routine does not complete successfully, the PixelsPerInch property in TScreen is used as the property value. +

+

+ PixelsPerInch can be used at run-time to ensure that the display density for a Font or Canvas matches the setting in a specific monitor. It is used in the Show and AutoScale methods in TCustomForm to apply an auto-adjust layout policy. It is also used in the form designer for the Lazarus IDE to perform similar actions during component streaming. +

+ + + TCustomForm.Show + TCustomForm.AutoScale + - A list of monitors available on the system. + + A list of monitors available on the system. +

TMonitorList is a TList descendant used to store TMonitor class instances representing the physical monitors attached to the system. It provides an indexed Items property that can be used to access monitor information by an ordinal position in the list. It also provides an overridden Notify method to free a TMonitor instance when the lnDeleted list notification is received. @@ -7256,7 +7490,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Type used for a screen notification handler, for form related events. + + Type used for a screen notification handler for form-related events. + @@ -7271,7 +7507,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Type for a screen notification handler used for control related events. + + Type for a screen notification handler used for control-related events. + @@ -7329,7 +7567,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Provides information about the screen display in an application. + + Provides information about screen displays in an application. +

TScreen is a TLCLComponent descendant which provides information about multiple monitors in an LCL application. TScreen allows the GUI for an application to be managed on multiple monitors. It includes the size and resolution for a screen, and allows mapping the virtual Desktop and Workareas to the physical Monitors known to the application. @@ -7464,14 +7704,18 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Gets the value for the indexed CustomFormsZOrdered property. + + Gets the value for the indexed CustomFormsZOrdered property. + - TCustomForm instance at the specified position in the Z-Order. + + TCustomForm instance at the specified position in the Z-Order. + @@ -7592,7 +7836,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Value for the property. - Ordinal position for the form instance in the property value. + + Ordinal position for the form instance in the property value. + @@ -7610,31 +7856,75 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Value for the property. - + + + Gets the value for the indexed Monitors property. + + + + + + - + + Value for the indexed Monitors property. + - + + Ordinal position for the TMonitor instance in the property value. + - + + + Gets the value for the MonitorCount property. + + + + + + - + + Value for the MonitorCount property. + - + + + Gets the value for the PrimaryMonitor property. + + + + + + - + + Value for the PrimaryMonitor property. + - + + + Gets the value for the Width property. + + + + + + - + + Value for the Width property. + - Internal notification handler, adds a new form to the lists. + + Internal notification handler which adds a new form to the list of forms on the screen. + @@ -7643,7 +7933,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Internal notification handler, removes the form from the lists. + + Internal notification handler which removes the specified form from the form list. + @@ -7651,58 +7943,150 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Form instance removed from the list. - + + + Handles form deactivation and activation changes, and makes the specified form the FocusedForm on the screen. + + +

+ SetFocusedForm ensures that the form in AForm becomes the FocusedForm in the class instance when needed. No actions are performed in the method, and the return value is set to True, when AForm and FocusedForm have the same values. +

+

+ SetFocusedForm sends a CM_DEACTIVATE message to the form instance in FocusedForm (when assigned). +

+

+ The return value indicates if the focus state has changed during form deactivation, and may return False if deactivation failed. FocusedForm is set to Nil if deactivation failed. +

+

+ Otherwise, AForm is saved to the FocusedForm property and a CM_ACTIVATE message is performed. The return value is False if the activation failed. +

+

+ SetFocuseForm is called from the SetFocusedControl method in TCustomForm when a new control becomes focused on a form other than FocusedForm. +

+ + + + + + - + + False if activation or deactivation fails. True on success or when no action is needed. + - + + Form instance to become the FocusedForm in the class instance. + - + + + Sets the value for the Cursor property. + + + + + + - + + New value for the Cursor property. + - + + + Sets the value for the indexed Cursors property. + + + + + + - + + Ordinal position for the cursor handle stored in the indexed property. + - + + New cursor handle stored in the property. + - + + + Sets the value for the HintFont property. + + + + + + - + + New value for the HintFont property. + - + + + Sets the value for the IconFont property. + + + + + + - + + New value for the IconFont property. + - + + + Sets the value for the MenuFont property. + + + + + + - + + New value for the MenuFont property. + - + + + Sets the value for the SystemFont property. + + + + + + - + + New value for the SystemFont property. + - Stores the currently active form and control in the last active members. - Notifies all registered handlers of eventual changes. + Stores the currently active form and control in the last active members. Notifies all registered handlers of changes. - Moves the Focus back to the previously focused control. + + Moves the Focus back to the previously focused control. + @@ -7757,7 +8141,7 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Removes a screen notification handler with the specified type. + Removes a screen notification handler using the specified type. @@ -7824,29 +8208,79 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Form instance for the notification. - + + + Gets the value for the WorkAreaHeight property. + + + + + + - + + Value for the WorkAreaHeight property. + - + + + Gets the value for the WorkAreaLeft property. + + + + + + - + + Value for the WorkAreaLeft property. + - + + + Gets the value for the WorkAreaRect property. + + + + + + - + + Value for the WorkAreaRect property. + - + + + Gets the value for the WorkAreaTop property. + + + + + + - + + Value for the WorkAreaTop property. + - + + + Gets the value for the WorkAreaWidth property. + + + + + + - + + Value for the WorkAreaWidth property. + @@ -7908,8 +8342,7 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Create is the overridden constructor for the class instance, and calls the inherited method on entry.

- Create allocates resources needed for properties, including: Fonts, Monitors, CustomForms, CustomFormsZOrdered, and - DataModules. Resources for internal members are also allocated. + Create allocates resources needed for properties, including: Fonts, Monitors, CustomForms, CustomFormsZOrdered, and DataModules. Resources for internal members are also allocated.

Create gets the default value used for the PixelsPerInch property from the ScreenInfo variable in the LCL interface. @@ -7939,7 +8372,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Gets the ordinal position in CustomForms for the requested form. + + Gets the ordinal position in CustomForms for the requested form. +

CustomFormIndex is an Integer function used to get the position in CustomForms for the specified TCustomForm instance. It iterates over the values in CustomForms in reverse order. The return value contains the ordinal position in CustomForms where the TCustomForm instance in AForm was found, or -1 when AForm does not exist in CustomForms. @@ -7962,7 +8397,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Gets the ordinal position in Forms for the requested form. + + Gets the ordinal position in Forms for the requested form. +

FormIndex is an Integer function used to get the position in Forms where the specified TForm instance in located. It iterates over the values in Forms in reverse order. The return value contains the ordinal position in Forms where the TForm instance in AForm was found, or -1 when AForm does not exist in Forms. @@ -8294,10 +8731,14 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Active control changed notification handler added in the method. + + Active control changed notification handler added in the method. + - True if the handler should be the first in the list for the type. + + True if the handler should be the first in the list for the type. + @@ -8318,7 +8759,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Active form changed handler added in the method. - True if the handler should be the first in the list for the type. + + True if the handler should be the first in the list for the type. + @@ -8339,7 +8782,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Form visible changed handler added in the method. - True if the handler should be the first in the list for the type. + + True if the handler should be the first in the list for the type. + @@ -8432,7 +8877,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Finds the monitor where the specified rectangle is located. + + Finds the monitor where the specified rectangle is located. +

MonitorFromRect is a TMonitor function used to get the monitor where the coordinates in the specified rectangle are located. @@ -8706,7 +9153,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Provides indexed access to the available mouse cursor shapes for the screen. + + Provides indexed access to the available mouse cursor shapes for the screen. +

Cursors is an indexed HCURSOR property which provides access to the handle for a mouse cursor shape by its numeric value. The cursor constants (like crHourGlass) defined in the controls.pp unit can be used instead of the numeric value. @@ -8729,7 +9178,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Number of TCustomForm form instances in the CustomForms property. + + Number of TCustomForm form instances in the CustomForms property. +

CustomFormCount is a read-only Integer property which contains the number of TCustomForm instances stored in the CustomForms property. Read access for the property value is redirected to the Count property in CustomForms. @@ -8770,7 +9221,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - The list of Custom Forms, indexed by Z-order (zero is top-most). + + The list of Custom Forms, indexed by Z-order (zero is top-most). +

CustomFormsZOrdered is a read-only indexed TCustomForm property which provides access to a custom form by its ordinal position in the Z-Order for the screen. The form at position 0 (zero) is displayed at the top of the Z-Order, and overlaps any form with a higher Z-Order value. @@ -8830,7 +9283,7 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); The left-most coordinate of the desktop.

- DesktopLeft is a read-only Integer property with the left coordinate for the desktop. The property value contains the virtual screen size returned from GetSystemMetrics for the SM_XVIRTUALSCREEN parameter. + DesktopLeft is a read-only Integer property with the left coordinate for the desktop. The property value contains the virtual screen coordinate returned from GetSystemMetrics for the SM_XVIRTUALSCREEN parameter.

DesktopLeft is used in the MoveToDefaultPosition method in TCustomForm. The values in DesktopLeft, DesktopTop, DesktopWidth and DesktopHeight are also assigned to members in the DesktopRect property. @@ -8846,7 +9299,7 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); The top-most coordinate for the desktop.

- DesktopTop is a read-only Integer property with the top coordinate for the desktop. The property value contains the virtual screen size returned from GetSystemMetrics for the SM_YVIRTUALSCREEN parameter. + DesktopTop is a read-only Integer property with the top coordinate for the desktop. The property value contains the virtual screen coordinate returned from GetSystemMetrics for the SM_YVIRTUALSCREEN parameter.

DesktopTop is used in the MoveToDefaultPosition method in TCustomForm. The values in DesktopLeft, DesktopTop, DesktopWidth and DesktopHeight are also assigned to members in the DesktopRect property. @@ -9041,7 +9494,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Currently used only in FindFontName in the TurboPower IPro package. + + Currently used only in FindFontName in the TurboPower IPro package. + @@ -9115,7 +9570,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Ordinal position for the TMonitor instance in the property value. + + Ordinal position for the TMonitor instance in the property value. + @@ -9137,7 +9594,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - The primary monitor which typically includes the task bar area. + + The primary monitor which typically includes the task bar area. +

PrimaryMonitor is a read-only TMonitor property with the primary monitor for the system. The property value is determined by checking for the TMonitor instance in Monitors with its Primary property set to True. The property value is Nil if a monitor is not found with its Primary property set to True. @@ -9163,7 +9622,7 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Use Height to get height for the primary monitor.

- Use DesktopWidth to get the usable width for the desktop minus the area reserved for a task bar. + Use DesktopWidth to get the usable width for the entire desktop.

@@ -9173,17 +9632,34 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - The usable display area on the primary monitor excluding the task bar. + + The usable display area on the primary monitor excluding the task bar. + +

+ WorkAreaRect is a read-only TRect property with the bounds for the usable display area on the primary monitor. It excludes the area covered by the system task bar. The return value is the result from the platform-specific SystemParametersInfo routine in the LCL interface using the SPI_GETWORKAREA parameter constant. +

+

+ Use DesktopRect to get the bounds for the entire desktop spanning all monitors. +

+

+ Use the Monitors property to access screen information for a specific monitor. +

+ - The usable height of the primary monitor excluding the task bar. + + The usable height of the primary monitor excluding the system task bar. + +

+ The property value is calculated as the difference between the Bottom and Top members in WorkAreaRect. +

@@ -9192,6 +9668,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); The usable left coordinate on the primary monitor. +

+ The property value contains the Left member from WorkAreaRect. +

@@ -9221,7 +9700,7 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Returns the difference between the Right and Left members in WorkAreaRect.

- Use DesktopWidth to get the width for the primary monitor including the task bar area. + Use DesktopWidth to get the width for the entire desktop spanning all monitors.

@@ -9379,7 +9858,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Specifies the type used for an asynchronous callback method. + + Specifies the type used for an asynchronous callback method. + @@ -9448,17 +9929,25 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); The hint timer is off. - Waiting to show a hint; used when a hint timer is started. + + Waiting to show a hint; used when a hint timer is started. + - Waiting to hide an hint; used when the hint control is changed or the mouse leaves a hint rectangle. + + Waiting to hide an hint; used when the hint control is changed or the mouse leaves a hint rectangle. + - Waiting to show the next hint; used when the hide hint timer is started. + + Waiting to show the next hint; used when the hide hint timer is started. + - Defines an event handler signalled to perform hint display. + + Defines an event handler signalled to perform hint display. +

TShowHintEvent is an object procedure type which defines an event handler signalled to perform hint display. It is the type used for the TApplication.OnShowHint event handler property. @@ -9558,7 +10047,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Set type used to store values from the TApplicationFlag enumeration. + + Set type used to store values from the TApplicationFlag enumeration. +

TApplicationFlags is the type used for the Flags property in TApplication. @@ -9583,11 +10074,13 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - The Tab key moves the Focus to the next (or previous) control in TabOrder. + + The Tab key moves the Focus to the next (or previous) control in TabOrder. - The Enter key triggers the default action. + + The Enter key triggers the default action. @@ -9621,7 +10114,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Application idle state is ending. - Handler for KeyDown events, invoked before interface and LCL handlers. + + Handler for KeyDown events, invoked before interface and LCL handlers. + @@ -9637,7 +10132,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Handler invoked on user input. - Used in NotifyUserInputHandler; implemented in Sparta MDI package + + Used in NotifyUserInputHandler; implemented in Sparta MDI package + @@ -9801,7 +10298,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Describes the policy for the application of how to show menu and button glyphs. + + Indicates the application policy for displaying glyphs on menus and buttons. +

TApplicationShowGlyphs is an enumerated type with values that indicate the policy for displaying glyphs on menus and buttons. TApplicationShowGlyphs is the type used to implement the ShowButtonGlyphs and ShowMenuGlyphs properties in both TApplication and TApplicationProperties. @@ -9874,7 +10373,7 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Application management and configuration for a GUI application.

- TApplication is a TCustomApplication descendant which provides facilities used to manage and configure a GUI application. Properties, methods, and event handlers are provided which allow a program to create, execute, monitor, maintain and destroy an application and its forms. Every GUI application contains an Application variable that represents the TApplication or descendent class instance. + TApplication is a TCustomApplication descendant which provides facilities used to manage and configure a GUI application. Properties, methods, and event handlers are provided which allow a program to create, execute, monitor, maintain and destroy an application and its forms. Every GUI application contains an Application variable that represents the TApplication or descendent class instance.

TApplication provides a message processing loop that includes hooks for event handlers and exception handling, and supports dispatching messages for TCustomAction instances used in application forms. TApplication provides support for hints and content-sensitive help for forms and controls used in the application. Convenience methods, like MessageBox, are provided to simplify access to dialogs and error messages in the application. @@ -9886,7 +10385,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Holds the registered handler routines for the application. + + Holds the registered handler routines for the application. + @@ -13508,7 +14009,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Contains the default BiDiMode value used for the current LCL version. + + Contains the default BiDiMode value used for the current LCL version. +

The default value is bdLeftToRight. @@ -13541,14 +14044,16 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - The default pause before a hint is hidden (in milliseconds). + The default pause (in milliseconds) before a hint is hidden. - The default pause added to DefHintHidePause (in milliseconds). + + The default pause (in milliseconds) added to DefHintHidePause. + @@ -14620,13 +15125,19 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Form instance that is the parent for the specified control. + + Form instance that is the parent for the specified control. + - Control used to locate the parent form in the control hierarchy. + + Control used to locate the parent form in the control hierarchy. + - True if the top-most form instance in the control hierarchy is needed. + + True if the top-most form instance in the control hierarchy is needed. + @@ -14654,7 +15165,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Does a recursive search for the first Parent of type TCustomForm. + + Performs a recursive search for the first Parent of type TCustomForm. +

GetFirstParentForm is a TCustomForm function used to find the first form instance in the Parents for the specified Control. GetFirstParentForm calls the GetParentForm routine to get the form instance used as the return value. The return value is Nil when Control has not been assigned, or a form is not found in GetParentForm. @@ -14668,10 +15181,14 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - The first custom form instance found by ascending the control hierarchy. + + The first custom form instance found by ascending the control hierarchy. + - TControl instance where the search for a parent form is started. + + TControl instance where the search for a parent form is started. + @@ -14753,7 +15270,7 @@ HintWindow.ActivateHint(Rect, 'This is the hint');

- Calls GetParentDesignControl to get the return value for the function. Raises an EInvalidOperation exception if a TCustomDesignControl instance is not found for the specififed control. + Calls GetParentDesignControl to get the return value for the function. Raises an EInvalidOperation exception if a TCustomDesignControl instance is not found for the specified control.

Used in methods which perform scaling operations for TCustomForm or TControl instances. @@ -14769,11 +15286,19 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Searches for the given virtual key, used as an accelerator. + + Determines whether the specified virtual key is used as an accelerator (short cut) in the given caption string. +

An accelerator consists of an ampersand followed by the accelerator key. Duplicate ampersands are ignored; they denote a literal (displayed) ampersand character (&).

+

+ IsAccel calls UTF8Pos to locate all occurrences of a single Ampersand character in Str. The character immediately following the Ampersand is the short cut character for the accelerator, and it is compared to the numeric value in VK. If one of the short cut characters matches the value in VK, the return value is set to True and the routine is exited. If none of the short cut characters match VK, or an accelerator is not present in Str, the return value is False. +

+

+ IsAccel is called from controls which implement overridden CMDialogChar or DialogChar methods. It is also called when widgetset classes handle menu item selection and execution in an application. +

@@ -14788,9 +15313,24 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - Invokes all application user input handlers. - - + + Signals all user input handlers for the application using the specified message. + + +

+ Calls the NotifyUserInputHandler method in the Application singleton when it has been assigned using Msg as an argument. +

+

+ NotifyApplicationUserInput is used as a callback routine in widgetset classes. It allows the widget to notify the application when a mouse or a keyboard event is pending in the LCL interface. +

+ + + + + + + + The message to process. @@ -14800,30 +15340,48 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Returns the short version of a Hint string.

- A short Hint is separated from the long Hint by a '|' character. When no such character is found, the whole Hint is returned. + A short Hint is separated from the long Hint by a '|' character. If the character is not found, the whole Hint string is returned.

- + + + + + - The short (or complete) Hint. + The short version of the Hint text (when available). - The string containing both a short and long Hint. + + The string containing both short and long Hint text in the format: 'Short Hint|This is the Long Hint for a control.' + Returns the long version of a Hint string. - + +

+ A long Hint is the part of the text which appears after a '|' character in Str. For example: +

+ 'Short Hint|This is the Long Hint for a control.' +

+ If the '|' character is not found, the value in Str is returned. +

+ + + - + The long variant of the specified hint text. - + + The string containing both short and long Hint text in the format: 'Short Hint|This is the Long Hint for a control.' + @@ -14844,14 +15402,26 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); The TScreen singleton for the application. - + +

+ Screen is a unit global TScreen variable which provides information about the display devices attached to the system. It allows access to the physical attributes for the monitors available in the application, as well logical attributes for the Desktop. It can also be used to access information about the Forms, DataModules, Fonts, and Cursor shapes used on the displays. +

+

+ See TScreen for more information about the properties, methods and events in the class instance. +

+

+ Screen is allocated in the initialization section for the forms.pp unit. It is freed in the finalization section for the unit. +

+ - Variable representing the current exception object in an application. + + Variable representing the current exception object in an application. +

Used in the implementation of the TApplication.HandleException method. @@ -14863,7 +15433,9 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - The class type used to create hint window instances for an application. + + The class type used to create hint window instances for an application. + @@ -14991,11 +15563,15 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); - TWidgetsetClass class type for the desired widgetset implementation. + + TWidgetsetClass class type for the desired widgetset implementation. + - + - Destroys singletons for the Screen, Application, and WidgetSet. + + Destroys singletons for the Screen, Application, and WidgetSet. +

FreeWidgetSet is a procedure used to free resources allocated to the Screen, Application, Clipboards, and WidgetSet singletons. @@ -15019,7 +15595,7 @@ HintWindow.ActivateHint(Rect, 'This is the hint'); Registers components declared in this unit.

- Register is a procedure used to register components declared in the forms.pp unit for use in the Lazarus IDE. The following components are added to the component palette in the Lazarus IDE: + Register is a procedure used to register components declared in the forms.pp unit for use in the Lazarus IDE. The following components are added to the component palette in the Lazarus IDE:

Standard Tab