'
'Class desription:
'
!short:Browse class structure:
Class  Browse:
~~~~~~~~~~~~~~
It serves as key-precessing by view/edit of structured data
(arrays or database files) with help of standard clipper class TBrowse.
Two ways of displaying of data table are introduced:
  1.Browse = classical form of displaying.
  2.Form = only one table row is displayed, with all data put one under other.

Common use:
~~~~~~~~~~~~
LOCAL OBJECT Br OF Browse
Br:Init(...)       //or Br:GoodInit(...)	
Br:AddBlock(...)   //could be repeated or could be Br:AddGet(...)
...

Methods AddBlock() and AddGet() could be mixed and repeated, or instvar
variables of this object can be changed (i.g.Br:CanSwap:=false).
You don't take care for displaying, editation because the parent class Task
methods do the work for us.

If you need to produce the displayer of structured data, and you can't use
the classes ABrowse or DBrowse, you can as superset of this class write 
your own displayer.

Source code of class Browse is in C_Browse.prg

!seealso: c_task.ngo:Task c_window.ngo:Window c_box.ngo:Box c_abrows.ngo:ABrowse c_dbrows.ngo:DBrowse c_color.ngo:Color ob_class.ngo:"Class hierarchy"

!short:~~~~~~~~~~~~~~~~~~~~~~~~
!short:create class Browse from Task
!short:  export:
!short:  var MoreRecords      //true
^BBrowse:MoreRecords^N: private: logical
  Internal variable for Browse and View used for correct displaying of help
  text obtained by F1 key.

!short:  var MaskFeature      //false
^BBrowse:MaskFeature^N: public:logical
  Abstract variable used for indication of creation of the object from
  the class Mask (or its descendats).

!short:  var CanShowSkip      //false
^BBrowse:CanShowSkip^N: public: logical
  If true, after each skip command is in the dialog line displayed information
  about searching for next record (usefull with filter switched on for long
  search for next record)

!short:  var CanEdit          //true
^BBrowse:CanEdit^N: public: logical
  Enables - disables editation of data displayed with this object.

!short:  var CanAppend        //true
^BBrowse:CanAppend^N: public: logical
  Enables - disables appending or deleting of a line of displayed table. If
  CanEdit is false no change of the table is allowed and instvar variable
  CanAppend  has no sense.

!short:  var CanSwap          //true
^BBrowse:CanSwap^N: public: logical
  Enables / disables  Browse - Form switching.

!short:  var CanSkip          //true
^BBrowse:CanSkip^N: public: logical
  Only in Form display, enables - disables next or previous table line
  skipping with PgDn/PgUp key.

!short:  var FormActive       //false
^BBrowse:FormActive^N: public: logical
  If display is switched to Form the instvar variable is true. The display
  mode (Form/Browse) of the object can be initialised by assigning of logical
  value to this variable.

!short:  var CanMoveCursor    //true
^BBrowse:CanMoveCursor^N: public: logical
  If true, the finishing of editation moves cursor in the direction in which
  we entered the edited field. Otherwise is cursor moved to right.
  (if is it possible)

!short:  var Direction        //K_RIGHT
^BBrowse:Direction^N: public: numeric
  Variable for saving the last cursor key pressed before entering edited
  field. After leaving this field cursor is moved to direction after this 
  variable.

!short:  var QuickEdit        //true
^BBrowse:QuickEdit^N: public: logical
  When starting the editation in Browse mode is this variable true, direct
  entering the field is enabled, if false the editation of the field is
  possible after pressing the Enter key.

!short:  var SetConfirm       //Set(_SET_CONFIRM)
^BBrowse:SetConfirm^N: public: logical
  Saves local value of clipper switch SET CONFIRM... for this object.
  Diferent objects can have diferent values of this switch.

!short:  var AddMsg           //""
^BBrowse:AddMsg^N: public: character
  Text string which is appended to dialog line when this window is active.

!short:  var InsBlock         //{|o|nil}
^BBrowse:InsBlock^N: public: code_block
  Code block (as parameter by activation recieves self object), serving for
  adding next line to table edited by this object.If CanAppen is false, this
  code block is not activated, otherwise it is activated by pressing the Ins
  key in Browse mode. Form mode has no possibility for appending or deleting
  of the line from edited table.

!short:  var DelBlock         //{|o|nil}
^BBrowse:DelBlock^N: public: code_block
  The same as InsBlock, but serves for deleting the line from the table,
  activated by pressing the Del key.

!short:  var PreSkip          //nil
public: code_block
  If not nil, is processed for each skip.

!short:  var PostSkip         //nil
public: code_block
  If not nil, is precessed after each skip.

!short:  var InfoBlock        //{|o|nil}
^BBrowse:InfoBlock^N: public: code_block
  This code block is processed when object is waiting for key pressing.
  As a parameter recieves self object.

!short:  var TestVRecord      //{|o,g|true}
^BTestVRecord(Brovse,Get)^N:public: code_block: return true
  Tests if variable which is manipulated by the Get object is not a virtual
  record in database file. (i.e.RecNo()<=LastRec()). It has no sense to edit
  virtual record due to lose of any changes after finishing of such editation.

!short:  var GetList          //{}
^BBrowse:GetList^N: private: array
  Array of clippper get objects for editation of table fields. Each field
  has its own get object.

!short:  var DoGetList        //{}
^BBrowse:DoGetList^N: private: array
  Array of code blocks, which with get objects from Getlist array serve for
  edit of table fields. Each field ha sits own (indenpendent) code block.

!short:  var DelGet           //{}
^BBrowse:DelGet^N: private: array
  User can exclude not interesting fields from the view. These are transferred
  from instvar variable Getlist to instvar variable (array) DelGet. In the same
  time are code blocks transferred from DoGetlist to DelDoGet.

!short:  var DelDoGet         //{}
^BBrowse:DelDoGet^N: private: array
  As DelGet, serves for saving of code blocks of instvar variable DoGetList,
  when user excludes some fields from the view of the table.

!short:  var Tb               //nil
^BBrowse:Tb^N: public: clipper_object
  This Clipper object manipulates with edited or viewed table.
  Must be used as instvar, because the Oclip-library don't allow to inherit
  from the original clipper classes.

!short:  var Freeze           //0
^BBrowse:Freeze^N: public: numeric
  Contains number of fields of the table which must be locked on left side
  of the window. The lock is valid for Form mode too, but there it appears
  as locking of form rows from the upper side of the window.

!short:  var FormTop          //1
^BBrowse:FormTop^N: public: numeric
  Contains field number in Form mode which should be displayed as first line
  in Form window.

!short:  var Form             //(object of Window)
^BBrowse:Form^N: private: object_of_window
  Serves as Form mode window.

!short:  var SetUp            //false
^BBrowse:SetUp^N: private: logical
  Before first processing of method Process() of this class is necessary
  to finish the initialisation of clipper object TBrowse, if it is done the
  instvar variable Setup is true. It is because the clipper class TBrowse
  has no Copy() method for returning of identical copy of self object.

!short:  method New=BrowseNew           //o:New() --> self
^BBrowse:New()^N: public: return self
  Fills object with default initialising values.

!short:  method Init=BrowseInit         //o:Init(Name,R,C,Rs,Cs,Clr,Shd) --> true
^BBrowse:Init(Name,R,C,Rs,Cs,Clr,Shadow)^N: public: return true
  Object is initialised, when method is finished the Tb object (of TBrowse
  class) is still empty. The parameters are passed till to the class Box 
  method Init(). For detailed description see the class Box.

!short:  method GoodInit=BrowseGoodInit //o:GoodInit(Name,R,C,Rs,Cs,CurSize,Clr,Shd) --> true
^BBrowse:GoodInit(Name,R,C,Rs,Cs,CurSize,Clr,Shadow)^N: public: return true
  It is the same as Browse:Init(..) but by placing of the window on the
  screen is used the principe ^UGoodInit^N defined in parent class Box.
  The parameters are the same as in the class Box.

!short:  method AddBlock=BrowseAddBlock //o:AddBlock(LongNm,ShortNm,VarNm,Block,DoGet,Pict,When,Valid) --> true
^BBrowse:AddBlock(LongName,ShortName,VarName,Block,DoGet,Picture,When,Valid)^N:
  public: return true
  Next column of the table is appended to this object.
  During the editation is the record virtuality not tested i.e. database
  record can be edited even if RecNo()>LastRec().

  Parameter description
  ~~~~~~~~~~~~~~~~~~~~~
  ^ULongName^N: character: default is ShortName
   It is name of column used in Form mode.

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

  ^UVarName^N: character: default is ShortName
   It is name of edited variable, or the name of database field and will
   be saved as information to clipper Get objet created in this method
   and saved to array DoGet. It is because clipper get object used for
   editation should know the name of the edited variable.

  ^UBlock^N: code_block: no default
   It is code block of get/set type, you can create by clipper functions
   FieldBlock(), FieldWBlock(), MemVarBlock() or by own piece of program.

  ^UDoGet^N: code_block: default is virtual_method_Browse:DoGet()
   It is code block which with help of Get object edits a variable
   (database field) in current table column.

  ^UPicture^N: character: default is ""
   It is display mask for display mode of current column.

  ^UWhen^N: code_block: default is {||true}
   It is code block, evaluated before entering the editation of current column,
   if it is false the editation is skipped. Could be used for computed fields
   of table or read-only columns.

  ^UValid^N: code_block: default is {||true}
   It is code block, evaluated after finishing of editation of current
   column. His job is to evaluate if the new entered value is valid, 
   in this case returns true, otherwise false.

!short:  method AddGet=BrowseAddGet     //o:AddGet(Get,DoGet) --> true
^BBrowse:AddGet(Get,DoGet)^N: public: return true
  Adds new column to this object.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UGet^N: clipper_Get_objekt: no  default
   Is used for variable input and the also for saving of new value
   to variable which refers to table column (of course to table row). 
   Pay attention to Cargo variable of this object (Get:Cargo) which should
   content a array with following data:
     1. cLongName  = name used in Form mode
     2. cShortName = name used in Browse mode
     3. cAlias     = Alias database name if it is a database field (or "")
     4. zero (0)   = internal (for saving Col() cursor coordinate)
   Example: Get:Cargo:={"Employee name","Name","DbfEmp",0}

  ^UDoGet^N: code_block: default is virtual_method_Browse:DoGet()
   It is code block which with help of Get object edits a variable
   (database field) in current table column.

!short:  method PostInit=BrowsePostInit //o:PostInit() --> true
^BBrowse:PostInit()^N: private: return true
  It is used for calculating of actual window size in Form mode.

!short:  method DoGet=BrowseDoGet       //o:DoGet() --> true
^BBrowse:DoGet()^N: private: return true
  It is used for one field editation in Browse mode. The Form mode
  is written as indenpendent static function BrowseDoForm()
  for speed reasons.

!short:  method VPaint=BrowseVPaint     //o:VPaint() --> true
^BBrowse:VPaint()^N: private: return true
  Paints window content with use of RefreshAll() method to clipper object Tb
  of TBrowse class. Tb object is the instvar variable of Tb object of Browse
  class.

!short:  method SwapForm=BrowseSwapForm //o:SwapForm() --> true
^BBrowse:SwapForm()^N: public: return true
  Browse - Form mode switching.

!short:  method VProcess=BrowseVProcess //o:VProcess() --> true
^BBrowse:VProcess()^N: private: return true
  The table editation.

!short:  method Process=BrowseProcess   //o:Process() --> true
^BBrowse:Process()^N: public: return true
  The parrent method (Task) is changed for use of PostInit() method
  in the Browse class.

!short:  method DoForm=BrowseDoForm     //o:DoForm() --> true
^BBrowse:DoForm()^N: private: return true
  It is VProcess() (i.e. key-processing) for Form mode.

!short:  method DoBrowse=BrowseDoBrowse //o:DoBrowse() --> true
^BBrowse:DoBrowse()^N: private: return true
  It is VProcess() (i.e. key-processing) for Browse mode.

!short:  method FormPaint=BrowseFormPaint  //o:FormPaint() --> true
^BBrowse:FormPaint()^N: public: return true
  It is VirtualPaint method (doing the job in current window) for Form mode
  (::FormActive==true) of Browse class object.

!short:  method MaskPaint=BrowseMaskPaint  //o:MaskPaint() --> true
^BBrowse:MaskPaint()^N: public: return true
  Abstract method used for class Mask objects (redefined in class Mask).

!short:  endclass