[Up] | Reference for unit 'StdCtrls' (#lcl)

## 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 should 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 action list, 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.BitButton1 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 in the constructor.