TDockManager is an abstract class for managing a dock site's docked controls.

The declaration contains a number of procedure definitions that are 'virtual' and 'abstract'. This means that there is no implementation specified: these essentially represent 'place-holders', and it is the responsibility of the developer of descendant classes to override these methods and implement them as desired.

Create - constructor for TControlBorderSpacing: sets some default positions, dimensions and alignments, then performs inherited Create

Overrides ancestor constructors, and may be overridden

TAnchorSide

    Class holding the reference sides of the anchors of a TControl.
    Every TControl has four AnchorSides:
    AnchorSide[akLeft], AnchorSide[akRight], AnchorSide[akTop] and
    AnchorSide[akBottom].
    Normally if Anchors contain akLeft, and the Parent is resized, the LCL
    tries to keep the distance between the left side of the control and the
    right side of its parent client area.
    With AnchorSide[akLeft] you can define a different reference side. The
    kept distance is defined by the BorderSpacing.
    
    Example1:
       +-----+  +-----+
       |  B  |  |  C  |
       |     |  +-----+
       +-----+

      If you want to have the top of B the same as the top of C use
        B.AnchorSide[akTop].Side:=asrTop;
        B.AnchorSide[akTop].Control:=C;
      If you want to keep a distance of 10 pixels between B and C use
        B.BorderSpacing.Right:=10;
        B.AnchorSide[akRight].Side:=asrLeft;
        B.AnchorSide[akRight].Control:=C;

      Do not setup in both directions, because this will create a circle, and
      circles are not allowed.
      
    Example2:
            +-------+
      +---+ |       |
      | A | |   B   |
      +---+ |       |
            +-------+
            
      Centering A relative to B:
        A.AnchorSide[akTop].Side:=arsCenter;
        A.AnchorSide[akTop].Control:=B;
      Or use this. It's equivalent:
        A.AnchorSide[akBottom].Side:=arsCenter;
        A.AnchorSide[akBottom].Control:=B;

TControlActionLink - links the current control to an action

Defines a number of protected methods (inherited from TActionLink) for checking which parts of the control are linked to the action

TControl is the main ancestor class for all visual controls.

The definition includes a large number of constants, types and methods that are inherited by derived classes and types.

These include devices for defining and controlling:

• the state and position of the object (including alignment and anchoring),
• the state of the mouse,
• whether dragging or docked,
• the size and type of border,
• the way child components should behave,
• the actions to be taken in response to various events,
• and the way the Control should be drawn.

Properties defined here can be overridden by descendant classes.

TControl.DoAutoSize

IMPORTANT: Many Delphi controls override this method and many call this method directly after setting some properties.

During handle creation not all interfaces can create complete Device Contexts which are needed to calculate things like text size.

That's why you should always call AdjustSize instead of DoAutoSize.

function TControl.AutoSizeCanStart: boolean;
  
  Returns true if DoAutoSize can start. That means, it tests the minimum
  requirements to start. Some controls need even more.

  It returns false if
  - AutoSize=false
  - or the control is currently autosizing
  - or the control is not visible
  - or the control is destroying

CalculatePreferredSize - find default/preferred height and width

procedure TControl.CalculatePreferredSize

(var PreferredWidth, PreferredHeight: integer; WithThemeSpace: Boolean);

Calculates 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.

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

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 passed to the widgetset.

{ try to set the automatic changed bounds
  If the interface does not like our bounds, it sends a message with the real
  bounds, which invokes the automatic realigning of the control, .. a circle.
  To break the circle, only bounds that are different from the last try will
  be sent.
}

MouseDown - a procedure that allows the programmer to simulate a mouse button being down over the control, and initiates the same Action as that associated with the event

Button specifies which mouse button; Shift signifies whether Ctrl, Shift or Alt keys are also pressed; X, Y show mouse position

MouseMove - a procedure that allows the programmer to simulate a mouse being moved over the control, and initiates the same Action as that associated with the event

Shift signifies whether Ctrl, Shift or Alt keys are also pressed; X, Y show mouse position

MouseUp - a procedure that allows the programmer to simulate a mouse button being Up over the control, and initiates the same Action as that associated with the event

Button specifies which mouse button; Shift signifies whether Ctrl, Shift or Alt keys are also pressed; X, Y show mouse position

AssignTo - if the Destination is a CustomAction, copies some specified properties to the Destination, otherwise calls inherited AssignTo

The copied properties are:

• Enabled
• Hint
• Caption
• Visible
• OnExecute (copied to OnClick)
• HelpContext
• HelpKeyword
• HelpType

The form is a real connection to the target screen.

For example, the gtk under X gathers some screen information, but not before form creation.

But this information is needed to create DeviceContexts, which are needed to calculate Text Size and such stuff needed for AutoSizing.

That's why AdjustSize delays AutoSizing till this moment.

Now do the AutoSize.

Notification - calls inherited Notification, then takes action depending on Operation

If Operation is removal, then nullifies any popupmenus or actions.

Disconnects all anchors.

// 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 are 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.

Defaults set by the Constructor include ControlStyle, Constraints, BorderSpacing, Anchoring, alignment, CaptureMouseBottons, Color, Visibility, Hinting, Cursor, Font, The WindowProcedure to be used, the Help type, the FloatingDockSite and Enabled properties

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.
 ------------------------------------------------------------------------------}

HasParent - returns True if there is a parent component responsible for streaming

This function will be called during streaming to decide if a component has to be streamed by its owner or parent

This control is the parent of another control.

AControl: the control of which this is a parent.

Result: true if this is a parent

The control is visible on the current desktop

Checks parents too

* 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

Create - constructor for TControlChildSizing: performs inherited Create then sets some default alignments and sizes

Overrides ancestors, may be overridden

Defines many of the properties inherited by child classes, particularly those related to size, position, bounds, docking, the responses to mouse movements and key presses.

Defines procedures and functions related to windowed controls, some of which override virtual methods defined in ancestor classes.

TWinControl DoSetBounds

Params: ALeft, ATop, AWidth, AHeight : integer

Anticipate the new clientwidth/height and call inherited method

Normally the clientwidth/clientheight is adjusted automatically by the interface. But it is up to interface when this will be done. The gtk for example just puts resize requests into a queue. The LCL would resize the child components just after this procedure due to the clientrect. On complex forms with lots of nested controls, this would result in thousands of resizes.

Changing the clientrect in the LCL to the most probable size reduces unneccessary resizes.

• Checks whether Autosize is in fact permitted
• Checks for unaligned child components and fits them in as best it can
• Moves the constrained (aligned) child components to the correct position
• Adjusts the size of the client rectangle
• Adjusts the bounds of the whole control

Because this method involves so much overhead, the simpler TControl.AdjustSize is often called instead.

procedure TWinControl.CalculatePreferredSize(var PreferredWidth, PreferredHeight: integer; WithThemeSpace: Boolean);

Calls the inherited method to calculate the default/preferred width and height for a TWinControl, 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.

TWinControl overrides this:

• If there are child components, their total preferred size is calculated
• If this value can not be computed (e.g. the children depend too much on their parent clientrect), then the interface is asked for the preferred size

For example the preferred size of a TButton is the size, where the label fits exactly. This depends heavily on the current theme and widgetset.

This value is independent of constraints and siblings, only the inner parts are relevant.

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 it is passed as a parameter to the widgetset.

CreateParams - create parameters for this windowed class

Definition of parameters:

TCreateParams = record
    Caption: PChar;
    Style: Cardinal;
    ExStyle: Cardinal;
    X, Y: Integer;
    Width, Height: Integer;
    WndParent: HWnd;
    Param: Pointer;
    WindowClass: TWndClass;
    WinClassName: array[0..63] of Char; 
End;

Creates the interface object, sets parameters and assigns the handle

Removes handles and restores colour and font flags

InitializeWnd - initialise the window for this control

Gets called after the Handle is created and before the child handles are created

Works out the correct bounds, sets style, fonts and colours, performs any pending resize operations

LM_SETFOCUS: gets parent form and show this control as focused

LM_KILLFOCUS: removes focus fromthis control

LM_NCHITTEST: check transparency etc

Mouse and Button messages: process any docking instructions

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.

Note: we recommend you to use OnUTF8KeyPress to prevent data lost. National chars are converted from UTF8 to the system encoding in OnKeyPressEvent. This can cause a data lost if symbol cannot be converted, which means OnKeyPress is not called or with Char=#0. OnUTF8KeyPress does not perform this conversion.

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.

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

Differs from OnKeyDown in that the char does not converts to the system encoding

Create - Constructor for TWinControl: performs inherited Create and initialises some local variables

Overrides ancestor constructor, and may in turn be overridden

Among additional variables initialised are: CompStyle, ChildSizing, Brush, TabOrder and TabStop

Destroy - destructor for TWinControl and derived classes

Destroys any allocated handles, removes any docking links, and frees the resources used by the control, then performs inherited Destroy

Overrides ancestor destructors, and may in turn be overridden

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.

Create - constructor for TGraphicControl: performs inherited Create then creates local Canvas

Overrides ancestor and may be overridden

Destroy - destructor for TGraphicControl: frees local canvas and performs inherited Destroy

Overrides ancestor destructors, and may be overridden

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.

Contains simple basic definitions to create, destroy and paint window controls and set basic properties like canvas and border

Destroy - destructor for TCustomControl: frees local Canvas then performs inherited Destroy

Overrides ancestor destructors, may be overridden

Create - constructor for TDockZone: sets local variables to show the Tree to which the zone belongs and the ChildControl which it contains, sets default bounds and then performs inherited Create

Overrides ancestor constructors, and may be overridden

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