                           The ACL library
                        ( API Controls Library)
                               ACL.PAS
                   Copyright: Alexander B. Bokovikov, 
                   Ekaterinburg, Russia, 1998 - 1999.

                             Version 3.0

                          GENERAL DESCRIPTION

1. For what ACL is necessary (a few common words).

    Once I needed to write a small (on the executable file size) program with a 
simple (but yet existing) interface. I have analyzed all available for me C++ 
and Delphi libraries and has understood, that they do not give the rather small
EXE size. In C++ the file size can be made small, but in this case it is neces-
sary to carry behind itself of DLL on a pair of hundreds kilobytes. Besides I
specialize on Delphi, and it does not give any alternative VCL at all.
    To write the program on pure API certainly it is possible, but I have deci-
ded to reach both goals - both to make that program and to receive the tool, 
through which it would be possible in further to build similar programs, almost,
as on Delphi with VCL. So the idea to create my own TWinControl and all standard
Windows controls classes, derived from it has appeared. I have tried to under-
stand, how it is made in Delphi and has seen, that the global window procedure
from which a transmission of handle to the particular control window procedure
has made (at least I have understood that just so). 
    And it was not pleasant to me. I would like to create the class COMPLETELY
including ALL interaction with the system - i.e. that also window procedure 
would be a method of that class. Moreover, I have gone further and has wanted 
to make it a virtual method, such a way to make a possibility to modify window
procedure without modification of source codes of the given unit in future.
    As the result this library has appeared. It is good, that Delphi 4 has be-
come to understand the instruction "stdcall" even for methods. Besides I would 
like to save habitual for Delphi style and names of objects. If you want to 
combine this unit with Delphi VCL, there will be a names conflict of classes
and many procedures. But I do not see sense in such combination, as anything
essentially new, except for the size of an executable file this unit does not
give. Moreover, for some reasons I'd like not recommend at all it to do.

2. Main features of the TWinControl class.

    The basic difference from VCL in the mechanism of construction of the main
window class (TWinControl) is that, as was already told, the window procedure
is a virtual method. It is made as follows.
    Any virtual method, declared in Delphi, as:

  Function MyVirtualMethod (Param1, Param2, Param3: integer): integer; virtual;

is compiled into the procedure, at which call, into the stack not three but 
four parameters (i.e. on 1 are more) are put. More precisely speaking, into the
stack they are placed by the one who calls the given method. But method restores
the stack by the RET command and remove from it just four parameters. This addi-
tional parameter usually carries the pointer to a particular copy of the class,
the owner of the given method. Otherwise from a body of a virtual method it 
would be impossible to address to fields of the given copy of the class, because
the address of a virtual method is dynamic. 
    And, as for usual methods (i.e. just with the above-stated declaration) the
particular parameter transmission mechanism depends on optimization presence at
compilation time (parameters are transferred through the CPU registers whenever
possible, instead of through the stack), if to declare such method, as 
"stdcall", such ambiguity disappears also parameters are always transferred 
through the stack.
    Thus, if we shall declare the window procedure, as a method of the class

           Function WindowProc (AMessage: TMessage;
                                WParam: integer;
                                LParam: integer): integer; virtual; stdcall;

and inside this procedure we shall take from the stack an additional (nearest 
to the ambassador EIP) parameter, this parameter will be Handle of the given
window. Here it is necessary to take into account, that the call of the window
procedure is ALWAYS made by the system and NEVER by the object. Therefore 
conflicts caused by incorrect interpretation of this parameter will not appear.
On the first sight such technique can seem by some "alchemy", but if to ponder,
anything dangerous here is not present. At least I so consider also converse as
early as one nobody has proved.
    The second problem solved in the given unit is the transmission of handle 
to that concrete copy of the class, whose window procedure has received the 
message. As was already told, the window procedure is always called by the 
system, which never knows about what object posesses the given procedure. In 
the first version of this unit it was decided by storing of the owner pointer
in area, the access to which provides the GWL_USERDATA parameter. In the second
version this area is released for the user, and the storing occurs through API
GetProp()/SetProp() functions.
    The third problem is the transmission of the pointer on the window procedure
at registration of the class of the window. It is impossible to receive the 
virtual method address simple, as @MyVirtualMethod, as such a way gives the 
static address and suits only for static methods. TObject.MethodAddress isn't
suitable too, because it gives right address for published methods only. But if
we apply the assembler, it is possible to write such method of the object:

  Function TMyClass. GetVirtualMethodAddress: pointer; assembler;
  begin
    Mov eax, [eax]                        // the VMT address
    mov eax address, [eax + MethodOffset] // the address of a 
                                          // concrete method 
  end;

which returns the pointer on a virtual method. The MethodOffset parameter is 
determined by offset of the necessary method in the virtual methods table. 
It is easy for receiving, by counting all declarations of virtual methods 
(just "virtual", but not "override") up to interesting us and multiplication
obtained number on 4. For the first virtual method this offset is equal to zero.
Thus it is supposed, that the class is derived directly from TObject. If it is
not so, it is necessary to count the virtual methods of all ancestors of the
given class the ambassador TObject also.

3. Classes of the unit.

TFont - encapsulates operation with Windows fonts
TFonts - stores the fonts list in the system similarly to Screen.Fonts in VCL
TControl - abstract class a component.
TWinControl - base class a window component.
TStdControl - base class a standard component Windows.
TLabel - label
TEdit - edit control
TListBox - listbox control
TButton - button
TCheckBox - checkbox
TComboBox - dropdown list
TGroupBox - group window
TProgressBar - progress indicator
TKeyboard - keyboard layout indicator

4. Main methods and properties of the TFont class.

== Methods of the TFont class of ======================================= =================

Constructor Create; 
            class constructor.
Destructor Destroy; override;
           class destructor.

== Properties of the TFont class ===============================================

Property Handle: HFont read FHandle; 
         Provides access to the Windows fonts handles.
Property PixelsPerInch: Integer read FPixelsPerInch write SetPixelsPerInch;
         font resolution(pixel per inch)
Property Charset: TFontCharset read GetCharset write SetCharset;
         font character set (language).
Property Color: TColor read FColor write SetColor; 
         font color.
Property Height: Integer read GetHeight write SetHeight; 
         height of font characters in pixels.
Property Name: TFontName read GetName write SetName;
         font name.
Property Pitch: TFontPitch read GetPitch write SetPitch;
         font type (fixed / proportional).
Property Size: Integer read GetSize write SetSize;
         font size.
Property Style: TFontStyles read GetStyle write SetStyle;
         font style.

5. Main methods and properties of the TFonts class.

== Methods of the TFonts class of ======================================= ================

Constructor Create; 
            class constructor. Is called in "initialization" section of the 
            Acl.pas unit.
Destructor Destroy; override; 
           destructor. Is called in "finalization" section of the Acl.pas unit.
Function IndexOf (APitch: TFontPitch; const AName: string): integer;
         Returns a font ordinal number in the list of fixed/proportional fonts.
Function IsDefaultPitch (const AFont: TLogFont): boolean; 
         is true, if 䮭 has the default type.
Function IsFixedPitch (const AFont: TLogFont): boolean;
         is true, if font has the fixed type.
Function IsVariablePitch (const AFont: TLogFont): boolean;
         is true, if font has the proportional type.
Function FindFont (AName: TFontName; APitch: TFontPitch): TLogFont;
         Finds given font.
Property Count: integer read FCount;
         fonts count registered in the system
Property Font [index: integer]: TLogFont read GetFont;
         Returns given font.

6. Main methods and properties of the TControl class.

== Methods of the TControl class of ======================================= ==============

Constructor Create (AOwner: TWinControl);
            the class constructor. AOwner - owner a component. It is that of 
            components, in whose window  the given component will be drawn.
Procedure Paint (DC: HDC); virtual; abstract; 
          the drawing procedure of a component. HDC - device context. 
          An abstract method. The successors should it override.
Destructor Destroy; override; 
           destructor of the class.

== Property of the TControl class of ======================================= ============

Property Left: integer read FLeft write FLeft;
         horizontal coordinate of the left upper corner a component. The 
         component - owner is counted of the rather left upper corner.
Property Top: integer read FTop write FTop; 
         vertical coordinate of the left upper corner a component. 
         The component - owner is counted of the rather left upper corner.
Property Width: integer read FWidth write FWidth; 
         width a component.
Property Height: integer read FHeight write FHeight;
         height a component.

7. Main methods and properties of the TWinControl class.

== Methods of the TWinControl class ============================================

Constructor Create (AParent: TWinControl); virtual; 
            the designer of the class. AParent - object - owner of the given
            window (not in sense VCL " Owner ", namely in sense VCL " Parent ").
Destructor Destroy; override;
           Destructor. Inside calls DestroyWindow(), therefore for destruction
           of the window it is enough only to destroy the object.
Procedure CreateWnd; virtual; 
          Creates the window. Previously it is necessary to set style of the
          window and others it parameters, and also (if necessary) to assign
          the handler of event OnCreate.
Procedure Close; 
          Closes the window, but does not destroy it.
Procedure Show; 
          Outputs the window on the screen makes it visible. At creation the 
          window is invisiblis.
Procedure Hide; 
          Hides the window.
Function ShowModal: TModalResult;
         makes the window modal, i.e. the messages are accepted by the window 
         before pressing the button with non-zero property ModalResult (as well
         as in VCL) or until EndModal() procedure is called;
Procedure EndModal (Value: TModalResult); 
          terminates a modal state of the window.
Procedure ProcessMessages; 
          Processes all the messages in queue.
Procedure Invalidate; 
          redraws the window.
Procedure SetFocus; 
          Gives the focus to the window.
Procedure SelectPrev; 
          Gives focus to the previous window among equal on an enclosure
Procedure SelectNext; 
          Gives focus to the following window among equal on an enclosure
Procedure SelectFirst; 
          Gives focus to the first window among equal on an enclosure,
Procedure SelectLast; 
          Gives focus to the last window among equal on an enclosure,
Function IsFirstSelected: boolean;
         Returns activity of the first window among equal on an enclosure.
Function IsLastSelected: boolean;
         Returns activity of the last window among equal on an enclosure.
Procedure InsertWinControl (AControl: TWinControl);
          Inserts the current window into the owner window.
Procedure InsertControl (AControl: TControl);
          Inserts the TControl class object into the current window.
Procedure SetFont (const AFont: TLogFont);
          Sets window font.

== Properties of the TWinControl class of =======================================

Property AutoStop: boolean read FAutoStop write FAutoStop;
         If true, at destruction of the given window the program is completed
         (the PostQuitMessage procedure (0) is executed;
Property Caption: shortstring read GetText write SetText;
         the window caption.
Property Color: TColor read FColor write SetColor;
         window background color.
Property HelpContext: DWORD read FHelpContext write FHelpContext;
         number of a context of the help of the window.
Property HelpFile: shortstring read FHelpFile write FHelpFile;
         help file name of the window.
Property Style: longint read FStyle write FStyle;
         window style. For more detailes see Win32 API CreateWindow().
Property ExStyle: longint read FExStyle write FExStyle;
         the extended window style. For more detailes see Win32 API 
         CreateWindowEx().
Property Ctl3D: boolean read FCtl3D write FCtl3D;
         window 3D-shape feature.
Property TextColor: TColor read FTextColor write SetTextColor;
         window text color.
Property Enabled: boolean read FEnabled write SetEnabled;
         window activity feature
Property Handle: HWnd read FHandle;
         the window handle.
Property Font: TFont read FFont; 
         window text font.
Property Left: integer read FLeft write SetLeft;
         horizontal coordinate of the left upper corner of the window.
Property Top: integer read FTop write SetTop;
         vertical coordinate of the left upper corner of the window.
Property Width: integer read FWidth write SetWidth;
         width of the window.
Property Height: integer read FHeight write SetHeight;
         height of the window.
Property Parent: TWinControl read FParent; 
         the owner of the window.
Property ClientWidth: integer read GetClientWidth; 
         width of a window client area.
Property ClientHeight: integer read GetClientHeight; 
         height of a window client area.
Property ClientRect: TRect read GetClientRect; 
         Describes a window client area, as a rectangle.
Property IsModal: boolean read FIsModal;
         modal state feature of the window in a current time.

== Events of the TWinControl class =============================================

Property OnCreate: TNotifyEvent read FOnCreate write FOnCreate; 
         creation of the window.
Property OnDestroy: TNotifyEvent read FOnDestroy write FOnDestroy; 
         destruction of the window.
Property OnClose: TCloseEvent read FOnClose write FOnClose; 
         closing of the window.
Property OnClick: TNotifyEvent read FOnClick write FOnClick; 
         pressing of the left key of the mouse in the window.
Property OnErase: TEraseEvent read FOnErase write FOnErase; 
         clearing of a window client area before it painting.
Property OnHitTest: THitTestEvent read FOnHitTest write FOnHitTest; 
         the analysis of a mouse disposition in the window.
Property OnMouseDown: TMouseEvent read FOnMouseDown write FOnMouseDown; 
         pressing of mouse buttons in the window.
Property OnKeyDown: TKeyEvent read FOnKeyDown write FOnKeyDown; 
         keyboard keys pressing down.
Property OnKeyUp: TKeyEvent read FOnKeyUp write FOnKeyUp;
         keyboard keys release.
Property OnKeyPress: TKeyPressEvent read FOnKeyPress write FOnKeyPress;
         keyboard input.
Property OnNIMove: TNotifyEvent read FOnNIMove write FOnNIMove; 
         moving of the mouse on an icon in the panel "near hours".
Property OnNILDown: TNotifyEvent read FOnNILDown write FOnNILDown; 
         pressing of the left key of the mouse on an icon in the panel 
         "near hours".
Property OnNILUp: TNotifyEvent read FOnNILUp write FOnNILUp; 
         a release of the left key of the mouse on an icon in the panel
         "near hours".
Property OnEndSession: TCloseEvent read FOnEndSession write FOnEndSession;
         completion of a session Windows.

8. Main methods and properties of the TStdControl class.

== Methods of the TStdControl class ===========================================

Procedure CreateWnd; override; 
          Creates the window. Previously it is necessary to set style of the 
          window and others it parameters, and also (if necessary) to assign 
          the handler of event OnCreate.

9. Main methods and properties of the TLabel class.

== Methods of the TLabel class ================================================

Constructor Create (AParent: TWinControl); override; 
            the designer. AParent - owner a component.

== Properties of the TLabel class ==============================================

Property TextFormat: longint read FFormat write FFormat; 
         the type of text formatting. For details see API DrawTextEx().

10. Main methods and properties of the TEdit class.

== Methods of the TEdit class =================================================

Constructor Create (AParent: TWinControl); override;

== Properties of the TEdit class ==============================================

Property MaxLength: integer read GetMaxLength write SetMaxLength; 
         maximum length of string.
Property MarginWidth: word read GetMargin write SetMargin; 
         an indent from the left and right edge(territory)
Property Text: shortstring read GetText write SetText; 
         the edited text.

11. Main methods and properties of the TListBox class.

== Methods of the TListBox class ==============================================

Constructor Create (AParent: TWinControl); override; the designer.

Function Add (const S: shortstring): Integer; 
         to add string into the list.
Procedure Insert (Index: Integer; const S: shortstring); 
          to insert string into the list.
Procedure Delete (Index: Integer); 
          to delete string from the list.
Procedure Clear; 
          to clear the list.
Procedure SelectItem (Value: integer); 
          to select string(line).

== Properties of the TListBox class ==========================================

Property Count: integer read GetCount; 
         number of strings(lines).
Property Focused: integer read GetFocused write SetFocused; 
         active string.
Property Items [Index: integer]: shortstring read Get write Put;
         strings of the list.
Property Objects [Index: integer]: TObject read GetObject write PutObject;
         the objects of strings of the list (defined by the user).
Property Sorted: boolean read FSorted write SetSorted;
         The sorting of strings according the alphabet is enabled.

12. Main methods and properties of the TButton class.

== Methods of the TButton class ==============================================

Constructor Create (AParent: TWinControl); override; 
            class constructor.

== Properties of the TButton class ===========================================

Property ModalResult: TModalResult read GetModalResult write SetModalResult; 
         If Not 0, at pressing this button in the modal window there is an 
         exit from the ShowModal procedure with result equals ModalResult.

13. Main methods and properties of the TCheckBox class.

== Methods of the TCheckBox class ============================================

Constructor Create (AParent: TWinControl); override; 
            class constructor.

== Properties of the TCheckBox class =========================================

Property Checked: boolean read FChecked write SetChecked; 
         a state of "choice" of the given check box.

14. Main methods and properties of the TComboBox class.

== Methods of the TComboBox class =============================================

Constructor Create (AParent: TWinControl); override; 
            class constructor.
Function Add (const S: shortstring): Integer; 
         Adds string into the dropdown list.
Procedure Insert (Index: Integer; const S: shortstring); 
          Inserts string into the given position of the list.
Procedure Delete (Index: Integer); 
          Deletes the given string(line).
Procedure Clear; 
          Clears the dropping out list.

== Properties of the TComboBox class ===========================================

Property Count: integer read GetCount; 
         number of strings(lines) in the dropping out list.
Property Error: integer read FError; 
         a state of an error returned by the messages CB _ XXXX.
Property ItemIndex: integer read GetFocused write SetFocused;
         an ordinal number of selected string in the list.
Property Items [Index: integer]: shortstring read Get write Put; 
         strings of the list.
Property Sorted: boolean read FSorted write SetSorted; 
         presence of sorting of strings by alphabet.
Property Text: shortstring read GetText write SetText; 
         value of a text field.

15. Main methods and properties of the TGroupBox class.

== Methods of the TGroupBox class ============================================

Constructor Create (AParent: TWinControl); override; 
            class constructor.

16. Main methods and properties of the TProgressBar class.

== Methods of the TProgressBar class =========================================

Constructor Create (AParent: TWinControl); override; 
            class constructor.

== Properties of the TProgressBar class =======================================

Property Range: word read GetRange write SetRange; 
         a range of progress - indicator.
Property Position: word read GetPosition write SetPosition; 
         a current position of progress - indicator.
Property Step: word read GetStep write SetStep; 
         step of progress - indicator.

/////////////////////////////////////// //////////////////////////////////////

