'
'Class description:
'
!short:Choice class structure:
Class Choice:
~~~~~~~~~~~~~~
This class combines properties of simple window Win and clipper function
AChoice.


Common use:
~~~~~~~~~~~
LOCAL OBJECT Cho OF Choice
Cho:Init(...)                //or Cho:FastInit(...)
n:=Cho:Process()
Cho:Done()

Due to inheritance the methods Hide() and Show() inherited from class Win
can be used for an object of class Choice. The menu can be temporary saved
and then redisplayed and after that by method Choice:Process() call can be
started the menu choice.

Source code of class Choice is in C_Choice.prg

!seealso: c_win.ngo:Win c_box.ngo:Box c_mnu.ngo:Mnu c_menu.ngo:Menu ob_funct.ngo:AValid ob_funct.ngo:DbfValid c_color.ngo:Color ob_class.ngo:"Class hierarchy"

!short:~~~~~~~~~~~~~~~~~~~~~~~~
!short:create class Choice from Win
!short:  export:
!short:  var Items      //{"item1",...}
^BChoice:Items^N: public: array
  Array of data for AChoice(...) function, which should contain a selectable
  items in form of text strings. Example:
  {"choice1","choice2", ... ,"choiceN"}

!short:  var SelItems   //{lSelectable,...}
^BChoice:SelItems^N: public: array
  Paralell array for Choice:Items used for selectable items marking.

!short:  var Cursor     //(object of Cursor)
^BChoice:Cursor^N: private: object
  Class Cursor object for saving the cursor shape during the menu choice.

!short:  var Choice     //1
^BChoice:Choice^N: read-only: numeric
  Stores the item number of Choice:Items field, selected by user.
  If user instead of selecting by pressing Enter pressed ESC,
  the ^UNegative^N value of actual item number is returned!

!short:  var Top        //1
^BChoice:Top^N: private: numeric
  Stores the number of the first displayed item in a window. (the items could
  scroll). It is used for correct display in repeated activation 
  of Choice:Process method.

!short:  var CanAppend  //false
^BChoice:CanAppend^N: public: logical
  If true, user can by pressing Ins/Del keys activate the code block
  for adding/deletting of an item from Choice:Items. The menu can be
  dynamicaly modified.

!short:  var InsBlock   //{|o|nil}
^BChoice:InsBlock^N: public: code_block
  This code block is activated from Choice:Process() when the Choice:Append
  is true and the user pressed Ins key during the selection. As parameter
  of this code block is passed the self object. The job of this code block
  is to add a new item to Choice:Items, or to reconfigure the instvar
  variables of this object. It enables during the selection
  the adition/deletion of menu items and dynamicaly modify the menu.

!short:  var DelBlock   //{|o|nil}
^BChoice:DelBlock^N: public: code_block
  This code block is activated from Choice:Process() when the Choice:Append
  is true and the user pressed Del key during the selection. As parameter
  of this code block is passed the self object. The job of this code block
  is to delete an item from Choice:Items, or to reconfigure the instvar
  variables of this object. It enables during the selection
  the adition/deletion of menu items and dynamicaly modify the menu.

!short:  var InRow      //0
^BChoice:InRow^N: private: numeric
  Stores the init (row) position  of Choice window on the screen
  for correct repainting after issuing code blocks Choice:InsBlock
  or Choice:DelBlock.

!short:  var InCol      //0
^BChoice:InCol^N: private: numeric
  Stores the init (column) position  of Choice window on the screen
  for correct repainting after issuing code blocks Choice:InsBlock
  or Choice:DelBlock.

!short:  var InCurSize  //0
^BChoice:InCurSize^N: private: numeric
  Stores the value of CursorSize parameter for parrent method Box:GoodInit()
  for correct repainting after issuing code blocks Choice:InsBlock
  or Choice:DelBlock.

!short:  method New=ChoiceNew           //o:New() --> self
^BChoice:New()^N: public: return self
  Object is filled with default values.

!short:  method Init=ChoiceInit         //o:Init(Name,R,C,CurSize,Items,SelItems,Clr,Shd) --> true
^BChoice:Init(Name,R,C,CurSize,Items,SelItems,Clr,Shadow)^N: public: return true
  This method is used for initialising and reasonable window placement
  for clipper function Achoice on the screen, to be as near as possible
  to cursor but not to cover any desired text. (It starts on R,C position
  with length of CurSize). Off course the window must be placed to be whole
  visible. After all preparing job is done the menu is painted to the screen
  and the control goes to calling function.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UName^N: text or code block : no default
   Text or code block as window title.

  ^UR^N: numeric: default is Row().
   Text position -row- (of cursor) on the screen, which shouldn't be covered
   but the window should be as near as possible to this text.

  ^UC^N: numeric: default is Col().
   Text position -column- (of cursor) on the screen, which shouldn't be
   covered but the window should be as near as possible to this text.

  ^UCurSize^N: numeric: default is 1.
   Text width, which shouldn't be covered but the window should be as
   near as possible to this text.

  ^UItems^N: array: no default must be entered
   It is an array of text strings, repersenting the menu. It is passed
   without any change as parameter to clipper function AChoice().

  ^USelItems^N: array: default is an array filled with true-values.
   It is an array (of the same size as the "Items" parameter) controling
   if the items can be selected from menu or the selection of this items
   is not allowed. It is passed without any change as parameter to function
   AChoice().

  ^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 window shadow will be painted.

!short:  method FastInit=ChoiceFastInit //o:FastInit(Name,R,C,CurSize,Items,SelItems,Clr,Shd) --> true
^BChoice:FastInit(Name,R,C,CurSize,Items,SelItems,Clr,Shadow)^N: public:
  return: true
  It is the same as Choice:Init(...) but with diference of initialising jobs
  and the menu is not painted to the screen. The painting is done after
  activating of the method Choice:Process().

!short:  method Process=ChoiceProcess   //o:Process() --> nChoice
^BChoice:Process()^N: public: return nChoice
  This method is making the own choice from the menu, it returns the selected
  item number, if it is negative, the user instead of selecting and pressing
  the Enter key pressed ESC key (he doesn't want to select anything).
  This method can be called repeatedly unrestricted number of times.
  The selected item value is stored to instvar variable Choice:Choice.

!short:  method Done=ChoiceDone         //o:Done() --> true
^BChoice:Done()^N: public: return true
  Stores the menu, i.e. restores the screen and the control goes to calling
  function.

!short:  endclass