Standard controls used in the Lazarus Component Library (LCL).

stdctrls.pp contains standard controls used in Lazarus Component Library (LCL) applications. Most of the controls are found on the Standard tab in the Lazarus IDE component palette, including:

- TButton
- TLabel
- TEdit
- TMemo
- TToggleBox
- TCheckBox
- TRadioButton
- TListBox
- TComboBox
- TScrollBar
- TGroupBox

The following controls are added to the Additional tab in the Lazarus IDE component palette:

- TStaticText

Determines the case for text in an edit box or a combo-box control.

TEditCharCase is an enumerated type with values that determine the case used for text in controls like TCustomComboBox and TCustomEdit. TEditCharCase is the type used to implement the CharCase property in both TCustomComboBox and TCustomEdit.

Normal mode (no case conversion).
Converts every character entered to upper case.
Converts every character entered to lower case.
How text in the edit box is displayed.

TEchoMode is an enumerated type with values that control whether text in a control is displayed with or without obfuscation. TEchoMode is the type used to implement the EchoMode property in TCustomEdit.

Characters are shown unmodified.
All characters are shown as spaces.
All characters shown as the value in PasswordChar.
Indicates the visibility for scrollbars on a control.

TScrollStyle is an enumerated type with values that indicates the visibility for one or more scrollbars displayed for an associated edit control. TScrollStyle is the type used to implement the ScrollBars property in TCustomMemo.

No scrollbars are displayed.
A horizontal scrollbar is shown.
A vertical scrollbar is shown.
Both horizontal and vertical scrollbars are shown.
A horizontal scrollbar is shown only when needed.
A vertical scrollbar is shown only when needed.
Both scrollbars are shown only when needed.
The scroll action type, as reported by the widget.

TScrollCode is an enumerated type with values that represent scroll actions received from the widgetset class for a scrollbar. The positions and values in the enumeration correspond to the constants defined in the LCLType unit, and include:

- SB_LINEUP
- SB_LINEDOWN
- SB_PAGEUP
- SB_PAGEDOWN
- SB_THUMBPOSITION
- SB_THUMBTRACK
- SB_TOP
- SB_BOTTOM
- SB_ENDSCROLL

Values in TScrollCode are passed as an argument to the Scroll method in TCustomScrollBar, and subsequently to the TScrollEvent event handler in the OnScroll property.

Scroll one line up (column left).
Scroll one line down (column right).
Scroll one page up (left).
Scroll one page down (right).
Scroll to the specified position.
Scroll tracking to the specified position.
Scroll to the top (left) end.
Scroll to the bottom (right) end.
Scrolling finished.
Defines an event handler type for scrollbar events.

TScrollEvent is an object procedure which defines an event handler signalled when a scroll event occurs in the scrollbar widgetset class. The event handler is called before the new Position is set for the control. The value in Position can be adjusted to implement custom scrollbar behavior.

TScrollEvent is the type used to implement the OnScroll event handler in TCustomScrollBar.

The scrollbar for the event notification.
The scroll action for the notification.
New position for the scrollbar.

The suggested new scroll position. Change this value to implement custom scroll behavior.

The base class for TScrollBar.

TCustomScrollBar is a TWinControl descendant which defines the base class for a scrollbar, such as TScrollBar. TCustomScrollBar can be used for horizontal or vertical scrollbars displayed on a form or scrolling window control.

A scrollbar allows the content in a client area to be scrolled when it extends beyond the window bounds. TCustomScrollBar provides the properties, methods, and events needed to interface with the widgetset class for the platform or operating system.

Use the Kind property to specify the orientation for the scrollbar.

Use Min, Max, SmallChange, LargeChange, PageSize and Position properties to control the scrolling behavior for the scrollbar.

Use the OnChange and OnScroll event handlers to respond to programmatic changes to the scrollbar, or messages received from the widgetset class.

See TControlScrollBar for information about scrollbars used for windowed controls.

TScrollingWinControl TControlScrollBar TWinControl
Performs actions needed to translate and apply scrollbar notification messages.
Message examined and applied in the method.
Always returns
Always returns True.
Sets the value for the Kind property.
New value for the property.
Sets the value for the Max property.
New value for the property.
Sets the value for the Min property.
New value for the property.
Sets the value for the Position property.
New value for the property.
Sets the value for the PageSize property.
New value for the property.
Handles the LM_HSCROLL message for the control.
Message handled in the method.
Handles the LM_VSCROLL message for the control.
Message handled in the method.
Handles the CN_CTLCOLORSCROLLBAR message for the control.
Message handled in the method.
Handles the LM_ERASEBKGND message for the control.
Message handled in the method.
Registers the widgetset class created for new instances of the control.

WSRegisterClass is an overridden procedure used to register the widgetset class instance created for new instances of the control. WSRegisterClass calls the inherited method, and calls RegisterCustomScrollBar for the widgetset.

TLCLComponent.WSRegisterClass
Gets the default size for new instances of the class.

GetControlClassDefaultSize is an overridden TSize class function used to get the default size for new instances of the class.

GetControlClassDefaultSize sets the values in members in the return value. The CX member contains the width for the new instance, and is set 121 (pixels). The CY member contains the height for the new instance, and is set to the number of pixels returned from GetSystemMetrics for the SM_CYHSCROLL constant.

TControl.GetControlClassDefaultSize
TSize instance with the default width and height for the control.
Initializes the creation parameters for the class instance.

CreateParams is an overridden method used initialize the creation parameters for the class instance. CreateParams calls the inherited method, and ensures that the Params argument is updated to include the value from the Kind property in the style information for the TCreateParams instance. This ensures that the correct orientation for the scrollbar is used in the creation parameters.

TCreateParams TWinControl.CreateParams
The creation parameters and flags for the instance.
CreateWnd
- calls inherited CreateWnd then initializes various Scroll Info properties.

The inherited method creates the interface object, sets parameters and assigns the handle. Then the size of scrollbar, maximum and minimum values, page size and position of scrollbar are set.

TWinControl.CreateWnd
Invokes the OnChange event handler for the control.

Change is a procedure used to perform the Changed method in the ancestor class, and to signal the OnChange event handler (when assigned) for the control. Change is called when SetParams is used to update the Position, Min, Max, or PageSize values in the scrollbar.

TControl.Changed
Signals the OnScroll event handler.

Scroll is a method used to signal the OnScroll event handler (when assigned) for the control.

ScrollCode contains the scrollbar command constant for the scroll operation. ScrollPos contains the new position for the scrollbar when the operation is completed.

Scroll is called from the implementation of the private DoScroll method, which handles scrollbar control messages and sets the values for the arguments to the method.

Scroll command code for the operation; up or down a line, a page, to the top or bottom, etc.
The new position for the scrollbar.
Gets the preferred size for new instances of the class.

CalculatePreferredSize is overridden in TCustomScrollBar. The inherited method is called, and the value in PreferredHeight or PreferredWidth is updated, based on the value in Kind, to use the corresponding value from GetSystemMetrics.

TWinControl.CalculatePreferredSize GetSystemMetrics
Preferred width calculated for the control.
Preferred height calculated for the control.
True when space is reserved for theme element details in the calculated dimensions.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry.

Create ensures that the component style is updated to csScrollBar and sets the initial bounds for the control to the values returned from GetControlClassDefaultSize. Create sets the default values for properties, like:

TabStop
  Set to True.
ControlStyle
  Includes the values: [csFramed, csDoubleClicks, csOpaque]. Excludes the values: [csAcceptsControls, csDoubleClicks, csCaptureMouse, csSetCaption].
Kind
  Set to sbHorizontal.
Position
  Set to 0.
Min
  Set to 0.
Max
  Set to 100.
SmallChange
  Set to 1.
LargeChange
  Set to 1.

Owner of the class instance.
Updates the Min and Max values, the size of the page, and the position in the scrollbar.

SetParams is an overloaded procedure used to update the values in the TScrollInfo structure passed to the widgetset class. Values passed in parameters are stored in the TScrollInfo instance, and used to validate the new settings for the scrollbar.

SetParams raises an EInvalidOperation exception if the value in AMax is smaller than the value in AMin.

The value in APosition is normalized to ensure that it is in the range specified by AMin and AMax.

APageSize is set to 0 (zero) if it contains a negative value.

When any of the parameter values differ from the current values in the class instance, the class instance is updated. SetScrollInfo is called to apply the changed values when a handle has been allocated for the control. SetScrollPos is called when APosition contains a value different than the one in the class instance. The Change method is called to process the updated values in the control and signal the OnChange event handler (when assigned). The SetParams method in the widgetset class is called to synchronize the changes.

SetParams is called when a new value is assigned to the Position, Min, Max, or PageSize property.

Value applied to the scrollbar position.
Value applied to the scrollbar minimum value.
Value applied to the scrollbar maximum value.
Value applied to the scrollbar page size.
Contains the scrollbar orientation, horizontal or vertical.

Kind is a TScrollBarKind property which indicates the orientation for the scrollbar.

Setting a new value for the property causes the Constraints for the control to be updated with values from the widgetset class. The widgetset class is also notified of the new value for the property. SetBounds is called to refresh the Width and Height for the control.

The default value for the property is sbHorizontal.

TControl.Constraints TControl.Width TControl.Height TWinControl.SetBounds
The distance to scroll on an click beneath the slider.

A large change is produced by clicks on the blank area above or below the slider; it is rather analogous to the Page Down or Page Up functions of the Keyboard, and is typically set up to move the slider and the control contents by a full page (window size).

Use SmallChange for the value applied when the Up or Down arrows are clicked, or when one of the cursor keys is pressed to navigate in the associated control.

The maximum value for the bottom or rightmost position depending on orientation.
The minimum value for the top or leftmost position depending on orientation.
The size of the slider relative to the total scroll range.
The position of the slider in the scrollbar.
The distance to scroll when the up or down button is clicked.

A small change occurs when the up or down buttons are clicked, or by up/down keyboard commands. It is typically used for scrolling by a few pixels, or by a single row or column of text.

Use LargeChange for the value applied when clicking the thumb in the scrollbar, or when using the Home or End keys to navigate in the associated control.

Enables navigation using the Tab key.

Allows the user to navigate to this control, by pressing the Tab key. The default value for the property is True in TCustomScrollBar.

TWinControl.TabStop
Event handler signalled when the value in Position, Min, Max, or PageSize is changed.

OnChange is a TNotifyEvent property which contains an event handler signalled when scroll information is updated in the control. OnChange is signalled (when assigned) from the Change method, and occurs when the value in Position, Min, Max, or PageSize is changed using SetParams.

Use the OnScroll event handler to respond to events signalled for control messages dispatched to the Scroll method.

Event handler signalled when scrollbar messages are applied.

OnScroll is a TScrollEvent property which provides an event handler signalled when the position for the scrollbar has been changed.

Sender contains the scrollbar for the event.

ScrollCode contains the scroll command constant for the operation.

ScrollPos contains the new position for the scrollbar when the operation is completed. The event handler can be used to override the value in ScrollPos before it is applied to the Position property in the class instance.

OnScroll is signalled (when assigned) from the Scroll method, and occurs when control messages, like CNHScroll and CNVScroll, are processed and applied.

Use the OnChange event to respond to programmatic changes to property values in the scrollbar.

A control that allows the user to scroll the content in an associated control by moving a slider.

A control that allows the user to scroll the content in a windowed control, by moving a slider.

TScrollBar appears as a long rectangular track bar, within which a smaller contrasting block or slider can move up and down (or from side to side in a horizontal ScrollBar). It has small triangular indicators or pointers on one or both ends of the bar, depending on the widgetset.

Clicking with the mouse on one of the pointers moves the slider a small distance (SmallChange) in the specified direction. Clicking with the mouse in the blank area of the scrollbar above or below the slider makes the slider move by a larger increment (LargeChange).

The slider can also be moved by clicking on it with the mouse, and holding down the button while moving the mouse. The slider then follows the mouse until the button is released.

If the mouse has a scrollwheel, the slider also can be moved by rotating the wheel.

The arrow keys or the Page Up/Page Down keys on the keyboard can be used to move the slider, too.

The location of the slider along the track is held in the Position property. It's the programmer's responsibility to ensure that the content of the window is scrolled to the new Position of the scrollbar.

The base class for TGroupBox, TRadioGroup and TCheckGroup.

TCustomGroupBox is a visual component used to organize related controls into a group. It acts a container. TCustomGroupBox is the base class for TGroupBox, TRadioGroup and TCheckGroup. Do not create instances of TCustomGroupBox; use one of the descendent classes.

TRadioGroup TCheckGroup
Default size for new instances of the class.
Updates the control style when the parent background is used.

UpdateOpaque is a method used to update the control style flags when the parent background is used for the control. When the ParentBackground property is set to True, ControlStyle is updated to remove the csOpaque flag. If ParentBackground is not enabled, ControlStyle is updated to include the csOpaque flag.

Ensures that creation parameters are updated for the control.

CreateParams is overridden in TCustomGroupBox to ensure that the Style information in Params is updated to include the value BS_GROUPBOX.

TWinControl.CreateParams TCreateParams BS_GROUPBOX
Creation parameters updated in the method.
Sets the value for the Color property.

SetColor is a method used to set the value in the Color property. It calls the inherited method on entry.

When the value for the Color property is set to clDefault, or has the same value as the Color property in Parent, no additional actions are performed in the method. Otherwise, the value in ParentBackground is set to False.

TControl.Color
New value for the property.
Sets the value for the ParentBackground property.

SetParentBackground is an overridden method in TCustomGroupBox used to set the value for the ParentBackground property. It calls the inherited method on entry.

When the property value is set to True and ParentColor is enabled, the Color property in the Parent control is assigned to the Color property for the group box. Otherwise, clDefault is assigned to the Color property.

SetParentBackground calls the UpdateOpaque method to ensure that the ControlStyle flags for the control reflect the transparency needed to draw the parent background.

TControl.ParentColor TControl.Parent clDefault
New value for the property.
Handles the CM_PARENTCOLORCHANGED message for the control.

Calls the inherited method on entry to update the value in the Color property. Calls UpdateOpaque to adjust the control style flags when the parent color is applied.

TControl.ParentColor TControl.CMParentColorChanged
Control message handled in the method.
Constructor for the class instance.

Create is the overridden constructor for the class instance. It calls the inherited constructor on entry to the method. Create ensures that the component style is set to the value csGroupBox, and includes the value csAcceptsControls in the ControlStyle property. Create calls SetInitialBounds to resize the control using the values returned from GetControlClassDefaultSize.

TControl.ControlStyle TControl.SetInitialBounds
Owner of the class instance.
Indicates if the control uses the background from the parent.

The write access specifier is overridden in TCustomGroupBox. It calls the inherited method on enty.

If AParentBackground is True and ParentColor is True, the Color from the Parent control is assigned to the Color property. Otherwise, the value clDefault is stored in the Color property.

The UpdateOpaque method is called to adjust the control style flags in the control.

The default value for the property is True.

TWinControl.ParentBackground
A container that allows a number of objects to be grouped physically and conceptually on a form.

TGroupBox is a TCustomGroupBox descendant which implements a visual component used to organize related controls into a group. It acts as a container for controls added to the component, and is assigned as the parent for each control.

TGroupBox sets the visibility for properties defined in ancestor classes.

Status values for an emulated TextHint display in a control.

TEmulatedTextHintStatus is an enumerated type with values which indicate the status for an emulated TextHint display in a control. TEmulatedTextHintStatus is the type used for the EmulatedTextHintStatus property in both TCustomComboBox and TCustomEdit.

An emulated TextHint not currently displayed for the control.
An emulated TextHint is currently being shown for the control. The value for control has been temporarily set to the value in TextHint.
The emulated TextHint is being displayed. Occurs while the HintFont is being created, and the hint text value and password character are passed to the widgetset class. Changes to thsShowing when the actions have been completed.
Defines the behavior of the AutoComplete feature in a combo-box control.

TComboBoxAutoCompleteTextOption is an enumerated type with values which control the auto-completion features and behaviors in combo-box controls. Values from the enumeration are stored in the TComboBoxAutoCompleteText type used in the AutoCompleteText property in TCustomComboBox and descendent classes.

Enable Auto-Completion features.
Perform Auto-Complete only when cursor is at the end of the string.
Retains the case of characters user has typed. This option has no effect if cbactEndOfLineComplete is not set.
Search for the completion string with case sensitivity.
Search completion strings in ascending order when set. Otherwise, search in descending order.
Set of TComboBoxAutoCompleteTextOption values.

TComboBoxAutoCompleteText is a set type used to store zero (0) or more values from the TComboBoxAutoCompleteTextOption enumeration. TComboBoxAutoCompleteText is the type used to implement the AutoCompleteText property in TCustomComboBox and descendent classes. It is also the type used for the DefaultComboBoxAutoCompleteText constant which defines the default values used in combo-box controls.

Default values for the AutoCompleteText property in combo-box controls.

DefaultComboBoxAutoCompleteText is a constant which contains the set of default values used in the AutoCompleteText property in combo-box controls. DefaultComboBoxAutoCompleteText is assigned to the property in the constructor for the class instance.

DefaultComboBoxAutoCompleteText contains the following values from the TComboBoxAutoCompleteTextOption enumeration:

- cbactEndOfLineComplete
- cbactSearchAscending

The display style available for combo-box controls.

TComboBoxStyle is an enumerated type with values which control the display style for combo-box controls. TComboBoxStyle is the type used for the Style property in TCustomComboBox and descendent classes.

The combo-box has an edit control and a button to open and close the drop-down list. This is the default value used for the control.
The combo-box has an edit control and a list box which is always visible.
The combo-box has a drop-down list for selecting an entry. The selected value is displayed like a label and is not editable.
Similar to csDropDownList, but is owner-drawn with a fixed height for items in the list.
The drop-down list elements are owner-drawn and can have a variable height for items in the list.
Helper for the TComboBoxStyle type.

TComboBoxStyleHelper is a type helper for TComboBoxStyle. TComboBoxStyleHelper provides convenience methods used to examine, adjust, or translate values in the TComboBoxStyle enumeration.

For example:

// does the style include an edit box? if AComboBox.Style.HasEditBox then DoSomething;

// does the style use owner-draw? if AComboBox.Style.IsOwnerDrawn then DoSomething;

// does the style use variable height items? if AComboBox.Style.IsVariable then DoSomething;

// toggle the edit box visibility and use in the current style AComboBox.Style := AComboBox.Style.SetEditBox(False);
Determines if the style includes an edit box.
True if an selected item value is editable.
Enables or disables an edit box according to the current style.
Style values after adding or removing the edit box.
True enables the edit box; False disables the edit box.
Indicates if the combo-box control is owner-drawn.
True if the style includes an owner-drawn option.
Indicates if list items can have a variable height in the combo-box control.
True when the option is included for variable height list items.
Alias for the TOwnerDrawState type in lcltype.pp.

TOwnerDrawState instances are passed as an argument to methods which draw list items in controls, like TCustomComboBox.DrawItem and TCustomListBox.DrawItem.

TOwnerDrawState
Specifies an event handler used to paint a single item in an owner-drawn list box or combo-box.

TDrawItemEvent is an object procedure type which specifies an event handler signalled to paint an single item in a owner-drawn list box or combo-box control. Arguments passed to the event handler identify the control, the index for the list item, the canvas coordinates, and the drawing state for the operation. The event handler is responsible for rendering the list item to its control in its entirety when the control uses owner-drawn style settings.

TDrawItemEvent is the type used to implement the OnDrawItem property in TCustomComboBox and TCustomListBox. An application must implement and assign an object procedure using the signature for the handler to respond to the event notification.

The control for the owner-drawn operation.
Index of the list item to draw.
The Canvas rectangle for the list item.
Flags describing the drawing state for the list item.
Specifies an event handler used to get the Height for a single item in an owner-drawn list box or combo-box.

TMeasureItemEvent is an object procedure type which specifies an event handler signalled to get the height for a single item in an owner-drawn list box or combo-box control. Arguments passed to the handler include the control for the event notification, the index position for the item measured in the handler, and the derived height for the item.

TMeasureItemEvent is the type used for the OnMeasureItem property in TCustomComboBox and TCustomListBox. An application must implement and assign a procedure using the signature for the handler to respond to the event notification. The handler should account for variable height items when enabled in settings for the control.

The list box or combo-box control.
Index of the list item to measure.
Height of the list item in pixels.
The base class for combo-box components.

TCustomComboBox is a TWinControl descendant which implements the base class for combo-box components in the LCL (Lazarus Component Library).

A combo-box is visually represented as an edit control and a scrollable list of items which can be selected. The list can be always visible, or opened when needed using a drop-down indicator. In addition, the items in the control be drawn using using the built-in mechanisms for the widgetset class or using an owner-drawn style.

Despite similarities in appearance to TCustomEdit and TCustomList, the class inherits no properties from these classes (Delphi compatible).

Use the Style property to control the display style and drawing mechanism enabled for Items in the control.

Use properties like AutoComplete, AutoCompleteText, and AutoDropDown to control the behavior of the edit field or drop-down list in the control.

Use Items to access existing list items defined the control. Use AddItem or AddHistoryItem to add entries to the list items in the control. Use OnGetItems to dynamically populate the Items in the control when the drop-down list is displayed.

Do not create instances of TCustomComboBox. Use one of the descendent classes, like TComboBox or TComboBoxEx.

Used internally, to return the state of arrow keys from temporary change.
Gets the value for the AutoComplete property.
Value for the property.
Gets the value for the DroppedDown property.
Value for the property.
Gets the value for the ItemWidth property.
Value for the property.
Sets the value for the AutoComplete property.
New value for the property.
Sets the value for the ArrowKeysTraverseList property.
New value for the property.
Sets the value for the ItemWidth property.
New value for the property.
Sets the value for the CharCase property.
New value for the property.
Sets the value for the ReadOnly property.
New value for the property.
Sets the value for the TextHint property.
New value for the property.
Tries to display an emulated TextHint for the control.

ShowEmulatedTextHintIfYouCan is a method which attempts to display an emulated TextHint for the control. ShowEmulatedTextHintIfYouCan calls CanShowEmulatedTextHint to determine if the control requires an emulated TextHint display, and is in a state which allows it. If CanShowEmulatedTextHint returns True, the ShowEmulatedTextHint method is called to display the TextHint.

ShowEmulatedTextHintIfYouCan is called from the implementation of the InitializeWnd and WMKillFocus methods, and when a new value is assigned to the TextHint property.

Displays an emulated TextHint for the control.
Hides an emulated TextHint display for the control.
Performs actions needed when the Sorted property is changed.
Handler for custom drawing items; calls DrawItem.
Message handled in the method.
Determines the height of an item, using MeasureItem in variable owner-draw mode.
Message handled in the method.
Handles selection change messages for the control.

LMSelChange is a method used to handle a LM_CHANGED message for the control. No actions are performed in the method during component streaming, when the control is freed, or at design-time.

LMSelChange calls the Select method to signal the OnSelect event handler (when assigned).

Message handled in the method.
Handles a CN_COMMAND notification message for the control.

CNCommand is a method used to handle a CN_COMMAND control notification message for the control. CNCommand examines TheMessage to determine the actions needed for the NotifyCode in the message.

When NotifyCode is CBN_DROPDOWN, the following actions are performed:

- DroppedDown is set to True.
- Calls DropDown to signal the OnDropDown event handler (when assigned).
- Calls AdjustDropDown to configure the height and width for the drop down list.

When NotifyCode is CBN_CLOSEUP, the following actions are performed:

- DroppedDown is set to False.
- Calls CloseUp to signal the OnCloseUp event handler (when assigned).

Message handled in the method.
Handles LM_CHAR window messages for the control.

Prevents ordinary characters from triggering accelerator keys.

Message handled in the method.
Implements a handler for the LM_KILLFOCUS message.
Message handled in the method.
Implements a handler for the LM_SETFOCUS message.
Message handled in the method.
Determines if an emulated TextHint can be displayed for the control.
True when emulated TextHints are used, and the control state allows the hint display.
Updates the specified creation parameters to include additional flags for the control.

CreateParams is an overridden method in TCustomComboBox, and calls the inherited method on entry. CreateParams ensures that the style information in Params is updated to include constants needed to represent values in the Style property for the control. The following constants are also included:

- WS_VSCROLL
- CBS_AUTOHSCROLL
- CBS_HASSTRINGS

When Sorted is set to True, the value CBS_SORT is also included in the style information in Params.

TWinControl.CreateParams
Creation parameters updated in the method.
Synchronizes the control and its widgetset class instance when the handle is created.

InitializeWnd is overridden in TCustomComboBox to ensure that the widgetset class and the current class instance are synchronized. InitializeWnd calls the inherited method on entry.

InitializeWnd gets the string values for list items stored in the widgetset class instance (when present), and applies them to the Items property. Other property values are forwarded to the widgetset class instance, including:

- ArrowKeysTraverseList
- DropDownCount
- ItemIndex
- MaxLength
- ReadOnly
- Style

Values in SelStart and SelLength are re-applied to update the edit box in the control to reflect any changes to property values.

InitializeWnd is called from CreateWnd after the Window handle has been allocated, and before any child handles are allocated.

TWinControl.InitializeWnd TWinControl.CreateWnd
Destroys the handle for the control (and its children).

DestroyWnd is an overridden method in TCustomComboBox used to destroy the handle for the windowed control. This occurs when the control is freed, and when the handle is re-created in the widgetset class. DestroyWnd ensures that values for the ItemIndex and Items properties are retrieved from the widgetset class before it is destroyed or re-created. The value in Sorted is applied to the Items retrieved from the widgetset class.

DestroyWnd calls the inherited method prior to exit.

DestroyWnd calls RaiseGDBException to raise a catchable debugger exception if a handle has not been allocated for the control.
TWinControl.DestroyWnd RaiseGDBException
Selects an item in the control when auto-complete is enabled and activated by a key event.

Calls the Select method to signal the OnSelect event handler (when assigned). DoAutoCompleteSelect is called from the KeyUp method when auto-completion has enabled in the AutoCompleteText property, and an alphanumeric key is handled in the method.

Updates the control when the Enter key is applied.

DoEnter is an overridden method used to update the edit and list box when the Enter or Return key is handled in messages to the control. The inherited method is called to signal the OnEnter event handler (when assigned).

DoEnter uses the value in Style to determine if an edit box is enabled for the control. If an edit box is not used, no additional actions are performed in the method.

When AutoSelect is enabled, the SelectAll method is called to select the text in the edit box and to locate the entry in the Items for the control. AutoSelected is updated to indicate if SelText matches the value in Text.

TWinControl.DoEnter TWinControl.OnEnter
Updates the control when the CM_EXIT control message is handled.

DoExit is an overridden method in TCustomComboBox used to perform actions needed when the CM_EXIT control message is handled for the control. DoExit sets the value in AutoSelected to False, and calls the inherited method to signal the OnExit event handler (when assigned).

TWinControl.DoExit TWinControl.OnExit
Draws a list item, using the OnDrawItem handler (when assigned).

DrawItem is a procedure used to draw a list item defined in the Items property. DrawItem is called when the LM_DrawListItem message is handled for the control. Arguments passed to the method include the position in Items for the value drawn, the canvas rectangle where the drawing occurs, and the drawing state for the list item.

DrawItem signals the OnDrawItem handler (when assigned) to perform the drawing operation. Otherwise, default painting is performed by filling the background for the Canvas rectangle (if needed) and calling the InternalDrawItem routine.

TRect
The position for the item drawn in the method.
The area to paint on the Canvas.
The drawing state for the item (selected...).
Handles key up events forwarded from the LCL interface.
Key code examined in the method.
Shift, Ctrl, or Alt modifier for the key code.
Gets the height for an item in the drop-down list.

MeasureItem is a procedure used to get the height for an item in the drop-down list for the control.

MeasureItem is called when the LM_MeasureItem message is handled for the control. The value in ItemHeight has already been updated in the message handler, and is used for a list box Style that has a fixed item height. MeasureItem is called from the message handler when the Style uses a variable item height. The derived item height is stored in the ItemHeight property when it is a non-zero positive value.

MeasureItem signals the OnMeasureItem event handler (when assigned) to calculate the height for the specified item. The value in the Index argument determines the string value in Items used for the calculation. TheHeight is updated with the derived height for the list box item. An application must implement the OnMeasureItem event handler to calculate the height for variable height items in the control.

TLMMeasureItem
The index of the item whose height is required.
The height of the item, in pixels, calculated in the OnMeasureItem handler.
Default size (bounds) for the new class instance.
Handles the LM_CHANGED message for the control.

LMChanged is a procedure used to handle a LM_CHANGED message received for the control. LMChanged occurs when the widgetset class calls the LCLSendChangeMsg routine for the control. LMChanged calls the Change method to perform the control message and to signal the OnChange event handler (when assigned).

TControl.Perform
Message handled in the method.
Handles the CM_WANTSPECIALKEY message for the control.
Message handled in the method.
Invokes the OnChange handler, signalling a change in the edit box.

Change is a procedure used to perform actions needed when the value for the control is changed. Change is called from the LMChanged method used to process the change notification message. Change calls the Changed method, inherited from TControl, to Perform the control message. The OnChange event handler is signalled (when assigned).

TControl.Changed TControl.Perform
Signals the OnSelect event handler when ItemIndex is changed.

Select is a procedure called when the item selection in the drop-down list for the control has changed. This can happen when text is entered and auto-completion is enabled, or when a new value is selected from the drop-down list.

Select signals the OnSelect event handler (when assigned). For Delphi compatibility, the event handler is not signalled when ItemIndex contains -1 (Text is not located in the Items for the control).

Signals the OnDropDown event handler.

DropDown is a procedure called whenever the drop-down list is displayed. DropDown is called when a CN_Command message with a CBN_DROPDOWN notification code is handled for the control. DropDown signals the OnDropDown event handler (when assigned).

Use DroppedDown to determine if the drop-down list has been displayed.

Signals the OnGetItems event handler.

GetItems is a procedure used to dynamically populate the values stored in the Items property. GetItems signals the OnGetItems event handler (when assigned) to perform actions needed to fill the Items property. GetItems is called from the IntfGetItems method executed when the widgetset class makes its drop-down list visible.

Sets the value for the Items property.
New value for the property.
Called when the drop-down list is closed.

CloseUp is a method called whenever the drop-down list for the control is closed. CloseUp is called when a CN_Command message with a CBN_CLOSEUP notification code is received in the control.

CloseUp does not perform any actions in the method at design-time, when the component is being loaded using LCL streaming, or when the control is freed.

CloseUp signals the OnEditingDone event handler when an edit box is enabled in the Style property in the control. The OnCloseUp event handler is signalled (when assigned).

When AutoSelect is enabled, the SelectAll method is called and the AutoSelected property is updated.

Adjusts the extent for the drop-down list.

AdjustDropDown is used to adjust the bounds for the drop-list list in the control. AdjustDropDown is called when the drop-list becomes visible, and when the value in the ItemWidth property is changed.

AdjustDropDown does not perform any actions in the method if a handle has not been assigned for the control.

AdjustDropDown ensures that the value in DropDownCount is applied (when needed) to the drop-down list for the control. The minimum height and width for the list is calculated using the ItemWidth and ItemHeight properties. The dimensions are passed to the widgetset class using the SetComboMinDropDownSize routine in the LCL interface.

Performs actions needed to auto-adjust the control using the specified layout policy.

DoAutoAdjustLayout is an overridden method used to apply an auto-adjust layout policy to the control. DoAutoAdjustLayout calls the inherited method on entry.

DoAutoAdjustLayout ensures that the item height for the control is scaled using the factor in AYProportion when AMode contains the lapAutoAdjustWithoutHorizontalScrolling or lapAutoAdjustForDPI layout adjustment policy values.

DoAutoAdjustLayout is called from the AutoAdjustLayout method.

TControl.DoAutoAdjustLayout TLayoutAdjustmentPolicy
Layout adjustment policy applied in the method.
Factor used to scale horizontal dimensions.
Factor used to scale vertical dimensions.
Returns the number of items defined in the drop-down list.

GetItemCount is an Integer function used to get the number of values stored in the Items for the control. It is a convenience method, and is equivalent to reading the value for the Count property in Items.

The number of Items defined in the control.
Gets the value for the ItemHeight property.
Value for the property.
Gets the value for the SelLength property.
Value for the property.
Gets the value for the SelStart property.
Value for the property.
Gets the value for the SelText property.
Value for the property.
Gets the value for the ItemIndex property.
Value for the property.
Gets the value for the MaxLength property.
Value for the property.
Sets the value for the DropDownCount property.
New value for the property.
Sets the value for the DroppedDown property.
New value for the property.
Sets the value for the ItemHeight property.
New value for the property.
Sets the value for the ItemIndex property.
New value for the property.
Sets the value for the MaxLength property.
New value for the property.
Sets the value for the SelLength property.
New value for the property.
Sets the value for the SelStart property.
New value for the property.
Sets the value for the SelText property.
New value for the property.
Sets the value for the Sorted property.
New value for the property.
Sets the value for the Style property.
New value for the property.
Gets the text/caption for the control.

RealGetText is an overridden method in TCustomComboBox which provides additional debugging support in the method. RealGetText ensures that a handle has been allocated for the control and the value in Text is available in the widgetset class prior to calling the inherited method.

The return value contains the Caption assigned to the control, or an empty string ('') when the control handle is not available.

TWinControl.RealGetText
Caption for the control, or an empty string.
Updates ItemIndex when the new value for the control is updated.

RealSetText is an overridden method in TCustomComboBox. It ensures that ItemIndex is updated with the ordinal position in Items where the AValue argument is found. If there are no values stored in Items, ItemIndex is set to -1. A visible emulated TextHint is hidden when AValue is not an empty string ('').

The inherited method is called prior to exit. This causes the widgetset class to be updated when its Handle is valid. The value in Caption is also updated, and a CM_TEXTCHANGED control message is performed for the control.

TWinControl.RealSetText TWinControl.RealGetText
The new value for the control.
Filters keys used to traverse the list.

KeyDown is an overridden method in TCustomComboBox. KeyDown ensures that keys like Escape, Tab, and Return are handled in the manner needed for the Style in the control. If the values in Key and Shift are not specifically handled in the method, the inherited KeyDown method is called.

TWinControl.KeyDown
The pressed key.
The state of the modifier keys and mouse buttons.
Handles AutoComplete and AutoSelect for the control.

KeyUp is an overridden method in TCustomComboBox, and calls the inherited method on entry.

KeyUp ensures that the VK_RETURN key code causes SelectAll to be called when AutoCompletion or AutoSelect is enabled for the control. AutoSelected is set to True when the values in SelText and Text are the same.

In addition, alphanumeric key codes are used to perform AutoComplete text location using the options enabled in the AutoCompleteText property. The values in Text, SelStart, and SelLength are updated (when needed) and the Select method is called to reflect the operation.

KeyUp is called when TLMKeyUp control messages are processed in the handlers for the control.

TWinControl.KeyUp
Virtual key code examined in the method.
Shift, Alt, or Ctrl modifier for the key code.
UTF8KeyPress
converts character case if required then calls the inherited method.

UTF8KeyPress is an overridden method, and calls the inherited method on entry. The inherited method emulates a UTF-8-encoded keypress. The UTF-8 encoding should be used when there is the possibility that input/output will occur in any language that requires multiple bytes to represent each character, i.e. all languages except English.

UTF8KeyPress uses the value in CharCase to determine if the character case for UTF8Key is converted:

ecNormalCase
  No conversion is required.
ecLowerCase
  Calls UTF8LowerCase to convert the value in UTF8Key.
ecUpperCase
  Calls UTF8UpperCase to convert the value in UTF8Key.

UTF8LowerCase UTF8UpperCase TWinControl.UTF8KeyPress
UTF-8-encoded character examined in the method.
Highlights the selected text in the control when the left mouse button is released.

MouseUp is an overridden method, and calls the inherited method on entry. MouseUp ensures that the selected text in the control is highlighted when the Left mouse button is released and AutoSelect is enabled. MouseUp calls SelectAll to select the value in the Text property in the edit box for the control. The value in AutoSelected is set to True.

No selection is performed in the method when AutoSelect is set to False.

TControl.MouseUp
Mouse button for the notification.
Shift, Alt, or Ctrl modifier for the notification.
Horizontal coordinate for the mouse pointer.
Vertical coordinate for the mouse pointer.
Selects the list item with the specified text.

SelectItem is a Boolean function used to select the list item in the control with the value specified in AnItem. The return value is True when the Items property contains an entry with the value in AnItem.

The value in ItemIndex is updated with the ordinal position in Items for the specified value, or -1 when AnItem does not exist in Items. When the value in ItemIndex is changed, the Click and Select methods are called to refresh the control display and to signal the OnClick and OnSelect event handlers.

TControl.Click TControl.OnClick
True when a matching item was found and selected.
The text to find in Items.
Indicates if the width and/or height for the control can be adjusted by a layout policy.

ShouldAutoAdjust is an overridden method in TCustomComboBox. It sets the values in the AWidth and AHeight parameters to indicate if the control can adjust the bound(s) when a layout policy is appiled to the control. True indicates the value for the property can be adjusted.

ShouldAutoAdjust is used in the implementation of the DoAutoAdjustLayout method.

TControl.ShouldAutoAdjust
Always set to True in the method.
True when AutoSize is not enabled for the control.
The default height of an item in the drop-down for the control.

ItemHeight is an Integer property which contains the height (in pixels) used when drawing an item in the drop-down list.

The value for the property is retrieved from the widgetset class when not already assigned in the class instance, or when using an owner-drawn Style. Setting a new value for ItemHeight calls the SetItemHeight method in the widgetset class for owner-drawn Styles.

The property value is updated when the LM_MeasureItem message is handled for the control. When variable height items are enabled in Style, the OnMeasureItem event handler must be implemented to calculate the height for individual value in Items.

ItemHeight, ItemWidth, Items, and DropDownCount are used in the AdjustDropDown method to determine the dimensions for the drop-down list in the control.

The minimum width of the items in the drop-down list.

ItemWidth is an Integer property which contains the minimum number of pixels used when displaying the static or drop-down list for the control. The default value for the property is 0 (zero).

Setting a new value for the property causes the AdjustDropDown method to be called to adjust the dimensions for the list to the values in ItemHeight, ItemWidth, and DropDownCount.

Use ItemHeight to specify the number of pixels required for items displayed in the drop-down list for the control.

The maximum length for text entered in the edit box for the control.

MaxLength is an Integer property which contains the maximum length for a value entered in the Text for the control. It controls the number of characters allowed in the edit box, but does not limit the length of the value that can be directly assigned to Text. MaxLength is passed to and read from the widgetset class when a handle has been assigned for the control.

The default value for the property is 0 (zero), and indicates that a maximum length has not been specified in the property. Setting the value for the property does not alter the existing value in Text.

Event handler signalled for user changes to the text in the edit box.

OnChange is a TNotifyEvent property which implements the event handler signalled when the value in the edit box has been changed.

The event applies to interactive changes to Text made by the user, not those made programmatically. Note that this differs from how other OnChange events work. For example: TEdit.OnChange is triggered by text changes that occur in code. This event is also triggered when the item selection is changed using the drop-down list in the combo-box.

OnChange is signalled (when assigned) in the Change method called when the control messages are handled in the window procedure. An application must implement and assign an object procedure using the signature in TNotifyEvent to respond to the event notification.

TNotifyEvent
Handler invoked when the drop-down list closes.

OnCloseUp is a TNotifyEvent property which contains the event handler signalled when the drop-down list in the control is hidden or closed. It can be used to perform any actions needed in an application, such as comparing pre-selection and post-selection values for properties. An application must implement and assign an object procedure to the property to respond to the event notification.

TNotifyEvent
Handler for special painting of an item (in owner-draw mode).

OnDrawItem is a TDrawItemEvent property which contains an event handler used to draw an item in the drop-down list for the control. OnDrawItem is used when Style contains one of the owner-drawn values. See TComboBoxStyle for more information about the owner-drawn styles available.

OnDrawItem is signalled (when assigned) from the DrawItem method. The event handler is responsible for all drawing operations needed to render the specified list item. This can include the text and any images or overlays drawn for the list item. Use the Canvas property to render the list item to the specified coordinate rectangle.

If OnDrawItem is not assigned, an internal default drawing routine is called to render the list item. It handles filling the canvas rectangle with the background for the item, and drawing the item text using the style, layout, and alignment defined in the control.

Handler invoked when the list has dropped down.

OnDropDown is a TNotifyEvent property with the event handler signalled when the drop-down list for the control is displayed. OnDropDown is signalled (when assigned) from the DropDown method. DropDown is called when the CBN_DROPDOWN message is handled for the control.

Implement and assign an object procedure to the handler to respond to the event notification.

TNotifyEvent
Handler invoked when widgetset items list can be populated.

OnGetItems is a TNotifyEvent property with the event handler signalled to load the values used in the Items property.

OnGetItems is signalled (when assigned) from the GetItems method. Some widgetsets, like GTK, call GetItems (via IntfGetItems) just before the drop-down list is displayed. Others call GetItems when the handle for the control is created. OnGetItems provides one event to handle both cases.

An application should implement and assign an object procedure to the handler to respond to the event notification. The procedure must perform any actions needed to load the values for the Items property from an appropriate source.

Values can always be stored in the Items property using code at run-time, or by entering the values using the Object Inspector at design-time.

TNotifyEvent
Handler invoked when the height for an item is needed.

OnMeasureItem is a TMeasureItemEvent property with the event handler signalled to get the height for an item displayed in the list box for the control.

OnMeasureItem is signalled (when assigned) from the MeasureItem method. MeasureItem (and OnMeasureItem) are used when the Style property indicates that the control uses a variable height for each item displayed in the list box. OnMeasureItem occurs when the LM_MeasureItem message is handled for the control.

Use the Index argument to get the value in Items examined in the event handler. Use ItemWidth to determine the maximum width allowed for the variable height item. Canvas can be used to get text metrics for the Font used in the control. Update the AHeight argument with the height calculated for the item.

Use ItemHeight for the item height used for fixed height drawing styles.

Handler invoked when an item is selected.

OnSelect is a TNotifyEvent property with the event handler signalled when an item is selected in the list box for the control.

OnSelect is signalled (when assigned) from the Select method when ItemIndex contains a positive non-zero value. Select (and subsequently OnSelect) are called from multiple methods in TCustomComboBox. SelectItem calls Select when the value in ItemIndex is changed as a result of assigning a value to Text. KeyUp calls Select when the value in Text is updated by auto-completion features in the control. Select is also called when the LM_SelChange message is handled for the control.

Implement and assign an object procedure to the handler to respond to the event notification.

TNotifyEvent
Uses the Color from the Parent control, when enabled.

ParentColor determines if the control should use the Color from the Parent control, when enabled. The default value for the property is False in TCustomComboBox.

When this property is True, all changes to the Color of the parent will also be applied to the Color of the control, ensuring that they both contain same value. If the Color of the control is changed by the application, then ParentColor will be automatically set to False.

TControl.ParentColor
Determines whether the list entries are sorted in alphanumeric order.

Sorted is a Boolean property which indicates if values in Items are stored and displayed in alphanumeric sort order.

Setting this property to True enforces ascending alphanumeric case-insensitive sorting of the list. When set to True, new entries are added in sort order, and not to the end of the Items list. When a new value is assigned to the property, the UpdateSorted method is called to set the Sorted property in Items to the corresponding value. ItemIndex is also set to the location in Items where the value in Text is stored, or -1 when not found.

The default value for the property is False.

Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create ensures that resources are allocated for members in the class instance. Create sets the default values for properties, including the following:

ControlSyle
  Removes csCaptureMouse from the style flags.
DropDownCunt
  Set to display 8 items by default.
ArrowKeysTraverseList
  Set to True to enable cursor key navigation in the control.
AutoCompleteText
  Set to the values in the DefaultComboBoxAutoCompleteText constant.
AutoSelect
  Set to True.
CharCase
  Set to ecNormal.
AutoSize
  Set to True. AutoSize must be true by default since some widgetsets (win32, wince) ignore the combo-box height and others (gtk2) look ugly with a very small height.

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

Destroy is the overridden destructor for the class instance. Destroy calls DestroyHandle if a handle has been allocated for the control. Destroy frees resources allocated for the Canvas property, and calls the inherited destructor.

Gets the values in the Items property for the widgetset class.

IntfGetItems is a procedure used to populate the values in the Items property. IntfGetItems is called when the widgetset class retrieves the values for the items displayed in the control. Some widgetsets perform this action when the handle is allocated, or the focus is set for the control. Others perform the action when the drop-list for the control is displayed.

IntfGetItems calls the GetItems method to signal the OnGetItems event handler (when assigned).

Adds the specified string (and optional object) to the Items displayed in the control.

AddItem is a procedure used to add the specified value (and an optional associated object) to the Items in the control. AddItem calls the AddObject method in Items to store the values in Item and AnObject.

TStrings.AddObject
The string added to Items.
The associated object, can be Nil.
Add an item as the first entry in the history list for the control.

AddHistoryItem is a procedure used to add the values in Item and AnObject to the beginning of the list items displayed for the control. AddHistoryItem uses the value in CaseSensitive to determine if case is significant when comparing the value in Item to the existing value at the beginning of Items.

AddHistoryItem calls the InsertObject method in Items to store the values at the initial position in the Items list (ordinal position 0). When Item exists at another position in Items, it is removed.

MaxHistoryCount contains the maximum number of entries allowed in the Items property. When the number of entries in Items exceeds the value in MaxHistoryCount, the excess is removed from the end of the Items property.

When SetText is True, the value in Item is stored to the Text property.

TStrings.InsertObject TStrings.Delete
The string to be added to the list.
Optional associated object added for the item.
The maximum number of items that can be added to the history.
When True the string also is copied into the edit box for the control.
True means that the list can contain multiple items with the same text, differing in case.
The object associated with the item; can be Nil.
Removes all items from the list, and clears the edit box.

Clear is a procedure used to remove all values stored in the Items property for the control. Clear calls the Clear method in Items to removed the strings and any associated objects stored in the TStrings property. Clear sets the value in Text to an empty string ('') which forces the value in ItemIndex to be changed to -1.

Use the Clear method in Items to remove all of the the values stored in Items but keep the current value in Text.

Use ClearSelection to reset the value in ItemIndex and de-select the selected value in Items.

TStrings.Clear
Removes the item selection in the list box for the control.

ClearSelection is a procedure used to remove the current item selection in the list box for the control. This causes the value in ItemIndex to be changed to -1, and the value in Text is set to an empty string ('').

Use SelStart, SelLength, and SelText to access or modify the text selection in the edit control. Set SelLength to zero (0) to remove the text selection in the edit box.

Indicates the case conversion applied to the value entered in the edit box for the control.

CharCase is a TEditCharCase property which indicates the case conversion applied to the value entered in the edit box for the control. The default value for the property is ecNormal, and indicates that no case conversion is performed.

Setting a new value for the property causes the value in Text to be converted to the specified case by calling either the UTF8LowerCase or the UTF8UpperCase routine. Text is not modified when ecNormal is assigned to the property.

The value in CharCase is used when the UTF8KeyPress is called to apply key press events for the control.

UTF8LowerCase UTF8UpperCase
Indicates whether the drop-down list has been displayed.

DroppedDown is a Boolean property which indicates whether the drop-down list for the control has been displayed.

Reading the value for the property causes the widgetset class to be queried when a handle has been allocated for the control. Otherwise, the stored value for the property is used.

Setting a new value for the property causes the widgetset class to be notified of the changed property value. No actions are performed if a handle has not been allocated for the control, or during LCL component streaming. Setting this property opens or closes the drop-down list.

The value in DroppedDown is maintained when the Style for the control is altered, when CBN_DROPDOWN or CBN_CLOSEUP control messages are handled, and when key down events are handled which change the visibility of the drop-down list.

Deprecated.
Deprecated. Will be removed in Lazarus 2.2.
Selects the text content in the edit box for the control.

SelectAll is a procedure used to select/highlight the Text displayed in the edit box for the control. SelectAll requires a Style that uses an edit box in the control. No actions are performed in the method when Style does not include an enabled edit box.

SelectAll sets the value in SelStart to 0 (zero) to move the selection to the beginning of the edit box, and sets SelLength to the number of UTF-8-encoded characters in Text. No selection/highlighting is performed when Text contains an empty string ('').

SelectAll is called from methods like DoEnter, KeyUp, CloseUp, and MouseUp.

Positions the list box using partial text matching.

AutoComplete is a Boolean property which indicates if partial text matching is used to locate values in the Items displayed for the control. When set to True, keystrokes entered in the edit box for the control are used to locate a value in Items which begins with the entered value. The ItemIndex property is updated with the ordinal position for the matching item, or -1 if an entry is not found that starts with the partial value.

Reading the value in AutoComplete causes the AutoCompleteText property to be examined, and returns True when the value cbactEnabled is included in the auto-complete options. Assigning a value to AutoComplete causes the AutoCompleteText property to include or exclude the corresponding value as needed.

Use AutoCompleteText to enable or disable other auto-complete features and behaviors in the control.

Auto-completion related tasks are performed when the KeyUp method handles valid keystrokes for the control.

Use AutoSelect to control whether text is automatically highlighted in the edit box when a new list item is selected in the control.

Options for the behavior of the Auto-Complete feature.

Enabled
  Enable Auto-Completion features.
EndOfLineComplete
  Perform Auto-Complete only when cursor is at the end of the string.
RetainPrefixCase
  Retains the case of characters user has typed. This option has no effect if cbactEndOfLineComplete is False.
SearchCaseSensitive
  Search completion string with case sensitivity.
SearchAscending
  Search completion string in ascending order. False will search in descending order.

This property exists as a Set of Options, so zero or more options may be operational.

Makes the drop-down list appear as soon as the user starts entering text.

AutoDropDown is a Boolean property which indicates if the drop-down list for the control is automatically displayed. When set to False, the drop-down list appears when the down button is clicked, or the Alt+Down key sequence is entered. The value in AutoDropDown is maintained, based on the Style for the control, when KeyDown is called to handle key events.

Use DroppedDown to show or hide the list box for the control.

Selects the entire content of the edit box when the control receives the focus.

When True, the edit control will select all its text when:

- It receives focus
- The Enter key is pressed.
- A new item is selected.

True indicates that the selection was marked automatically by the control.

True indicates that the combo-box control has just performed an AutoSelect operation so that subsequent mouse-clicks and keystrokes proceed normally without selecting the text.

False is set when the combo-box control loses focus.

Indicates if keyboard Arrow (or cursor) keys to move through the list.

ArrowKeysTraverseList indicates if Arrow (or Cursor) keys on the keyboard can be used to navigate the Items displayed in the drop-down list box for the control. The default value for the property is True.

The value in the property is passed to the widgetset class when the LCL interface object is created. Changing the value for the property causes the widgetset class to be notified using its SetArrowKeysTraverseList method.

The property value is used in the implementation of the KeyDown method, and may be updated as the drop-down list for the control is displayed or hidden. For some widgetsets (Darwin), the arrow keys cannot be handled in the LCL and the keyboard message(s) are ignored.

Provides access to the drawing surface for the control.

Canvas is a read-only TCanvas property which provides access to the drawing surface used for the control. The class implementation actually uses a TControlCanvas instance in the member.

Canvas is used in methods like DrawItem, and in private methods which handle the LM_DrawListItem message for the control. Canvas is also passed as an argument to methods in the ancestor class like PaintTo. Canvas can be useful in OnDrawItem event handler when used to render list items for the control.

TWinControl.PaintTo TCanvas TControlCanvas
The maximum number of Items visible in the drop-down list for the control.

DropDownCount is an Integer property which specifies the maximum number of values from Items that can be displayed in the drop-down list for the control. Setting a new value for the property causes the widgetset class to be notified using its SetDropDownCount method when a handle has been allocated for the control.

DropDownCount is used (along with the item count and ItemHeight) in the AdjustDropDown method to set the minimum dimensions for the drop-down list.

The default value for the property is 8.

Status for the emulated TextHint in the control.

EmulatedTextHintStatus is a read-only TEmulatedTextHintStatus property which contains the status value for an emulated TextHint display in the control. EmulatedTextHintStatus is used when a value has been assigned to the TextHint property and the widgetset does not natively implement the capability. The LCL emulates the TextHint display by assigning the value in TextHint to the Text for the control.

EmulatedTextHintStatus is updated in the private ShowEmulatedTextHint and HideEmulatedTextHint methods.

The list of items displayed in the combo-box control.

Items is a TStrings property which contains the strings displayed in the static or drop-down list for the control. Settings a new TStrings value for the property causes the Assign method to be called to load the string values into the current class instance.

As an alternative, use the OnGetItems event handler to dynamically populate the values in Items when the drop-down list for the control is displayed (or created).

String values in Items can be ordered alphabetically by setting the Sorted property to True. This also affects the ordinal position for new values added to Items. Its index will be the position in the sorted order, and not necessarily at the end of the list.

Use ItemIndex to determine the ordinal position in Items with the value displayed the edit box for the control.

TStrings
The index of the currently selected item, or -1 if none is selected.

ItemIndex is an Integer property which contains the ordinal position in Items for the current list box selection in the control. The first value in Items is at index position 0 (zero). The final value in Items is at the index position ItemCount-1. When no value is selected in the list box, ItemIndex is set to -1. The default value for the property is -1.

When the value for the property is read, the widgetset class is queried when a handle has been assigned for the control.

Assigning a new value to the property causes the value in Text to be updated to reflect the new selection in the control. When ItemIndex is -1, Text is set to an empty string ('').

Disallows free-form entry of Text into the combo-box edit field.

When True, the text can be changed only by selecting an item from the combo-box items list. When False, the text can be changed by free-form entry of a value in the edit field.

Changing the property value doesn't affect the style for the control in any manner. Changing the style doesn't affect the value in the property, as well. For some styles (such as csDropDownList) the property might have no effect because it is ignored.

The number of selected UTF-8 characters in the edit box.

SelLength is an Integer property which indicates the number of UTF-8-encoded characters selected in the edit box for the control. SelLength is used along with SelStart to determine the value in SelText.

Use SelStart to determine the position in Text for the selected value in the edit box for the control.

Use SelText to get the content selected in the edit box. Assigning a new value to SelText causes the value in SelLength to be updated.

SelLength is updated in the SelectAll method after the selection text is updated. It is also updated when KeyUp performs auto-completion for alphanumeric values entered in the control.

zero-based index to the UTF-8 character at the beginning of the selected text in the edit box.

If text is selected in the edit box for the control, this is the starting position. When no text is selected, SelStart is the cursor position and SelLength is 0 (zero).

Writing a new value to the property moves the cursor, and removes the current text selection. Set SelLength after changing SelStart, to establish a new text selection.

SelStart is a zero-based index to UTF-8 character in the Text, in contrast to the usual 1-based string indices. The value 0 means the first UTF-8 character, the value 1 means the second UTF-8 character, etc.

The selected text in the edit box for the control.

SelText is a String property which contains the selected text in the edit box for the control. The property value is determined by the values in SelStart and SelLength. Assign a new string value to replace the selected text within the Text for the control.

Appearance and behavior of the combo-box.

Style is quite Windows centric, reflecting the evolution of combo-box styles. The basic styles are:

csSimple
  Displays an edit box with an attached list (not a drop-down list).
csDropDown
  Displays an edit box with a drop-down list.
csDropDownList
  Values cannot be entered by the user in the edit box, only selected from the drop-down list.

Owner-drawn drop-down lists have been added, with the values:

csOwnerDrawFixed
  All items in the drop-down list are drawn with the same height.
csOwnerDrawVariable
  Each item in the list can have a different height.

Enables or disables navigation using the Tab key.

Allows the user to navigate to this control, by pressing the Tab key. The default value for the property is True in TCustomComboBox.

TWinControl.TabStop
The value in the edit box for the control.

Text is a public property in TCustomComboBox and contains the TCaption value for the control. It is the value displayed in the edit box for the control.

Setting a new value for Text in program code causes the RealSetText method to be called. The new property value is located in the Items property, and the value in ItemIndex is updated with the ordinal position for the found value. A case-insensitive comparison is used to locate the value in Items. The value applied to Text retains the original case used in the new property value. ItemIndex is set to -1 if a value is not located in Items that is a case-insensitive match the new property value.

At run-time, the value in Text can be updated using the edit box for the control when it is enabled for the selected Style (such as csDropDown and csSimple). When Style contains csDropDownList, the edit box is not displayed. But the button for the drop-down list handles the first character key pressed, and locates a value in Items when the button has focus.

AutoComplete enables or disables auto-completion for the value in Text. When set to True, the first item that matches the entered character(s) is located in Items and the value is highlighted in the drop-down list for the control. By default, a case-insensitive comparison is used to find the entered value. Case sensitivity can be enabled using cbactSearchCaseSensitive in the AutoCompleteText options, and requires the value in Items to be an exact case-sensitive match for the character(s) entered in the edit box. Text is updated to contain the complete value for the entry in Items. By default, the case for the value in Items is retained and applied to Text. Include cbactRetainPrefixCase in AutoCompleteText options to use the value as entered in the edit box in the Text property.

When the edit box loses input focus, ItemIndex is updated with the ordinal position in Items where the partial value was found. It is set to -1 when a matching value could not be located in Items.

When AutoComplete is disabled (set to False), the entered value is still located located and highlighted in the drop-down list for Items. However, the value in Text is not expanded and the the value in ItemIndex is not updated. The item must be selected using the drop-down list to apply the value to Text and update the value in ItemIndex.

Use ItemIndex to select one of the Items by its ordinal position, and apply the value to the Text property.

A test application was used to verify the described functionality on the Windows platform. It has been attached to Issue #39413 to allow testing for other platforms / widgetsets.

Default hint text shown when the Text property is empty and the control is not focused.

TextHint is a TTranslateString property which contains the inline hint text displayed for the control. TextHint is displayed in the editable area for the control when Text is an empty string ('') and the control is not focused. As a TTranslateString value, it can be translated using the LCL localization mechanism when enabled for the project.

A combination of an edit box and a (drop-down) list allowing one of several options to be chosen.

The Text property reflects the text entered into the edit box, or selected from the list.

The selectable values are kept in the Items list. Clicking on the ellipsis character (...), next to Items in the Object Inspector, opens an editor which allows the designer to populate the Items list.

At run-time, the entry selected from the list replaces the text in the edit box, and ItemIndex holds the (zero-based) index number of the selected item.

If no value is selected from the drop-down list, the default text (if any) remains, or any information typed directly into Text will be returned, and ItemIndex takes the value of -1.

Determines how items are drawn in a list box control.

TListBoxStyle is an enumerated type with values that determine how items in the list box control are populated and drawn. TListBoxStyle is the type used to implement the Style property in TCustomListBox.

Items drawn by the widgetset class.
Items drawn by user code, and all items have the same height.
Items drawn by user code, and each item can have a different height.
Not used in the current LCL version.
Specifies an event handler for change notifications from a list box control.

TSelectionChangeEvent is an object procedure type which specifies an event handler signalled when the select is changed in a list box control. Arguments passed to the handler identify the list box control, and the origin of the change notification.

TSelectionChangeEvent is the type used to implement the OnSelectionChange property in TCustomListBox. The application must implement and assign an object procedure using the signature for the handler to respond to the event notification.

The list box control for the notification.
True if the user changed the selection, False if changed by code.
Represents options available in a list box control.
Draws a focus rectangle when owner draw is enabled.
Set type used to store values from the TListBoxOption enumeration.

Set type used to store zero or more values for the TListBoxOption enumeration. TListBoxOptions is the type used for the Options property in TCustomListBox.

The base class for TListBox.

TCustomListBox is a TWinControl descendant which specifies the base class used for a list box control. A list box displays a scrollable list which allows selection of one or more of the item values.

TCustomListBox provides methods, properties, and events used to display, order, and select item values. The Items for the control can be assigned at design-time in the Lazarus IDE, or stored at run-time. Owner-drawn styles are available to render icons or bitmaps along with the text for the items, or using a variable height for list items. A Canvas property is provided for owner-drawn usage. Items in the list box can be display in one or more columns.

Do not create instances of TCustomListBox; use the TListBox descendant.

TWinControl
Value for the property.
Value for the property.
Value for the property.
Raises an exception if an invalid index position is used to access Items in the list box control.
Index value generating the exception.
New value for the property.
New value for the property.
New value for the property.
Sends values for ExtendedSelect and MultiSelect to the widgetset class.
Sends values in Items and Sorted to the widgetset class.
Handles the LM_DrawListItem message for the control.
Message handled in the method.
Handles the LM_MeasureItem message for the control.
Message handled in the method.
Handles the LM_SelChange message for the control.
Message handled in the method.
Handles Left mouse button Up events for the control.
Prevents Click from being called twice when using ClickOnSelChange to trigger a click event.
TControl.WMLButtonUp
Message handled in the method.
Notifies the widgetset class when the selected item in the control is changed.
Ordinal position for the item.
True when the item is selected; False when it is not selected.
Resets cached item selections for the control.
Sets the cached selection state for the specified item.
Ordinal position in Items to update in the cache.
Selection state for the cached item.
Gets the selection state for the specified item from the cache.
True when the item is selected in the cache.
Ordinal position in Items for the cached item.
Copy selection state into the cache.
Ordinal position in Items for the entry updated in the cache.
Pointer to the data stored in the cache for the specified item.
Sends the cached selection state to the widget.
Called to restore the ItemData after a handle is created.
Ordinal position for the item data read from the cache.
Pointer to the data read from the cache for the specified item.
Notifies the widgetset class that a Drag operation is starting.

BeforeDragStart is an overridden method in TCustomListBox used to perform actions needed to start a drag operation for the control. In TCustomListBox, this means that the DragStart method in the widgetset class is called. No actions are performed in the method if the Handle has not been allocated for the control.

BeforeDragStart is called when mouse up, down, and move messages are handled by the DragManager for an application.

Starts a non-immediate drag / dock operation for the control.

Calls the inherited BeginDrag method with the Immediate argument set to False. The drag operation is detected and handled by the DragManager for the application.

TControl.BeginAutoDrag
Determines the standard Height of the items, when no widget has yet been created.
Height for the items in the control.
Sends the design-time value for ItemIndex to the widgetset class.
TComponent.Loaded
Initializes the creation parameters for the class instance.

CreateParams is an overridden method used initialize the creation parameters for the class instance.

CreateParams calls the inherited method, and ensures that the Params argument is updated to include style constants needed for properties in the list box control. These include the constants needed for the Sorted, MultiSelect, and Columns properties. Owner-drawn constants are also included based on the value in Style. Style constants are always included for scrollbars (horizontal and vertical), non-integral item height, string content, and notify events.

TWinControl.CreateParams
The creation parameters and flags for the instance.
Updates Items from the widgetset class and invalidates the item cache.

InitializeWnd is an overridden method used to synchronize the control and the widgetset class. InitializeWnd copies values for the Items property from the ones allocated in the widgetset class. The value in ItemIndex is passed to the widgetset class when needed. An internal flag is reset to invalidate the item cache for the control, and the item data from the widgetset class is applied. Finally, the value in ScrollWidth is passed to the widgetset class.

TWinControl.InitializeWnd
Frees the handle for the window and its canvas.

Calls the inherited method to free the window handle and update flags for the control. Frees the handle for the Canvas when assigned.

TWinControl.DestroyWnd
Caches the Items stored in the widgetset class.

FinalizeWnd is an overridden method used to capture values from the widgetset class when the handle is destroyed or re-created. FinalizeWnd gets the value for ItemIndex when the handle is being re-created. Values in Items (and its cached item data) are copied before they are freed in the widgetset class. The value in Sorted is re-applied to the new values in Items.

FinalizeWnd calls the inherited method prior to exit.

TWinControl.FinalizeWnd
Default dimensions for a new instance of the class.
Ensures that the Item index is within the bounds for the Items in the control.

CheckIndex is a procedure used to ensure that the specified index value is within the range of values allowed for the Items in the control. CheckIndex examines the value in AIndex, and raises an IndexOutOfBounds exception if it is not in the range 0 (zero) to Items.Count-1.

CheckIndex is used in the access specifiers for the Selected property (GetSelected, SetSelected).

Raises an IndexOutOfBounds exception when the index is out of bounds.
Index position examined in the method.
Gets the value for the ItemHeight property.
Value for the property.
Gets the value for the ItemIndex property.
Value for the property.
Gets the value for the SelCount property.
Value for the property.
Gets the value for the Selected property.
The selection state of the item.
Ordinal position for the item examined in the method.
Returns the size for cached item data in the control.

Passed as an argument when creating the TExtendedStringList instance used in the Items property.

TExtendedStringList
Number f bytes required for the item data in the cache.
Returns a pointer to the cached item data.

Gets a pointer to the item data for the specified list box item. The return value contains the attributes stored in Items at the position in AIndex. Items is cast to a TExtendedStringList instance to access its indexed Records property.

Raises an InvalidOperation exception when the cache is marked as invalid, i. e. when the widgetset class has already been created.
TExtendedStringList.Records
Pointer to the item data in the cache.
Ordinal position in Items for the values retrieved in the method.
Sets the value for the ExtendedSelect property.
New value for the property.
Sets the value for the ItemIndex property.
New value for the property.
Sets the value for the Items property.
New value for the property.
Sets the value for the ItemHeight property.
New value for the property.
Sets the value for the MultiSelect property.
New value for the property.
Sets the value for the Selected property.
Ordinal position for the item updated in the method.
New value for the property.
Sets the value for the Sorted property.
New value for the property.
Sets the value for the Style property.
New value for the property.
Paints an item in owner-draw mode.

DrawItem is a procedure used to render an item in the list box control using the owner-draw mode.

Item contains the ordinal position in Items for the item drawn in the method.

ARect is a TRect instance with the canvas coordinates where the drawing operation is performed.

State contains the drawing state for the owner-drawn item.

DrawItem signals the OnDrawItem event handler (when assigned). An internal default drawing method is used when the event handler has not been implemented.

DrawItem is called when the LM_DrawListItem message is handled for the control.

Ordinal position for the item drawn in the method.
Canvas rectangle with the coordinate for the drawing operation.
Drawing state for the item.
Performs actions needed to auto-adjust the control using the specified layout policy.

DoAutoAdjustLayout is an overridden method used to apply an auto-adjust layout policy to the control. DoAutoAdjustLayout calls the inherited method on entry.

DoAutoAdjustLayout ensures that the item height for the control is scaled using the factor in AYProportion when AMode contains the lapAutoAdjustWithoutHorizontalScrolling or lapAutoAdjustForDPI layout adjustment policy values.

DoAutoAdjustLayout is called from the AutoAdjustLayout method.

TControl.DoAutoAdjustLayout
Layout adjustment policy applied in the method.
Factor used to scale horizontal dimensions.
Factor used to scale vertical dimensions.
Signals the OnSelectionChange handler.

DoSelectionChange performs actions needed when the selected item in the list box control has been changed. DoSelectionChange signals the OnSelectionChange event handler (when assigned).

User indicates if the selection was changed as a result of user interaction with the control, as opposed to a change performed in code at run-time. When User is set to True, and ClickOnSelChange is enabled, an internal flag is set to prevent execution of the method by a subsequent mouse click.

DoSelectionChange is called when the LM_SelChange message is handled for the control, and when a new value is assigned to the ItemIndex property. User is set to False when the selection change is caused by setting a new value in ItemIndex.

True when the selection change results from user interaction with the control.
Sends the value in ItemIndex to the widgetset class.
Handles Tab, Return, and Escape characters in control messages.
Message examined in the method.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create sets the component style to csListBox, and allocates resources needed for the Items and Canvas properties. Create sets the default values for properties, including:

BorderStyle
  Set to bsSingle.
ClickOnSelChange
  Set to True.
ItemIndex
  Set to -1 to indicate no item is selected.
ExtendedSelect
  Set to True.
Options
  Set to DefOptions.
Canvas
  Cast to a TControlCanvas instance for the current class instance.
ParentColor
  Set to False.
TabStop
  Set to True.

Create calls SetInitialBounds to assign the dimensions from the GetControlClassDefaultSize method.

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

Destroy is the overridden destructor for the class instance. Destroy frees resources allocated for the Items and Canvas properties. Destroy calls the inherited destructor prior to exiting from the method.

Adds an item to the list.

AddItem is a method used to add a string (and an optional associated object) to the Items for the control. AddItem calls the AddObject method in Items using Item and AnObject as arguments.

Item contains the string value added to the Items in the control.

AnObject is an optional object instance associated with the item, and contains Nil when an object instance has not been assigned. The object can be retrieved using the Items.Objects property for the ItemIndex, and must be cast to the required class type to access values in the object instance.

The item text.
The associated object, or Nil when not used.
Performs the Changed method when the control is clicked.

Click is an overridden method in TCustomListBox, and calls the inherited method on entry. Click calls the Changed method (inherited from TControl) to perform the CM_CHANGED control message. Click is used in the implementation of the DoSelectionChange method when the control is changed by a user interaction.

TControl.Changed TControl.Click
Removes all items from the list box control.

Clear is a procedure used to remove all values stored in the Items property. Clear calls the Clear method in Items, and sets the value in ItemIndex to -1 to indicate that no item is selected in the control.

TExtendedStringList.Clear TStrings.Clear
Unselects all items in the control.

ClearSelection is a procedure used to clear one or more selected items in the control. When MultiSelect is enabled, values in the Selected property are reset to False. Otherwise, the ItemIndex property is set to -1 to indicate that no item is selected in the control.

Gets the index for the item at the given client coordinates.

GetIndexAtXY is an Integer function used to get the ordinal position in Items for the list item at the specified coordinates. No actions are performed in the method if a handle has not been allocated for the control (the widgetset class instance). GetIndexAtXY calls the GetIndexAtXY method in the widgetset class to get the return value.

The item index, -1 if an item could not be found.
The X client coordinate.
The Y client coordinate.
Gets the index position for the item at the specified vertical coordinate.

Calls GetIndextAtXY to get the return value using the vertical coordinate in Y. The value 1 is used as the horizontal coordinate.

The item index, -1 if no item could be found.
The vertical client coordinate.
Get the text for all selected items as a string value.

GetSelectedText is a String function used to retrieve a string with all selected items in the control. The return values uses each selected entry in Items separated by the LineEnding character sequence for the platform or operating system. The return value is an empty string ('') when ItemIndex does not contain a positive non-zero value (no item is selected) or SelCount contain 0 (zero).

GetSelectedText iterates over the values in Items, and includes the string when its Selected property is set to True. This is useful when MultiSelect is enabled for the control.

The item strings, one per line.
Get the item index for the given client coordinates.

ItemAtPos is an Integer function used to get the index position in Items for the value at the specified screen coordinates.

Pos is TPoint instance with the X and Y coordinates used in the method.

Existing indicates whether the return value is set to -1 or the number of entries in Items when Pos refers to entry which does not exist. When Existing is set to True, -1 is returned for an invalid entry. Otherwise, the value in Item.Count is returned.

ItemAtPos calls GetIndexAtXY using the X and Y values in Pos to locate the index for the item.

The calculated item index, can be out of the Items bounds.
The item position.
True when the index is requested for insertion of a new item.
Returns the client rectangle for an item (including scrollbar area).

Index must be in the range 0 to ItemCount to be considered valid. The result is valid also for the next item, that will be added subsequently.

The item area; all zeroes for an invalid item index.
The tentative item index.
Returns True if the item is at least partially visible in the scrollable list.

ItemVisible is a Boolean function used to determine if the item at the position in Index is at least partially visible in the list box control. The return value is False for the following conditions:

- Index is out of range for the values in Items.
- An item rectangle could not be retrieved from the widgetset class.
- The item rectangle is invalid for the control (where Bottom < 0 or Top > ClientHeight).

Use ItemFullyVisible to determine if the specified list box item is fully visible in the control.

True when the specified item is at least partially visible in the control.
Ordinal position for the item examined in the method.
Returns True if the item is fully visible in the scrollable list.

ItemFullyVisible is a Boolean function used to determine the item at the position in Index is fully visible in the list box control. The return value is False under the following conditions:

- Index is out of range for the values in Items.
- An item rectangle could not be retrieved from the widgetset class.
- The item rectangle is invalid or obscured in the control (where Top < 0 or Bottom > ClientHeight).

Use ItemVisible to determine if the specified item is at least partially visible in the list box control.

True when the specified item is fully visible in the list box control.
Ordinal position for the item examined in the method.
Blocks selection changes during update to the widgetset class.

Increments the internal counter used to track selection change events. Used in the implementation of the AssignCacheToItemData, InitializeWnd, FinalizeWnd, UpdateSelectionMode, UpdateSorted, and SetItems methods.

The value is examined when the LM_SelChange message is handled for the control.

UnlockSelectionChange is used to decrement the internal counter.

Makes the item at ItemIndex visible, possibly scrolling the list.

MakeCurrentVisible is a procedure used to ensure that the current item selected in the control is also visible. The current selection is the value in Items stored at the position in ItemIndex. No actions are performed in the method when ItemIndex is out of bounds.

MakeCurrentVisible calls ItemFullyVisible to determine if the item at ItemIndex is already visible in the scrollable list. No additional actions are needed in the method when the item is already visible. Otherwise, the value in ItemIndex is assigned to the TopIndex property which causes the selected item to scroll to the top of the visible area in the list box.

Gets the height for an item in the list.

MeasureItem is a procedure used to get the height for an item displayed in the list box control.

Integer is the ordinal position in Items for the value measured in the method.

TheHeight is a variable parameter which contains the calculated height for the text in the item. The value on entry is the text height for the current font calculated using the Canvas for the control. The value returned in TheHeight is assigned to the ItemHeight property when it is a non-zero value.

MeasureItems signals the OnMeasureItem event handler (when assigned) using the arguments passed to the method. An application must implement an object procedure to calculate the height for the requested item using the logic required.

MeasureItem is called when the LM_MeasureItem message is handled for the control.

Ordinal position in Items for the string examined in the method.
The height of the item in pixels, can be changed by the event handler.
Selects all items in the list (in ExtendedSelect mode).

SelectAll is a procedure used to mark all of the values defined in the Items property as Selected. No actions are performed in the method when Items is empty (Count is 0). SelectAll calls the SelectRange method to select items at position 0 (zero) through Count-1 (inclusive).

Use Selected to change the selection state for an individual item when MultiSelect is enabled. Set ItemIndex to -1 to clear the current selection when MultiSelect is not used.

Changes the selection state for a range of Items in the control.

SelectRange is a procedure used to change the selection state for a range of Items in the list box control to the value specified in ASelected.

ALow and AHigh contain the ordinal positions in Items affected in the method. ALow must be a positive integer value or zero (0). AHigh must be less than the value in the Count property for Items. When either value is out of range, no actions are performed in the method.

When MultiSelect is set to True, the widgetset class is notified of the changes to item selection state and DoSelectionChange is called to trigger the OnSelectionChange event handler (when assigned). No actions are performed in the method when MultiSelect is set to False.

SelectRange is similar to the SelectAll method, but limits the affected items to the specified range of values - and only when MultiSelect is enabled.

Use SelCount to determine the number of Items selected in the control when MultiSelect is enabled.

Use Selected to maintain the selection state for a single entry in the Items property.

Ordinal position for the initial item changed in the method.
Ordinal position for the final item changed in the method.
True if the items are selected; False when they are unselected.
Removes one or more selected entries from the Items property.

DeleteSelected is a procedure used to delete one or more entries in the Items property based on their selection state.

DeleteSelected uses the value in MultiSelect to determine if multiple values in Items are examined and removed. When MultiSelect is True, the values in Items are visited in reverse order and the Delete method in Items is called if the item is Selected. When MultiSelect is not enabled, the value in the ItemIndex property is used to examine a single entry and remove it when it is Selected.

No values are removed from Items when none of the entries in Selected are True.

Removes a previous selection change lock.
Line style used for the border on the control.

Indicates the line style drawn as a border around the control. The default value for the property is bsSingle in TCustomListBox.

TWinControl.BorderStyle
Drawing surface where the control is drawn.

Canvas is a read-only TCanvas property with the drawing surface where the control is drawn.

Its value is assigned the constructor for the class instance, and uses a TControlCanvas instance to maintain an association between the control and its device context. It is freed when the control is destroyed.

Values in the Font and Brush properties are assigned to Canvas, and used to measure and draw the Items for the control.

TWinControl.Brush TControl.Font TControlCanvas TCanvas
Allows selection changes to generate a Click event.

Delphi generates an OnClick event when the selection changes. The LCL adds a more specific OnSelectionChange event.

Set ClickOnSelChange to False when selection changes should be handled by the OnSelectionChange event, and should not generate an OnClick event. Setting ClickOnSelChange to True gives the Delphi compatible behavior. The default value for the property is True.

The number of visible vertical columns displayed in the control.

A list box can have multiple columns, as well as multiple rows. When Columns is greater than 0 (zero), it specifies the number of columns that are visible without horizontal scrolling. i. e. the width of a single column becomes Width/Columns. Setting a new value for Columns causes the widgetset class to be notified when a handle has been allocated for the control.

The number of items defined in the scrollable list box.

Count is a read-only Integer property which indicates the number of Items defined in the control. Count is provided for Delphi compatibility, and redirects access to the Count property in Items.

True when a contiguous range of items can be selected by a Shift+Click. Default is True.

Normally a click into the list selects one item, and deselects all other items.

When MultiSelect is True, the user can select/deselect further items with Ctrl+Click.

When ExtendedSelect is also True, the user can Shift-click on an item, to select all items between this and the last selected item.

Not implemented: shrink the Height of the widget, so that it only shows fully visible rows.
The default height for an item displayed in the list.

ItemHeight is an Integer property which contains the default height for an item displayed in the list box control. For a list box using the lbStandard Style, the property value is derived using the dimensions in the ItemRect for the item stored at TopIndex. For other styles, the stored property`value is used. Setting a new value for the property causes the RecreateWnd method to be called when a handle has been allocated for the control.

Ordinal position for the currently selected item, -1 if none.

ItemIndex is an Integer property which contains the position for the current selection in the control. If MultiSelect is True, ItemIndex represents the selected item which also has focus. Use the Selected property to access items when MultiSelect is enabled.

The list of all items defined in the control.

Items is a TStrings property which contains the string values (and associated objects) displayed in the list box control. Reading allows access to the contents of the list (TStrings compatible). Assign another string list to the property to replace the Items in the control. Internally, Items is often cast to a TExtendedStringList to access the item attribute data for the entry.

Use ItemIndex to access the selected item in the list box control. Use the Selected property to select or de-select values in Items when MultiSelect is enabled. Use SelectRange to select a range of Items in the control.

TStrings
Allows selection of more than one item from the list.

MultiSelect is a Boolean property which indicates if multiple values in Items can be selected using the Ctrl+Click mouse button, or by setting values in the indexed Selected property. When set to True, selection state is determined by reading / writing the cached item data for the Selected items in the widgetset class. When set to False, the value in ItemIndex is used to determine the selected item.

The default value for the property is False. Setting a new value for the property causes UpdateSelectionMode to be called to notify the widgetset class of the change.

Handler for painting of a list item in owner-draw mode.

OnDrawItem is a TDrawItemEvent property with the event handler signalled to render a list item when an owner-drawn method is used in the Style property. OnDrawItem is signalled (when assigned) from the DrawItem method. DrawItem provides the arguments for the event handler.

An application should implement an object procedure to respond to the event notification. Use the Canvas for the control to get text metrics or render the control and any graphic images. An internal drawing routine which uses the Font, Color, Layout and Alignment in the control is called when OnDrawItem has not been assigned.

TControl.Color TCanvas.TextStyle TTextStyle
Handler invoked when the height for an item is needed.

OnMeasureItem is a TMeasureItemEvent property with the event handler signalled to get the height for specified item in the list box control. OnMeasureItem is signalled (when assigned) from the MeasureItem method, and occurs when the LM_MeasureItem message is handled for the control. MeasureItem provides the arguments passed to the event handler, while the message handler stores the calculated height in ItemHeight when it is not 0 (zero).

An application must implement an object procedure to respond to the event notification. Index contains the position in Items with the string to examine in the event handler. On entry, TheHeight contains the text height for the current Font calculated using the Canvas in the control. The value in TheHeight can be updated with the value derived in the event handler.

Handler invoked when an item is selected in the control.

OnSelectionChange is a TSelectionChangeEvent property with the event handler signalled when a selection is changed in the list box control. OnSelectionChange is signalled (when assigned) from the DoSelectionChange method, and occurs prior to calling the Click method for the control.

The User argument indicates whether the selection change results from user interaction with the control (True), or from code or methods called at run-time (False).

Use the Color from the Parent control, when enabled.

ParentColor determines if the control should use the Color from the Parent control, when enabled. The default value for the property is False in TCustomListBox.

When this property is True, all changes to the Color of the parent will also be applied to the Color of the control, ensuring that they both contain same value. If the Color of the control is changed by the application, then ParentColor will be automatically set to False.

TControl.ParentColor
The virtual width of the list box, in pixels.

ScrollWidth is an Integer property with the logical horizontal extent for the list box, or the scrollable area inside the control. When ScrollWidth is set to a value larger than ClientWidth, the horizontal scrollbar is displayed for the control.

The value for ScrollWidth is read from the widgetset class (at run-time) when a Handle has been allocated for the control. Changing the value for the property causes the value in the widgetset class to be updated.

The default value for the property is 0 (zero).

Use Columns to set the number of adjacent vertical columns used to display the items in the control.

The number of selected items in the list.

SelCount is a read-only Integer property which contains the number of Items selected in the list box control. The return value is the result returned by the GetSelCount method in the widgetset class, or 0 (zero) when a handle has not been allocated for the control. SelCount is significant when the MultiSelect property is enabled.

Use Selected to read or write the selected state for a single value defined in the Items for the control.

Use SelectRange to set the selected state for Items in a specified range of positions.

Use SelectAll to select all Items in the control.

Use ClearSelection to remove all item selections in the control.

The Selected state for an item in the control.

Selected is an indexed Boolean property used to set the selection state for an item defined in the list box control.

The index value is the ordinal position in Items with the selection state value. Read and write access for the property value call the CheckIndex method to verify that the index is in bounds for the defined Items in the control. CheckIndex raises an exception if an index value is not in the required range.

Property values are read from the widgetset class when it has been created, or from the cached selection values when it has not. Write access ensures that ItemIndex is updated as needed, and notifies the widgetset class and/or the item selection cache when a value is changed.

Use SelectAll to set the selection state for all Items in the control.

Use SelectRange to set the selection state for Items in the specified range of positions in the control.

Use ClearSelection to reset the selection state for all Items in the list box control.

Ordinal position in the item list.
Determines whether the list entries are sorted in alphanumeric order.

Sorted is a Boolean property which determines whether the values in Items are sorted and stored in alphanumeric order in the control.

Setting this property to True enables use of ascending alphanumeric case-insensitive sorting of items in the list. When True, new entries are added in sort order, and are not necessarily stored at the end of the list.

Setting a new value for the property causes the private UpdateSorted method to be called to notify the widgetset class of the change in order, or to update the Sorted property in Items when needed.

Appearance of the list box (normal, owner-draw fixed, or owner-draw variable).

Style is a TListBoxStyle property which controls the appearance of the Items drawn in the list box control. The default value for the property is lbStandard, and causes the appearance and text height native to the widgetset to be used. When another value from TListBoxStyle is used, Items are drawn using the routine assigned to the OnDrawItem event handler.

Enables navigation using the Tab key.

Allows the user to navigate to this control, by pressing the Tab key. The default value for the property is True in TCustomListBox.

Index of the first visible (or top-most) item.

TopIndex is an Integer property which contains the ordinal position in Items for the first visible list item in the scrollable control. The default value for the property is 0 (the first value in Items).

The property value is retrieved from the widgetset class when a handle has been allocated for the control. Setting a new value for the property causes the widgetset class to be notified of the value change when a handle has been allocated for the control.

The value in TopIndex is updated in the MakeCurrentVisible method where the current selection in ItemIndex is assigned to the property.

Contains options enabled for the list box control.

Options is a TListBoxOptions property with the options enabled for the list box control. The values in the property are assigned in the Create constructor, and used when the LM_DrawListItem message is handled for the control.

The default value for the property is [lboDrawFocusRect], and draws a focus rectangle for the selected item in the list box.

Control which displays a scrollable list of strings.

The strings are stored in the Items list.

At design time, a click on the ellipsis character (...) next to the Items entry in the Object Inspector opens a string-list editor in which the individual text-strings for the list items can be entered or edited. The editor also allows the entries to be sorted alphabetically in normal or reverse order.

Get or set the height of a single item in the control.

ItemHeight is an Integer property which contains the height used to render the Items in the control.

The property value is used when the drawing Style for the control is set to lbStandard, or when the handle has not been allocated for the control. For other drawing styles, the property value is determined using the item rectangle used for the first visible item in the list or by using the OnMeasureItem event handler.

Changing the value for the property causes RecreateWnd to be called to re-create the widgetset handle for the control.

The value in ItemHeight may be scaled when AutoAdjustLayout is called using a layout policy that includes auto-adjustment for display density.

The base class for controls presenting editable text.

TCustomEdit is a TWinControl descendant which implements the base class for an edit control presenting a single line of text. TCustomEdit provides properties, methods, and events needed for common editing features in the control, including:

- Text
- TextHint
- Modified
- ReadOnly
- MaxLength
- Clear
- NumbersOnly
- CharCase
- EchoMode
- PasswordChar
- AutoSelect
- SelectAll
- SelStart
- SelLength
- SelText
- HideSelection
- ClearSelection
- CaretPos
- CopyToClipboard
- CutToClipboard
- PasteFromClipboard
- Undo

Do not create instances of TCustomEdit in an application; use one of the descendent classes like TEdit, TLabeledEdit, TMaskEdit, or TMemo.

TLabeledEdit TMaskEdit TWinControl
Status for the emulated TextHint for the control.
Displays an emulated text hint when possible.
Displays a TextHint using the hint font for the control.

ShowEmulatedTextHint is a method used to display an emulated Text hint using the hint font for the control. Emulated text hints are used for widgetsets that do not natively support the TextHint capability.

ShowEmulatedTextHint gets the Hint font for the display by calling CreateEmulatedTextHintFont, and passes the value to the widgetset class. The value in Text is set to the text in the TextHint property. The widgetset class is notified of the property changes, and an internal flag used to track emulated hint display is set to True.

The compliment to ShowEmulatedTextHint is HideEmulatedTextHint.

ShowEmulatedTextHint is used in the implementation of the private ShowEmulatedTextHintIfYouCan method.

Hides an emulated TextHint display and restores the editing font and PasswordChar in the control.
Sets the value for the Alignment property.
New value for the property.
Gets the value for the CanUndo property.
Value for the property.
Gets the value for the Modified property.
Value for the property.
Sets the value for the HideSelection property.
New value for the property.
Sets the value for the MaxLength property.
New value for the property.
Sets the value for the Modified property.
New value for the property.
Sets the value for the PasswordChar property.
New value for the property.
Indicates if the value in TextHint can be displayed in the edit control.

CanShowEmulatedTextHint is a Boolean function which indicates if the value in TextHint can be emulated for the edit control. The return value is True when the following conditions are met:

- A handle has been allocated for the control.
- The widgetset class does NOT include the lcTextHint LCL capability flag (the lack of native widgetset support for the feature is why it's being emulated).
- ComponentState indicates that the component is not being loaded using LCL streaming, and is not being edited at design-time.
- TextHint is not an empty string ('').
- Text is an empty string ('').
- The control is not Focused.

CanShowEmulatedTextHint is used in the WMKillFocus method, and when the values in Text or TextHint are applied for the control.

In the current LCL implementation, TextHint display is emulated for all widgetsets except Win32/Win64 (since ComCtIVersionIE6) and QT5.
TWinControl.Focused TComponent.ComponentState
True when the emulated text hint can be displayed.
Gets the preferred size for a new instance of the class.

CalculatePreferredSize is overridden in TCustomEdit, and calls the inherited method on entry. CalculatePreferredSize sets the value in the PreferredWidth parameter to 0 (zero).

TWinControl.CalculatePreferredSize
Preferred width calculated for the control.
Preferred height calculated for the control.
True when space is reserved for theme element details.
Ensures the required creation parameters are set for handle creation.

CreateParams is an overridden method used to ensure that the creation parameters for the control are updated to reflect property values in the control instance. CreateParams is called when the handle for the control is create (or re-created).

CreateParams calls the inherited method on entry, and updates the Style flags in Params to include values required for the control. The following edit style flags are included in the method:

ES_AUTOHSCROLL
  Always included in TCustomEdit.
ES_LEFT
  Included when Alignment contains taLeftJustify.
ES_RIGHT
  Included when Alignment contains taRightJustify.
ES_CENTER
  Included when Alignment contains taCenter.
ES_READONLY
  Included when ReadOnly is set to True.
ES_NUMBER
  Included when NumbersOnly is set to True.
ES_NOHIDESEL
  Included when HideSelection is set to False.

TWinControl.CreateParams
Creation parameters updated in the method.
Initializes the window handle for the control.

InitializeWnd is an overridden method used to ensure that property values from the class instance are stored in the widgetset class when the handle for the control is created (or re-created). InitializeWnd calls the inherited method on entry.

Values in the following properties are posted using methods in the widgetset class:

- CharCase
- EchoMode
- MaxLength
- PasswordChar
- ReadOnly
- Alignment
- CaretPos
- SelStart
- SelLength
- TextHint

The ShowEmulatedTextHintIfYouCan method is called when inline hints are emulated for the widgetset.

TWinControl.InitializeWnd
Applies case conversion (if needed), and updates the editing cursor selection text.

TextChanged is a an overridden method used to perform actions needed when the CM_TEXTCHANGED message is handled for the control. No actions are performed in the method when a previous call to TextChanged has not been completed.

TextChanged uses the value in CharCase to determine if case conversion is applied to the value in Text. When CharCase contains ecUpperCase or ecLowerCase, the corresponding UTF-8 conversion routine is called. When Text is modified in the method, the values in CaretPos, SelStart, and SelLength are re-applied to the control. At run-time, the value in Modified is set to True when Text has been changed in the method.

UTF8UpperCase UTF8LowerCase TControl.TextChanged
Handles changes to the font used in the control.

FontChanged is an overridden method in TCustomEdit. It ensures that the Font used for an emulated TextHint display is (re-)created when visible by calling CreateEmulatedTextHintFont.

FontChanged calls the inherited method to set flags in the control, and to perform notifications of the changed value to any child controls. The hint font is freed when the inherited method is completed.

FontChanged is assigned as the OnChange event handler for the TFont class instance in the Font property.

TWinControl.FontChanged TControl.Font
Object for the event notification.
Performs actions needed when the text in the control is changed.

Change is a procedure used to perform actions need when the CM_CHANGED message is handled in the control. Change calls the inherited Changed method, and signals the OnChange and/or the internal FOnChangeHandler event handlers (when assigned).

Change is called from the TextChanged method after case conversion and updates to the editing cursor and text selection.

TControl.Changed
Signals the OnEnter event handler, and selects the entire text when AutoSelect is True.

This special handling is required when the control is entered using keystrokes (keyboard navigation), and not by a mouse click.

TWinControl.DoEnter
Clear the value in AutoSelected when the control loses focus.
TWinControl.DoExit
Enforces the setting in the ReadOnly property when editing is finished in the control.

EditingDone is an overridden method in TCustomEdit. It ensures that the inherited method is NOT called when the value in ReadOnly is True. EditingDone is called from the KeyUpAfterInterface method when the VK_RETURN key code is handled.

TControl.EditingDone
Gets the value for the CaretPos property.
Value for the property.
Gets the value for the NumbersOnly property.
Value for the property.
Gets the value for the ReadOnly property.
Value for the property.
Gets the value for the SelLength property.
The number of selected UTF-8 characters in the control.
Gets the value for the SelStart property.
Value for the property.
Gets the value for the SelText property.
Value for the property.
Gets the value for the TextHint property.
Value for the property.
Sets the value for the CaretPos property.
New value for the property.
Sets the value for the CharCase property.
New value for the property.
Sets the value for the EchoMode property.
New value for the property.
Sets the value for the NumbersOnly property.
New value for the property.
Sets the value for the ReadOnly property.
New value for the property.
Sets the value for the SelLength property.
New value for the property.
Sets the value for the SelStart property.
New value for the property.
Sets the value for the SelText property.
New value for the property.
Sets the value for the TextHint property.
New value for the property.
Indicates whether child controls using the specified class are allowed.

ChildClassAllowed is overridden in TCustomEdit to use the widgetset class to determine whether child controls can be embedded within the control. The return value is True when the GetLCLCapability method in the widgetset class returns LCL_CAPABILITY_YES for the lcAllowChildControlsInNativeControls query.

TWinControl.ChildClassAllowed
True if a child control using the specified class type are allowed for the control.
Class type for the child control.
Handles mouse up events for the control.

Selects all of the Text in the control when a left mouse button event occurs in the focused control and AutoSelect is set to True.

TControl.MouseUp
Mouse button examined in the method.
Shift / Ctrl / Alt modifier for the mouse event.
Horizontal screen coordinate for the mouse event.
Vertical screen coordinate for the mouse event.
Uses the TextHint display status when getting the value for Text.

RealGetText is an overridden method in TCustomEdit. It ensures that an emulated TextHint display status is considered when getting the value for the Text property. In other words, the inherited method is not called when the TextHint display is visible. The return value is an empty string ('') in this case.

TControl.RealGetText
Value used for the Text property.
Updates Modified and the TextHint display when storing the new Text value.

RealSetText is an overridden method in TCustomEdit. It ensures that the value in Modified is updated when a new value in Text is applied to the Caption for the control. It also hides the TextHint display when the new value is not an empty string ('') by calling HideEmulatedTextHint.

RealSetText calls the inherited method to store the Text value, and to adjust the control size when needed.

The TextHint is re-displayed when it is hidden and CanShowEmulatedTextHint returns True.

TWinControl.RealSetText TControl.Caption
New value stored as the text/caption for the control.
Handles Key Up events forwarded from the LCL interface.

KeyUpAfterInterface handles the VK_RETURN key code for the control. It calls EditingDone to signal the OnEditingDone event handler (when assigned). When AutoSelect is set to True, the SelectAll method is called to select all of the Text in the control. AutoSelected is updated to reflect the action.

TWinControl.KeyUpAfterInterface
Virtual key code examined in the method.
Shift, Ctrl, or Alt modifier for the key code.
Handles a WM_CHAR window message for the control.

Prevents keystrokes for normal characters from acting as accelerator keys. When the Shift state in Message contains ssCtrl or ssAlt, the inherited method is called to handle the WM_CHAR message.

TWinControl.WMChar
Window message examined in the method.
Handles the CM_WANTSPECIALKEY message for the control.

For the Darwin platform/widgetset, the LCL must be prevented from handling the arrow (cursor) keys VK_LEFT, VK_RIGHT, VK_UP, and VK_DOWN. The Result in Message is set to 1 to indicate that these keys have already been handled.

Message handled in the method.
Suppresses the CM_CHANGED control message when an emulated TextHint is visible.

WndProc is an overridden method in TCustomEdit. It ensures that the CM_CHANGED message is suppressed when an emulated TextHint is visible for the control. Otherwise, the inherited method is called to dispatch the control Message.

TWinControl.WndProc
Message examined and handled for the control.
Determines if the control should auto-adjust its Height and/or Width.

ShouldAutoAdjust is an overridden method in TCustomEdit used to determine if the control can auto-adjust its Height and/or Width.

AWidth and AHeight are variable Boolean parameters which indicate if the corresponding property can be auto-sized. AWidth is always set to True for TCustomEdit. AHeight is set to the inverse of the value in AutoSize.

ShouldAutoAdjust does NOT call the inherited method.

TControl.ShouldAutoAdjust
True when Width can be auto-adjusted.
True when Height can be auto-adjusted.
Handles the LM_SETFOCUS message for the control.

WMSetFocus is an overridden method in TCustomEdit. It is used to hide a visible emulated TextHint display when the control is focused. Calls HideEmulatedTextHint to remove the TextHint display. Calls the inherited method prior to exit.

TWinControl.WMSetFocus
Message handled in the method.
Handles the LM_KILLFOCUS message for the control.

Calls the inherited WMKillFocus method on entry to perform the EditingDone method when the parent form is Active. Ensures that an emulated TextHint is displayed when needed and allowed.

TWinControl.WMKillFocus
Message handled in the method.
Enables auto-selection of text when focused.

AutoSelect is a Boolean property which enables or disables auto-selection of text when the control receives focus. If True, the edit control will select all its text when it receives focus or when the Enter key is pressed. The default value for the property is True.

AutoSelect is used in the KeyUpAfterInterface method, and determines if the SelectAll method is called when editing is completed in the control. It is used in MouseUp to determine if SelectAll is called when the Left mouse button is clicked. It is also used in DoEnter to determine if SelectAll is called when the Enter key is pressed.

Set to True when the text selection was made automatically.

AutoSelected is a Boolean property which indicates if the text selection in the control was made automatically after handling key press or mouse events.

AutoSelected is used in conjunction with the AutoSelect property which enables the capability. AutoSelected is not set to True when AutoSelect has not been enabled. AutoSelect is enabled by default in TCustomEdit.

AutoSelected is updated when the Enter (^M) key is handled for the control, or when a left mouse up event is handled for an already focused control. When AutoSelect is set to True, the SelectAll method is called to select all of the the text in the control. AutoSelected is set to True when SelText has the same value as the Text property.

AutoSelected is set to False when focus leaves the control.

Uses the Color from the Parent control, when enabled.

ParentColor determines if the control should use the Color from the Parent control, when enabled. The default value is False in TCustomEdit.

When this property is True, all changes to the Color of the parent will also be applied to the Color of the control, ensuring that they both contain same value. If the Color of the control is changed by the application, then ParentColor will be automatically set to False.

Using ParentColor when the Color value is clDefault can cause problems in resolving the actual color value. To obtain the Color property of a control while taking into account clDefault and ParentColor, use the GetColorResolvingParent method. This method might return a non-RGB color, but will never return clDefault. To obtain a purely RGB result use the GetRGBColorResolvingParent method.

TControl.ParentColor TControl.Color TControl.GetColorResolvingParent TControl.GetRGBColorResolvingParent
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create ensures that values in the component and ControlStyle properties are set for the control. ControlStyle excludes the value csCaptureMouse and includes the value csRequiresKeyboardInput.

Create sets the default values for properties, including: MaxLength, HideSelection, ParentColor, TabStop, EchoMode, BorderStyle, AutoSelect, AutoSelected, and TextHint.

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 internal change handler are freed, and calls the inherited destructor prior to exit.

Deletes all text in the edit box for the control.

Clear is a procedure used to remove the text in the control. Clear sets the value in Text to an empty string ('').

Selects the entire text in the edit control.

SelectAll is a procedure used to select all of the text content in the edit box for the control.

SelectAll checks the value in Text to ensure that content is available for the selection. No actions are performed in the method when Text is an empty string ('').

When Text is not empty, the values in SelStart and SelLength are updated to use the content in Text starting at the first UTF-8-encoded character. UTF8Length is called to get the length for Text, and the value stored in SelLength.

Clears the current text selection in the edit control.

ClearSelection is a procedure used to clear the currently selected text in the edit control. ClearSelection sets the value in SelText to an empty string ('') to discard selected value in the edit control. It does not affect the values in the Text property.

No actions are performed in the method when SelLength contains 0 (zero).

Use HideSelection to disable text selection in the edit control.

Copies the selected text in the control to the clipboard.

CopyToClipboard is a procedure used to copy the selected text in the control to the clipboard. CopyToClipboard is performed for selected text when the Ctrl+C or Ctrl+Insert key combination is handled for the edit control. Meta+C or Meta+Insert is used for MacOS. No actions are performed when text is not selected in the control.

CopyToClipboard calls the Copy method in the widgetset class when a handle has been allocated for the control.

Use CutToClipboard to copy the selected text to the clipboard, and delete it from the text in the edit control.

Use PasteFromClipboard to insert the contents of the clipboard into the text for the edit control.

Use Undo to revert the last editing action performed in the control.

Moves the selected text into the clipboard (removes it from the control).

CutToClipboard is a method used to move the current text selection in the control to the clipboard. The selected value is removed from the Text in the control.

CutToClipboard is performed when the Ctrl+X or Shift+Delete key combination is handled in the control (MacOS uses Meta+X or Shift+Delete). Pressing Shift+Delete when text is not selected (SelLength is 0) causes the the character prior to the editing cursor to be deleted but not copied to the clipboard. No actions are performed if the editing cursor is positioned before the first character in the Text for the control.

CutToClipboard calls the Cut method in the widgetset class when its handle has been allocated.

Use CopyToClipboard to copy the current text selection in the control to the clipboard.

Use PasteFromClipboard to insert the contents of the clipboard at the current position in the edit control.

Use Undo to revert the last editing action performed in the control.

Inserts text from the clipboard at the current position in the control.

PasteFromClipboard is a method used to insert the contents of the clipboard at the current position in the edit control. If Text is selected in the control, the SelText is replaced with the clipboard content. When SelLength is 0, the clipboard values are inserted at the position for the editing cursor.

PasteFromClipboard is performed when the Ctrl+V or Shift+Insert key combination is handled for the control (MacOS uses Meta+V or Shift+Insert).

PasteFromClipboard calls the Paste method in the widgetset class when its handle has been allocated.

Use CopyToClipboard to copy the current text selection in the control to the clipboard.

Use CutToClipboard to copy the selected text to the clipboard, and delete it from the text in the edit control.

Use Undo to revert the last editing action performed in the control.

Reverts the last editing action in the control.

Undo is a method used to revert the last editing action performed in the control. Undo is performed when the Ctrl+Z (or Meta+Z on MacOS) key combination is handled for the control. Pressing Ctrl+Z causes the value in Text to revert to its value before editing. A subsequent Ctrl+Z key press causes the edited value to be toggled.

Undo calls the Undo method in the widgetset class when its handle has been allocated.

Removes all event handlers assigned for the specified object.

RemoveAllHandlersOfObject is an overridden method in TCustomEdit, and calls the inherited method on entry to remove handlers for the specified object.

RemoveAllHandlersOfObject uses the internal TMethodList instance (when assigned) and calls its RemoveAllMethodsOfObject method to remove entries where the TMethod data points to the object specified in AnObject.

TControl.RemoveAllHandlersOfObject
Object instance to remove for the list of handlers in the control.
Adds the specified OnChange event handler to the control.
Event handler added in the method.
True if the handler is stored at the top of the method list for the handler type.
Removes the specified OnChange event handler for the list of handlers in the control.

RemoveHandlerOnChange is a method used to remove the event handler specified in AnOnChangeEvent from the list of OnChange handlers for the control. AnOnChangeEvent is a TNotifyEvent instance, and it is used to locate and remove the TMethod entry registered for the handler. RemoveHandlerOnChange reverses the actions performed in AddHandlerOnChange, called when an OnChange event handler is assigned to the control.

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

TMethodList TMethodList.Remove TMethod TNotifyEvent
Event handler removed from the list of handlers in the control.
The horizontal alignment for the text in the control (left, right, or centered).

Alignment is a TAlignment property which controls the horizontal alignment of text in the control. The default value for the property is taLeftJustify. See TAlignment for more information about the enumeration values and their meanings.

Alignment is used in CreateParams when alignment style flags are added to the creation parameters for the method. The value is also passed to the widgetset class then the handle is created (or re-created) for the class instance. Changing the value in the property causes the widgetset class to be notified when a handle has been allocated for the control.

Allows automatic adjustment of the size for the control, according to its content.

The action performed depends on the control type. For example, a label or button can become bigger or smaller to accommodate a longer or shorter caption. The default value for the property is True in TCustomEdit. and enables auto-sizing the control instance to its content.

TControl.AutoSize
Indicates the line style drawn as a border around the control.

The default value for the property is bsSingle in TCustomEdit.

TWinControl.BorderStyle
Indicates whether the last change can be reverted in the control.

CanUndo is a read-only Boolean property which indicates whether the last editing change can be reverted in the control using the Undo method.

The property value is False if a handle has not been allocated for the widgetset class. Otherwise, the property value is determined by calling the GetCanUndo method in the widgetset class.

The position of the editing cursor in the control.

CaretPos is a TPoint property which contains the coordinates for the caret (or editing cursor) in the control. The coordinates reflects logical (UTF-8) characters and lines.

TPoint.X
  Contains the zero-based offset into the UTF-8-encoded characters in the control Text. Position 0 is immediately prior to the first UTF-8 character in Text. If there is selected text in the control, the caret is considered to be positioned right after the last selected character. Character positions are independent of the LTR/RTL BiDi-ness for the control.
TPoint.Y
  Contains the zero-based relative line number for the editing cursor. For single-line edits the value is normally 0.

The value in CaretPos is updated by the widgetset class when key and selection control messages are handled.

Allows to force the text into all upper or lower case.

The following conversions can be specified:

- Unchanged
- All upper case letters
- All lower case letters

Conversions apply to the entire text, and cannot be reverted.
Allows to modify the text display, useful for entering passwords.

The following conversions can be specified:

emNormal
  No changes are performed.
emNone
  Spaces are echoed instead for the control value.
emPassword
  The value in PasswordChar is echoed.

Conversions apply to the entire text, and cannot be reverted.
Status for the emulated TextHint in the control.

EmulatedTextHintStatus is a read-only TEmulatedTextHintStatus property which contains the status value for an emulated TextHint display in the control. EmulatedTextHintStatus is used when a value has been assigned to the TextHint property and the widgetset does not natively implement the capability. The LCL emulates the TextHint display by assigning the value in TextHint to the Text for the control.

EmulatedTextHintStatus is updated in the ShowEmulatedTextHint and HideEmulatedTextHint methods.

Determines if selected text to be hidden when the control does not have focus.

HideSelection is a Boolean property which determines whether the selected text in the control is hidden when the control does not have focus.

HideSelection negates the default behavior in the edit control. The default behavior hides the selection when the control loses focus, and displays the text selection when the control receives focus. When set to False, the selected text (if any) is always displayed in the selected state - even when the control loses focus.

The default value for the property is True.

Changing the value for the property causes the SetHideSelection method in the widgetset class to be called when its handle has been allocated. No actions are performed in the method when the handle has not been allocated for the widgetset class.

The value in HideSelection is used in the CreateParams method to determine whether the ES_NOHIDESEL edit style flag is included in or omitted from the creation parameters for the control. When HideSelection is set to False, the ES_NOHIDESEL edit style is included in the flag values.

Use SelText, SelStart, and SelLength to change the text selection in program code. Use ClearSelection to remove the current text selection in the edit control.

The maximum length of the value entered in Text, or 0 (zero) for unlimited length.

In Delphi MaxLength only limits user input. The LCL actually restricts the maximum length of the stored text; this simplifies the implementation for non-Win32 widgetsets.

True when the value in Text has been changed.

Modified is a Boolean property which indicates if the value in Text has been changed when a CM_TEXTCHANGED message is handled for the control. The value is set to True in the TextChanged method. The value is reset to False when RealSetText is called to store the value in Text to the buffer for the control.

Indicates if the edit control accepts numeric values only.

NumbersOnly is a Boolean property which controls whether the edit control is limited to numeric characters when edited. The default value for the property is False.

Changing the property value causes the widgetset class to be notified when a handle has been allocated for the control.

NumbersOnly is used in CreateParams to include the ES_NUMBER edit style in the creation parameters for the control when set to True.

Event handler signalled when the text for the control is changed.

OnChange is a TNotifyEvent property with the event handler signalled when the text for the control is changed.

OnChange is triggered when the value in Text is modified either by using the keyboard or assigning a new value in program code. Please note that this differs from controls, like TCustomComboBox / TComboBox, where the event is not signalled when the control value is changed in program code.

OnChange is signalled (when assigned) from the Change method, and occurs after the Changed method is used to post the CM_CHANGED control message.

When the control value is edited using the keyboard, OnChange is signalled after each character or keystroke is handled and applied to the value in Text. To avoid visible delays during editing, the event handler should not be too time or resource intensive.

TControl.Changed
Allows obfuscation of the displayed text, showing all characters as PasswordChar.

Typically used in password input, to hide the input from other viewers. The value in Text is still available for the WM_GETTEXT message.

Indicates if the user is prevented from changing the value for the Text in the control.

ReadOnly is a Boolean property which indicates if the user is prevented from changing the value in the control.

ReadOnly is used in the CreateParams method to determine if the ES_READONLY edit style flag is included in the creation parameters for the control. The value is also passed to the widgetset class in the InitializeWnd method, and when the value for the property is changed.

When ReadOnly is True, the EditingDone method does not signal the OnEditingDone event handler (in the ancestor).

The default value for the property is False, and indicates that the value can be edited in the control.

TControl.EditingDone TControl.OnEditingDone
The number of currently selected UTF-8-encoded characters in the control.

SelLength is an Integer property which contains the number of UTF-8-encoded characters currently selected in the edit box for the control. The current selection is the value in Text starting at the ordinal position in SelStart and continuing for the number of characters in the property.

The value for the property is read from the widgetset class when a handle has been allocated for the control. Otherwise, the internal member is read get the value for the property. Setting a new value for the property notifies the widgetset class when a handle has been allocated for the control.

Use SelStart to set the zero-based position in Text for the first UTF-8-encoded character in the current text selection.

Use SelText to examine the values selected in the control, or to replace the value in the current text selection. ClearSelection can be used to remove the characters in the current text selection for the control.

Use SelectAll to make all values in Text the current text selection in the control.

Use HideSelection to un-select the current text selection in the control.

The zero-based index for the first UTF-8 character in the current text selection.

SelStart is an Integer property which contains the ordinal position in Text for the UTF-8-encoded character at the start of the current text selection. The current text selection includes the number of characters in SelLength. SelStart is a zero-based value.

The value for SelStart is read from the widgetset class when a handle has been allocated for the control. Otherwise, the value is read from the internal member for the property. Setting a new value for the property notifies the widgetset class when a handle has been allocated for the control.

Use SelLength for the number of UTF-8-encoded characters in the current text selection.

Use SelText to examine the values selected in the control, or to replace the value in the current text selection. ClearSelection can be used to remove the characters in the current text selection for the control.

Use SelectAll to make all values in Text the current text selection in the control.

Use HideSelection to un-select the current text selection in the control.

The currently selected text in the edit box for the control.

SelText is a String property which contains the current text selection in the control. The current text selection is the UTF-8-encoded characters in Text identified by the SelStart and SelLength properties.

The property value is derived by calling the UTF8Copy routine in lazutf8.pas. Setting a new value for the property causes the text selection in Text to be replaced with the specified value. The widgetset class is notified when a handle has been allocated for the control.

Values must assigned to the SelStart and SelLength property before accessing SelText.

SelText is updated when the ClearSelection is called to remove the text selection value from the content in Text. SelText is compared to Text to determine the value for AutoSelected when VK_RETURN key or MouseUp messages are handled.

UTF8Copy
Enables navigation using the Tab key.

Allows the user to navigate to this control, by pressing the Tab key. The default value for the property is True in TCustomEdit.

TWinControl.TabStop
The text displayed and edited for the control.

Text is a TCaption property which contains the UTF-8-encoded characters maintained as the value for the edit control. The value in Text is read and written using the RealGetText and RealSetText methods. Not only do they provide code compatibility with the Delphi VCL, they support use of emulated TextHint displays. The value in TextHint is assigned to Text when the inline hint text is displayed for the control.

The value in Text may be altered in the TextChanged method when the setting in CharCase requires case conversion for the value in the control.

TControl.Text
Default hint text shown when the Text property is empty and the control is not focused.

TextHint fills the TCustomEdit with the value in the property when the Text in the control is empty and the control does not have focus. This is different than Hint, which displays a balloon tip when ShowHint is set to True and the mouse is over the control.

Setting a new value in TextHint causes the widgetset class to be notified, and the value is displayed in the edit control when allowed. If the new value is an empty string (''), the text hint is removed from the control.

A scrollbar for use in Memo controls.

A scrollbar specifically for use with TMemo controls. Inherits most of its properties from its ancestor, TControlScrollBar.

Gets the HorzScrollBar in the associated memo control.
Value for the property.
Gets the VertScrollBar in the associated memo control.
Value for the property.
The base class for multi-line text controls.

TCustomMemo is a TCustomEdit descendant which implements the base class used for a multi-line edit control. TCustomMemo extends TCustomEdit with additional properties and methods needed for the control. Overridden methods are provided to create and initialize the control using style flags needed for the widgetset class.

The textual values in the multi-line control can be accessed using the Lines property. An individual line of text can be accessed by its ordinal position in the list of values. For example:

// var sContent: String; ... sContent := AMemo.Lines[2];

This provides access to the third value in List (index positions are zero-based).

The values for all of the text in Lines can be retrieved as a single String using the Text property in the TStrings class instance. Each line of text is separated by the LineEnding character sequence for the host platform or operating system. For example:

// var sContent: String; ... sContent := AMemo.Lines.Text;

Please note: There is a difference in TCustomMemo / TMemo between the Text and Lines properties. Text is actually the Caption for the control as inherited from TControl. Lines is the multi-line TStrings instance specific to the memo control. Setting the control value using Text does NOT cause the Modified property to be updated. Setting the value using the Lines property does cause the Modified property to be updated.

This is important if an OnChange event handler is used to detect changes to the value in the control, and you need to identify whether the change was performed in program code. You can identify a programmatic change by manipulating the value in Modified.

For changes in program code, set Modified to False before setting the value using the Text property. If Modified is False when OnChange is signalled, the change occurred in program code. Modified can be set as desired in your program code after the value is assigned to Text. For example:

// use Modified and Text to track program changes procedure TForm1.Button1Click(Sender: TObject); begin Memo1.Modified := False; Memo1.Text := 'Whiskey' + LineEnding + 'Tango' + LineEnding + 'Foxtrot'; Memo1.Modified := True; end;

procedure TForm1.Memo1Change(Sender: TObject); begin if not TCustomMemo(Sender).Modified then StaticText1.Caption := 'Memo changed in code' else StaticText1.Caption := 'Memo changed by user'; end;

Changes entered by the user are applied when methods update the Lines property in the control. As a result, Modified is set to True. If Modified is True in OnChange, the change was triggered by user interaction with the control.

The value in Modified is retained when the control gains or loses focus whether by keyboard navigation or by using the mouse.

The text displayed in the control uses the attributes defined in the Font property. No capabilities are provided for formatting individual characters, words, or lines in the content for the control.

Both horizontal and vertical scrollbars can be used in the control. Use the ScrollBar property to define the scrollbars displayed for the control. It can be used to enable automatic scrollbars which are only displayed when the content for the control does not fit within its bounds.

Use the Append method to add a line of text to the values in Lines.

Use the WantTabs and WantReturns properties to determine whether the corresponding keys are captured and stored in Lines. This affects the way control messages are applied to the control.

Use WordWrap to indicate if the control should automatically wrap a line of text longer than the visible area for the control.

Applications should not create instances of TCustomMemo; use TMemo instead.

TControl.Font
Updates creation flags used to create the handle for the control.

CreateParams is overridden in TCustomMemo, and calls the inherited method on entry. CreateParams ensures that style flags needed for the multi-line control are included in the Style property in the Params argument.

Values from the ScrollBars and WordWrap properties are checked, and flags are added as needed. ScrollBars causes window style flags to be added like WS_HSCROLL and/or WS_VSCROLL. When WordWrap is set to True, the WS_HSCROLL window style is removed from the creation parameters. Otherwise, the edit style ES_AUTOHSCROLL is added to the creation parameters.

Creation parameters for the control.
Copies existing string values from the widgetset class.

InitializeWnd is an overridden method in TCustomMemo. InitializeWnd ensures that property values from widgetset class are stored in the current class instance when handle for the control is created (or re-created). InitializeWnd is called after the handle for the control was created, but before the the handle for child controls is created.

InitializeWnd ensures that string values in the widgetset class (if any) are copied to a new TStrings instance and assigned to the Lines property. The previous TStrings instance in Lines is freed.

InitializeWnd calls the inherited method prior to exit.

TStrings
Frees resources when the handle for the control is freed.

FinalizeWnd ensures that string values in Lines are freed in the widgetset class before the handle is destroyed for the control. Existing text (and objects) are copied, and assigned to the member variable for Lines after the widgetset class has been notified.

FinalizeWnd calls the inherited method proper to exit.

TWinControl.FinalizeWnd
Returns the textual content stored in Lines as a single String value.
TStrings.Text TControl.RealGetText
The entire text in a single string.
Replaces the value in Lines.Text.
TControl.RealSetText
Sets the value for the control from a single string.

Sets the value for the control from a single string. Lines are separated by LineFeed (LF) and/or CarriageReturn (CR) characters.

Always False, a cache is not implemented in TCustomMemo.
TCaption instance with the cached value for the control.
Get the value for the CaretPos property.

GetCaretPosition is an overridden method in TCustomMemo used to get the value for the CaretPos property. It calls the GetCaretPos method in the widgetset class to get the return value for the method.

Returns the position of the editing cursor or caret.
Handles Key Up events forwarded from the LCL interface.

KeyUpAfterInterface handles the VK_RETURN key code for the control when WantReturns is set to True. It sets the value in Key to 0 to indicate that the key code does not finish editing in the control.

It calls the inherited method prior to exit to handle the key code normally when WantReturns is set to False.

TWinControl.KeyUpAfterInterface
Virtual key code examined in the method.
Shift, Ctrl, or Alt modifier for the key code.
Sets the position for the editing cursor or caret to the specified location.

SetCaretPos is an overridden method in TCustomMemo used to set the position for the editing cursor (or caret).

AValue is a TPoint instance with the character and line coordinates for the editing cursor. The X member contains the 0-based relative column offset to the UTF-8-encoded character where the caret is positioned. 0 is immediately before the first character in the current line of text. The Y member contains the 0-based offset to the line where the caret is positioned.

SetCaretPos ensures that the widgetset class is cast to a TWSCustomMemoClass instance, and calls its SetCaretPos method.

New position for the editing cursor or caret.
Sets the value for the Lines property.
New value for the property.
Sets the value for the SelText property.
New value for the property.
Sets the value for the WantReturns property.
New value for the property.
Sets the value for the WantTabs property.
New value for the property.
Sets the value for the WordWrap property.
New value for the property.
Sets the value for the ScrollBars property.
New value for the property.
Performs actions needed when the component has been loaded using the LCL streaming mechanism.

Loaded is an overridden method in TCustomMemo, and calls the inherited method on entry. When a handle has been allocated for the control, the widgetset class is notified of the current values in the ScrollBars and WordWrap properties.

Handles control messages for Return and Tab keys when enabled in the control.

CMWantSpecialKey is an overridden method in TCustomMemo. It ensures that control messages for VK_RETURN and VK_TAB keys are marked as handled when WantReturns or WantTabs are enabled in the control. All other messages are handled by calling the inherited method.

Message examined and updated in the method.
Handles Tab, Return, and Escape characters in control messages.
Message examined in the method.
Gets the default size used for new instances of the class.
Returns the default size for the control as a TPoint value.
Implements the handler for UTF8 key press events in the control.

UTF8KeyPress is an overridden method in TCustomMemo which implements the handler for UTF-8-encoded key press events in the control.

UTF8KeyPress calls the inherited method on entry to signal the OnUTF8KeyPress event handler (when assigned). It ensures that a Carriage Return (decimal character 13) key is handled using the setting specified in the WantReturns property. When WantReturns is set to False, the value in UTF8Key is set to an empty string ('') to discard the character.

TWinControl.UTF8KeyPress
Key examined in the method.
Indicates if an emulated TextHint can be displayed for the control.

CanShowEmulatedTextHint is an overridden Boolean function in TCustomMemo, and does not call the inherited method in its implementation.

CanShowEmulatedTextHint determines whether an emulated TextHint can be displayed for the control. Normally, this requires a control handle and an unassigned value in the control text. In addition, some widgetsets implement text hints natively, and do not require LCL to emulate the capability (Windows, QT5). Emulated hint displays can also be suppressed when the widgetset class is being freed (when the Lines in the control have already been destroyed).

The current implementation always returns False for Memo controls.

True when an emulated TextHint can be displayed for the control.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry.

Create allocates resources needed for the Lines, HorzScrollBar, and VertScrollBar properties. It also sets the default values for properties, including: WantTabs, WantReturns, WordWrap, AutoSelect, and AutoSize.

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 Lines, HorzScrollBar, and VertScrollBar properties are freed by calling the FreeThenNil routine in lazutilities.pas.

Destroy calls the inherited destructor prior to exiting from the method.

Appends the specified text to the Lines in the control.

Append is a procedure used to append the line of text in AValue to the end of the values in the Lines property. It is a convenience method, and calls the Add method in the Lines member.

// var sLine: String; // the following are equivalent AMemo.Append(sLine); AMemo.Lines.Add(sLine);
The text value added to Lines in the method.
Scrolls the visible area in the control by the specified amounts.

ScrollBy is an overridden method in TCustomMemo used to scroll the visible area for the control by the specified amounts.

DeltaX and DeltaY contain the number of pixels the content in the control is scrolled. DeltaX is applied to the horizontal position. DeltaY is applied to the vertical position. A positive value means that he control scrolls towards its bottom or right (respectively). Conversely, a negative value scrolls the content towards its top or left.

ScrollBy calls the ScrollBy_WS method in the ancestor class. It essentially replaces the method in the ancestor with the same name, and does not call the inherited method.

TWinControl.ScrollBy TWinControl.ScrollBy_WS
Amount to scroll horizontally.
Amount to scroll vertically.
Contains the individual lines of text in the multi-line edit control.

Lines is a TStrings property which contains the individual lines of text in the multi-line edit control. The values in Lines can be accessed using the Strings and Text properties defined in TStrings. The Strings property in Lines allows an individual line of text to be accessed by its ordinal position. For example:

// var sContent: String; sContent := AMemo.Lines.Strings[2]; // equivalent to preceding since Strings is the default property sContent := AMemo.Lines[2];

The Text property in Lines allows access to all of the values stored in Lines. Text lines are separated by the LineEnding character sequence defined for the host platform or operating system. For example:

// var sContent: String; sContent := AMemo.Lines.Text;

Changing the values in Lines causes the Modified property to be set to True. Use Text to make changes to the control value that do not cause the Modified property to be updated.

Use the Append method to add a line of text to the end of the values in Lines.

Set values in the WantTabs, WantReturns, and WordWrap properties to control the content and behavior for the multi-line edit control.

Use the OnChange event handler to perform actions needed when the value for the control has been changed.

TStrings TTextStrings
The horizontal scrollbar for the control.

HorzScrollBar is a TMemoScrollBar property which contains the horizontal scrollbar displayed for the control. Resources are allocated to the property in the constructor, and freed in the destructor.

Use ScrollBars to determine the scrollbars visible for the control.

The vertical scrollbar for the control.

VertScrollBar is a TMemoScrollBar property which contains the vertical scrollbar displayed for the control. Resources are allocated to the property in the constructor, and freed in the destructor.

Use ScrollBars to determine the scrollbars visible for the control.

Defines the vertical and/or horizontal scrollbars used in the control.

ScrollBars is a TScrollStyle property which defines whether the horizontal and vertical scrollbars are displayed for the control. It is a single value from the TScrollStyle enumeration.

The default value for the property is ssNone, and disables both horizontal and vertical scrollbars in the control.

Setting a new value for the property causes the widgetset class to be notified when a handle has been allocated for the control.

Allows the user to insert Return characters (line breaks) into the text.

The Enter key is normally used to press the default button in a form, so it cannot be used to add line breaks into the text by default. Set WantReturns to True to allow line breaks to be entered using Enter when the control has the input focus. Ctrl+Enter can be used to insert a line break, even if WantReturns is set to False.

Allows Tab characters to be entered into the text.

The Tab key is normally used to move the input focus to the next control, and does not add Tab characters to the text.

When WantTabs is True, the Tab key inserts a Tab character into the text, instead of moving the focus to then next control. Even if WantTabs is True, the Tab key can be used to navigate into the control. But it prevents use of Tab to exit the control.

Allows long lines (paragraphs) to wrap into multiple display lines.

When False, the display for long lines is truncated at the right margin for the control. It can be made visible when the text can be scrolled horizontally.

Implements an edit control with a single line of text.

TEdit is a TCustomEdit descendant which implements an edit control presenting a single line of text. TEdit sets the visibility for properties and events introduced in the TCustomEdit ancestor, and does not introduce any new methods.

TLabeledEdit TMaskEdit
Control used to display and edit multi-line text.

TMemo is a TCustomMemo descendant which implements a multi-line text edit control. TMemo sets the visibility for properties introduced in TCustomMemo, but does not introduce any new methods.

The textual values in the multi-line control can be accessed using the Lines property. An individual line of text can be accessed by its ordinal position in the list of values. For example:

// var sContent: String; ... sContent := AMemo.Lines[2];

This provides access to the third value in List (index positions are zero-based).

The values for all of the text in Lines can be retrieved as a single String using the Text property in the TStrings class instance. Each line of text is separated by the LineEnding character sequence for the host platform or operating system. For example:

// var sContent: String; ... sContent := AMemo.Lines.Text;

Please note: There is a difference in TCustomMemo / TMemo between the Text and Lines properties. Text is actually the Caption for the control as inherited from TControl. Lines is the multi-line TStrings instance specific to the memo control. Setting the control value using Text does NOT cause the Modified property to be updated. Setting the value using the Lines property does cause the Modified property to be updated.

This is important if an OnChange event handler is used to detect changes to the value in the control, and you need to identify whether the change was performed in program code. You can identify a programmatic change by manipulating the value in Modified.

For changes in program code, set Modified to False before setting the value using the Text property. If Modified is False when OnChange is signalled, the change occurred in program code. Modified can be set as desired in your program code after the value is assigned to Text. For example:

// use Modified and Text to track program changes procedure TForm1.Button1Click(Sender: TObject); begin Memo1.Modified := False; Memo1.Text := 'Whiskey' + LineEnding + 'Tango' + LineEnding + 'Foxtrot'; Memo1.Modified := True; end;

procedure TForm1.Memo1Change(Sender: TObject); begin if not TCustomMemo(Sender).Modified then StaticText1.Caption := 'Memo changed in code' else StaticText1.Caption := 'Memo changed by user'; end;

Changes entered by the user are applied when methods update the Lines property in the control. As a result, Modified is set to True. If Modified is True in OnChange, the change was triggered by user interaction with the control.

The value in Modified is retained when the control gains or loses focus whether by keyboard navigation or by using the mouse.

The text displayed in the control uses the attributes defined in the Font property. No capabilities are provided for formatting individual characters, words, or lines in the content for the control.

Both horizontal and vertical scrollbars can be used in the control. Use the ScrollBar property to define the scrollbars displayed for the control. It can be used to enable automatic scrollbars which are only displayed when the content for the control does not fit within its bounds.

Use the Append method to add a line to text to the values in Lines.

Use the WantTabs and WantReturns properties to determine whether the corresponding keys are captured and stored in Lines. This affects the way control messages are applied to the control.

Use WordWrap to indicate if the control should automatically wrap a line of text longer than the visible area for the control.

Applications should use TEdit for a single line edit control.

Contains border styles used for static text controls.

TStaticBorderStyle is an enumerated type with values that represents border styles used for static text controls. TStaticBorderStyle is the type used for the BorderStyle property in TCustomStaticText and decendants.

No border.
Single line border.
Sunken 3-D border.
The base class for TStaticText.

Specifies the base ancestor for TStaticText, a control used to display static text. TCustomStaticText is a TWinControl descendant. It can be used in place of TLabel for situations where a TWinControl descendant is required.

Gets the value for the Transparent property.
Value for the property.
Sets the value for the Alignment property.
New value for the property.
Sets the value for the BorderStyle property.
New value for the property.
Sets the value for the Transparent property.
New value for the property.
Handles the window activate message for the control.

Received when the control has a registered activation shortcut for the FocusControl. Defers the focus to FocusControl when assigned and enabled.

Window message examined in the method.
Returns the Caption for the control.
The text stored in Caption.
Handles a notification that a component used in the control has been added or removed.

Notification is an overridden method in TCustomStaticText, and calls the inherited method on entry. Notification ensures that FocusControl is set to Nil when it is the component for the opRemove Operation.

TControl.Notification
Component for the notification.
Operation for the notification.
Sets the value for the FocusControl property.
New value for the property.
Sets the value for the ShowAccelChar property.
New value for the property.
Handles an accelerator key for the control.
TControl.DialogChar
True if the message was handled as an accelerator key.
Message examined in the method.
TSize instance with the default size for new instances of the class.
Constructor for the class instance.
Owner of the class instance.
The horizontal alignment for the text; centered, left- or right-justified.
The border drawn around the control.
The control that receives focus instead of this control.
Indicates if an accelerator character is drawn in the displayed text.

ShowAccelChar is a Boolean property which indicates if the character used as an accelerator key is drawn with an underline in the control.

An accelerator character is any value with a leading Ampersand (&) character in Caption. To use an Ampersand character as an accelerator, it must be entered as 2 Ampersand characters (&&).

Set ShowAccelChar to True to enable underline drawing for the accelerator character. The default value for the property is True. Changing the value in the property causes the InvalidatePreferredSize method to be called to update the bounds for the control.

The value in ShowAccelChar is used in widgetset class methods, such as when the text value is assigned and when the handle for the control is created (or re-created).

Use FocusControl to specify the control which receives focus when the accelerator key is handled in DialogChar.

TControl.Caption TControl.InvalidatePreferredSize
Makes the background for the control transparent when True.
Control to display a text value which does not change.

TStaticText is a TCustomStaticText descendant which implements a control used to display text that does not change. It can be used in place of TLabel for situations where a TWinControl descendant is required. It has a window handle, and allows the accelerator key for the control to be forwarded to another windowed control.

Text displayed in the control.
Specifies a base class for button controls.

TButtonControl is a TWinControl descendant which specifies the base class used for controls with button-like behavior, such as: TCustomButton, TButton, TCustomCheckBox, TCheckBox, TToggleBox, and TRadioButton.

TButtonControl introduces properties, methods, and events needed to read and write the Checked state for the control, handle Click events, and perform actions using OnChange or an action link.

Do not create instances of TButtonControl in an application; use one of the descendent classes.

True when the value in Checked is included in the LCL streaming mechanism.
Implements the default handler for the LM_CLICKED message.
Message handled in the method.
Gets the value for the Checked property.
Value for the property.
Sets the value for the Checked property.
New value for the property.
Signals the OnEditingDone and OnChange event handlers (when assigned).

DoOnChange performs actions needed when the button control is clicked. DoOnChange calls EditingDone to signal the OnEditingDone event handler (when assigned). The OnChange event handler is also signalled (when assigned).

DoOnChange is called from the Click method before the inherited method in TControl is executed. DoOnChange performs no actions at design-time, during component streaming, or when the component is freed.

TControl.EditingDone TControl.OnEditingDone TControl.Click TComponent.ComponentState
Performs actions needed when a click message is handled for the control.

Click is an overridden method in TButtonControl. Click calls the DoOnChange method to signal the OnEditingDone and OnChange event handlers (when assigned). Click calls the inherited method prior to exit.

Click is used when messages are handled in the control and csClickEvents is not used in the ControlStyle property.

TControl.Click
Handles the CM_WANTSPECIALKEY message for the control.
Control message examined in the method.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method on entry. TheOwner is the owner for the new class instance, or Nil.

Create ensures that values in ControlStyle are updated to remove the csMultiClicks, csAcceptsControls, and csCaptureMouse style flags. The accessibility role and description are set to "Button" for the new class instance.

Owner of the class instance.
Indicates the checked state for the control.

Checked is a Boolean property which indicates if the control is displayed using its "checked" or "unchecked" state. The value for the property is always False in TButtonControl, and is overridden in a descendent class.

Disables clicking on the button, without showing the button in a disabled state.
Event handler for changes to properties in the control.
Links a button control to a basic action.

TButtonActionLink is a TWinControlActionLink descendant which links a TButtonControl to a TBasicAction component.

TWinControlActionLink TBasicAction
The button control for the action link.
Assigns the button control for the action link.
Button assigned in the method.
Sets the value in the Checked property for the linked button.
TActionLink.SetChecked
New value for the checked property.
Class reference used to create new instances of TButtonActionLink.
The base class for a push button control.

TCustomButton is a TButtonControl descendant which provides the base class for a push button control.

TCustomButton / TButton are used to perform an action when the control is clicked. An OnClick event handler is provided to perform actions needed when the push button is clicked.

Properties are provided to control the appearance and behavior for the control. This includes whether it is the Default or Cancel button on a modal form, and the modal result returned when the push button is clicked.

The control displays a text-based caption and is drawn using a style appropriate for the platform or widgetset. An accelerator key can be defined in the caption which simulates clicking on the push button when the shortcut key is pressed. Support for TBasicAction from the FPC Run-time Library (RTL) is present, but not published in the control.

Please note that the Caption is always center aligned on the push button. The values in properties like BiDiMode and UseRightToLeftAlignment are ignored in the control.

Please note that the Color for the control defaults to the system-defined color used for button controls (clDefault or clBtnFace).

Do not create instances of TCustomButton; use the TButton descendant instead.

Use TBitBtn for a push button control which displays a bitmap instead of a text-based caption.

Use TSpeedButton for a push button control which can remain in the pressed or down state.

Sets the value for the Cancel property.
New value for the property.
Sets the value for the Default property.
New value for the property.
Sets the value for the ModalResult property.
New value for the property.
Handles a UIActivate control message.

Calls UpdateFocus to make the button the active control in the parent form.

Message handled in the method.
Handles a set focus window message for the control.

WMSetFocus calls the inherited method in TWinControl on entry. Calls UpdateFocus to make the button the active control in the parent form.

TWinControl.WMSetFocus
Message handled in the method.
Handles a kill focus message for the control.

WMKillFocus calls the inherited method in TWinControl on entry. When the window handle in Message is the Handle for the control, the UpdateFocus method is called to remove the button as the active default control in the parent form.

TWinControl.WMKillFocus TWinControl.Handle TLMKillFocus
Message handled in the method.
Handles changes to the focus for the control.

UpdateFocus is a method used to update the control and its parent form when the control gets or loses focus on its form.

AFocused indicates whether the control is getting or losing focus.

UpdateFocus calls GetParentForm to get the parent form for the control. No additional actions are performed in the method when the parent form has not been assigned for the control.

When AFocused is True, ActiveDefaultControlChanged is called to synchronize values in the control and the parent form. Active (in the control) is updated to reflect its use as the ActiveControl on the parent form. ActiveDefaultControl (in the parent form) is updated when the control is focused.

UpdateFocus is called when the LM_SETFOCUS or LM_KILLFOCUS messages are handled for the control. It is also called when the CM_UIACTIVATE message is dispatched by the parent form when it is focused.

GetParentForm TCustomForm.SetWindowFocus
True when the button is focused, False when it loses focus.
Creates the handle for the widgetset class instance.

Calls the inherited method on entry. Calls UpdateDefaultCancel to set the Default and Cancel controls on the Parent form (when needed).

TWinControl.CreateWnd
Updates creation parameters to use values needed for the control.

Calls the inherited method on entry. Ensures that the style flags in Params is updated to include BS_DEFPUSHBUTTON when the Default property is True. Otherwise, BS_PUSHBUTTON is included in the style flags.

TWinControl.CreateParams
Creation parameters updated in the method.
Virtual key code examined in the method.
Shift, Ctrl, or Alt modifier for the key.
Virtual key code examined in the method.
Shift, Ctrl, or Alt modifier for the key.
Handles an accelerator key for the control.

DialogChar is an overridden Boolean function used to handle a TLMKey message received for the control.

DialogChar examines the CharCode member in Message to determine if it contains the accelerator key defined in the Caption for the control. If it is found, and the control can receive focus, the Click method is called and the return value is set to True. If the Message has a CharCode that is not the accelerator key, the inherited method is called to handle the message and get the return value for the method.

The return value is True when the Message is successfully handled for the control.

TControl.DialogChar TControl.Caption TControl.OnClick
True if the message was handled as an accelerator key.
Message examined in the method.
True when the widgetset class indicates child controls are allowed.
Not used in the current implementation.
Gets the default size for new instances of the control.

GetControlClassDefaultSize is an overridden TSize class function used to get the default height and width for new instances of the control. GetControlClassDefaultSize sets the CX and CY members in the return value to the defaults used for the control. CX contains the width and is set to 75 (pixels). CY contains the height and is set to 25 (pixels).

TControl.GetControlClassDefaultSize TSize
TSize instance with the width and height for the new control.
Notifies the widgetset class of a change to the Default property.

WSSetDefault is a method used to notify the widgetset class when the value in the Default property has been changed.

WSSetDefault calls the SetDefault method in the widgetset class using the value in the Active property. Active is used because Default represents the design-time setting for the control. At run-time, Active contains the default button clicked when the Enter key is pressed.

Called when a new value is assigned to the Default property. Called when the value in Active is changed in the ActiveDefaultControlChanged method. Called when UpdateDefaultCancel sets the default and cancel controls on the parent form.

Notifies the widgetset class of a change to the caption text for the control.

WSSetText is an overridden method used to notify the widgetset class instance when the value in the caption text has been changed. No actions are performed in the method when the handle for the control has not been allocated, or at design-time.

WSSetText ensures that Ampersand (&) characters used to define an accelerator key in AText are handled for the widgetset class. The Ampersand character(s) are removed from AText, and the virtual key code equivalent is stored in the Shortcut property. By default, the Shortcut uses the ssCtrl shift modifier for the accelerator key.

The SetShortCut method in the widgetset class is called to store values from both Shortcut and ShortCutKey2.

The inherited WSSetText method is called prior to exit.

TControl.Text TControl.Caption ShortCut Char2VK
New value for the caption text in the control.
Performs actions needed when the CM_TEXTCHANGED message is handled in the control.

TextChanged is an overridden method used to performs actions needed when the CM_TEXTCHANGED message is handled in the control.

TextChanged calls InvalidatePreferredSize to force the preferred height and width for the control to be recalculated. When Parent has been assigned and its AutoSize property is set to True, the AdjustSize method in Parent is called. The AdjustSize method for the control is called to resize the control or update control flags when delayed auto-sizing is in use.

TextChanged calls the inherited method prior to exit.

TControl.TextChanged TControl.AdjustSize TControl.AutoSizeDelayed
Performs actions needed when LCL component streaming has been completed.

Loaded is an overridden method used to perform actions needed when LCL component streaming has been completed.

Loaded calls the inherited method on entry. Loaded calls UpdateDefaultCancel to update the default and cancel controls on the parent form.

Updates the Default and Cancel properties in the parent form.

UpdateDefaultCancel is a method used to update the default and cancel controls on the parent form.

UpdateDefaultCancel calls GetParentForm to get the parent for the control. When the parent form has been assigned, its DefaultControl and CancelControl properties are updated when needed. DefaultControl is updated when the Default property is set to True. CancelControl is updated when the Cancel property is set to True.

UpdateDefaultCancel calls WSSetDefault to notify the widgetset class when the control is the default control.

UpdateDefaultCancel is called from the CreateWnd and Loaded methods.

GetParentForm TCustomForm.DefaultControl
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry.

Create updates the internal component style and ControlStyle with values needed for the control. Create sets the default values for properties, including:

Color
  Set to clDefault or clBtnFace (depending on the platform or widgetset).
ParentColor
  Set to False.
TabStop
  Set to True.
Align
  Set to alNone.

Create calls SetInitialBounds using the height and width returned from GetControlClassDefaultSize.

Owner of the class instance.
Handles a button click event for the control.

Click is an overridden method used to handle a button click event for the control.

Click uses the value in ModalResult to determine if the modal result for the button control is posted to the parent form. When ModalResult contains a value other than mrNone, it is stored in the ModalResult property in the parent form (when assigned).

Click calls the inherited method to signal other event handlers or an Action used for the control. OnChange is signalled first. OnClick is signalled if an Action is not in use, or the Action does not have an OnExecute event handler.

Click is called from ExecuteDefaultAction when the control is both Active and the Default button on the parent form. It is called from ExecuteCancelAction when the control is the Cancel button on the parent form. It is called from DialogChar when the accelerator key in Shortcut is handled for the control.

TControl.Click
Performs the Click method if the control is an Active or a Default button.

ExecuteDefaultAction is an overridden method used to perform the Click method when the button control is Active or the Default button. No actions are performed in the method when both properties are set to False.

See Click for more information about the actions performed in the method.

ExecuteDefaultAction is called when a Return (VK_RETURN) key is handled in the Application singleton for the ActiveDefaultControl in a Form.

TControl.ExecuteDefaultAction TApplication.DoReturnKey
Performs the Click method if the control is the Cancel button.

ExecuteCancelAction is an overridden method used to perform the Click method when the control is the Cancel button on its parent form. No actions are performed in the method when Cancel is set to False.

See Click for more information about the actions performed in the method.

ExecuteCancelAction is called when an Escape (VK_ESCAPE) key is handled in the Application singleton for the CancelControl in a Form.

TControl.ExecuteCancelAction TApplication.DoEscapeKey
Updates the button and/or parent form when the active default control has been changed.

ActiveDefaultControlChanged is an overridden method used to update properties in the control and/or parent form when active default control has been changed. NewControl contains the control which is the ActiveControl given focus on the parent form, or Nil when a button control loses focus.

When NewControl is the current class instance, its Active property is set to True to reflect the active focused control status. The ActiveDefaultControl property in the parent form is set to the current control to indicate it is also the active default control for the form.

When NewControl is assigned, but a different control than the current instance, the button control is not focused and its Active property is set to False.

When NewControl is unassigned (Nil), the button control has just lost focus and Active is set to the value in the Default property. The control is also removed as the ActiveDefaultControl in the parent form (when needed).

ActiveDefaultControlChanged is called from the UpdateFocus method.

TControl.ActiveDefaultControlChanged
New value assigned as the active default control in the parent form.
False; always uses center alignment.
True if the control is the Cancel or Default button.

Active is a read-only Boolean property which indicates if the control is the active default control for the parent form.

The property value is updated in ActiveDefaultControlChanged when the focus for the control has been changed. It is set to True when the button gains focus and becomes the ActiveDefaultControl on the parent form. It is set to False when another control is set as the ActiveDefaultControl on the parent form. It is set to the value in the Default property when the ActiveDefaultControl is set to Nil.

TCustomForm.ActiveDefaultControl
True if the button is the modal Cancel button.

Cancel is a Boolean property which indicates if the button is the modal Cancel button on a form. The default value for the property is False.

Setting a new value for the property causes the CancelControl in the parent form to be updated. When set to True, the CancelControl property in the parent form is set the current class instance. When set to the False, the form property is set to Nil.

No actions are performed in the method when NewCancel has the same value as the Cancel property, or the parent form has not been assigned.

The value in Cancel is automatically updated in methods like UpdateRolesForForm and UpdateDefaultCancel. The property value is used in ExecuteCancelAction to determine if the Click method can be called for the control.

Pressing Escape (VK_ESCAPE) in a modal form is equivalent to clicking on the Cancel button.

Color used for the button face.

Color is a TColor property with color used for the surface (or face) on the button control. The default value for the property in TCustomButton is clDefault or clBtnFace, depending on the platform or widgetset.

Changes made to the Color for the control or its Font are ignored in TCustomButton. It is always drawn using the color(s) needed for the platform or widgetset.

TControl.Color
True if the button is the default button in a modal form.

Default is a Boolean property which indicates if the button can be used as the default button control on a form. Default is essentially a design-time setting that indicates an intent. At run-time, the default button is the ActiveDefaultControl on the form. The default value for the property is False.

Setting a new value for the property causes the button control to be assigned to the DefaultControl property in the parent form. The widgetset class is notified when the property value is set.

The value in Default is used in the CreateParams method to determine style flags included in the creation parameters for the control. It is used in ExecuteDefaultAction to determine if the Click method can be called for the control.

The value in Default is automatically updated in the UpdateRolesForForm method.

Pressing Enter in a modal form is equivalent to clicking on the Default button.

Value returned when the control is clicked in a modal form.

ModalResult is a TModalResult property used to provide the modal result value when the button control is clicked in a modal form.

The value in ModalResult is used in the Click method to update the ModalResult value in the parent form (when assigned). The default value for the property is mrNone, and indicates that the property value is not used as a modal result in the Click method.

By convention, the value in ModalResult is associated with the usage and caption for the button control. Common values and usage in ModalResult includes:

mrNone
  ModalResult is not used.
mrOK
  The OK button was clicked.
mrCancel
  The Cancel button was clicked.
mrAbort
  The Abort button was clicked or the modal dialog was aborted.
mrRetry
  The Retry button was clicked.
mrIgnore
  The Ignore button was clicked.
mrYes
  The Yes button was clicked.
mrNo
  The No button was clicked.
mrAll
  The All button was clicked.
mrNoToAll
  The No To All button was clicked.
mrYesToAll
  The Yes To All button was clicked.
mrClose
  The Close button was clicked.

Indicates if the parent color is used to draw the control.

The default value for the property is False in TCustomButton. Changes to the property value are ignored in TCustomButton; the control is always drawn using the color(s) needed for the platform or widgetset.

TControl.ParentColor
Shortcut key for the control.

ShortCut is a TShortCut property with the primary shortcut key or accelerator key for the control. The property value contains both the virtual key code and the shift modifier for the short cut key.

The value in ShortCut is automatically updated when a caption is assigned for the control which includes an accelerator key. The accelerator key is designated using an Ampersand (&) character before the character used as the short cut. A value assigned in this manner always includes the ssCtrl modifier in the short cut value by default.

The property value (along with ShortcutKey2) is passed to the widgetset class when the WSSetText method is called.

Use the ShortCut and ShortCutToKey routines in the menu.pp unit to convert to and from virtual key codes with shift modifiers.

Secondary shortcut key for the control.

ShortCutKey2 is a TShortCut property with the secondary shortcut key or accelerator key for the control. The property value contains both the virtual key code and the shift modifier for the short cut key. The property value (along with Shortcut) is passed to the widgetset class when the WSSetText method is called.

Use the ShortCut and ShortCutToKey routines in the menu.pp unit to convert to and from virtual key codes with shift modifiers.

Enables navigation using the Tab key.

Allows the user to navigate to this control, by pressing the Tab key. The default value for the property is True in TCustomButton.

Implements a push button control.

TButton is a TCustomButton descendant which implements a push button control. TButton is used to perform an action when the control is clicked. An OnClick event handler is provided to perform actions needed when the push button is clicked. TButton provides support for the TBasicAction class defined in the FPC Run-time Library (RTL).

Properties are provided to control the appearance and behavior for the control. This includes whether it is the Default or Cancel button on a modal form, and the modal result returned when the push button is clicked.

The control displays a text-based caption and is drawn using a style appropriate for the platform or widgetset. An accelerator key can be defined in the caption which simulates clicking on the push button when the shortcut key is pressed.

Please note that the Caption in the control is always centered. The values in properties like BiDiMode and UseRightToLeftAlignment are ignored in the control.

Please note that the Color for the control defaults to the system-defined color used for button controls.

TButton sets the visibility for properties defined in the ancestor class, and does not introduce any new methods.

Use TBitBtn for a push button control which displays a bitmap instead of a text-based caption.

Use TSpeedButton for a push button control which can remain in the pressed or down state.

Represents the states for a check box.

TCheckBoxState is an enumerated type with values which represent the states for a check box control. TCheckBoxState is the type used to implement the State property in TCustomCheckBox and descendent classes.

The check box has no check mark, indicating that the item is not selected.
The check box has a check mark in it, indicating that the item is selected.
The check box state cannot be changed by the user, or is disabled.
The base class for a check box component.

TCustomCheckBox is a TButtonControl descendant which specifies an interface used for a check box component. It is the common ancestor for TCheckBox, TToggleBox, and TRadioButton descendants.

A check box control allows the user to choose the state for the control independent of other check box controls (unlike a radio button). TCustomCheckBox introduces the State property which contains the check, unchecked, or grayed state for the control. The AllowGrayed property indicates if the grayed state is allowed in the control; otherwise only checked and unchecked are used. The Checked property allows the value in State to be updated by setting a Boolean value that indicates if the control is check or unchecked.

Sets the value for the State property.
New value for the property.
Gets the value for the State property.
Value for the property.
Handles the LM_CHANGED message for the control.

Performs either the OnClick or the OnChange event handler. Use ClicksDisabled is control the event handler signalled.

Message examined in the method.
Performs actions when the control is clicked.

Overridden in TCustomCheckBox to ignore mouse up event notifications.

TControl.Click
Implements the Click behavior for the control.

DoClickOnChange is a procedure used to signal event handler(s) when the LC_CHANGED message is handled for the control. DoClickOnChange calls the Changed method to dispatch the control message. DoClickOnChange uses the value in ClicksDisabled to determine the event handler(s) signalled in the method.

When ClicksDisabled is False, the inherited Click method is called. When set to True, the DoOnChange method is called to signal the OnEditingDone and OnChange event handlers. This emulates the OnClick behavior in the Delphi VCL.

DoClickOnChange is called from the DoChange method after the value in State has been updated. It is also called when a new value is assigned to the Checked property.

TControl.Changed TControl.EditingDone TControl.OnEditingDone
Gets the checked state for the control from the widgetset class.

RetrieveState is a TCheckBoxState function used to get the checked, unchecked, or grayed state for the control from the widgetset class. Access to the widgetset class requires a valid handle in the control. If the handle has not been assigned, the return value is set to the existing value in the State member.

RetrieveState calls the RetrieveState method in the widgetset class to get the return value for the method.

RetrieveState is used to get the value for the State property. It is called from DoChange when the LM_CHANGED control message is handled for the control. It is also called when setting a new value for the Checked property.

TCheckBoxState value returned from the widgetset class.
Alternates between the checked and the unchecked state in the control.

Calls GetChecked to retrieve the current checked State for the control. Negates the value and calls SetChecked to store the toggled state value. Called from DialogChar when the accelerator key is handled for the focused control.

Implements support for accelerator keys in the control.

DialogChar is an overridden Boolean function in TCustomCheckBox which handles accelerator keys in messages for the control. The return value is set to True when the check box is successfully toggled in the method.

Message is the TLMKey instance with the key code examined in the method. When the key code matches the accelerator key in Caption, the control is focused and its State is toggled. If the control cannot be focused, or Message does not represent an accelerator key code, the inherited method is called to get the return value.

This method is called even if the control is disabled or hidden. Provided for Delphi VCL compatibility.

TControl.DialogChar
True when the control state is toggled by the accelerator key.
Control message examined in the method.
Gets the value for the Checked property.
Value for the property.
Sets the value for the Checked property.
New value for the property.
New value stored in the text/caption for the control.
Sets the checked state in the widgetset class and redraws the control.

No actions are performed in the method if a handle has not been allocated for the control, or during component streaming.

Size used for new instances of the class.
Performs actions needed after the control is loaded using LCL component streaming.

Loaded is an overridden method in TCustomCheckBox. Loaded ensures that the value in State is passed to the widgetset class when a handle has been allocated for the control. This prevents loss of the stored value in State during component streaming. The inherited method is called prior to exit.

TWinControl.Loaded
New value for Text.
Performs actions needed when the CM_TEXTCHANGED message is handled for the control.

TextChanged is an overridden method in TCustomCheckBox used to perform actions needed when the CM_TEXTCHANGED control message is handled for the control.

TextChanged calls InvalidatePreferredSize to update the sizing flags for the control and its Parent. When Parent has been assigned and its AutoSize property is True, its AdjustSize method is called. The AdjustSize method in the control is called to resize the visible control.

TextChanged calls the inherited method prior to exit.

TControl.TextChanged TControl.InvalidatePreferredSize TControl.AdjustSize
Creation parameters updated in the method.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method on entry. TheOwner is the owner for the new class instance. Create sets the default value for the Alignment property to taRightJustify. Create calls SetInitialBounds to set the initial control size to the values returned from the GetControlClassDefaultSize class method.

Owner of the class instance.
Indicates the alignment for the caption text in the control.

Alignment is a TLeftRight property with the horizontal alignment for the caption text relative to the check box. The default value for the property is taRightJustify, and causes the text to be drawn to the right of the check box. Use taLeftJustify to draw the caption text in front of the check box.

Changing the value for the property causes the widgetset class to be updated when its Handle has been allocated.

The value in Alignment is used to set the creation parameters for the control.

TLeftRight
Allows the check box to use a "grayed" state.

If AllowGrayed is set to True, the check box has three possible states: checked, unchecked and grayed. If AllowGrayed is set to False, the check box has only two possible states: checked and unchecked.

The check, unchecked, or grayed state for the control.

Indicates whether the check box is checked (selected), unchecked (deselected) or grayed (disabled). See TCheckBoxState for the possible values in State.

Shortcut key for the control.

ShortCut is a TShortCut property with the primary shortcut key or accelerator key for the control. The property value contains both the virtual key code and the shift modifier for the short cut key.

The value in ShortCut is automatically updated when a caption is assigned for the control which includes an accelerator key. The accelerator key is designated using an Ampersand (&) character before the character used as the short cut. A value assigned in this manner always includes the ssCtrl modifier in the short cut value by default.

Use the ShortCut and ShortCutToKey routines in the menu.pp unit to convert to and from virtual key codes with shift modifiers.

Secondary shortcut key for the control.

ShortCutKey2 is a TShortCut property with the secondary shortcut key or accelerator key for the control. The property value contains both the virtual key code and the shift modifier combined to form the short cut key.

The property value (along with Shortcut) is passed to the widgetst class when the WSSetText method is called.

Use the ShortCut and ShortCutToKey routines in the menu.pp unit to convert to and from virtual key codes with shift modifiers.

ShortCutKey2 may not be implemented for all platforms supported in the LCL.
A label with a box which can contain a check mark.

TCheckBox is a TCustomCheckBox descendant which implements a check box component. A check box control allows the user to choose the state for the control independent of other check box controls (unlike a radio button).

The State property contains the checked, unchecked, or grayed state for the control. The AllowGrayed property indicates if the grayed state is allowed in the control; otherwise only checked and unchecked are used. The Checked property allows the value in State to be updated by setting a Boolean value that indicates if the control is check or unchecked.

Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method on entry. Creates sets the internal component style for the control to csCheckbox, and sets the default values for properties including TabStop (True) and AutoSize (True).

Owner of the class instance.
Allows automatic adjustment of the size for the control, according to its content.

The action performed depends on the control type. For example, a label or button can become bigger or smaller to accommodate a longer or shorter caption. The default value for the property is True in TCheckBox, and enables auto-sizing for the control instance.

TControl.AutoSize
Enables navigation using the Tab key.

Allows the user to navigate to this control, by pressing the Tab key. The default value for the property is True in TCheckBox.

TWinControl.TabStop
A labelled box capable of being checked or unchecked.

TToggleBox is TCustomCheckBox descendant which implements a labelled control with state values like a check box control. TToggleBox differs from TCheckBox in that it displays only the Caption text for the control; the graphical check mark representation is not used. TToggleBox is similar in appearance to a push button control. The control state determines whether the button is drawn using its up or down position.

The programmer must ensure that the OnClick event handler recognizes the State of the control, takes the appropriate Action, and stores the State into the appropriate storage.

Bounds used for new instances of the class.
Creation parameters with style flags updated in the method.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method using TheOwner as the owner for the new class instance. Create ensures that the internal component style for the control is set to csToggleBox, and sets the default values for the TabStop (True) and ParentColor (False) properties.

Owner of the class instance.
Enables navigation using the Tab key.

Allows the user to navigate to this control, by pressing the Tab key. The default value for the property is True in TToggleBox.

TWinControl.TabStop
Implement a radio button control.

TRadioButton is a TCustomCheckBox descendant which implements a selection button that works with other radio buttons in a mutually exclusive way. If one radio button is selected, none of the others in the group can be selected.

Ensure that the OnClick event handler for each button has a unique Action, and that Actions for the other (deselected and therefore inactive) buttons are turned off.

TRadioGroup behaves differently from a group of TRadioButton controls placed on a form.

In the case of TRadioButton, the mutual exclusivity is a feature that applies to any RadioButton anywhere in the Form, and the RadioButtons can be rearranged in any order or placed anywhere within the containing Form, while in TRadioGroup the exclusivity applies only to buttons within the Group, which are ordered strictly according to their ItemIndex within the Items stringlist.

TRadioButton is an entity in itself, with a number of additional properties, whereas the buttons within TRadioGroup are not separate entities, but rather are simply entries in a list of strings, each of which is associated with the on-screen image of a RadioButton.

The example shows the difference between the use of TRadioButton and TRadioGroup.

TRadioGroup
Updates the state for sibling radio buttons in the parent.

ApplyChanges is an overridden method in TRadioButton. ApplyChanges ensures that other radio buttons in the Parent control are unchecked when the current class instance is Checked.

The siblings controls are normally unchecked by methods in the widgetset class. ApplyChanges performs the actions needed when a handle has not been allocated for the control (widgetset class). This involves iterating over the controls in Parent, and setting the Checked state for sibling TRadioButton instances to False.

ApplyChanges is called when the value in the State property is changed.

TControl.Parent
Implements support for an accelerator key in the control.

DialogChar is an overridden Boolean function in TRadioButton which handles accelerator keys in messages for the control. The return value is set to True when the radio button is successfully toggled in the method.

Message is the TLMKey instance with the key code examined in the method. When the key code matches the accelerator key in Caption, the control is focused and the return value is set to True. If the control cannot be focused, or Message does not represent an accelerator key code, the inherited method is called to get the return value.

This method is called even if the control is disabled or hidden. Provided for Delphi VCL compatibility.

True when the message is handled and the control is focused.
Message examined for the accelerator key.
Sets the value for the text and/or caption in the control.

RealSetText is an overridden method used to set value for the control using the TCaption instance in Value. In TRadioButton, the method ensures that the value in the caption is updated and that the control size is invalidated and adjusted using auto-sizing.

New value for the control.
Performs actions needed when the control has been changed using a mouse click.

DoClickOnChange is an overridden method used to signal an OnChange event handler when the mouse is clicked on the control. DoClickOnChange ensures the value in TabStop is updated to reflect the State for the control. When State contains cbChecked, TabStop is set to True. Otherwise, it is set to False.

DoClickOnChange also ensures that the correct click/change behavior is used for the current control State. If the control is Checked, the inherited DoClickOnChange method is called. This also emulates the Delphi Click behavior where the OnChange event handler is signalled when ClicksDiabled is True. When the control is not Checked, the DoOnChange method is called to signal both the OnEditingDone and OnChange event handlers.

DoClickOnChange is called from the DoChange method in the TCustomCheckBox ancestor class.

Initializes the creation parameters for the class instance.

CreateParams is an overridden method used to update creation parameters for the class instance, and calls the inherited method on entry. CreateParams ensures that Style flags in the Params argument are updated to include the BS_RADIOBUTTON style flag, and to exclude the BS_3STATE style flag.

Creation parameters updated in the method.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create ensures that the csRadioButton style flag is included in the component style flags for the control. The default value for the AutoSize property is set to True.

Owner of the class instance.
Enables or disables auto-sizing the control to its content.

The default value for the property is True in TRadioButton.

TControl.AutoSize
Enables navigation using the Tab key.

Allows the user to navigate to this control, by pressing the Tab key. The default value for the property is True in TRadioButton.

TWinControl.TabStop
Control used to show static text optionally using multiple lines.

TCustomLabel is a TWinControl descendant which specifies a control to display static text on a form. The value in the control is not editable visually, and can be used to label or describe another control or a container on the form. Since it cannot be edited, it is not allowed to receive the input focus. It can, however, be used to set focus to an associated control using an accelerator key defined in the Caption for the control.

TCustomLabel is the ancestor class for TLabel. Do not create instances of TCustomLabel; use the TLabel descendant.

Use TStaticText to display static text and respond to keyboard input directly in the control.

TWinControl
Sets the value for the Alignment property.
New value for the property.
Sets the value for the OptimalFill property.
New value for the property.
Always False, since you cannot tab into a label control.

CanTab is an overridden method in TCustomLabel. The return value is always False since the Tab key cannot be used to give focus to the control.

TControl.CanTab
Always False in TCustomLabel.
Performs actions needed to draw the text for the label.

DoDrawText performs action needed to draw the text for the label.

The GetLabelText method is called to get the text value drawn in the method.

The Font color may be temporarily changed when when the Enabled property is False. If themes are enabled, the Font color is set to clGrayText. When themes are not enabled, the Font color is set to clBtnHighlight. The original Font color is restored prior to exiting the method.

DoDrawText calls the DrawText routine to draw the text on the Canvas using the text rectangle and flags passed as arguments. DrawText is called a second time to render the shadow for the label text when themes are not enabled. The shadow text uses the color clBtnShadow.

DoDrawText is called from the Paint method.

Text rectangle used to draw the label text.
DrawText flags used to render the text.
Checks for CR or LF characters in the label text for the control.

HasMultiLine is a Boolean function used to determine if CR (Carriage Return, Decimal 13) or LF (LineFeed, Decimal 10) characters are included in the text for the control. HasMultiLine calls GetLabelText to get the text stored in the label.

The return value is True when either character occurs in the text for the label.

HasMultiLine is used in the CalculateSize method to determine whether the DT_SINGLELINE flag is included in the drawing flags for the control.

DT_SINGLELINE
True when CR or LF characters are used in the text for the label.
Calculates the preferred size for the control using its anchoring and constraints.

CalculatePreferredSize is an overridden method used to calculated the preferred size for the control. Values stored in the Anchors, Constraints, and WordWrap properties are used to determine the effective width for the control. CalculateSize is called to calculate the text rectangle for the control using the requested dimensions.

CalculatePreferredSize checks the assigned Font for the control to determine whether text rotation is used in its Orientation property. When a value other than 0 (zero) is used, the text rectangle is rotated by the number of radians needed for the property value. The values in PreferredWidth and PreferredHeight are updated for the new text rectangle.

No actions are performed in the method if Parent has not been assigned (contains Nil), or when a handle has not been allocated in the Parent control.

Please note: CalculatePreferredSize does not call the inherited method.

TControl.CalculatePreferredSize
Preferred width calculated for the control.
Preferred height calculated for the control.
True to reserve space for theme element details.
Gets the height and width needed for the label text.

Calculates the size for the label text using the formatting defined in related property values.

NeededWidth and NeededHeight are variable parameters updated in the method to reflect the values needed after applying DrawText flags to the label text. The DrawText flags include constants which represent the following properties:

- WordWrap
- HasMultiLine
- ShowAccelChar
- UseRightToLeftReading

The following constants are also used in the DrawText flags:

- DT_CALCRECT
- DT_EXPANDTABS
- DT_NOCLIP

Maximum width for the text rectangle in the label.
Width needed for the text.
Height needed for the text.
Handles an accelerator key for the control.
True when the message is handled as an accelerator key.
Message examined in the method.
Performs actions when the CM_TEXTCHANGED message is handled for the control.

TextChanged is an overridden method used to perform actions needed when the CM_TEXTCHANGED message is handled for the control. TextChanged calls Invalidate to force the control to be redrawn. UpdateSize is called to perform auto-sizing, and recalculate the dimensions for the control and its font.

TextChanged does not calls the inherited method.

Performs a bounds change for the control.

DoSetBounds is an overridden method in TCustomLabel. It calls the inherited method to store the values in ALeft, ATop, AWidth, and AHeight to the corresponding properties in the control. Values in OptimalFill, WordWrap, and Autosize are used to determine if additional actions are needed for the bounds change.

When OptimalFill is True and AutoSize is False, the AdjustFontForOptimalFill method is called. If Width was changed and WordWrap is True, both the InvalidatePreferredSize and AdjustSize methods are called.

DoSetBounds is called from the ChangeBounds method in an ancestor class.

TControl.DoSetBounds
New value for the Left property.
New value for the Top property.
New value for the Width property.
New value for the Height property.
Implements the OnChange event handler for the Font in the control.

FontChanged is an overridden method in TCustomLabel which implements the OnChange event handler for the Font in the control. FontChanged calls the inherited method on entry, and calls UpdateSize to resize the control for any changes to font properties.

TControl.FontChanged TFont
Object for the event notification.
Gets the size used for new instances of the class.

GetControlClassDefaultSize is an overridden TSize class function used to get the height and width for new instances of the control. GetControlClassDefaultSize uses 65 pixels for the width, and 17 pixels for the height.

The return value is the TSize instance where the values are stored; the CX member is used for the width and the CY member is used for the height.

TControl.GetControlClassDefaultSize
Size used for new instances of the class.
Defers the focus to the control in the FocusControl property.

WMActivate is a procedure used to handle LM_ACTIVATE messages for the control.

WMActivate ensures that the control in the FocusControl property receives the input focus by calling its SetFocus method. No actions are performed in the method when FocusControl has not been assigned (contains Nil) or its CanFocus method returns False.

TWinControl.CanFocus TWinControl.SetFocus
Message examined in the method.
Handles a notification that a component used in the control has been added or removed.

Notification is an overridden method in TCustomLabel, and calls the inherited method on entry. Notification ensures that FocusControl is set to Nil when it is the component for the opRemove Operation.

TControl.Notification
Component for the notification.
Operation for the notification.
Returns the string value in the Caption for the control.
TControl.Caption
Text displayed in the control.
Gets the value for the Transparent property.
Value for the property.
Sets the value for the Color property.
TControl.SetColor TControl.Color
New value for the property.
Sets the value for the FocusControl property.
New value for the property.
Sets the value for the Layout property.
New value for the property.
Sets the value for the ShowAccelChar property.
New value for the property.
Sets the value for the Transparent property.
New value for the property.
Sets the value for the WordWrap property.
New value for the property.
Performs actions when the component has been loaded using LCL component streaming.

Loaded is overridden in TCustomLabel, and calls the inherited method on Entry. Loaded calls the AdjustSize method to handle delayed calls to AutoSize during component streaming.

TControl.Loaded TControl.AdjustSize TControl.AutoSizeDelayed
Adjusts the size for the control based on settings in AutoSize and OptimalFill.

UpdateSizevar is a method used to adjust the size for the control based on settings in the AutoSize and OptimalFill properties. UpdateSize calls InvalidatePreferredSize.

When OptimalFill is True and AutoSize is False, the AdjustFontForOptimalFill method is called to adjust the font size used in the control. AdjustSize is called to resize the control (and any parent controls). When Alignment is set to taRightJustify, the value in Left may be changed to reflect the new Width for the control.

UpdateSize is called from the implementation of the FontChanged and TextChanged methods, and when setting a new value for the ShowAccelChar or WordWrap properties.

Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry to the method.

Create updates the values in ControlStyle to enable mouse capture and both click and double-click events. Create calls SetInitialBounds using the default dimensions for the class instance. Create sets the default values for properties, including: ShowAccelChar, Color, AutoSize, and AccessibleRole.

Owner of the class instance.
Calculates the font height needed to fill the specified width and height constraints.

CalcFittingFontHeight is a Boolean function used to calculate the maximum font height needed to make the specified string fill the available space, given the MaxWidth and MaxHeight constraints.

The return value is True when the text rectangle using the new font height fits within the size constraints in MaxWidth and MaxHeight. NeedWidth and NeedHeight are set to the values indicated in the text rectangle. The return value is False when the text rectangle is either too wide or too tall, or cannot be calculated using the specified parameter values.

No actions are performed in the method when AutoSizeDelayed is set to True, when TheText is an empty string, or when MaxHeight or MaxWidth contain 0 or a negative value.

The font height is calculated using a temporary TFont instance with the current Font for the control, setting its drawing flags to calculate the text rectangle. The drawing flags include wrapping when the WordWrap property is set to True. The font height is incrementally increased or decreased until the maximum font height which fits with MaxHeight and MaxWidth is determined.

CalcFittingFontHeight is used in the implementation of the AdjustFontForOptimalFill method.

True when the text fits within the size constraints in MaxWidth and MaxHeight.
Text measured in the method.
Width constraint for the text rectangle.
Height constraint for the text rectangle.
Font height calculated in the method.
Width needed for the text using the calculated font size.
Height needed for the text using the calculated font size.
Implements the storage specifier for the Color property.
True when a value other than clNone has been assigned to the Color property.
Adjusts the font height for the control text to fill the available client area.

AdjustFontForOptimalFill is a Boolean function used to adjust the font height so that text in the label expands to fill the available client area for the control. AdjustFontForOptimalFill calls CalcFittingFontHeight to determine the font height needed to make the label text (caption) fill the Width for the control. The calculated font height is stored in the Font property.

The return value is True when the Font height was changed in the method.

AdjustFontForOptimalFill is called from DoSetBounds and UpdateSize when OptimalFill is set to True and AutoSize is set to False. It is also called when a new value is assigned to the OptimalFill property.

TControl.Font
True when the font height was changed in the method.
Performs actions needed to draw the control on its Canvas.

Paint is an overridden method in TCustomLabel used to draw the control on its Canvas. Paint ensures that property values in the control are applied to the Canvas before measuring and drawing its Text, including:

- AutoSize
- Alignment
- Layout
- WordWrap
- Transparent
- Color
- Font
- ShowAccel
- Enabled
- Alignment
- UseRightToLeftAlignment
- UseRightToLeftReading

DoDrawText is called to render the label text using the DrawText flags needed for the property values.

Paint does not call the inherited method in TGraphicControl. As a result, it does not signal the OnPaint event handler in the ancestor class.
TControl.Caption TGraphicControl.Canvas TGraphicControl.Paint TGraphicControl.OnPaint
Sets the bounds (Top, Left, Width, Height) for the control.

Overridden to call InvalidatePreferredSize the first time the method is used and both AutoSize and WordWrap are enabled in the control. Calls the inherited method prior to exit.

TControl.InvalidatePreferredSize TControl.SetBounds
Horizontal coordinate for the left-hand edge of the control.
Vertical coordinate for the top edge of the control.
New width for the control.
New Height for the control.
Horizontal text justification in the control (centered, left- or right-justified).

Alignment is a TAlignment property which controls the horizontal justification of the text displayed in the control. The default value for the property is taLeftJustify. When a new value is assigned to the Alignment property, the Invalidate method is called to repaint the control.

Alignment (and other properties) are used in the Paint method when the text is rendered to the Canvas for the control. It is also used in UpdateSize when right alignment needs to be considered for an auto-sized or optimal-filled control.

Use the Layout property to control the vertical alignment of the text displayed in the control.

Use OptimalFill to indicate if the font height can be adjust to fill the client area for the control.

TControl.Invalidate TAlignment
Enables or disables auto-sizing for the control to its content.

The action performed depends on the control type. For example, a label or button can become bigger or smaller to accommodate a longer or shorter caption.

The default value for the property is True in TCustomLabel.

TControl.AutoSize
Sets the color used for the background in the control.

The default value for the property is clNone in TCustomLabel. This value is used because labels, by default, are transparent in the LCL. Please note that this differs from the Delphi VCL where the default value for Transparent is False.

Set Transparent to False to fill the control background with a given TColor value. Set ParentColor to True to use the Color defined for the parent control or form.

TControl.Color
The control associated with the label and its accelerator key (AccelChar).

Set FocusControl to the control which is focused when the accelerator key in the label is pressed.

A label control cannot receive the input focus (it is read-only), but can display an accelerator key indicator, just like a menu entries. A windowed control (Edit...) can receive focus, but cannot indicate an accelerator key.

Using a combination of a label and another control allows setting the accelerator key in the label caption. The other control receives focus when the user presses the accelerator key.

An accelerator key is marked by an Ampersand '&' in the label caption, immediately preceding the character to be used as the accelerator key. The marked character appears underlined on screen, when ShowAccelChar is set to True.

For example: When you have a NameEdit1 control on a form, preceded by a label NameLabel1, you can set NameLabel1.FocusControl to NameEdit1, and NameLabel1.Caption to '&Name'.

Vertical alignment for control text (at the top, bottom, or center).

Layout is a TTextLayout property with the vertical alignment used for the text displayed in the control. The default value for the property is tlTop. Changing the value in Layout causes the Invalidate method to be called to redraw the control.

Use the Alignment property to control the horizontal alignment for the text in the control.

Use OptimalFill to indicate if the font height can be adjusted to fill the client area for the control.

TTextLayout TControl.Invalidate
If True, the font size is adjusted for optimal fill of the available space.

OptimalFill is a Boolean property which indicates that the Font height should be maximized to fill the available width in the control. The default value for the property is False.

Setting OptimalFill to True causes AutoSize to be set to False. The AdjustFontForOptimalFill method is called to get and apply the maximum font height allowed for the Width and Height in the control.

Changing the value for the property causes Invalidate to be called to redraw the control.

TControl.Width TControl.Height TControl.Font TControl.Invalidate
Underlines the character in the label that acts as the accelerator or short cut key.

When False, an Ampersand (&) character in the label caption is displayed as an ordinary character (as used in the Object Inspector).

When True, the character following the Ampersand is drawn with an underline. When the user presses the accelerator key, input focus is given to the associated FocusControl.

TControl.Caption
Indicates whether the viewer can see through the control.

Opaque labels have their enclosing rectangle filled with the background Color for the label. This can be the color of the Parent control, when ParentColor is True. Setting Transparent to True makes the label transparent, and does not fill the background for the control or hide any background details.

Please note: The default value of this property in the LCL is True, which differs from the default value in the Delphi VCL.

TControl.ParentColor
Allows the caption to wrap into multiple lines when it is too long for the available Width.

WordWrap is a Boolean property which indicates if the caption in the control can be wrapped into multiple lines when its length exceeds the value in Width. The default value for the property is False.

When a new value is assigned to the property, the Invalidate and UpdateSize methods are called to auto-size and repaint the control.

When WordWrap is False, the text is truncated at the right boundary when it is too long for the control Width. When WordWrap is True and AutoSize is True, the maximum Width is determined by anchoring the left and right sides for the control to its Parent.

TControl.Width TControl.Invalidate
Uses the color from the parent control, when enabled.

ParentColor determines if the control should use the Color from the Parent control, when enabled. The default value is False in TCustomLabel.

When this property is True, all changes to the Color of the parent will also be applied to the Color of the control, ensuring that they both contain same value. If the Color of the control is changed by the application, then ParentColor will be automatically set to False.

TControl.ParentColor
Control used to display static text, possibly in multiple lines.

TLabel is a TCustomLabel descendant which implements a control to display static text on a form. The value in the control is not editable visually, and can be used to label or describe another control on the form or a container. Since it cannot be edited, it is not allowed to receive the input focus. It can, however, be used to set focus to an associated control using an accelerator key defined in the Caption for the control.

Use TStaticText to display static text and respond to keyboard input directly in the control.

Gets the font instance used for an emulated TextHint display.

CreateEmulatedTextHintFont is a TFont function which gets the font instance used to display an emulated TextHint in the control. It is retrieved by calling the CreateEmulatedTextHintFont method in the widgetset class. Widgetset classes use the font assigned to the control, but change the font color to clGrayText.

CreateEmulatedTextHintFont is called from FontChanged, and the private ShowEmulatedTextHint method.

TFont instance used for the emulated TextHint.
Registers components declared in the unit.

Register is a procedure used to register components in the stdctrls.pp unit for use in the Lazarus IDE.

Register calls RegisterComponents to add the following components to the Standard tab in the IDE:

- TButton
- TLabel
- TEdit
- TMemo
- TToggleBox
- TCheckBox
- TRadioButton
- TListBox
- TComboBox
- TScrollBar
- TGroupBox

Register calls RegisterComponents to add the following components to the Additional tab in the IDE:

- TStaticText

How to use StdCtrls, ComCtrls or ExtCtrls.

The Units StdCtrls, ComCtrls and ExtCtrls contain definitions and descriptions of many of the most commonly used controls for constructing Forms and other objects in Lazarus GUI applications.

Most controls are split into a final class, such as TButton, TMemo, TScrollBar etc., and a corresponding ancestor class such as TCustomButton, TCustomMemo or TCustomScrollBar. The final class is designed for immediate use, it almost only publishes the properties of the control. The corresponding custom ancestor class (TCustomXXX) can be used to derive controls with special (customized) appearance or behavior.

If you drop a component from the component palette on the form editor you don't need to add code explicitly to create it. The component is automatically created by the IDE together with the form, and destroyed when the form is destroyed.

However, if you create the component yourself by code, and don't specify an Owner for it (Create(Nil)), you are responsible for freeing the component when it is no longer needed. You better construct it with Create(Self), where Self means the containing Form or Parent control.

A control also must have a Parent control, maybe the Form, so that it can become visible within the client area of its Parent. The Top and Left properties specify the placement of the control within its Parent. The Object Tree reflects the Parent-Client relationships of all controls on the form.

Unlike controls, mere components are invisible at run-time (Open Dialogs...). Controls can be made invisible at run-time as well, by setting their Visible property to False.

If you place a component on the Form Designer and look at the Object Inspector, you can observe the Top and Left properties change as you move the component around. The same for the Width and Height properties, when you resize a control by dragging it's size grips.

When you modify the properties in the Object Inspector, the control on the form will reflect the changes as well.

You can also explicitly change the properties of the object in code by typing (in the appropriate Implementation section of the Source editor), for example

Form1.Button1.Height := 48;

In summary, there are usually about three different ways to determine each property of a component:

- by using the mouse,
- by setting the values in the Object Inspector,
- or explicitly by writing code.

The components defined in these Units have several properties that are common to most of them, and other properties that are specific to the individual components. We shall describe the most common ones here. Unusual or control-specific properties will be described for the individual controls.

Additional Help can always be obtained by selecting a property or keyword, in either the Object Inspector or the Source Editor, and pressing F1. You will be taken by your Help browser to the appropriate page in the documentation.

If the description of a property on that page is insufficient, you can navigate to the corresponding description in the ancestor classes, by selecting the links in the Inheritance listing or by selecting the ancestor Type in the declaration of the object.

Some commonly listed properties

| Property | Meaning
Action | Use Action when e.g. a button and a menu entry shall perform the same task, e.g. the Close action.
Align | Defines how a control is lined up within its parent control. Possible values are alTop, alBottom (stacked at the top or bottom, using the full available width), alLeft, alRight (placed at the left or right, using the full available height), alNone (place anywhere on parent control) or alClient (takes all available space left over by other controls).
Anchor | Used to keep a control at a fixed distance from the edges of its Parent control, when the Parent is resized. For example [akBottom, akRight] will keep the control a fixed distance from the bottom right corner. Anchoring both [akLeft, akRight] will make the control extend or shrink in Width, together with its Parent.
AutoSelect | When True, a text control will select all its text when it receives focus or when the Enter key is pressed.
AutoSelected | True indicate that the edit or combo-box control has performed an AutoSelect operation, so that subsequent mouse-clicks and keystrokes proceed normally without selecting the text.
BorderSpacing | The space around the edge between an control and its siblings.
Caption | The text that is displayed on the control; it should preferably give some clue as to the function of the control, or an instruction such as 'Close' or 'Execute'. By default Caption is set to be the same as the 'Name' property, and the application designer should substitute meaningful text instead of the default values.
CharCase | Indicates how text is displayed in a text editing control: Normal (retaining the case of the letters typed by the user), converted to uppercase, or converted to lowercase
Constraints | Sets the minimum and maximum sizes for a control. If a control is resized the new dimensions are always within the ranges given here. You should take care when setting these options that they do not conflict with the Anchors and Align settings.
Color | The Color to be used to draw the control's background.
Enabled | Determines whether a control can be selected or perform an action. If it is not Enabled, it is often Grayed out on the Form.
Font | The Font to be used for writing the text associated with the control - either the caption or label, or the text-strings contained within the control. The entry on the Object Inspector usually has a (+) box on the left, and selecting this box reveals further options such as character set, color and size.
Hint | A short informative pop-up text that appears when the mouse-cursor moves over the control.
Items | The list of 'Things' that the object contains, such as a group of images, a series of lines of text, a number of actions in an actionlist, etc.
Lines | An array of strings, containing the paragraph texts in Memo controls. The array index is zero-based, i.e. the lines are numbered 0..numLines-1.

Name

The identifier by which the control is known in the program. The IDE gives it a default name based on the underlying type, for example successive instances of TBitButton would be named Form1.BitBitton1 and Form1.BitButton2; it is up to the application programmer to give them more meaningful names such as ExitButton or OKButton. By default the Name of the control is applied to the Caption for the control, but the text of the Caption may be changed separately.

PopUpMenu | A window containing context-sensitive menu entries, that pops up when the right mouse button is clicked on the object.
Position (or Top, Left) | Determines where the control is located on the parent form or control.
ReadOnly | If True, the user cannot change the text in the control.
ShowHint | Allows to enable or suppress Hints.
Size (or Height and Width) | The dimensions of the control
Style | The options available for Style depend upon the sort of Control being considered: for instance the Style may be defined by TFormStyle, TBorderStyle, TButtonStyle etc.
TabOrder | Specifies the sequence of controls, that are entered when the user presses the Tab key.
TabStop | Specifies whether the control can be reached (or is skipped) by pressing the Tab key.

Text

Like Caption, the user editable text that appears in the control. Applies particularly to Edit, Memo and Combo-Box types of controls. Most of the editing operations (such as Select, Clear, Cut, Copy) are performed in this property. If the control contains more than a single line of text, then the textual elements are arranged as a zero-based array of strings in Lines (TMemo) or Items (TListBox, TComboBox).

Visible | If True, the control can be seen on the Form; if False, it is hidden.
WordWrap | Allows wrapping the Text into multiple lines. When False, the text is clipped at the right margin of the control, but it still can be inspected by moving the caret within the text.

The 'Events' tab in the Object Inspector contains a list with events, which can occur for this control. If you select an entry in the list, a combo-box appears with a drop-down list showing any event handlers that have already been defined, and allowing you to choose one for this event. Alternatively you can select the ellipsis (three dots ...) and you will be taken to the Source Editor, where the Object Inspector created an new event handler method for you. You also can type the name of your handler in the Object Inspector and press Enter, to create a new handler method.

While a large number of events is available for any given control, in practice it is only necessary to populate a few of them. For most controls, it is sufficient to provide coding for 'OnClick'; for more complex controls it may be necessary also to provide for 'OnEntry' (when the control receives the focus) and 'OnExit' (when the control looses the focus); or you may need to write an event handler for 'OnChange' or 'OnScroll', depending on the nature of the particular control with which you are dealing.

Many controls have a default event, usually OnClick, for which an handler is created with a double click on the control. Or right click on the control, and select the first entry: 'Create default event'.

A common strategy in Object-Oriented programming is to provide an ActionList with the facility for entering, removing or editing a number of predefined actions, from which the most appropriate can be selected to use in any particular instance.

Some commonly listed Actions

| Event | Meaning
OnChange | Action to be taken if any change is detected (e.g. by mouse click, key press, edit text, etc).
OnClick | Action to be taken when the (left) mouse button is clicked. This is usually the main or default action of the control; for example clicking on a button or check box initiates the action associated with the check box. It may alternatively initiate a process of selection, for instance in a TextBox or Memo.

Click

A method to emulate in code the effect of clicking on a control. This method is most often found in Button-type controls (TButton, TBitBtn, TSpeedButton etc). A procedure can be written that calls the same code as the OnClick action. This facility can be particularly useful if the activation of one control by clicking causes a cascade of other controls to be activated, and the Click method can be used to initiate the action rather than having the user explicitly click on a lot of controls.

OnDragDrop | Action to be taken when a dragged control has been dropped onto this control.
OnEntry | Action to be taken when the control receives the focus. This might include changes in the appearance of the object such as highlighting or raising the border.
OnExit | Action to be taken when control is about to loose the focus. This is the right place for validity checks of user input, with a chance to disallow moving to a different control when the input is invalid.
OnKeyPress | Action to be taken on an entered character. Checks...???
OnKeyDown | Action to be taken if a key is down while focus is in this control. This allows one to filter or process control characters in a special way.
OnKeyUp | Action to be taken if a key goes up. This event occurs only once, while auto-repeated keystrokes trigger multiple OnKeyDown or OnKeyPress events.
OnMouseMove | Action to be taken if the mouse cursor moves over the control. This event fires with every small move, while OnMouseEnter and OnMouseLeave occur only when the mouse enters or leaves the control.
OnMouseDown | Action to be taken when a mouse button is pressed over the control.
OnMouseUp | Action to be taken if a mouse button goes up over the control.
OnResize | Action to be taken when the control is resized. Might include re-alignment of text or selection of a different font size etc. Do not mix up with AutoSize, or you ask for trouble!

Constructors such as Create allocate memory and system resources needed by the object. They also call the constructor of any sub-objects present in the class.

Destructors remove the object and de-allocate memory and other resources. If you call Destroy for an object which hasn't being initialized yet it will generate an error. Always use the Free method to deallocate objects, because it checks whether an object's value is nil before invoking Destroy.

Take the following precautions when creating your own Destroy method:

- Declare Destroy with the override directive, because it is a virtual method.
- Always call the inherited Destroy method as the last action in the destructor code.
- Be aware that an exception may be raised by the constructor when there is not enough memory to create an object, or something else goes wrong. If the exception is not handled inside the constructor, the object will be destroyed immediately. In this case Destroy will be called with a partially initialized object, so your destructor must check if the resources were really allocated before disposing of them.
- Remember to call Free for all objects created on the constructor.