'
'Class description:
'
!short:View class structure:
Class View:
~~~~~~~~~~~
this is standard I/O engine for your programs, which with exception of menu
maintains the user interface. The data are displayed in two modes (Form and
Browse). The databases can be viewed, edited, the information can be
selected, with use of user defined indexes, filters and reports.
All this functionality is network capable.


Common use:
~~~~~~~~~~~
The best is to study the examples DEMO1.prg, DEMO2.prg and DEMO3.prg.

The source code is in C_View.prg

!seealso: c_dbrows.ngo:DBrowse c_task.ngo:Task c_report.ngo:Report c_finfo.ngo:FInfo c_menu.ngo:Menu c_dbf.ngo:Dbf c_color.ngo:Color ob_class.ngo:"Class hierarchy"

!short:~~~~~~~~~~~~~~~~~~~~~
!short:create class View from DBrowse
!short:  export:
!short:  var ViewID    //0
^BView:ViewID^N: read-only: numeric
  the unique object identification number for user defined indexes,filters
  and reports in a database cIFR (OBasic1.dbf). All copies odf the object
  have this number same to have the same menu.

!short:  var MenuID    //0
^BView:MenuID^N: private: numeric
  The menu item number, which started it to active this menu item as a local
  task menu. See the static function ViewSlipMenu() in C_View.prg.

!short:  var MenuNtxID //0
^BView:MenuNtxID^N: private: numeric
  The number for index definition for supressing of a recursive index
  definition.

!short:  var MenuFltID //0
^BView:MenuFltID^N: private: numeric
  Number for filter definition, to supress the recursive filter definition
  for this object.

!short:  var MenuRptID //0
^BView:MenuRptID^N: private: numeric
  Number for report definition, to supress the recursive report definition
  for this object.

!short:  var CanGoto   //true
^BView:CanGoto^N: private: logical
  Enables / disables the goto command for this object, to select the record
  must be the window active.

!short:  var Fields    //{}
^BView:Fields^N: private: array
  All database fields to handle information in form of:
  Fields:={}
  AAdd( Fields, {cLongName,cShortName,cAlias,cField,cPicture,bWhen,bValid,;
                 [nMemoRowSize,nMemoColSize,[bDoGet]} )
  ...
Where:
  cLongName    - is the fieldname for Form mode
  cShortName   - is the fieldname for Browse (Columun header)
  cAlias       - is Alias() of fields database
  cField       - is a fieldname
  cPicture     - is a display mask
  bWhen        - is a code block evaluated before entering this field, when
                 returns false the field aditation is disabled. It can be
                 used for result fields, or read only fields.
  bValid       - is a code block to validate the entered data, when returns
                 true the data is valid.
  nMemoRowSize - window height for memo file (number of rows)
  nMemoColSize - window width for memo field (number of columns)
                 The memo field is edited in its own window of this sizes.
  bDoGet       - is a code block to edit the field, if nothing is set the
                 DoGet() method of DBrowse class is used.

!short:  var Action    //{}
^BView:Action^N: private: array
  The array with a structure:
  Action:={}
  AAdd( Action, {nKey,bNewProc,bOldProc,cShortInfo} )
  ...
  Every object of this class can have its own hot key set with connected
  functions. The element meaning is:
  nKey       - is a InKey() code of a hot key
  bNewProc   - code block to perform when a key is pressed
  bOldProc   - this key previous assigned code block
  cShortInfo - short help text to be displayed in dialog line about the
               hot key

!short:  var Filter    //{{},{},{},{}}
^BView:Filter^N: private: array
  This is object defined filter information. this instavar variable is
  composed of theree paralel arrays:
  first of them consists of filter names as menu items (character)
  second of them consists of the filter expression (Character)
  third is the array of logical values defining if the user is enabled
        to modify the filter definition. The filter definitions created
        in a program are unchangeable but there is a possiblity to change
        the user run time defined filters.

!short:  var Report    //{{},{},{}}
^BView:Report^N: private: array
  This is current object report information. This instvar variable consists
  off three paralel arrays:
  first of them consists of report names as menu items (character)
  second of them is the report definition
   array={cTop,aFields,cBottom,lOnlyTotals}
  third is the array of logical values defining if the user is enabled
        to modify the report definition. The report definitions created
        in a program are unchangeable but there is a possiblity to change
        the user run time defined reports.

  cTop is a report header, the lines are separated by semicolon (;)
  aFields={cShortName,cField,cPicture,lTotal,cSubtotal} where:
    cShortName report column header
    cField database field to print
    cPicture output mask for cField
    lTotal sets the field to be totaled
    cSubTotal sets the field to subtotal according to
  cBottom final (Bottom) report text, lines of which are semicolon (;)
    separated.
  lOnlyTotals default is false, i.e. standart (full) report.
    is is true, then report will be contain only subtotals and totals.

!short:  method New=ViewNew              //o:New() --> self --> self
^BView:New()^N: public: return self
  The object is filled with default values.

!short:  method Copy=ViewCopy            //o:Copy() --> copy_of_current_view_object
^BView:Copy()^N:public: return copy_of_self
  Returns a current copy of this class object.

!short:  method CreateObj=ViewCreateObj  //o:CreateObj() --> new_object_of_this_class
^BView:CreateObj()^N:public: return new_self_of_this_class
   Returns new object of this class.

!short:  method Init=ViewInit            //o:Init() --> true
^BView:Init()^N: public: return true
  Object internal init.

!short:  method Select=ViewSelect        //o:Select(cAlias) --> true
^BView:Select(cAlias)^N: public: return true
  Select of active database, when object is active.

!short:  method DefWindow=ViewDefWindow  //o:DefWindow(Name,R,C,Rs,Cs,Clr) --> true
^BView:DefWindow()^N:public: return true
  Object window size (fill of instavar variables)

!short:  method AddBlock=ViewAddBlock    //o:AddBlock(cLongNm,cShortNm,cVarNm,bBlock,bDoGet,cPict,bWhen,bValid) --> true
^BView:AddBlock(LongName,ShortName,VarName,Block,DoGet,Pict,When,Valid)^N:
  public: return true
  Next column appended to the object by a code block. When editing it is not
  tested the record virtuality, the records with je RecNo()>LastRec() can be
  edited.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^ULongName^N: character: default is ShortName
   Column name used in mode of Form(ular).

  ^UShortName^N: character: default is ""
   Column name used in mode of Browse.

  ^UVarName^N: character: default is ShortName
   Edited variable name, or database fieldname stored as an information to clipper
   Get object, created in this method and stored to DoGet array. The clipper get object
   should know the edited variable name.

  ^UBlock^N: code_block: no default
   Get/set code block created by the functions FieldBlock(), FieldWBlock(), MemVarBlock() or
   own code piece.

  ^UDoGet^N: code_block: default is virtual_method_Browse:DoGet()
   Code block to edit the column respective variable with use of the Get object.

  ^UPicture^N: character: default is ""
   The column picture display mask.

  ^UWhen^N: code_block: default is {||true}
   Code block to be evaluated before the entering the column editation.
   If false the editation is disabled. The result fields or read-only
   fields can be produced this way.

  ^UValid^N: code_block: default is {||true}
   Code block to validate the entered data, if the result is true the data
   is valid, if false the entered data must be reedited.

!short:  method AddMemo=ViewAddMemo      //o:AddMemo(cLongNm,cShortNm,cField,bWhen,bValid,nRowSize,nColSize) --> true
^BView:AddMemo(cLongName,cShortName,cField,bWhen,bValid,nRowSize,nColSize)^N:
  public: return true
  The object is appended with next column defined as memo field.
  The virtuality is tested, it is not allowed to edit the fields
  with RecNo()>LastRec().

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^ULongName^N: character: default is ShortName
   Column name used in mode of  Form(ular).

  ^UShortName^N: character: default is ""
   Column name used in mode of Browse.

  ^UcField^N: character: no default
   Full memo field name (field->name),
   if no prefix used, it is taken from instvar variable View:Alias.

  ^UWhen^N: code_block: default is {||true}
   Code block to be evaluated before the entering the column editation.
   If false the editation is disabled. The result fields or read-only fields
   can be produced this way.

  ^UValid^N: code_block: default is {||true}
   Code block to validate the entered data, if the result is true the data
   is valid, if false the entered data must be reedited.

  ^UnRowSize^N: numeric: default is MaxRow()/3
   The MemoEdit window height as row number.

  ^UnColSize^N: numeric: default is MaxCol()/2
   The MemoEdit window width as column number.

!short:  method AddField=ViewAddField    //o:AddField(cLongNm,cShortNm,cField,cPict,bWhen,bValid) --> true
^BView:AddField(LongName,ShortName,Field,Picture,When,Valid)^N:
  public: return true
  The object is appended with next column defined as database field.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^ULongName^N: character: default is ShortName
   Column name used in mode of  Form(ular).

  ^UShortName^N: character: default is ""
   Column name used in mode of  Browse.

  ^UcField^N: character: no default.
   Full memo field name (field->name),
   if no prefix used, it is taken from instvar variable View:Alias.

  ^UcPicture^N: character: default is ""
   The column picture display mask.

  ^UWhen^N: code_block: default is {||true}
   Code block to be evaluated before the entering the column editation.
   If false the editation is disabled. The result fields or read-only
   fields can be produced this way.

  ^UValid^N: code_block: default is {||true}
   Code block to validate the entered data, if the result is true the data
   is valid, if false the entered data must be reedited.

  ^UnRowSize^N: numeric: default is MaxRow()/3
   The MemoEdit window height as row number.

  ^UnColSize^N: numeric: default is MaxCol()/2
   The MemoEdit window width as column number.

!short:  method AddFilter=ViewAddFilter  //o:AddFilter(cName,cExpr,lMark) --> true
^BView:AddFilter(cName,cExpr)^N: public: return true
  Programmer defined filter.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UcName^N: character: no default.
   Filter name to display as menu item name. The prefix ~ sets the hilited
   character to be accelerator for menu item selection speeding up.

  ^UcExpr^N: character: no default.
   The filter expression

!short:  method AddRAll=ViewAddRAll      //o:AddRAll(cName,cTop,aFields,cBottom,lOnlyTotals) --> true
^BView:AddRAll(cName,cTop,aFields,cBottom,lOnlyTotals)^N: public: return true
  One command report definition append.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UcName^N is report name to diplay as a menu item, the prefix ~
  sets the hilited character to be the accelerator for
  menu item selection speeding up.

  ^UcTop^N is report header, each row is semicolon separated.

  ^UaFields^N={cShortName,cField,cPicture,lTotal,cSubtotal} kde:
   cShortName is report column header
   cField is database field to print
   cPicture is cField output picture mask
   lTotal sets the field to be totaled
   cSubTotal sets the field to total according to

  ^UcBottom^N is final report text, each line to be semicolon separated.

!short:  method AddReport=ViewAddReport  //o:AddReport(cName,lOnlyTotals) --> true
^BView:AddReport(cName,lOnlyTotals)^N: public: return true
   Begin of programmer defined report.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UcName^N is report header name, to be displayed as menu item, the
   prefix ~ is to set the hilited character to be the accelerator key,
   for speeding up the menu selection.

!short:  method AddRTop=ViewAddRTop      //o:AddRTop(cTop) --> true
^BView:AddRTop(cTop)^N: public: return true
  Continues in programmer defining of a report.
  cTop report header, the lines are semicolon separated

!short:  method AddRField=ViewAddRField  //o:AddRField(cTitle,aField,cPict,lTot,cSubT) --> true
^BView:AddRField(cTitle,cField,cPicture,lTotal,cSubTotal)^N:
  public: return true
  Continues in programmer defining of a report.
  cTitle: character: default is cField, the report column header
  cField: character: no default.
   contain full name of database field that must be printed (alias->filed)
   if isn't full name (only field part exist) then alias will be instvar
   variable View:Alias.
  cPicture: character: no default.
   Output picture mask for cField.
  lTotal: logical: default is false, sets the field to be totaled
  cSubTotal: character: default is "", sets the field to make subtotal
   according to.

!short:  method AddRBottom=ViewAddRBotto //o:AddRBottom(cBottom) --> true
^BView:AddRBottom(cBottom)^N: public: return true                                  
  Continues in programmer report definition.
  cBottom is final report text, each line to be semicolon separated.

!short:  method AddAction=ViewAddAction  //o:AddAction(nKey,bProcedure,cInfo) --> true
^BView:AddAction(nKey,bFunction,cShortInfo)^N: public: return true
  Own hot keys definition for this object, and their assigned functions
  definition, for performing these functions with a single keypress.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UnKey^N: numeric: no default.
   It is InKey() code of a "hot key"

  ^UbFunction^N: code_block: no default.
   Code block to be performed after a hot key is pressed.

  ^UcShortInfo^N: character: default is ""
   It is short help text, to be apended to a dialog line, to inform
   about the hot key.

!short:  method View=ViewView            //o:View(ID,Name,R,C,Rs,Cs,Clr,Shd) --> true
^BView:View(ID,Name,R,C,Rs,Cs,Clr,Shadow)^N: public: return true
  Copy of an object is created, default initialised as a view object,
  painted to the screen and started as the task.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UID^N: numeric no default.
   It is a menu item number to start this method, for compatibility of menu system.

  ^UName^N: text or code block: default is {||""}, no title.
   Text or code block as window title.

  ^UR^N: numeric: default is 3.
   Top window border.

  ^UC^N: numeric: default is 4.
   Left window border.

  ^URs^N: numeric: default is MaxRow()-7.
   Window height in number of rows to fit in.

  ^UCs^N: numeric: default is MaxCol()-9.
   Window width in number of columns to fit in.

  ^UClr^N: character: default is m->Color:Edit.
   Window colors.

  ^UShadow^N: logical: default is true for color monitor, false for monochrom.
   If true, the shadow will be painted.

!short:  method Edit=ViewEdit            //o:Edit(ID,Name,R,C,Rs,Cs,Clr,Shd) --> true
^BView:Edit(ID,Name,R,C,Rs,Cs,Clr,Shadow)^N: public: return true
  The same as View:View, but instead of view object is edit object created.

!short:  method ViewEdit=ViewViewEdit    //o:ViewEdit(ID,Name,R,C,Rs,Cs,Clr,Shd) --> true
^BView:ViewEdit(ID,Name,R,C,Rs,Cs,Clr,Shadow)^N: public: return true
  It is the initialising method of an new edit or view object. Use it
  to make your own object copies.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  the same as in View:View

!short:  method Goto=ViewGoto            //o:Goto(ID,Name,R,C,Rs,Cs,Clr,Shd) --> true
^BView:Goto(ID,Name,R,C,Rs,Cs,Clr,Shadow)^N: public: return true
  Jumps to user entered current database record number.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  the same as in View:View

!short:  method Locate=ViewLocate        //o:Locate(ID,Name,R,C,Rs,Cs,Clr,Shd) --> true
^BView:Locate^N: public: return true
  Searches from current record to the end of file in selected field
  for a substring.

!short:  method PreGoto=ViewPreGoto      //o:PreGoto(Menu,MdId) --> true
^BView:PreGoto(Menu,MdId)^N: public: return true
  Prevalid (when) function called from a menu to validate the atempt
  of method View:Goto() activation.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UMenu^N: object_of_Menu: no default.
   Menu which requests the validity test and sends self to the method.

  ^UMdId^N: numeric: no default.
   The MenuDataID number for setting the data structure of Menu object to
   prevalidate.

!short:  method PostGoto=ViewPostGoto    //o:PostGoto(Menu,MdId) --> true
^BView:PostGoto(Menu,MdId)^N: public: return true
  The postvalid function to be prformed after the finish of View:GoTo()
  method, to enable (if disabled by PreGoto() method) the method View:GoTo()
  activation.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UMenu^N: object_of_Menu: no default.
   Menu that requested the validation sends self to the method.

  ^UMdId^N: numeric: no default.
   It is the MenuDataID number to set the Menu object data structure
   that needs the postvalidation.

!short:  method SetIndex=ViewSetIndex    //o:SetIndex(ID,R,C,CurSize,Clr,Shd) --> true
^BView:SetIndex(ID,R,C,CurSize,Clr,Shadow)^N: public: return true
  Selects the programmer defined or user runtime defined index, to be active.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  the same as in View:View

!short:  method SetFilter=ViewSetFilter  //o:SetFilter(ID,R,C,CurSize,Clr,Shd) --> true
^BView:SetFilter(ID,R,C,CurSize,Clr,Shadow)^N: public: return true
  Selects the programmer defined or user runtime defined filter, to be active.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  the same as in View:View

!short:  method SetReport=ViewSetReport  //o:SetReport(ID,WinNam,R,C,CurSize,Clr,Shd) --> true
^BView:SetReport(ID,WinName,R,C,CurSize,Clr,Shadow)^N: public: return true
  Selects the programmer defined or user runtime defined report, to be active.
  The report file is generated, it can be viewed and printed to produce
  a report.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  the same as in View:View

!short:  method ModIndex=ViewModIndex    //o:ModIndex(ID,WinNam,R,C,CurSize,Clr,Shd) --> true
^BView:ModIndex(ID,WinName,R,C,CurSize,Clr,Shadow)^N: public: return true
  User is enabled to create its own index and append it to other ones.
  He is enabled to modify himself created indexes and to delete them.
  The new index creation is performed in a child process, activated
  from a main menu or from a class view local menu. This child process,
  is assigned the indenpendent help process to, about how to create a new
  index. When finishing the child process, this process is finished too.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  the same as in View:View

!short:  method ModFilter=ViewModFilter  //o:ModFilter(ID,WinNam,R,C,CurSize,Clr,Shd) --> true
^BView:ModFilter(ID,WinName,R,C,CurSize,Clr,Shadow)^N: public: return true
  The same as in ModIndex but handles the filter definitions.

!short:  method ModReport=ViewModReport  //o:ModReport(ID,WinNam,R,C,CurSize,Clr,Shd) --> true
^BView:ModReport(ID,WinName,R,C,CurSize,Clr,Shadow)^N: public: return true
  The same as in ModIndex but handles the report definitions and the help
  process is not created.

!short:  method VProcess=ViewVProcess    //o:VProcess() --> true
^BView:VProcess()^N: private: return true
  The parent VProcess() definition is apended with a activation
  and deactivation of object hot keys.

!short:  method Done=ViewDone            //o:Done(lRePaint) --> true
^BView:Done(lRePaint)^N: private: return true
  The parent Done() method is apended with current view objects stack top
  object erase. Pay attention that this is not class task stack.
  The view class maintains its own stack of view objects for index,
  filter and report enabling, disabling and modifiing maintenance.

!short:  private:
!short:  method EndViewEdit=ViewEndViewEdit    //o:EndViewEdit() --> true
^BView:EndViewEdit^N: public: return true
  The necessary object copy update is performed before activating of the
  VProcess(). The multiple opening of the same window must have the same
  index, filter and report definitions for all copies of the same object.
  Therefore the created object copy must be updated to have the definition
  storing fields not to be a copies (by AClone()), but only a pointers
  assigned to the same fields for all copies of an object.

!short:  endclass