The 10.01.2002 Information about the examples and library.

All examples where developed with DevPascal version 1.9, which works
with FreePascal under windows 95.
I used FreePascal version 1.0.4.

I did it first to learn FreePascal under windows. Then to develop
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.

Developed by Bernard Gisin, for fun.

Many adjunction has been made since last version (Demo01)
Next version (Demo03) will improve some details in the library,
and add new examples and functionality. It should come in the
middle of January 2002.

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

1) The Examples : (and test of units)
"""""""""""""""""
tDebug.pp  Show how to use the  wDebug0.pp  unit
           It is very useful 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
           wParamApplic2.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
   Eighth example of program using the units
   wApplication0.pp  and  wWindow0.pp
   wRichText0.pp
   This example is very similar to the previous one.
   The debugging information have been removed.
   Some functionality 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 usual
   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

tEx011.pp
   This example is very similar to the tEx008.pp
   Most improvements has been done in the  wRichText0.pp  unit, thus are
   reported on tEx008.pp
   Still little improvements have been done.

tEx012.pp
   This example is a combination of  MDI  +  RichEdit  controls.
   It is a Multiple Document Interface, where each child window is a
   simple text editor. Text length is unlimited, but functionality are very poor.

tEx013.pp
   This serves to test and demonstrate the use of  wErrors0.pp,  a unit to write in
   an independent window, errors messages. There are always parts of program, where
   normally, a condition must be satisfied, but we are never sure. For example, when
   memory becomes unavailable, many errors can occurs, which were not planned.
   It starts from tEx004.pp, and generate some error message
   to see how it works.
   See wErrors0.pp for more comments.

tEx014.pp
   This shows how windows creates and handles controls.
   Usually they are used in dialog boxes, but they can also be put
   in any normal window.
   To use the default behaviour, it is quit simple, but
   to change the default colours, it becomes complicate.
   The object library will simplify all this.
   Later we will show the use of Dialog Boxes.

tEx015.pp
   This might be a bad example.
   It is similar to  tEx014.pp,  but with some effects which doesn't work.
   I tried to change colours, but I don't understand the documentation in
   the  win32.hlp  SDK documentation.
   Using the library I manage to change easily some colours, but there must
   be a simpler way defined in windows. I just didn't find it.

tEx016.pp
   This example show how to create control window, like
   edit boxes, buttons, scroller, combo boxes, list boxes
   Normally they are used in a Dialog Box, but they can also be put
   in any normal window.
   Uses the object library to simplify using these controls.
   Here, only push buttons are presented.
   Their localisation in the main window is the same for all controls.
   Later we will show the use of Dialog Boxes.

tEx017.pp
   This example is like the previous one.
   It shows more controls, and how to use them, with the help of the
   library. Later we will show the use of Dialog Boxes.

tEx018.pp
   This example is quite simple and shows the use of timer under
   Windows. One timer is used in  wControl0.pp to  show Hints
   associated with controls.

tEx019_X.pp   X='a', 'b', 'c' or 'd'
   Here are four examples of using graphics. Direct drawing on the window
   and drawing when needed, because another window has hidden part
   of your window.
   Many things are quite complicate to do. Choosing a single colour
   for a line needs 4 lines of code plus two variables.
   Later it will be simplified with the use of the library.
   For more information, see the examples.

tEx020.pp
   This example shows many line styles, fill styles (Brushes),
   Fonts styles and their use.
   and system information like screen size, resolution, etc.
   I hope to simplify it with the library.

tEx021.pp
   This is a special example, being more a test for me.
   Object can be either created with the  "new(poObj, Init)"  procedure,
   or be defined directly as a variable.
   If we have a pointer on an object, how can we know the difference between
   the two previous cases. In general, it is not possible, as far as I know.
   But in some important cases, it is possible. This example test
   how to make the distinction.

tEx022.pp
   This example shows the use of dialog boxes, with the help of
   resources, build with an external program : the resource compiler.
   A modal and a modeless dialog box are shown.
   I dislike this way of defining dialog boxes, and want the library
   to simplify it a lot. I hope at the beginning of February 2002 to
   have the big simplification I had under window 3.1 with
   Borland Pascal 7.0

tEx023.pp
   This is a step in the direction of simplifying the use of dialog boxes.
   Only one step.
   No resources are needed to build a dialog box. Controls defined
   previously are used in these dialog boxes, simplifying their use.
   A modal and a modeless dialog box are shown.

tEx024.pp
   This example shows how to create dialog boxes without any resources.
   It is quit complicate.
   But I will use it to create a minimal
   empty dialog box, to add controls with the help of the library.
   This is done in example tEx023.pp, and will be used a lot
   in examples to come, using the wMessages.pp unit and the
   Application.msg messages text file.

tEx025.pp
  This is a test of the wParamApplic2.pp unit.
  Test also the GetIntValue of the wUtiles0.pp unit.
  Short test.

tEx026.pp
  This is a test of the wHashTable2.pp unit.
  Test also the GetIntValue of the wUtiles0.pp unit.
  Short test.

tEx027.pp
 While developping a new unit, it's a good idea to test it specially.
  Very short ...
  I used many DBW0(...) in the wHashTable2.pp unit to test.
  Then I removed them.
  To study how it works, add DBW0(...) yourself.

tEx028.pp
  Test of the unit wVariableNumLink2.pp  and  wErrors2.pp
  While developping a new unit, it's a good idea to test it specially.
  Simple and short test, but usefull to detect errors and
  to understand how some procedures (or methodes) works.

tEx029.pp
  Test of the unit wMenus0.pp
  While developping a new unit, it's a good idea to test it specially.
  The wMenus0.pp unit is an important one, which allows you to create
  menus very easilly, just from a description made in the
  text message files.

  Very short ...
  I used many DBW0(...) in the wMenus0.pp unit to test.
  Then I removed them.
  To study how it works, add DBW0(...) yourself.

  The next example, tEx030.pp will use the menu description in the
  message file. It's a stronger test.

  tEx031.pp and tEx032.pp  will show how simple it is to define a menu,
  with informations displayed in the status line.

tEx030.pp
  Example of a program using the  wMenus0.pp  unit.
  This is the first example which uses really the Message file, and
  and a description of its menu in the message file.
  Do some tests on the menu.

tEx031.pp
Example of a program using the  wMenus0.pp  unit.
  This is the second example which uses really the Message file, and
  and a description of its menu in the message file.
  It uses the facilities of the library.
  The menu is generated automatically, because the corresponding
  message file exist (tEx031.msg) and line index 10000 is :
  10000 AutoCreate
  # here the menu description comes, c.f. tEx031.msg

  Also the handling of window messages is done automatically,
  the disposal of the menu object also.

  If you remove all comments, you get a very short programme, having
  a menu, a status line, information displayed in the status line
  when you are in the menu.
  The  WMCommand(...)  is the heart of the program.
  When a menu is selected, it calls the desired action.
  For the moment, does not much.

  In the next example, tEx032.pp, a little text editor will be demonstrated,
  similar to the one of example tEx008.pp
  See how many code lines have been removed, because they are automatically
  treated in the library.

tEx032.pp
  Example of a program using the  wMenus0.pp  unit.
  This is the third example which uses really the Message file, and
  and a description of its menu in the message file.
  It uses the facilities of the library.
  The menu is generated automatically, because the corresponding
  message file exist (tEx031.msg) and line index 10000 is :
  10000 AutoCreate
  # here the menu description comes, c.f. tEx032.msg

  Also the handling of window messages is done automatically,
  the disposal of the menu object also.

  This example is the same as example tEx031.pp but adds the
  functionality of a little editor, similar to the one of example tEx008.pp
  See how many code lines have been removed, because they are automatically
  treated in the library.

  It's only to show how simple it became to have the beginning
  of an editor if the GAP library is used.

tEx033.pp
  Example of a program using the  wMenus0.pp  unit.
  This is the third example which uses really the Message file, and
  and a description of its menu in the message file.
  It uses the facilities of the library.
  The menu is generated automatically, because the corresponding
  message file exist (tEx031.msg) and line index 10000 is :
  10000 AutoCreate
  # here the menu description comes, c.f. tEx032.msg

  Also the handling of window messages is done automatically,
  the disposal of the menu object also.

  This example is the same as example tEx032.pp but adds the
  functionality of a little MDI editor, similar to the one
  of example tEx012.pp
  See how many code lines have been removed, because they are automatically
  treated in the library.

  It's only to show how simple it became to have the beginning
  of an editor if the GAP library is used.

tEx034.pp
  Example of a program using the  wRichTextFrame0.pp  unit.

  This should simplify a lot having a text editor.
  All functionalities will be in the  TRichTextFrame  object.

  Menu numbers in  [65200..65399]  are reserved to treat
  menu commands concerning the RichTextFrame.
  These menu numbers are used in tEx034.msg

tEx035.pp
  Test of the unit wDialogCreator2.pp
  While developping a new unit, it's a good idea to test it specially.
  The wDialogCreator2.pp unit is an important one, which allows you to create
  dialog boxes very easilly, just from a description made in the
  text message files.
  Normally, the  wDialogCreatorLOW2.pp  unit should be used.
  See example  tEx038.pp,  much better.

tEx036.pp
  Test of the unit wMenus0.pp
  To have contextual menus.

tEx037.pp
  Test of the unit wPopupWindow0.pp

tEx038.pp
  Test of the unit wDialogCreatorLOW2.pp
  Some test have been made in  tEx035.pp
  Here, we are near from a final use of the dialog boxes.
  Use the  wDialogCreatorLOW2  instead of the  wDialogCreator2.
  It will hide many constant, types etc. which are not usefull
  to know for creating Dialog boxes.
  Remark : wDialog0.gglpoActiveDialog  points to the active dialog,
  Modal or modeless.
  See how simple it is to create a dialog box.

tEx039.pp
  Testing the wMessages2.pp unit.
  This is a very important unit in the GAP Library.
  I already tested it in tEx026.pp,  but I want more.
  Useless example. I do not use it, see  tEx040.pp  for what I wanted.

tEx040.pp
  Testing the wStringDataLink2.pp unit.
  My goal is that if we give a name to a main Window or a dialog box,
  Its position (and size) are saved in a file, and each time they are
  reopened, they come to the place they where last time.
  To do this, I want to associate to a string another string, or
  4 or 5 numbers, storing information associated with this string.
  I want to :
  - Set the information associated to the string :
  - Get the information associated to the string :
  - Deleting a string and its data will come later, maybe.
  All dialog boxes having a name (with @$DLGNAME("name..."))
  uses this unit to memorise their position.

tEx041.pp
  Example of creating dialog boxes.
  In tEx017, we used many controls to see their use.
  Here, we will use the facilities of dialog boxes to do the same thing,
  but with much less code. All the description will be made in the  .msg  file
  See how simple it is to create a dialog box.
  See  tEx044.pp  to define the backcolors of the radio buttons and
  the check boxes, in the  .msg  file.
  See example tEx042.pp for the final touch, i.e. the changing color
  Of the Background.
  tEx042.pp demonstrate also the use of the TObject creator.

tEx042.pp
  Example of creating dialog boxes.
  This is a continuation of  tEx041.pp
  It shows the use of the  TOjectCreator
  to modify the behaviour of the dialog box.
  It is unusual, but it's an example.
  It does the same useless thing as in  tEx017.pp
  But with two times less code lines.
  It shows also the use of the  TObjectCreator, and
  of  TWindow.InitDialogBegin  which can modify what could not
  have been modified in the  .msg  dialog description.

tEx043.pp
  Example of creating a modeless dialog box.
  Example of a simple calculator in a modeless dialog box.
  This example shows the use of the wObjectCreator2.pp
  to modify the default behaviour of objects created in the library.
  It shows the use of the dialog box creator and
  some treatment of keyboard input.
  It shows also the use of popup windows to display warnings.
  It could be developped much more, but it's not my goal.
  Many details are missing...

tEx044.pp
  Example of creating dialog boxes.
  This is more a test. In  tEx041.pp  we created a special dialog box,
  having controls, like in example  tEx017.pp
  Here it is exactly the same, but we use and test the facilities of
  defining colors with :
  TextColor, BackColor and WindowColor.  That's all.

See  BugsReport03.txt  for knows errors in these examples.
See  BugsReport02.txt  for knows errors in the Demo02 examples.

2) Conventions :
""""""""""""""""
Filename beginning with a  't'  are test programs or demo programs
Filename beginning with a  'w'  are units of the library.
Filename beginning 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 :
"""""""""""""""""""""""""""""""""
See some type definitions in wGlobals2.pp
As a convention, lower case letters before the first
uppercase letter indicate the type of the variable. For example :
  n  before an int32     ex:  nInt  : int32;  ( = longint; )
 sn  before an int16     ex:  snInt : int16;  ( = integer; )
  w  before a  word32    ex:  wNum  : word32; ( = Cardinal; )
 sw  before a  word16    ex:  swNum : word16; ( = word; )
  b  before a  byte      ex:  bVal  : byte;
  c  before a  char      ex:  cH    : Char;
  h  before a  handle    ex:  hWin  : HWND; ( = word32 = Cardinal = DWord)
  col before a variable designing a color, type = word32.
  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 Float      ex:  vX   : Float;  ( = Double; )
 sv  before a FloatS     ex:  svX  : FloatS; ( = Single; )
 vv  before a FloatE     ex:  vvX  : FloatE; ( = Extended; )
  z  before a Complex    ex:  zExp : Complex; ( Each component is a Double )
                                                It is useful for math.

Older convention, which might be used at some places :
  l  before a  longint   ex:  lVal  : longint;
  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.

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 useful unit for developing. 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.pp;
   This unit uses object programming to simplify the development of programs.
   It contains the loop getting 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.

wButtonCheck0.pp;  descendent of wControl0
   This unit serves to create a check box button in a window or in
   a dialog box.
   See tEx017.pp to see their use in a normal window

wButtonPush0.pp;  descendent of wControl0
   This unit serves to create a push button in a window or in
   a dialog box.
   See tEx016.pp and tEx017.pp to see their use in a normal window
   See tEx023.pp to see their use in a dialog box

wButtonRadio0.pp;  descendent of wControl0
   This unit serves to create a radio box button in a window or in
   a dialog box.
   See tEx017.pp to see their use in a normal window

wComboBox0.pp
   This unit serve to create combo boxes, either with predefined
   limited choice (DropDownList), or with some predefined choices
   but with an edit box where a user can type other choices.
   See tEx017.pp to see their use in a normal window

wControl0.pp;  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 descendants.
   See tEx016.pp and tEx017.pp to see their use in a normal window
   See tEx022.pp and tEx023.pp to see their use in a dialog box

wDebug0.pp;
   This unit can be useful while developing, to write information
   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 developing.

wDialog0.pp;  descendent of tWindowBase0
   This unit facilitate the construction and use of dialog boxes.
   Much more work has to come, to have dialog boxes really easy to
   define and use. But I hope to have these facilities in one month.
   See tEx022.pp and tEx023.pp to see how they are used.

wDialogCreator2.pp;  descendent of  wDialogCreatorLOW2
  This unit Creates a dialogbox from a description made in
  a text message file '.msg'
  This helps a lot creating dialog boxes.
->USE the parent unit  wDialogCreatorLOW2.pp  to create a dialog box.
  This unit is only inteded to overridde the functionnalities of
  its parent object  TDialogCreatorLOW2.
  This helps to hide constants, type and variables, which are not
  necessary to know for using the  Dialog Creator.
  And allow lower level units to use the dialog creator without
  having to "uses" a high level unit.
  It is one of the largest unit of the library.
  In version Demo03 it is the largest.

wDialogCreatorLOW2.pp;  parent of wDialogCreator2
  This unit Creates a dialogbox from a description made in
  a text message file '.msg'
  This helps a lot creating dialog boxes.
  See the file for more documentation.
  See tEx035.pp, tEx038.pp, tEx040.pp, tEx041.pp, tEx042.pp tEx043.pp
  for examples. See the Doc file  SyntaxDiagram03.rtf  for other info.

wEditBox0.pp;  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.
   See tEx016.pp and tEx017.pp to see their use in a normal window
   See tEx023.pp to see their use in a dialog box

wErrors0.pp
   This is a unit to write in an independent window, errors messages.
   There are always parts of program, where normally, a condition must
   be satisfied,
   but we are never sure.
   For example, when memory becomes unavailable, many errors can occurs,
   which were not planned.
   See wErrors0.pp for more info.
   See tEx013.pp for example of testing this unit.

wErrors2.pp;
   This unit is a continuation of the unit  wErrors0.pp,
   But is independent of window.
   Uses wErrors0, wGlobals2, wMessages2, wVariableNumLink2
   To write error information in the error window, but
   using text witten in the message file  '.msg', usually in StandardEn.msg

wGlobals2.pp
   Saves some global constants, type and maybe variables.

wGlobals0.pp
   Saves some global constants, dependent of Windows.

wHashTable2.pp;
  To store information, indexes by one or two word32 indexes.
  See the comments in the unit.

wMDIChildWindow0.pp;  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.
   See tEx012.pp to see a MDI RichText very simple editor.

wMDIClientWindow0.pp
   This unit might be useless. It describe the Client window of
   a main MDI window. Does nothing, just keep information about
   its handle and parent.

wMDIWindow0.pp;  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 constant of its
   client region, and the client window is completely 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.
   See tEx012.pp to see a MDI RichText very simple editor.

wMenus0.pp
  This unit serves to create a menu from a description in the
  message file.
  With the adjuction that to each menu line, correspond a text
  which will be displayed in the status line, if it exist.
  Menu number above 30'000 are reserved for the library.
  All example from the  tEx031.pp  uses systematically this unit
  to create their menus.
  If it is defined a line 10000 and it begins like :
  10000 AutoCreate
  Then no code is necessary. The menu is automatically added to the main
  window.

wMessages2.pp;     Still many comments have to be translated from french to english
  To store everything which is (human) language dependent.
  It is a text file, which stores every texts used in the program (or should use).
  For example, the menu is described here.
  It simplfies the creation of menus.
  It (will) simplify the creation of dialog boxes.
  All example for tEx028.pp uses this unit.
  It is The CENTER of the library.

wMsgFileCreate2.pp
  This unit Creates a text message file '.msg'
  Which can then be used with the  GetMsg  procedure
  Maybe not very usefull.
  Not tested ... and mixed comment, french and english.

wObjectCreator2.pp;  descendent of  wObjectCreatorLOW2
   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 TParamApplic2
   object. But by creating it through calling
   gglpoObjCreate^.CreateParamApplic;
   you can make that a descendent of  TParamApplic2  is created instead.
   In tEx006.pp another method was used to create a descendent of
   the application parameters.
   Overwrite some methodes of it if you want the library to create
   descented of objects from the library.
   Examples are given in  tEx042.pp  and  tEx043.pp

wObjectCreatorLOW2.pp; parent of wObjectCreator2
  Units will include this one, to create new objects from the library, or
  descendents of object from the library.
  Unit of the library will be included in  wObjectCreator2,
  which creates them.
  It is usefull to be overriden by the final application.
  This way allows the library to create objects defined in the final
  application, i.e. objects the library didn't know where the library
  was written. This is one of the power of object programming.
  It is used only for the global variable  gglpoObjCreate.
  Use the descendent  wObjectCreator2.pp  for the rest.

wParamApplic.pp;
   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
   (maximised 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.
   In the future, any important application will use it, to save in a
   text file the parameters of the application.
   The way data are saved will change in the next version (Demo03).

wPopupWindow0.pp
  This unit helps creating and manipulating simple popup windows
  to show a help text givent in the  .msg  file.
  example is given in tEx037.pp. Others in tEx043.pp

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

wRichTextFrame0.pp; descendent of  wRichText0
  It is a descendent of wRichText which treats many Windows messages.
  Menu numbers in  [65200..65399]  are reserved to treat
  menu commands concerning this control.

wStatic0.pp;  descendent of  wControl0
   To have a control which represent static text.
   It is quit complicate to change the colour of the text in a
   static text. The library simplifies it a lot.
   See tEx016.pp and tEx017.pp to see their use in a normal window
   See tEx023.pp to see their use in a dialog box.

wStatusLine0.pp;  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.
  See tEx012.pp to see its used in an Multiple Document Interface.

wStringDataLink2.pp
  This unit Creates helps associating (=linking) some information with a string.
  And this association is saved in a file.
  Three things are possible.
  1) Create a new link  string --> Data
  2) Modifiy the data linked to a string
  3) From a string, get the linked data.
  We will suppose that only few such links are wanted ( < 200 ),
  but its not important, and it works with more also.
  See the unit for more information.
  See example  tEx040.pp  for test.
  The it is used systematically in the library to store the position of
  every dialog box which has been given a name in the Directives :
  0 @$DLGNAME("name you want to give")
  tEx041.pp  to  tEx044.pp  uses it in some of their dialog boxes.

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

wVariableNumLink2.pp
  This unit serves to keep a correspondance between a word32 number
  and a variable.
  This allow to have a linke between a number, usually used in
  the messages file '.msg' and a variable used in the program.

  It can make PROGRAM CRASHES, if an association is made between a
  number and a variable, and the variable doesn't exist anymore.
  This can be the case for local variables of procedures, or
  disposed dynamical variables.
  For security, when an association (=link) isn't valid anymore,
  Call  ClearField(wNum, 0, 0, NIL);  to cancel this association.

wWindow0.pp;  descendent of  wWindowBase0
   This object describe the windows. It is very useful 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.pp;
   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 first name + name + address 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 methods (=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 methods and properties are
   defined in  wWindow0.
   No examples are associated with it.


5) Objects hierarchy (Family tree)
"""""""""""""""""""""""""""""""""""
TWindowBase0
   TWindow0
      TMDIWindow0
      TMDIChildWindow0
   TMDIClientWindow0 (not very useful I think)

   TStatusLine0
   TDialog0
   TControl0
      TButtonCheck0
      TButtonPush0
      TButtonRadio0
      TComboBox0
      TEditBox0
      TRichText0
      TStatic0
         to come TListBox0, TScrollBar0, TControlCustom (maybe)
        wRichTextFrame0
TApplication0
TMenus0
TParamApplic0
wObjectCreatorLOW2
  wObjectCreator2
...

See UnitHierarchy03.txt for a unit uses hierarchy.

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

const  gglpoActiveDialog : PDialog0 = NIL;
   Defined in wDialog0.pp
   Pointer on the active modeless dialog box.
   It is more used internally than destined to be used by
   end developer.

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

const   gglpoPrm : PParamApplic2 = NIL;
   Defined in wParamApplic2.pp;
   Pointer on the objet which is responsible 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  TParamApplic2
   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.
   Every application using the library, uses it to save the position
   of the main window.

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 useful

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.

const  gglhDialogWin : HWND = 0;
   Handle of a modeless dialog box, or of a window containing
   controls.
   It should be = 0 if not used. It's its default value
   It should be a valid modeless dialog box or window handle
   if it should be used.
   It will be rarely used.

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

Defined in wGlobals2.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 a non MDI window. (might be an independent one.)
  GGLCTE_A_WINDOW = 3;

  // designate the MDI client window
  GGLCTE_CLIENT_MDIWINDOW = 4;

  // designate an MDI child window
  GGLCTE_CHILD_MDIWINDOW = 8;

  // designate a Modal Dialog
  GGLCTE_A_DIALOG_Modal = 10;

  // designate a Modeless Dialog
  GGLCTE_A_DIALOG_Modeless = 11;

  // if bigger than 200, it defines a control window.
  //'''''''''''''''''''''''''''''''''''''''''''''''''

  GGLCTE_CTRL_RichEdit       = 201;
  GGLCTE_CTRL_EditBox        = 202;
  GGLCTE_CTRL_ComboBox       = 203;
  GGLCTE_CTRL_StatusLine     = 204;

  GGLCTE_CTRL_ButtonPush     = 205;
  GGLCTE_CTRL_ButtonRadio    = 206;
  GGLCTE_CTRL_ButtonCheck    = 207;

  GGLCTE_CTRL_Static         = 210;

  // 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 wGlobals2.pp

word32 = Cardinal has been defined in wGlobals2.pp,
int32  = longint;
Many other has been defined in wGlobals2.pp

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.

procedure gglGetPointerObjectWinCtrl(hWinPrm:HWND; var wType:word; var poWin:PWindowBase0);
//=========================================================================================
   Defined in wWindowBase0.pp;
// This is a little more genera than  gglGetPointerObject.
// Given the handle on any window, a normal or a control window,
// returns the pointer on the corresponding object window
// if it was created with this library.
// If fails, return a NIL pointer.
// See comments of  gglGetPointerObject

7) Windows Message Handling remarks.
""""""""""""""""""""""""""""""""""""
The messages handling of Windows has been redirected to simplify its use and to have
a better access to the messages. But the calling sequence can be quite complicate.
Here is an example. Suppose we have a RichEdit control in a window.
When this control receive a message :
a) TRichText0.CtrlWindowProc  receives the message.
b) It sends it to the normal messages handler of that control.
   For some messages, the calling continues.
c) TWindow0.WindowProc  receives a  WM_COMMAND  or  WM_NOTIFY  message.
   The library calls the methods  WMCOMMAND  or  WMNOTIFY
d) Theses methods sends back the message to
   the control  TRichText0.CtrlNotifMessageHandle.  It ends here.

You can ignore most of it.
- You can handle a message sent to a control in the  TRichText0.CtrlWindowProc  method,
  which is unusual.
- You can handle a message sent to a control in the  parent WMCOMMAND  or  WMNOTIFY
  methods, which is the normal way Windows (M$-soft) would do it.
- You can handle a message sent to a control in the  TRichText0.CtrlNotifMessageHandle
  method, which is the way I would do it.

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

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

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

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

The two first methods can become quite long procedures, some hundredth of
lines.
But since they will 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 methods declared in the library are virtual.

Simplicity + comments have my preference.

9) 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'm working of creating dialog boxes, with a description in the text message file. .msg


I have over ten years experience 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/demo03/index.html
See also improvements in :
http://www.perso.ch/Bernard.Gisin/FreePascal/index.html

Last modified : The 01st of January 2002, by Bernard Gisin.
