'
'Class description:
'
!short:Mnu class structure:
Class Mnu:
~~~~~~~~~~~
This class enables to create the simple menu objects, the selecting of
which is done by the cursor arrows or by the stressed character.
(instead of the choice class which doesn't know the stressed characters
but it is processed more quickly)

Common use:
~~~~~~~~~~~
LOCAL OBJECT Mnu OF Mnu
Mnu:Init(...)
n:=Mnu:Process()
Mnu:Done()

Due to the heredition can the methods Hide() and Show() of class Win be used
in the class Mnu. It is possible to save temporary the menu and refresh it
and restart the menu selection by repeated call of the Mnu:Process() method.

The source code is in the C_Mnu.prg

!seealso: c_win.ngo:Win c_box.ngo:Box c_menu.ngo:Menu c_choice.ngo:Choice c_color.ngo:Color ob_class.ngo:"Class hierarchy"

!short:~~~~~~~~~~~~~~~~~~~~~
!short:create class Mnu from Win
!short:  export:
!short:  var Help       //{}
^BMnu:Help^N: public: array
  Paralel array for Mnu:Items, for saving of the "MenuID", which is need for
  the correct detecting of the index (RecNo) for interactive help text
  displaying, for every item from Mnu:Items.

!short:  var Items      //{}
^BMnu:Items^N: public: array
  The array of data, where the items of the text strings to be selected are
  saved. Example:
  {"Choice1","Choice2",...,"ChoiceN"}

!short:  var SelItems   //{}
^BMnu:SelItems^N: public: array
  The paralel array for Mnu:Items, it marks the selectability of the item.

!short:  var Cursor     //(object of Cursor)
^BMnu:Cursor^N: private: object
  Class Cursor object, which stores the cursor shape and position during the
  menu selection.

!short:  var Choice     //1
^BMnu:Choice^N: read-only: numeric
  The current item number of Mnu:Items array is stored here (it was user
  selected). If user instead of item selecting pressed Esc, the negative
  current item number is returned.

!short:  var Top        //1
^BMnu:Top^N: private: numeric
  The first displayed item in the window is stored here. (the menu items can
  scroll in the window). It is need for repeated activation of the method
  Mnu:Process().

!short:  var CanAppend  //false
^BMnu:CanAppend^N: public: logical
  If true, the user can by pressing of Ins/Del keys activate the code block
  which must append/delete some item from Mnu:Items. The menu can be
  dynamicaly changed.

!short:  var InsBlock   //{|o|nil}
^BMnu:InsBlock^N: public: code_block
  This code block is activated from Mnu:Process() only when the Mnu:CanAppend
  is true and when the user pressed the Ins key. As parameter to this code
  block is passed the self object. The task for the code block is to append
  a new item to Mnu:Items(), or to change the instvar variables of this
  object. The menu items can be added/deleted an the menu can be dynamicaly
  changed during of the selection.

!short:  var DelBlock   //{|o|nil}
^BMnu:DelBlock^N: public: code_block
  This code block is activated from Mnu:Process() only when the Mnu:CanAppend
  is true and when the user pressed the Del key. As parameter to this code
  block is passed the self object. The task for the code block is to delete
  an items from  Mnu:Items(), or to change the instvar variables of this
  object. The menu items can be added/deleted an the menu can be dynamicaly
  changed during of the selection.

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

!short:  method Init=MnuInit       //o:Init(Name,R,C,CurSize,Items,SelItems,Clr,Shd) --> true
^BMnu:Init(Name,R,C,CurSize,Items,SelItems,Clr,Shadow)^N: public: return true
  This method serves for initialising and positioning of the window for
  the menu to the screen to be nearest as possible to the cursor and
  not to cover the desired text (started on the R,C position with the length
  of CurSize). The window must be whole visible. After the preparing task is
  done, the menu is painted to the screen and the control is returned to the
  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 -row- (cursor) screen position, which shouldn't be covered,
   but the window should be as near as possible to this text.

  ^UC^N: numeric: default is Col().
   Text -column- (cursor) screen position, 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 the data must be entered
   Text strings array, representing the menu.

  ^USelItems^N: array: default is the array filled with the true items of
   the same size as the array selected by Items parameter.
   This array enables the menu items selection.

  ^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 is painted around the window.

!short:  method Process=MnuProcess //o:Process() --> nChoice
^BMnu:Process()^N: public: return nChoice
  This method makes the own menu choice, it returns the selected item number,
  if negative, the user instead of the item selecting pressed Esc.(he doesn't
  wanmt to select anything). This method can be called repeatedly, unlimited
  number of times. The data about the selected item is stored to instvar
  variable Mnu:Choice().

!short:  method Done=MnuDone       //o:Done() --> true
^BMnu:Done()^N: public: return true
  The menu is saved, the screen is refreshed and the control is returned to
  calling function.

!short:  endclass