Anubis / Anubis

                                  The Anubis Project. 
   
                              A Widget System (4th version). 
                                The 'menu manager' widget.
   
                             Copyright (c) Alain Proute' 2005. 

   
   Authors:   Alain Prouté

   Last revision: Oct 21 2005. 


read tools/basis.anubis   
   
read widget.anubis   
read tools.anubis
   
   
   This widget  provides a 'menu' facility  which may be  used by other widgets.   In most
   cases you don't  need to use more than  one 'menu manager' widget within  a single host
   window.
   
   The menu manager widget has two main components:
   
      - A widget which is its 'content' (over  which the menus will be poped up). The menu
        manager has  the same size as  its content, and  only the content is  visible (the
        menu manager by itself has no visible part). 
   
      - A 'command' variable through which commands may be transmitted to the menu manager
        widget.

   The command variable holds a datum of the following type:
   
public type MenuCommand:
   clear,...
   
   This type should  be considered as 'opaque', except for  the first alternative 'clear'.
   The  reason is  that components  in  the other  alternatives need  some conversions  of
   coordinates, which should  remain hidden to the user of the  widget system.  We provide
   below the appropriate functions for constructing the other menu commands.
   
   The menu manager widget itself is created by:
   
public define Widget
   menu_manager
     (
       RGB                             color,  // main color used when insertion of
                                               //   a menu in a window with scrollbars
                                               //   is required
       Var(MenuCommand)     command_variable,  // you may use 'clear' as the inital value
       Widget                        content   // over which menus will appear
     ).
   
   'content' may contain widgets using the command variable. These widgets will be able to
   send commands to the menu manager.
   
   
   --- That's all if you are not creating a new kind of widget ! -------------------------
   
   
   
   Read the subsequent text  only if you plan to create a new kind  of widget using a menu
   manager.
   
   Transmitting a command to  the menu manager amounts to put this  command in the command
   variable  (which is  monitored by  the menu  manager). For  example, assuming  that the
   command variable of your menu manager is named 'menu_command_v', executing:
   
                                   menu_command_v <- clear
   
   removes all the menus currently displayed. 
   
   Other  commands allow  to pop  up a  new menu  (which may  be a  submenu of  an already
   displayed menu). The  content of the menu  is a widget that you  provide yourself.  The
   menu manager does not  insert this widget into anything, so that  it appears exactly as
   defined by you. However,  there is an exception when this widget  does not fit into the
   region  within  which it  should  pop  up. In  this  case,  the  menu manager,  inserts
   automatically the widget  into a window with the appropriate  scrollbars (this is where
   it needs to use a color).
   
   A new menu is normally poped up just beside a given rectangle. You have two choices: 
   
     - letting the menu appear either on the right or on the left of the rectangle,
     - letting the menu appear either below or above the rectangle. 
   
   Hence, you have two functions creating a menu command:
   
public define MenuCommand
   left_right
     (
       WidgetEventToolBox   etb,
       Widget               new_menu,
       WidgetRectangle      r
     ).
   
   This function constructs the command to be put into the command variable.  The new menu
   is  displayed either  on the  immediate right  or on  the immediate  left of  the given
   rectangle. The decision between right and left is taken by the menu manager.

   For example, if you  want to popup the menu 'm' beside  the rectangle 'r', just execute
   this:
   
                        menu_command_v <- left_right(etb,m,r)
   
   where 'etb' is the event tool box of the widget. 
   
   
public define MenuCommand
   top_bottom
     (
       WidgetEventToolBox   etb, 
       Widget               new_menu,
       WidgetRectangle      r
     ).
   
   This functions  constructs the command  for poping up  a new menu immediately  below or
   immediately above the given rectangle. The decision between below and above is taken by
   the menu manager.
   
   The file 'menus.anubis' in the same directory, contains tools for creating usual menus,
   like vertical lists of items and submenus, etc...
      
   
   
   --- That's all for the public part ! --------------------------------------------------
   
   
      
   

   
   --------------------------------- Table of Contents -----------------------------------
   
   
   ---------------------------------------------------------------------------------------
   
   
read window.anubis   
 read box.anubis   

   
   *** [1] Positioning a new menu. 
   
   When a new  menu needs to be displayed, its position  is computed automatically.  There
   are two cases: left_right and top_bottom, which are similar. Hence, we explain only for
   left_right.
   
   First of all,  if the menu is too high  or too wide for fitting within  the area of the
   menu manager,  it is inserted  into a window  with appropriate scrollbars.   After this
   operation, the menu necessarily fits into the area of the menu manager.
   
   We have two rectangles at hand: the area  of the menu manager (which is the same as the
   area of  the 'content' widget of  the menu manager),  and the rectangle given  with the
   command. It is not  necessarily the case that the latter is  included in the former, as
   in the figure below:
   
      +--------------------------------------+
      |menu manager area                     |
      |                                      |
      |       +---------+                    |
      |       |command  |                    |
      |       |rectangle|                    |
      |       +---------+                    |
      |                                      |
      |                                      |
      |                                      |
      |                                      |
      |                                      |
      |                                      |
      +--------------------------------------+

   If the command  rectangle is not included in  the menu manager area, it  is replaced by
   another 'best possible' rectangle included in it.  We also know the width and height of
   the new menu. The best position for this new menu is as in the figure below:
   
      +--------------------------------------+
      |menu manager area                     |
      |                                      |
      |       +---------+-----------+        |
      |       |command  |           |        |
      |       |rectangle|   new     |        |
      |       +---------+   menu    |        |
      |                 |           |        |
      |                 |           |        |
      |                 |           |        |
      |                 +-----------+        |
      |                                      |
      |                                      |
      +--------------------------------------+
   
   if the current 'horizontal direction for menus'  is 'right'. If the menu does'nt fit on
   the right, we try to put it on the left, and if this succeeds, the horizontal direction
   for menus is changed to 'left'. If the menu  still does'nt fit on the left it is put on
   the side it fits best, hidding part of the command rectangle, but completely within the
   area of the menu manager.
   
   
   
   
      *** [1.1] Inserting the new menu into a window (if needed). 

   The  function  'insert_if_needed'  returns  the  given  widget  'new_menu',  eventually
   inserted into a window. 
   
define Widget
   insert_if_needed
     (
       RGB                        color,
       Widget                  new_menu, 
       Widget                   content       // content of menu manager
     ) =
   if size(content) is (cw,ch) then 
   if size(new_menu) is (mw,mh) then 
   if (cw -< mw)
   then if (ch -< mh)
        then // new menu if both too wide and too high
             window(color,cw-30,ch-30,new_menu,not_resizable,both,(One u) |-> color)
        else // new menu is just too wide 
             window(color,cw-30,mh,new_menu,not_resizable,horizontal,(One u) |-> color)
   else if (ch -< mh)
        then // new menu is just too high
             window(color,mw,ch-30,new_menu,not_resizable,vertical,(One u) |-> color)
        else // new menu fits
             new_menu.  
   
   
   
      *** [1.2] Computing the position of the new menu. 
   
type HorizontalDirection:
   left,
   right. 
   
type VerticalDirection:
   top,
   bottom. 
   
type DirectionVariable:
   left_right   (Var(HorizontalDirection)), 
   top_bottom   (Var(VerticalDirection)). 
   
   
   
define (Word32,Word32)
   get_menu_position
     (
       WidgetRectangle         command_rect, 
       Word32                   menu_width,
       Word32                   menu_height, 
       Word32                   manager_width, 
       Word32                   manager_height,
       DirectionVariable       dvar
     ) =
   if command_rect is rect(cx,cy,cu,cv) then 
   // replace the command rectangle by one included in the manager area
   with ncx = max(0,min(cx,manager_width)), 
        ncu = max(0,min(cu,manager_width)), 
        ncy = max(0,min(cy,manager_height)), 
        ncv = max(0,min(cv,manager_height)), 
   // the rectangle rect(ncx,ncy,ncu,ncv) may be empty, but is included in the manager area
   if dvar is 
     {
       left_right(hdvar) then 
         with y = min(ncy,manager_height-menu_height),
         if *hdvar is 
           {
             left    then 
               if menu_width -=< ncx // new menu fits on the left
               then (ncx-menu_width,y)
               else if menu_width -=< manager_width-ncu  // new menu fits on the right
                    then (hdvar <- right; (ncu,y))
                    else // new menu does'nt fit: try to hide as few as possible of the command rectangle
                      if ncx -=< manager_width-ncu
                      then (hdvar <- left; (manager_width-menu_width,y))
                      else (hdvar <- right; (0,y)),
   
             right   then 
               if menu_width -=< manager_width-ncu // new menu fits on the right
               then (ncu,y)
               else if menu_width -=< ncx  // new menu fits on the left
                    then (hdvar <- left; (ncx-menu_width,y))
                    else // new menu does'nt fit: try to hide as few as possible of the command rectangle
                      if ncx -=< manager_width-ncu
                      then (hdvar <- left; (manager_width-menu_width,y))
                      else (hdvar <- right; (0,y))
           },
   
       top_bottom(vdvar) then 
         with x = min(ncx,manager_width-menu_width),
         if *vdvar is 
           {
             top      then 
               if menu_height -=< ncy // new menu fits above
               then (x,ncy-menu_height)
               else if menu_height -=< manager_height-ncv  // new menu fits below
                    then (vdvar <- bottom; (x,ncv))
                    else // new menu does'nt fit: try to hide as few as possible of the command rectangle
                      if ncy -=< manager_height-ncv
                      then (vdvar <- top; (x,manager_height-menu_height))
                      else (vdvar <- bottom; (x,0)),
   
             bottom   then 
               if menu_height -=< manager_height-ncv // new menu fits below
               then (x,ncv)
               else if menu_height -=< ncy  // new menu fits above
                    then (vdvar <- top; (x,ncy-menu_height))
                    else // new menu does'nt fit: try to hide as few as possible of the command rectangle
                      if ncy -=< manager_height-ncv
                      then (vdvar <- top; (x,manager_height-menu_height))
                      else (vdvar <- bottom; (x,0))
           }
     }. 
   
   

   
   
   *** [2] Drawing. 
   
   The menu  manager widget has  a list  of child widgets:  the menus which  are currently
   displayed. Since  the menu manager  is responsible of  the positions of its  childs, we
   define the following type:
   
type PositionedMenu:
   pmenu(Word32    x, 
         Word32    y, 
         Widget   content). 
   
   The menu manager  has a internal variable 'menu_list_v'  of type 'List(PositionedMenu)'
   containing the  list of all  currently displayed  menus. The head  of list is  the most
   recent (topmost in the Z-order) menu.
   
   Redrawing the menu  manager amounts to redraw the menus, beginning  by the topmost one,
   and at the end  redraw the content widget. Of course each  one of these redrawings must
   occur in  the difference  between the  menu manager area  and the  area covered  by the
   already redrawn menus.
   
define One
   redraw_menus_and_content
     (
       WidgetDrawToolBox       dtb, 
       List(PositionedMenu)    menus, 
       Widget                  content,
       List(WidgetRectangle)   clip,
       WidgetRectangle         content_rect
     ) =
   if menus is 
     {
       [ ] then draw(dtb)(content,0,0,clip),
       [pm1 . other_menus] then 
         if pm1 is pmenu(x1,y1,m1) then 
         draw(dtb)(m1,x1,y1,clip);
         redraw_menus_and_content(dtb,other_menus,content,
                if size(m1) is (w1,h1) then 
                intersection(clip,content_rect - rect(x1,y1,x1+w1,y1+h1)),
                content_rect)
     }.

   
   
   The draw method itself. 
   
define WidgetDrawToolBox -> One
   draw_method
     (
       Var(List(PositionedMenu))    menu_list_v, 
       Widget                       content
     ) =
   (WidgetDrawToolBox dtb) |-> 
      if size(content) is (w,h) then 
      with content_rect = (WidgetRectangle)rect(0,0,w,h), 
      redraw_menus_and_content(dtb,*menu_list_v,content,[content_rect],content_rect). 
   
   
   
   
   
   

   
   *** [3] Handling events. 
   
   The menu manager never captures the mouse, and is sensible to the following events:
   
     mouse_click     in order to remove menus eventually
     changed         when the command variable is changed
   
   When a  mouse_move or mouse_click event arrives,  the menu manager checks  the menus in
   the Z-order  in order  to find  the first one  containing the  mouse pointer.   This is
   important because  since menus may overlap,  mouse events should not  be transmitted to
   all of them.
   
   If the list of menus is empty, the event is simply transmitted to the content. 
   
   From  now on,  we  suppose that  the list  of  menus is  not  empty.  If  the event  is
   'mouse_click', each  menu in the  Z-order (starting with  the topmost one)  is removed,
   until one is found  containing the mouse pointer. If such a  menu is found, more recent
   menus  are removed  and  the click  is transmitted  to  the menu  containing the  mouse
   pointer. If no such menu is found, all  menus are removed and the click is lost. If the
   event is 'mouse_move', it is not  transmitted and the answer is 'not_handled([])'. This
   is important not to transmit 'mouse_move' events to the content when a menu is visible,
   because the visible  menus may be logically linked to highlighted  areas of the content
   for example, which may  change when the mouse is moved. Hence,  when a menu is visible,
   the content must be somewhat inhibited,  otherwise the semantics of the menu itself may
   be wrong. The same rule applies to keyboard events. 
   
   If a  changed event is received,  and if the  command variable is concerned,  menus are
   removed or added, and an appropriate  answer is generated (combined with the answers of
   the remaining childs).
   
   Other events are just transmitted to all childs. 
   
   
   
   
   
define WidgetAnswer
   add_area
     (
       WidgetEventToolBox       etb, 
       List(WidgetRectangle)    l,
       WidgetAnswer             an
     ) =
   if an is 
     {
       not_handled(a)                then not_handled(a+area(etb)(l)), 
       handled(a)                    then handled(a+area(etb)(l)), 
       resized                       then resized,
       ignored                       then not_handled(area(etb)(l)), 
       want_to_capture_mouse(v,c,a)  then want_to_capture_mouse(v,c,a+area(etb)(l)),
       want_to_capture_keyboard(v,a) then want_to_capture_keyboard(v,a+area(etb)(l))
     }. 


define List(WidgetRectangle)
   get_area
     (
       List(PositionedMenu)   l
     ) =
   if l is 
     {
       [ ] then [ ], 
       [pm1 . others] then 
         if pm1 is pmenu(x1,y1,m1) then 
         if size(m1) is (w1,h1) then 
         [rect(x1,y1,x1+w1,y1+h1) . get_area(others)]
     }. 
   
   
define WidgetAnswer
   merge_answers
     (
       WidgetAnswer  a1, 
       WidgetAnswer  a2
     ) =
   if a1 is 
     {
       not_handled(area1) then if a2 is 
         {
           not_handled(area2)            then not_handled(area1+area2), 
           handled(area2)                then handled(area1+area2), 
           resized                       then resized,
           ignored                       then a1
           want_to_capture_mouse(_,_,_)  then a2,
           want_to_capture_keyboard(_,_) then a2
         },
   
       handled(area1) then if a2 is 
         {
           not_handled(area2)            then handled(area1+area2), 
           handled(area2)                then handled(area1+area2), 
           resized                       then resized,
           ignored                       then a1,
           want_to_capture_mouse(_,_,_)  then a2,
           want_to_capture_keyboard(_,_) then a2
         }, 
   
       resized                           then resized,
       ignored                           then a2,
       want_to_capture_mouse(v,cf,area)  then a1,
       want_to_capture_keyboard(v,area)  then a1,
     }. 
   

define WidgetAnswer
   default_event_handling
     (
       WidgetEventToolBox       etb, 
       List(PositionedMenu)     menus, 
       Widget                   content, 
       WidgetEvent              e
     ) =
   if menus is 
     {
       [ ] then transmit(etb)(content,0,0,e), 
       [pm1 . others] then
         if pm1 is pmenu(x1,y1,m1) then 
         with answer1 = transmit(etb)(m1,x1,y1,e), 
              answers = default_event_handling(etb,others,content,e),
           merge_answers(answer1,answers)
     }. 
   
   
define WidgetAnswer
   handle_mouse_click
     (
       WidgetEventToolBox           etb, 
       KeyboardState                ks,
       MouseClick                   mc, 
       Word32                        mx, 
       Word32                        my, 
       Var(List(PositionedMenu))    menu_list_v,
       List(PositionedMenu)         menu_list, 
       Var(MenuCommand)             command_v, 
       Widget                       content,
       List(WidgetRectangle)        to_be_redrawn
     ) =
   if menu_list is
     {
       [ ] then // the click is outside any menu 
         if mc is left_down
         then (
               menu_list_v <- []; 
               command_v <- clear;
               not_handled(area(etb)(to_be_redrawn))
              )
         else (
               ignored
              ),
   /*
         command_v <- clear; 
         add_area(etb,to_be_redrawn,transmit(etb)(content,0,0,mouse_click(ks,mc,mx,my))),                
   */
   
       [pm1 . others] then 
         if pm1 is pmenu(x1,y1,m1) then 
         if size(m1) is (w1,h1) then 
         if (x1 -=< mx & mx -< x1+w1 & y1 -=< my & my -< y1+h1)
         then menu_list_v <- menu_list; 
              add_area(etb,to_be_redrawn,transmit(etb)(m1,x1,y1,mouse_click(ks,mc,mx,my)))
         else handle_mouse_click(etb,ks,mc,mx,my,menu_list_v,others,command_v,content,
                                 [rect(x1,y1,x1+w1,y1+h1) . to_be_redrawn])
     }. 
    
   
   
define WidgetAnswer
   transmit_mouse_gone
     (
       WidgetEventToolBox       etb, 
       Widget                   content,
       List(PositionedMenu)     menus
     ) =
   if menus is 
     {
       [ ] then transmit(etb)(content,0,0,mouse_gone),  
       [pm1 . pms] then if pm1 is pmenu(x1,y1,m1) then 
         merge_answers(transmit(etb)(m1,x1,y1,mouse_gone),
                       transmit_mouse_gone(etb,content,pms))
     }.
   
   
define WidgetAnswer
   handle_mouse_move
     (
       WidgetEventToolBox           etb,
       KeyboardState                ks, 
       Word32                        mx, 
       Word32                        my, 
       List(PositionedMenu)         menu_list,
       Widget                       content
     ) =
   if menu_list is 
     {
       //[ ] then transmit(etb)(content,0,0,mouse_move(ks,mx,my)), 
       [ ] then ignored, 
       [pm1 . others] then 
         if pm1 is pmenu(x1,y1,m1) then 
         if size(m1) is (w1,h1) then 
         if (x1 -=< mx & mx -< x1+w1 & y1 -=< my & my -< y1+h1)
         then merge_answers(transmit(etb)(m1,x1,y1,mouse_move(ks,mx,my)),
                            transmit_mouse_gone(etb,content,others))
         else merge_answers(transmit(etb)(m1,x1,y1,mouse_gone),
                            handle_mouse_move(etb,ks,mx,my,others,content))
     }.
   
   
   
   
public type MenuCommand:
   l_r  (Widget,Rectangle),
   t_b  (Widget,Rectangle).

   
   
define WidgetAnswer
   handle_changed
     (
       WidgetEventToolBox           etb, 
       Var(List(PositionedMenu))    menu_list_v, 
       List(Word32)                 l, 
       Var(MenuCommand)             command_v,
       Widget                       content,
       Var(HorizontalDirection)     hdvar,
       Var(VerticalDirection)       vdvar,
       RGB                          menu_color
     ) =
   if member(l,var_id(command_v))
   then if *command_v is 
     {
       clear then
         with to_be_redrawn = union(get_area(*menu_list_v)),
         menu_list_v <- []; 
         merge_answers(handled(area(etb)(to_be_redrawn)),
                       default_event_handling(etb,[],content,changed(l))), 
   
       l_r(menu1,r) then 
         with menu = insert_if_needed(menu_color,menu1,content), 
         if size(menu) is (w1,h1) then
         if size(content) is (w,h) then
         if get_menu_position(widget_rectangle(etb,r),w1,h1,w,h,left_right(hdvar)) is (x1,y1) then 
         menu_list_v <- [pmenu(x1,y1,menu) . *menu_list_v]; 
         merge_answers(handled(area(etb)([rect(x1,y1,x1+w1,y1+h1)])),
                       default_event_handling(etb,*menu_list_v,content,changed(l))),
   
       t_b(menu1,r) then 
         with menu = insert_if_needed(menu_color,menu1,content), 
         if size(menu) is (w1,h1) then
         if size(content) is (w,h) then
         if get_menu_position(widget_rectangle(etb,r),w1,h1,w,h,top_bottom(vdvar)) is (x1,y1) then 
         menu_list_v <- [pmenu(x1,y1,menu) . *menu_list_v]; 
         merge_answers(handled(area(etb)([rect(x1,y1,x1+w1,y1+h1)])),
                       default_event_handling(etb,*menu_list_v,content,changed(l))),
     }
   else default_event_handling(etb,*menu_list_v,content,changed(l)). 
   
   
   
   
define (WidgetEventToolBox,WidgetEvent) -> WidgetAnswer   
   event_handler
     (
       Var(MenuCommand)             command_v,
       Var(List(PositionedMenu))    menu_list_v,
       Widget                       content,
       Var(HorizontalDirection)     hdvar,
       Var(VerticalDirection)       vdvar,
       RGB                          menu_color
     ) = 
   (WidgetEventToolBox etb, WidgetEvent e) |->
     if e is 
       {
         quit                         then default_event_handling(etb,*menu_list_v,content,e),
         mouse_move(ks,x,y)           then if *menu_list_v is [] 
                                           then transmit(etb)(content,0,0,mouse_move(ks,x,y))
                                           else handle_mouse_move(etb,ks,x,y,*menu_list_v,content),
         mouse_click(ks,mc,x,y)       then if *menu_list_v is []
                                           then transmit(etb)(content,0,0,mouse_click(ks,mc,x,y))
                                           else handle_mouse_click(etb,ks,mc,x,y,
                                                     menu_list_v,*menu_list_v,command_v,content,[]),
         mouse_wheel(ks,d,x,y)        then default_event_handling(etb,*menu_list_v,content,e),
         mouse_gone                   then default_event_handling(etb,*menu_list_v,content,e),
         captured_mouse_move(f)       then default_event_handling(etb,*menu_list_v,content,e),
         captured_mouse_liberated(f)  then default_event_handling(etb,*menu_list_v,content,e),
         key_down(f)                  then default_event_handling(etb,*menu_list_v,content,e),
         keyboard_recaptured(f)       then default_event_handling(etb,*menu_list_v,content,e),
         changed(l)                   then handle_changed(etb,menu_list_v,l,command_v,content,
                                                          hdvar,vdvar,menu_color),
         could_drop(_,_,_,_)          then default_event_handling(etb,*menu_list_v,content,e),
         want_to_drop(_,_,_)          then default_event_handling(etb,*menu_list_v,content,e)
       }. 
   
   

   *** [4] Creating the menu manager. 
   
public define Widget   
   menu_manager
     (
       RGB                             color,
       Var(MenuCommand)            command_v,
       Widget                        content 
     ) =
   with    hdvar = var((HorizontalDirection)right), 
           vdvar = var((VerticalDirection)bottom), 
     menu_list_v = var((List(PositionedMenu))[]),
   
   /*
   ticket = register_monitor(menu_list_v,
               (One u) |-> print("\nmenu_list_v: "+length(*menu_list_v))), 
   */
   
     create_widget
       (
         stretch_cap(content),
         stretch_to(content), 
         (One u) |-> /*forget(ticket);*/ size(content), 
         draw_method(menu_list_v,content),
         event_handler(command_v,menu_list_v,content,hdvar,vdvar,color),
         (One u) |-> [register(command_v) . registrations(content)(unique)]
       ). 

   
   
public define MenuCommand
   left_right
     (
       WidgetEventToolBox   etb,
       Widget               new_menu,
       WidgetRectangle      r
     ) =
   l_r(new_menu,rectangle(etb,r)). 

public define MenuCommand
   top_bottom
     (
       WidgetEventToolBox   etb, 
       Widget               new_menu,
       WidgetRectangle      r
     ) =
   t_b(new_menu,rectangle(etb,r)).