'
'This chapter menu
'^^^^^^^^^^^^^^^^^
'
'!short:Basic of the library
'!short:Meaning of the words
'!short:Syntax
'!short:How to compile source code to obtain *.exe
'!short:Library created and used database files
'!short:Simple demo for working with objects
'!short:Visibility of objects in the CLD (clipper debugger)
'!short:Hardware requirements
'!short:System anomal behavior or what to expect and what no
'!short:
'!short:Public variables = global variables created by the library
'!short:===================================================================
'!short:name       type     short description
'!short:---------- -------- -----------------------------------------------------
'!short:m->tColor  numeric  0=monochrom, 1=laptop, 2=VGAmono, 3=color monitor
'!short:m->Color   object   color values recieved by the window painting
'
'
'####################################################################################
!short:Basic of the library
^BBasic of the library - short description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

                                 OBJECT.LIB
            high level object oriented library for Clipper v5.01
           ******************************************************
               copyright (c) 1992, JHK, JHK-Software, Piestany

Motto:
~~~~~~
   Database programs on the fly!



Basic features:
~~~~~~~~~~~~~~~
   - object oriented (classes,heredity,...)
   - user task swapping
   - "Windows - like" user interface
   - multithreading is enabled
   - event driven programming support through the philosophy of the library
   - data driven programming capability and design
   - generated code is true network capable
   - user defined reports
   - user defined filters
   - user defined indexes
   - unlimited paswords, user privileges individual to every menu item,
     every database field
   - automatic generated help system with context help
   - user defined help system
   - all graphical cards text mode support
     (CGA,EGA,VGA,HGC,laptops,monochromVGA,...)
   - clipper language enhancements
   - dramatical shortening of a aplication developement time, aplication
     length in 200 to 2000 (for very large apps.) source code lines
   - basic functions of a program can be presented to the user in the very
     first time consulting his problem
   - simple program maintenance
   - documentation in a form of "norton guide" in a file OBJECT.NG

   The library is 420kB of source code with 330kB of documentation,
   consists of 450 functions, methods or procedures and many new commands.


!seealso: "Meaning of the words" Syntax "Simple demo"


'####################################################################################
!short:Meaning of the words
^BMeaning of the words:
~~~~~~~~~~~~~~~~~~~~~~~

 CLASS ... is a composing of common features of any later defined object
   It consists of all needed variables (VAR) and functions (METHOD) for exact
   description of any object features. It remembers to Pascal record
   definition or to union in C with extensions to methods and hereditarity.

 OBJECT ... is a real variable derived from further defined class. Clipper
   objects can be of four basic classes (Error,Get,Tbrowse,Tbcolumn).
   Non-clipper objects can be of any user defined class.

 NON-CLIPPER OBJECT ... uses clipper send technique (:) for sending messages
   to objects. It is created of user defined classes, with use of
   herediterity and overlaying of methods. When using the object system
   o:Clip it is not possible to use the standard clipper classes (Error,Get,
   TBrowse,TBColumn). The system Class(y) enables this use. Hovever this
   library cannot use this Class(y) feature, because this must work with
   o:Clip too. If you have the Class(y) library, use it! (instead default
   o:Clip). o:Clip has various problems in debugging in multifile
   application.

 VAR ... one object variable, as array element of object representing array.

 METHOD ... is the proces (code) part of the object, describing how to change
   the object satus. It presents some function which can manipulate the
   object instances (variables) and in that way change the object status.

 INHERITANCE ... is the basic feature of object oriented language.
   It enables to create a new class in the following way:
   1. New class inherits all variables and methods of some other class
   2. It modifies the methods, which are not sufficient to new demands.
   3. New class is apended with new variables and methods which are not
      present in parent class.
   This enables incremental programing with reuse of once generated code.

 PUBLIC, PRIVATE, READ-ONLY, OVERRIDE
   By description of variables of some class are used this labels to
   emphasize the possible use of any variables.

   PUBLIC means that variable can be changed anywhere

   PRIVATE is variable for internal object use, it is not recomended to
     change its content or use it in any way.

   READ-ONLY is variable only for reading, it is modified by the own
     object methods.

   OVERRIDE indicates that the herited default value is rewritten to
     new default value.

   ^UMethod description:^N
   PUBLIC is common used method
   PRIVATE is internal method of the class


!seealso: Syntax "Simple demo" "System anomal behavior"


'####################################################################################
!short:Syntax for non-clipper objects
^BSyntax for non-clipper objects:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can decide for Class(y) or o:Clip object systems.
Your decision must be ressponsed in your used syntax and help.
The library is written in the way that by defining of options
#define CLASSY or #define OCLIP in the file  object.ch can be generated
the required object library.


'####################################################################################
!short:How to compile source code to obtain *.exe
^BHow to compile source code to obtain *.exe :
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Yor programs can be converted from the form of *.prg to *.exe in the next
steps:

1. Compilation with debug option
             Clipper my_file /n/m/w/a/b/p
             RtLink FI my_file PLL Object

2. Compilating to distribute
             Clipper my_file /n/m/w/a/l
             RtLink FI my_file LIB Object

The first line creates from the file my_file.PRG the files:
      my_file.PPO  (if there was a /p switch)
      my_file.OBJ

the second line produces the very desired file my_file.exe !!!. Off course
only when the compiling was without error(s). (:-))

!seealso: "Meaning of the words" "Simple demo" "System anomal behavior"


'####################################################################################
!short:Library created and used database files
^BLibrary created and used database files:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The classes View (file c_view.prg), Menu (file c_Menu.prg) and Dbf (file
c_dbf.prg) need for user defined indexes, filters and reports and for help
to menu system and to database fields three system databases:

^USystem1.dbf^N usernames, passwords and privileges of users are stored here.

^USystem2.dbf^N index, report and filter definitions.

^USystem3.dbf^N help texts to menu items and to databse fields, the respective
            functions are in file Object2.

For creating any new index file (user defined) is the name created by library
as following: ^USysN0000.ntx^N where for 0000  can be substituted any number
in range from 0000 to 9999.

When producing a report, it is printed to a file and this file is printed
to printer. The file name is created by library as following: ^USysR0000.ntx^N
where for 0000  can be substituted any number in range from 0000 to 9999.

The program created with help of Object.lib searches the curerrent directory
for needed database files. If you need to store any database fields to other
then current directory, use the full pathaname in database structure
definition (object of class Dbf), (in form of Dos path + file name).

When program ends with an error (that can be handled by clipper ErrorBlock)
is file SysError.txt created and the stack list is written to it. The
file name can be changed by SET ERRORS FILE.

The temporary file ^USysTmp$$^N is used for creating of temporary indexes for
totaling and subtotaling in reports (c_report.prg) or as temp file for
database structure generating (c_dbf.prg)

System file names can be changed in source library code (Object.ch), this
needs recompiling of the library to take effect.



!seealso: c_dbf.ngo:Dbf c_view.ngo:View c_menu.ngo:Menu ob_comma.ngo:"SET ERRORS FILE"


'####################################################################################
!short:Simple demo for working with objects
^BSimple demo for working with objects:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

//class definition example:
//----------------------------------------
 class Loc                 //class Loc (location)
   export:                 //instances and methods visible in child classes
                           //and also in class Loc object
   var Row                 //Row element
   var Col                 //Column element
   method New=LocNew       //call o:New()  instances initialisation
   method Get=LocGet       //call o:Get()  storing the position
   method Set=LocSet       //call o:Set()  reseting the stored position
   endclass

 constructor LocNew() no parent   //preprocessor compile see Object.ch
   ::Row:=0
   ::Col:=0
   return(self)            //returns self (object)

 method function LocGet()  //can be rewritten in "child" classes
   ::Row:=Row()            //stored the row
   ::Col:=Col()            //stored the column
   return(nil)

 method function LocSet()  //can be rewritten in "child" classes
   SetPos(::Row,::Col)     //restore the position
   return(nil)

 //...................................................................
 class Cursor from Loc   //class cursor herited all features of class Loc
   export:               //and has new variable
   var Size              //size and methods
   method New=CursorNew  //instances initilisation
   method Get=CursorGet  //o:Get()  modify Loc:Get() in sense of
                         //           store the size of cursor too
   method Set=CursorSet  //o:Set()  reset the stored cursor
   endclass

 constructor ScreenNew()  //instances of class Cursor are initialised
   ::Size:=SC_NONE        //(i.e. Size, Row, Col)
   return(self)           //returns self (object)

 method function CursorGet() //can be rewritten in "child" classes
   ::parent:Get()            //store Row,Col (use the herited method)
   ::Size:=SetCursor()       //store the cursor size
   return(nil)

 method function CursorSet() //can be rewritten in "child" classes
   ::parent:Set()            //store Row, Col (use herited instance)
   SetCursor(::Size)         //restore the cursor
   return(nil)

 //.....................................................................
 class Screen from Cursor //the class screen herited the cursor features
   export:                //and adds the items
   var Screen             //screen_buffer
   var Color              //clipper color definition
                          //and the methods
   method New=ScreenNew   //o:New()  initial instances set
   method Get=ScreenGet   //o:Get()  modify Cursor:Get() to store the screen
   method Set=ScreenSet   //o:Set()  restore the saved screeen
   endclass

 constructor ScreenNew()  //class Screen instances are modified
   ::Screen:=""           //(i.e. Screen, Color, Size, Row, Col)
   ::Color:=""
   return(self)           //returns self (object)

 method function ScreenGet()  //can be rewritten in "child" classes
   ::parent:Get()             //store the cursor
   ::Color:=SetColor()        //store the colors
   ::Screen:=SaveScreen(0,0,MaxRow(),MaxCol())  //store the screen
   return(nil)

 method function ScreenSet()  //can be rewritten in "child" classes
   ::parent:Set()             //restore the cursor
   SetColor(::Color)          //restore the colors
   RestScreen(0,0,MaxRow(),MaxCol(),::Screen)  //restore the screen
   return(nil)

//defined classes using demo:
//---------------------------
function OurFunction()
  local object Cursor of Cursor //create local object Cursor of class Cursor
  local object Obr1 of Screen   //create local object Obr1 of class Screen
  local object Obr2 of Screen   //...
  Cursor:Get()                  //store the current cursor location
  InaProcedura("Change cursor") //cursor change
  Cursor:Set()                  //resture the cursor size and location
  Obr1:Get()                    //store the whole screen
  InaProcedura("Change screen") //screen change
  Obr2:Get()                    //store the changed screen
  repeat                        //repeat to until
    PauseKey(0)                 //wait for keypressing (SetKey() processed)
    Swap(Obr1,Obr2)             //swap of variables
    Obr2:Set()                  //show the screen (two screens swapping)
  until LastKey()==K_ESC        //ends when pressing ESC
  return(nil)

WARNING!
If you use the Class(y), the each class description must be in another file.


!seealso: "Meaning of the words" Syntax "System anomal behavior"


'####################################################################################
!short:Visibility of objects in the CLD (clipper debugger)
^BVisibility of objects in the CLD (clipper debugger):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  The instances handling in form of ::Inst or ::Meth(listpar) are only the
  abreviations of self:inst, self:Meth(listpar), which are preprocesored,
  in the CLD use the full form.



'####################################################################################
!short:Hardware requirements
^BHardware requirements:
~~~~~~~~~~~~~~~~~~~~~~
Due to Clipper internal dyamic overlay system you have not to check the
exe file size. You can run a 5MB exe file in 450Kb RAM, but internal VMM
(Virtual Memory Manager) often accesses the HDD. For your programs the
minimal configuration is AT286, 12MHz, 1MB RAM. The XT computers are too
slowly for database aplications. I recomend to use maximal amount of memory
as disk cache, with 1MB RAM it can be 640kB for DOS and 384kB for cache
(it is better to use some WRITE-THROUGH cache with deferred write).

Your config.sys should contain the lines:
                  FILES=79
                  COUNTRY=41,,COUNTRY.SYS
The amount of FILES is high because the Object.lib maintains the database
files opened till finishing the program. The Country is used for Central
European date format: DD.MM.YY (default clipper format is american MM.DD.YY)

Autoexec.bat should contain :
                  SET CLIPPER=E0;F:69;
The line (SET...) supresses the use of EMS memory
(if you have memory enough can be changed) and it is enabled to open 69 files.

!seealso: "System anomal behavior"


'####################################################################################
!short:System anomal behavior or what to expect and what no
^BSystem anomal behavior or what to expect and what no:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 1. SetKey(...)    --> doesn't work for ALT-D

 2. ALT-C          --> immediate abort of program and return to DOS

 3. StuffKey(nKey) --> the queue is not erased and can be modified wrong
                       when containing InKey codes out of (0..255)

 4. CLASS... and  METHOD...  definitions of the same class should be in one
    separate file.
    The reason: identifier names colision (only for Class(y), o:Clip has'nt
    this problem but it is recomended to follow this rule.

 5. Error with text (DOS Error 4) is caused by low number of FILES in 
    config.sys or low number opened files in SET CLIPPER=... in 
    autoexec.bat

!seealso: "Hardware requirements" "Meaning of the words" Syntax

'
'####################################################################################
!short:m->tColor  numeric  0=monochrom, 1=laptop, 2=VGAmono, 3=color monitor
Public variable: ^Bm->tColor^N:
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Value type: numeric

This variable defines monitor type, with values
  0=monochrom monitor with two colors; black and white (hercules)
  1=monochrom with 8-gray colors; (some laptops)
  2=VGAmonochrom with 16-gray colors; (EGA,VGA monochrom)
  3=color monitor with 16-colors; (EGA,VGA,HGC-InColor,...)

!seealso: ob_class.ngo:Color ob_class.ngo:"Class hierarchy"


'####################################################################################
!short:m->Color   object   color values recieved by library when painting the windows
Public variable: ^Bm->Color^N:
~~~~~~~~~~~~~~~~~~~~~~~~~~
Value type: object of Color

This object defines all colors used by the library, it is created when
initialising the object system (ObjectInit() function in file object1.prg.
The current color values are assigned according the m->tColor variable value
for the respective monitor type.

The description of m->Color object is in part Classes.

!seealso: ob_class.ngo:Color m->tColor

'
'תתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתתת eof (c)JHK תתתתתתתתתתתתתתת
'