// standard properties, which should be supported by all descendants

AutoSize permits the size of a control to be adjusted automatically, for example a button can become bigger or smaller to accommodate a longer or shorter caption.

Reads logical (boolean) flag to see whether auto-sizing is to be operated, or writes the flag to say it should be done. Default is false, ie no auto-sizing

Text - the character string in the name or caption of the control

But BEWARE: Text is used in another context in editing controls such as TEdit and TCustomEdit, TLabeledEdit and TCustomLabeledEdit, where it contains the character string that is being edited in the Edit Box.

Event handler needs to be supplied to cover the need to resize a control within the given constraints of maximum and minimum width and height

Double-clicking is much more common in a Windows environment than in Unix or Linux, where single-clicking is the default method for selecting an object. However, in all environments there could be valid use for a double-click, and a method should be supplied if appropriate.

// DEPRECATED. Enables (valid) use of 'IN' operator (this
      // is a hack for speed. It will be replaced by the use of the widgetset
      // classes.
      // So, don't use it anymore.        

Dock - Procedure governing Docking of Control

Performs checks that there is already a valid host control to which the present control is to be docked, removes old controls from the list of docked controls and adds the new control to the list, then calls DoDock to perform the actual docking process

Docks this control to DropControl or on NewDockSite.

If DropControl is not nil, ControlSide defines on which side of DropControl this control is docked. (alNone,alClient for stacked in pages). DropControl will become part of a TDockManager.

If DropControl is nil, then DropControl becomes a normal child of NewDockSite and ControlSide is ignored.

function TControl.ManualFloat(TheScreenRect: TRect;
    KeepDockSiteSize: Boolean = true): Boolean;

  Undock and float.
  Float means here: create the floating dock site and dock this control into it.
  Exception: Forms do not need float dock sites and float on their own.

TControl.AdjustSize calls DoAutoSize in a smart fashion.

During loading and handle creation the calls are delayed.

This method initially does the same as TWinControl.DoAutoSize. But since DoAutoSize is commonly overriden by descendant components, it is not useful to perform all tests, which can result in too much overhead. To reduce this the LCL calls AdjustSize instead.

{------------------------------------------------------------------------------
  procedure TControl.AnchorToNeighbour(Side: TAnchorKind; Space: integer;
    Sibling: TControl);

  Setup AnchorSide to anchor one side to the side of a neighbour sibling.
  For example Right side to Left side, or Top side to Bottom.
 ------------------------------------------------------------------------------}

AnchorParallel - instructions for anchoring beside another control

Sibling - another control beside which the current control is to be anchored

GetPreferredSize - find default/preferred height and width

procedure TControl.GetPreferredSize 
        (var PreferredWidth, PreferredHeight: integer; 
          WithThemeSpace: Boolean);

Returns the default/preferred width and height for a control, which is used by the LCL autosizing algorithms as default size. Only positive values are valid. Negative or 0 are treated as undefined and the LCL uses other sizes instead.

WithThemeSpace: If true, adds space for stacking.

For example: TRadioButton has a minimum size. But for stacking multiple TRadioButtons there should be some space around. This space is theme dependent, so the parameter is passes to the widgetset

TWinControl overrides this and asks the interface for theme dependent values. See TWinControl.CalculatePreferredSize for more information.

Create a new Control - Constructor. Overrides constructors of ancestor classes and sets a number of defaults. Often overridden by descendant classes.

Destructor for Control. Detaches control from parents, removes graphics, frees memory and Operating System handles, pointers etc.

Overrides destructors of ancestor classes, and in turn may be overridden by descendant classes.

TControl.EditingDone

Called when user has finished editing. This procedure can be used by data links to commit the changes.

For example:

• When focus switches to another control (default)
• When user selected another item

It's totally up to the control, what events will commit.

{------------------------------------------------------------------------------
  Method: TControl.BeginDrag
  Params: Immediate: Drag behaviour
          Threshold: distance to move before dragging starts
                     -1 uses the default value of Mouse.DragThreshold
  Returns: Nothing

  Starts the dragging of a control. If the Immediate flag is set, dragging
  starts immediately.
 ------------------------------------------------------------------------------}

* The VCL implementation relies on the virtual Get/SetTextBuf to 
 * exchange text between widgets and VCL. This means a lot of 
 * (unnecesary) text copies.
 * The LCL uses strings for exchanging text (more efficient).
 * To maintain VCL compatibility, the virtual RealGet/SetText is
 * introduced. These functions interface with the LCLInterface. The
 * default Get/SetTextbuf implementation calls the RealGet/SetText.
 * As long as the Get/SetTextBuf isn't overridden Get/SetText 
 * calls RealGet/SetText to avoid PChar copying.
 * To keep things optimal, LCL implementations should always 
 * override RealGet/SetText. Get/SetTextBuf is only kept for
 * compatibility.

* The VCL implementation relies on the virtual Get/SetTextBuf to 
 * exchange text between widgets and VCL. This means a lot of 
 * (unnecesary) text copies.
 * The LCL uses strings for exchanging text (more efficient).
 * To maintain VCL compatibility, the virtual RealGet/SetText is
 * introduced. These functions interface with the LCLInterface. The
 * default Get/SetTextbuf implementation calls the RealGet/SetText.
 * As long as the Get/SetTextBuf isn't overridden Get/SetText 
 * calls RealGet/SetText to avoid PChar copying.
 * To keep things optimal, LCL implementations should always 
 * override RealGet/SetText. Get/SetTextBuf is only kept for
 * compatibility.

// standard properties, which should be supported by all descendants

The (default) action to be associated with this control

Can either read the action already associated with the control (GetAction), or write an action to be associated (SetAction)

// standard properties, which should be supported by all descendants

Either reads a flag containing alignment instructions (FAlign) or writes alignment instructions (SetAlign)

May have no alignment, may have custom or client alignment, or can be aligned to top, bottom, left or right

// standard properties, which should be supported by all descendants

Determines how the control is to be anchored to its client or parent conrol

Either reads a flag containing the set of anchors to be used, or writes a set of anchors. If they have been written, this is indicated in IsAnchorsStored

// standard properties, which should be supported by all descendants

Finds which side is to be used to anchor this control, and what relationships it has to other controls nearby.

For complex relationships, use the Side property of the parent class TAnchorSide, and make a reference eg using asrCenter

// standard properties, which should be supported by all descendants

Determines the border spacing for this control

Reads flag to find stored spacing values required for the border of the control, or writes the flag to set the spacing.

The properties are defined in the parent class TControlBorderSpacing

// standard properties, which should be supported by all descendants

Finds the values for the bounding rectangle, or sets the values.

Bounding rectangle (top-left, bottom-right) is defined in TRect

Gets caption as a text-string (GetText), or stores the new caption (SetText). Shows flag if caption is stored (IsCaptionStored).

By default, the Caption appears the same as the control Name in the Object Inspector, and the developer needs to set it explicitly to some new text.

The VCL implementation relies on the virtual Get/SetTextBuf to exchange text between widgets and VCL. This means a lot of (unnecesary) text copies.

The LCL uses strings for exchanging text (more efficient). To maintain VCL compatibility, the virtual RealGet/SetText is introduced. These functions interface with the LCLInterface.

The default Get/SetTextBuf implementation calls the RealGet/SetText. As long as the Get/SetTextBuf isn't overridden Get/SetText calls RealGet/SetText to avoid PChar copying.

To keep things optimal, LCL implementations should always override RealGet/SetText. Get/SetTextBuf is only kept for compatibility.

// standard properties, which should be supported by all descendants

Finds or sets the client height, and sets a flag if it has been stored

// standard properties, which should be supported by all descendants

Finds origin of client (read-only)

// standard properties, which should be supported by all descendants

ClientRect - finds the coordinates of the rectangle for the client within which the control exists (read-only)

// standard properties, which should be supported by all descendants

ClientWidth - determines the width of the client within which the control exists; reads the width of the client control or sets the value. Sets flag if value is stored

// standard properties, which should be supported by all descendants

Reads the value for colour, or stores the value, and sets a flag if the colour is stored.

The default colour is the same as the window in which the control is located.

// standard properties, which should be supported by all descendants

Determine Constraints (max and min height and width) for this control; reads the size constraints or stores new ones.

// standard properties, which should be supported by all descendants

Reads value for the Origin (top left pixel) of this control. (read-only)

// standard properties, which should be supported by all descendants

ControlState - whether mouse has been clicked, data being read, control being re-drawn, etc. Reads or stores the state of the control.

// standard properties, which should be supported by all descendants

ControlStyle - whether the control responds to mouse clicks, can be re-sized, has particular actions, etc. Reads the stored style, or saves the new style

// standard properties, which should be supported by all descendants

Whether the control is Enabled. If not, it usually appears 'greyed-out'

Reads a flag to see whether the control is enabled, or stores a new value. If stored, sets a flag to say so.

// standard properties, which should be supported by all descendants

Reads a flag to see what font should be used, or sets a flag to store it. If stored, sets a flag to say so

The properties of Font are defined in the parent class TFont

// standard properties, which should be supported by all descendants

Reads or Writes flag if bounds are changed

// standard properties, which should be supported by all descendants

This is often the default action for many controls, and is often the ONLY action specified by the programmer. The action can be spcified by the user, either by typing explicit code into the implementation section for this control, or by selecting an action from a pre-supplied ActionList

Reads or writes a flag if a mouse click is detected, and sets a flag if a value is stored.

The Visible property represents the ability to see a visual control. 
          If Visible is True the control is shown, otherwise it is hidden.
          Calling Show sets, among others, Visible to True.
          Setting Visible to False is equivalent to calling Hide method.

Hint - a small informative pop-up box that appears when the mouse 'hovers' over a control

Requires ShowHint to be True

Reads or writes boolean flag; default is False

Use the TabStop to allow or disallow access to the control using the Tab key.

If TabStop is True, the control is in the tab order. If TabStop is False, the control is not in the tab order and the user can't use the Tab key to move to the control.

OnKeyDown - event handler for instance when key is down while control has focus

Differs from OnKeyPress in that the key may have already been down when the control received focus; with OnKeyPress the key needs to become pressed while the control has focus.

OnKeyPress - event controller for a key being pressed while the control has focus

Differs from OnKeyDown in that the key needs to become pressed while the control has focus; with OnKeyDown the key may have already been down when the control received focus.

OnKeyUp - event handler for instance when a key is up (not pressed) while the control has focus

The key may already have been up when the control received focus, or a pressed key may become released during the time the control has focus.

TGraphicControl supports simple lightweight controls that do not need the ability to accept keyboard input or contain other controls.

Since lightweight controls do not wrap GUI screen objects, they are faster and use fewer resources than controls based on TWinControl.

TGraphicControl provides a Canvas property for access to the control's drawing surface and a virtual Paint method called in response to paint requests received by the parent control.

The TGraphicsControl.Canvas is a clipping window to the parent canvas.

If you ask for the Canvas.Width or Canvas.Height, you are actually getting the parent control's Canvas dimensions.

To get the dimensions of the TGraphicControl, you must query the ClientRect.

TDockTree - a tree of TDockZones - Every docked window has one tree

  
    This is an abstract class. The real implementation is in ldocktree.pas.

    Docking means here: Combining several windows to one. A window can here be
    a TCustomForm or a floating control (undocked) or a TDockForm.
    A window can be docked to another to the left, right, top, bottom or "into".
    The docking source window will be resized, to fit to the docking target
    window.

    Example1: Docking "A" (source window) left to "B" (target window)
    
       +---+    +----+
       | A | -> | B  |
       +---+    |    |
                +----+
      Result: A new docktree will be created. Height of "A" will be resized to
              the height of "B".
              A splitter will be inserted between "A" and "B".
              And all three are children of the newly created TLazDockForm of the
              newly created TDockTree.
      
       +------------+
       |+---+|+----+|
       || A ||| B  ||
       ||   |||    ||
       |+---+|+----+|
       +------------+

      If "A" or "B" were floating controls, the floating dock sites are freed.
      If "A" or "B" were forms, their decorations (title bars and borders) are
      replaced by docked decorations.
      If "A" had a TDockTree, it is freed and its child dockzones are merged to
      the docktree of "B". Analog for docking "C" left to "A":
      
       +------------------+
       |+---+|+---+|+----+|
       || C ||| A ||| B  ||
       ||   |||   |||    ||
       |+---+|+---+|+----+|
       +------------------+
       

      
    Example2: Docking A into B
                +-----+
       +---+    |     |
       | A | ---+-> B |
       +---+    |     |
                +-----+

      Result: A new docktree will be created. "A" will be resized to the size
              of "B". Both will be put into a TLazDockPages control which is the
              child of the newly created TDockTree.
              
       +-------+
       |[B][A] |
       |+-----+|
       ||     ||
       || A   ||
       ||     ||
       |+-----+|
       +-------+

    Every DockZone has siblings and children. Siblings can either be
    - horizontally (left to right, splitter),
    - vertically (top to bottom, splitter)
    - or upon each other (as pages, left to right).


    InsertControl - undock control and dock it into the manager. For example
                    dock Form1 left to a Form2:
                    InsertControl(Form1,alLeft,Form2);
                    To dock "into", into a TDockPage, use Align=alNone.
    PositionDockRect - calculates where a control would be placed, if it would
                       be docked via InsertControl.
    RemoveControl - removes a control from the dock manager.

    GetControlBounds - TODO for Delphi compatibility
    ResetBounds - TODO for Delphi compatibility
    SetReplacingControl - TODO for Delphi compatibility
    PaintSite - TODO for Delphi compatibility

FindControl

Returns the TWinControl associated with the Handle.

This is very interface specific. Better use FindOwnerControl.

Handle can also be a child handle, and does not need to be the Handle property of the Result.

IMPORTANT: So, in most cases: Result.Handle <> Handle in the params.

FindOwnerControl

Returns the TWinControl owning the Handle. Handle can also be a child handle,

and does not need to be the Handle property of the Result.

IMPORTANT: Therefore, in most cases: parameter Handle <> Result.Handle

RemainingClientRect: remaining clientrect without CurBorderSpace

CurBorderSpace: current borderspace around RemainingClientRect

Left, Top, Right, Bottom: apply these borderspaces to CurBorderSpace

CurBorderSpace will be set to the maximum of CurBorderSpace and Left, Top, Right, Bottom.

RemainingClientRect will shrink.

RemainingClientRect will not shrink to negative size.