The 16.12.2001 Information about the examples and library.

All examples where developped with DevPascal version 1.9, which works
with FreePascal under windows 95.

I did it first to learn FreePascal under windows. Then to developp
a library which I had under Borland Pascal under Windows.

You can use all this information as you want, but you cannot
put a copyright on any of these files.

Developped by Bernard Gisin, for fun.

 1 )The Examples :
 2) Conventions :
 3) Variable notation convention :
 4) The units of the library :
    Units alphabetically ordered :
 5) Objects hierarchy (Familly tree)
 6) Global variables, constant and procedures of the library.
    Global variables : 
    Global constants : 
    Global procedures : 
 7) Personal remarks.
 8)To come in the future I hope :

1) The Examples :
"""""""""""""""""
tDebug.pp  Show how to use the  wDebug0.pp  unit
           It is very usefull to write information in an independent 
           window. Very easy to use.
tEx001.pp  First example of a program using the units
           wApplication0.pp  and  wWindow0.pp
           It is the minimal program.
tEx002.pp  Second example of program using the units
           wApplication0.pp  and  wWindow0.pp
           This example shows how to react to events,
           and how to write text in the main window
tEx003.pp  Third example of program using the units
           wApplication0.pp  and  wWindow0.pp
           This example show how to create a menu.
tEx004.pp  Fourth example of program using the units
           wApplication0.pp  and  wWindow0.pp
           wEditBox0.pp  to facilitate to have an editBox in a window
           wStatusLine0.pp to have a status line at the bottom of a window
           This example show how to create a mini text editor
           The amount of text accepted is quite small, less than 50 Kbytes !
           This example is based on the  Edit.pp  example, created by
           Copyright (c) 1999 by Michael van Canneyt and Goran Andersson
tEx005.pp  Fifth example of program using the units
           wApplication0.pp  and  wWindow0.pp
           It gives an example of creating a second window,
           having its own window message processing, and its
           own menu. It is an independent window.
tEx006.pp  Sixth example of program using the units
           wApplication0.pp  and  wWindow0.pp
           wEditBox0.pp  to facilitate to have an editBox in a window
           wStatusLine0.pp to have a status line at the bottom of a window
           wApplicParam2.pp to add some information in the  .prm  parameter file
           which saves information about the application,
           such as windows sizes and positions.
           Example of a second window, having its own menu and own
           message processing. This is unusual, and needs some work.
           In  tEx005.pp  example was given, with minimal changes.
           This example is more elaborated, modifying more things
           in the secondary window.

tEx007.pp
   Seventh example of program using the units
   wApplication0.pp  and  wWindow0.pp
   wRichText0.pp
   This unit helps understanding the use of RichText controls.
   It uses a lot the  wDebug0.pp  unit to show the messages handling.
   It is quit complicate, and will be simplified in the library,
   normally in january 2002.
   It uses the  Riched32.dll  file, which should be in your
   windows\system directory.
   This example show how to create a basic text editor
   using the richedit control

tEx008.pp
   Eigth example of program using the units
   wApplication0.pp  and  wWindow0.pp
   wRichText0.pp
   This example is very similar to the previous one.
   The debugging informations have been removed.
   Some functionnalities may be have added.
   It uses the  Riched32.dll  file, which should be in your
   windows\system directory.
   This example show how to create a basic text editor
   using the richedit control. Much more has to be done...

tEx009.pp
   Ninth example of program using only the Window unit
-  This example show how to create a Multiple Document Interface (MDI)
   which is a window containing other windows.
-  The library is not used. I did this in order to show how MDI
   can be created from nothing. But with the library,
   as shown in tEx010.pp, it is much simpler.
-  This is a minimal example, of creating an MDI, with a menu,
   and default simple behaviour

tEx010.pp
   Tenth example of program using :
   wApplication0  as usuall
   wMDIWindow0  to treat MDI main window
   wMDIChildWindow0  to treat MDI child window
   This example show how to create a Multiple Document Interface (MDI)
   which is a window containing other windows.
-   Uses the library to simplify greatly the treatment of MDI windows.
-  This is a small example, of creating an MDI, with a menu,
   and default simple behaviour

See  BugsReport01.txt  for knows errors in these examples.

2) Conventions :
""""""""""""""""
Filename beggining with a  't'  are test programs or demo programs
Filename beggining with a  'w'  are units of the library.
Filename beggining with a  'u'  are units of the application
(application = program)
If an application is made of more than one file, 
it is put in a sub-directory

The  '0'  ending most of my units indicate that they use the
unit Windows,  and thus are dependent of windows.

The  '1'  ending my units indicate that they don't use the
unit Windows. They still could depend of Windows.
I'm still not very clear about it.

The  '2'  ending my units indicate that they only use units
from the library and no others. Thus if the units ending with  '0'
of the library are rewritten for linux, the units ending with  '2'
should also work under linux.
This is a long term project...  But when will the fun stop ?

For a unit, you must put the number '0' or '1' or '2' at the end of the filename
to use it. But for objects, it is better removing this number. See remarks at
the beginning of '4) The units of the library :'.

3) Variable notation convention :
"""""""""""""""""""""""""""""""""
As a convention, lower case letters before the first 
uppercase letter indicate the type of the variable. For example :
  n  before an integer   ex:  nInt  : integer;
  w  before a  word      ex:  wNum  : word;
 dw  before a double word, which is the same as a Cardinal.
  b  before a  byte      ex:  bVal  : byte;
  c  before a  char      ex:  cH    : Char;
  h  before a  hangle    ex:  hWin  : HWND;
  l  before a  longint   ex:  lVal  : longint;
  f  before a  boolean   ex:  fFlag : boolean;
  f  before a  text      ex:  fIn, fOut :text; ('f' is used twice, but I never had confusion)
  p  before a  pointer   ex:  pPtr : ^word;
  o  before an object    ex:  oApp : TApplication;
  a  before an array     ex:  anT  : array[1..10] of integer;
  str before a string    ex:  strS : ShortString;
  r  before a record     ex:  rRec : RECT;
  v  before a double     ex:  vX   : double;
 sv  before a single     ex:  svX  : single;
  z  before a complex    ex:  zExp : complex;  This type will be defined later.
                                               Tt is usefull for math.

Other examples :
pcH : PCHar;   poWin : PWindow0;   
paoW  = pointer on an array of objects
papoW = pointer on an array of pointer on objects. 

I put also 'gl'  before variable which are global to the unit,
but defined in the IMPLEMENTATION part.

I put also 'ggl'  before variable which are global to the unit,
and defined in the INTERFACE part.

4) The units of the library :
"""""""""""""""""""""""""""""
Each unit correspond to one object, with the same name, beginning with a  "T"
instead of the  "w". Sometimes I will not make a distinction between
the unit and the object defined in that unit.
For a unit, you must put the number '0' or '1' or '2' at the end of the filename
to use it. But for objects, it is better removing this number, sice methods
and properties can move from the parent object to its descendent, being
an object ending with a higher number. In this last case, you will have to
rename the uses part of your application. For example,
uses wWindow0.pp  might become  
uses wWindow2.pp  or
uses wWindow0.pp, wWindow2.pp

First I want to begin with :
wDebug0;
   This is THE most usefull unit for developping. It is a tool for debugging
   by writing information in a separate text window during the execution
   of the program. It is independent of the others.
   See bellow and the wDebug0.pp for more info.

Units alphabetically ordered :
''''''''''''''''''''''''''''''
wApplication0;
   This unit uses object programming to simplify the developpment of programs.
   It contains the loop geting the windows messages, and dispatching it.
   It creates the main window of the application.
   See tEx002.pp and all nearly all other to see this unit can be used.

wApplicParam2;
   This unit help saving and loading parameters of an application,
   as for example the position and size of the main window.
   The file where the parameters are saved is a text file, saved
   in the same directory as the  .exe  file, with the same name as
   the  .exe  file, but with the extension  .prm
   It is easy to define a child object, which saves more parameters
   dependent of the application.
   It is done in a way, such that it is compatible up and down with older 
   and newer version. It means the parameters can be used by any version of
   the program. Older version will not use the added information. 
   Newer versions will use default values for information that was not
   contained in the parameters. For example remembering the window state
   (maximized or normal) has been added later, but this extra info will
   not disturb older versions using the parameters file.
   See tEx006 to see how this unit can be used.

wControl0;  descendent of wWindowBase0
   Parent of any control, such that EditBox, StatusLine and RichEdit.
   Contain what is common to every control.
   Help treating the messages handle of controls.
   No examples are associated with this unit-object, since it is
   used for its descendents.

wDebug0;
   This unit can be usefull while developping, to write informations 
   into a window, called the debugging window.
   To use it, add this unit in the uses, typically :
   uses  Strings,Windows,wDebug0;
   Then each time you want to write information in the debugging window, call
   DBW0(wNumber, string);
   If the debugging window is not open, it will open automatically.
   string is the information you want to be written.
   wNumber is used to select if the information will be or not written
   in the debugging window.
   see  wDebug0.pp for more information.
   See tDebug.pp to see an example of using this unit.
   I uses this unit in every other unit while developping.

wEditBox0;  descendent of  wControl0
   To facilitate to have an EditBox in a window.
   See tEx004.pp, tEx005.pp and tEx06.pp to see how this unit can be used.

wMDIChildWindow0;  descendent of  wWindow0
   This unit simplifies the handling of Multiple Interface Document 
   child windows (MDI). Each MDI child window is associated with an object
   TMDIChildWindow0 which can contain all variables (=information) 
   associated with the MDI child windo.
   This object works in relation with the  TMDIWindow0  object.
   See tEx009.pp and tEx010.pp to see how this unit can be used.

wMDIClientWindow0.pp
   This unit & object doesn't exist yet.
   It will come later.

wMDIWindow0;  descendent of  wWindow0
   This unit simplifies the handling of Multiple Interface Document 
   main window (MDI). A main MDI window is a normal window, containing
   another window called the client window which has its own predefined
   class 'MDICLIENT'. The main window do not show the contant of its
   client region, and the client window is completly invisible. I don't
   know why it has been done this way?
   The client window is the parent of any MDI child window, which are
   visible in the client region of the main window.
   This object works in relation with the  TMDIChildWindow0  object.
   See tEx009.pp and tEx010.pp to see how this unit can be used.

wObjectCreator2;
   The idea of this unit is that objects like  Windows  EditBox etc.
   which are created in the library, can be objects you defined
   in your main application.
   The library will call
   gglpoObjCreate^.xxx  to create a new object, where  'xxx'  represent
   the object to be created.
   Thus if  gglpoObjCreate  points to a descendent of  TObjectCreator2
   defined in your application, it will create the object as you want.
   For example, the  TApplication0  object creates  an TApplicParam2
   object. But by creating it through calling  
   gglpoObjCreate^.CreateApplicParam;
   you can make that a descendent of  TApplicParam2  is created insead.
   In tEx006.pp another method was used to create a descendent of
   the application parameters.
   Example will come later.

wRichText0;  descendent of  wControl0
   To facilitate to have an RichEdit control in a window.
   This allow to have a texte processor in your application.
   See tEx007.pp, tEx008.pp to see how this unit can be used.

wStatusLine0;  descendent of  wControl0
   to facilitate to have a Status line in a window
   See tEx004.pp, tEx005.pp and tEx06.pp to see how this unit can be used.

wUtiles0;
   Some utilities procedures and function.
   This is not associated with an object.

wWindow0;  descendent of  wWindowBase0
   This object describe the windows. It is very usefull to define the windows
   used in your application. It is the parent of MDI main and child windows.
   See tEx002.pp and all nearly all other to see this unit can be used.

wWindowBase0;
   To group what is common to every window.
   For example the handle of the window.
   In windows, the handle of a window is what defines the window, like
   the firstname + name + adresse of any person defines you for any 
   administration. In object programming, it is a pointer on the object
   which defines the object. Knowing the pointer, you can know 
   the properties (=variables) and the methodes (=procedures) of the object.
   Each window is associated with an object.
   In the object, the property (=variable)  hWin  gives you the handle of the
   corresponding window, which is used in most windows call.
   Knowing the handle, you can get the pointer on the corresponding object
   by calling the procedure :
   gglGetPointerObject(hWinPrm:HWND; var wType:word; var poWin:PWindowBase0);
   hWinPrm is the handle.
   poWin will point on the window object.
   wType will indicates you the type of the object, main window, 
   main MDI window or child MDI window, or maybe more later.
   It the window was not a descendent of  TWindowBase0  or not created
   by the  WinCreate  method of the window, it will return wType = 0 and
   poWin = NIL. In this case the handle will not give information about
   the corresponding object, if it exist.
   This unit is quite small, most window methodes and properties are
   defined in  wWindow0.
   No examples are associated with it.

5) Objects hierarchy (Familly tree)
"""""""""""""""""""""""""""""""""""
TWindowBase0
   TWindow0
      TMDIWindow0
      TMDIChildWindow0
   TControl0
      TEditBox0
      TStatusLine0
      TRichText0

6) Global variables, constant and procedures of the library.
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Global variables : 
'''''''''''''''''''
They are initialised variable, this is why the are declared with "const".

const   gglpoApplication : PApplication0 = NIL;
   Defined in wApplication0.pp;
   Pointer on the  TApplication0  object. Not very usefull for the moment.
   There is normally only one such object.

const   gglpoAppPrm : PApplicParam2 = NIL;
   Defined in wApplicParam2.pp;
   Pointer on the objet wich is respondible for 'saving in' and 'loading from'
   a file, all parameters which should be memorised from an application.
   By making this pointer point on an descendent of  TApplicParam2  
   at the very beginning of the application, this will allow to save 
   more information in the parameter file.
   There is normally only one such object.
   See tEx006 for an example.

const   gglpoMDIActiveWindow : PMDIChildWindow0 = NIL;
   Defined in wMDIChildWindow0.pp;
   Pointer on the active MDI child window.
   It none are active, it points to NIL.
   Only used if MDI windows are used.

   wWindow.gglpoMainWindow is more usefull

const   WM_USERDestroyMDIChildObj = WM_User + 11;
   Defined in wMDIChildWindow0.pp;
   User library message. The MDI child window send this message to its
   grandparent to ask him to destroy the corresponding Object MDI child win.

const  gglpoObjCreate : PObjectCreator2 = NIL;
   Defined in wObjectCreator2.pp;
   Pointer to the object creator. There is normally only one such object.

const   gglpoMainWindow : PWindow0 = NIL;
   Defined in wWindow0.pp;
   Pointer on the main application window.
   There is normally only one such object.

Global constants : 
'''''''''''''''''''

Defined in wWindowBase0.pp;
  // each Window created by the library has a pointer on the corresponding
  // object, and an information on what kind of object it is in the library
  // number of extra bytes reserved in the window to maintain this
  // information.
  // The first eight bytes are used for a signature
  // The next four bytes (9 to 12) do designate the type of the object
  // The next four bytes (13 to 16) do designate the pointer
  // on the window object  PWindowBase0  or a descendent
  GGLCTE_NB_WND_EXTRA = 16;

  // designate the main window, not an MDI window
  GGLCTE_MAIN_WINDOW = 1;

  // designate the main window, which is an MDI window
  GGLCTE_MAIN_MDIWINDOW = 2;

  // designate the MDI client window
  GGLCTE_CLIENT_MDIWINDOW = 4;

  // designate an MDI child window
  GGLCTE_CHILD_MDIWINDOW = 8;

  // signature to avoid problems if windows where created
  // without using the library
  GGLCTE_SIGNATURE_WND_EXTRA = 2173465789; // 4 bytes signature

  // number of extra bytes reserved.
//  GGLCTE_NB_WND_EXTRA = 16; defined in wMDIWindow0.pp

word32 = Cardinal has been defined in wWindow0.pp,
   but this will change later and be defined more globally.

Global procedures : 
''''''''''''''''''''
procedure gglGetPointerObject(hWinPrm:HWND; var wType:word; var poWin:PWindowBase0);
   Defined in wWindowBase0.pp;
   It has already be defined above in the description of wWindowBase0;
   It can get the pointer on a window, when the handle on it is know.

7) Personal remarks.
""""""""""""""""""""
I like to keep visible the procedure handling all windows messages. I think
this helps while developping, and keeps the program more readable.
They are treated in the three methodes of TWindow0:

procedure WMCommand(wPar:WPARAM; lPar:LPARAM); virtual;
   Handles the menu messages
   It is usually overriden

function WindowProc(hWindow:HWND; wMsg:UINT; wPar:WPARAM; lPar:LPARAM):LRESULT; virtual;
   Handles the window messages
   It is usually overriden

function WindowProcFirst(hWindow:HWND; wMsg:UINT; wPar:WPARAM; lPar:LPARAM):LRESULT; virtual;
   Handles messages for the library, before calling  WindowProc
   It is usually not overriden

The two first methodes can become quite long procedures, some hundredth of lines.
But since they wil contain a very long "case" statement, the procedure
will be very linear, and will not be complicate to read.

I dislike hiding any methods (=procedure) or properties (=variables)
I prefer put a comment on it saying that it should not be ridden and/or written.
Then, if a mistake is done in it, it can be redefined.
This is why all methodes declared in the library are virtual.

Simplicity + comments have my preference.

8) To come in the future I hope :
"""""""""""""""""""""""""""""""""
RichText object, to help having text windows.
Line and text drawing facilities.
A unit helping to create human language independent applications.
wMenu0.pp to help creating menus, with the text defined in an external
   file. This way, the menu part of the program will be human language 
   independent.
wDialog0.pp to facilitate creating dialog boxes. Again, all text will be 
   defined in an external file so that the program will not depend on a
   human language.
Facilities to draw graphics.
... and much more I hope.


I began this about ten days ago, to discover Free Pascal.
I have over ten years experiance windows programming, and was very very very
sad when Borland Pascal was not taken under windows 95. I dislike Delphi.
I began programming under windows 2.1


Information published on the web by  Bernard.Gisin@Infomaniak.ch  at the URL :
http://www.perso.ch/Bernard.Gisin/FreePascal/demo01/index.html
See also improvements in :
http://www.perso.ch/Bernard.Gisin/FreePascal/index.html

Last modified : The 17th of december 2001, by Bernard Gisin.
