Anubis / Anubis

   
   
                             The Anubis/Paradize Project.
   
                               The menu manager widget. 
   
                         Copyright (c) Alain Prouté 2004-2005. 

   
   Authors:   Alain Prouté

   
   
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), 
      - 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 menu commands.
   
   The menu manager widget itself is created by:
   
public define Widget
   create_menu_manager
     (
       WidgetParameters           parameters,  
       Var(MenuCommand)     command_variable,  // you may use 'clear' as the inital value
       Widget                        content   // over which menus will appear
     ).
   
   
   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. The content of the menu is a widget that you
   provide yourself. The menu manager does not  insert this widget in 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.
   
   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 commands for poping up menus:
   
public define MenuCommand
   add_left_right
     (
       WidgetEventToolBox   etb, 
       Widget               new_menu,
       WidgetRectangle      r
     ).
   
   This command adds a new menu 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.
   
   
public define MenuCommand
   add_top_bottom
     (
       WidgetEventToolBox   etb, 
       Widget               new_menu,
       WidgetRectangle      r
     ).
   
   This command  adds a new menu either  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 -----------------------------------
   
   *** (1) Positioning a new menu. 
      *** (1.1) Inserting the new menu into a window (if needed). 
      *** (1.2) Computing the position of the new menu. 
   *** (2) The command handler. 
   *** (3) Setting positions of childs. 
   *** (4) Redrawing. 
   *** (5) Normal events handler. 
   *** (6) Creating the menu manager. 
   
   ---------------------------------------------------------------------------------------
   
   
read window.anubis   
read box.anubis   
   
   *** (1) Positioning a new menu. 
   
   When  a new  menu  arrives (through  an  'add_?'  command),  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 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 ios 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
     (
       WidgetParameters           parms,
       Widget                  new_menu, 
       Widget                   content       // content of menu manager
     ) =
   if get_size(content)(unique) is (cw,ch) then 
   if get_size(new_menu)(unique) is (mw,mh) then 
   if (cw < mw)
   then if (ch < mh)
        then // new menu if both too wide and too high
          create_box(relief(parms),2,
             create_window_both(parms,var((Int32)cw-30),var((Int32)ch-30),new_menu))
        else // new menu is just too wide 
          create_box(relief(parms),2,
             create_window_horizontal(parms,var((Int32)cw-30),var((Int32)mh),new_menu))
   else if (ch < mh)
        then // new menu is just too high
          create_box(relief(parms),2,
             create_window_vertical(parms,var((Int32)mw),var((Int32)ch-30),new_menu))
        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 (Int32,Int32)
   get_menu_position
     (
       WidgetRectangle         command_rect, 
       Int32                   menu_width,
       Int32                   menu_height, 
       Int32                   manager_width, 
       Int32                   manager_height,
       DirectionVariable       dvar
     ) =
   if command_rect is rect(cx,cy,cu,cv) then 
   // replace the command erctangle 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) The command handler. 
   
   When a command arrives in the command variable, the function 'command_handler' below is
   called.  It receives a tool for redrawing, the command which has been received, and the
   variable holding the list of currently poped up menus.


public type MenuCommand:
   add_l_r  (Widget,Rectangle),
   add_t_b  (Widget,Rectangle).
   
   
define One 
   command_handler
     (
       WidgetParameters                 parms, 
       WidgetMonitoringToolBox          mtb,  
       List(WidgetRectangle) -> One     redraw,
       MenuCommand                      command,
       Widget                           content, 
       Var(List(Widget))                menu_list_v,
       Var(HorizontalDirection)         hdvar, 
       Var(VerticalDirection)           vdvar
     ) =
   if command is 
     {
       clear then 
         with menus_area = get_area(*menu_list_v), 
         menu_list_v <- [];
         redraw(menus_area), 
   
       add_l_r(menu,c_rect) then 
         with new_menu = insert_if_needed(parms,menu,content), 
         if get_size(content)(unique) is (manager_width,manager_height) then 
         if get_size(new_menu)(unique) is (menu_width,menu_height) then 
         if get_menu_position(receive_rectangle(mtb)(c_rect),
                              menu_width,menu_height,
                              manager_width,manager_height,
                              left_right(hdvar)) is (nmx,nmy) then 
         store_relative_position(new_menu,position(nmx,nmy)); 
         menu_list_v <- [new_menu . *menu_list_v]; 
         redraw([rect(nmx,nmy,nmx+menu_width,nmy+menu_height)]),
   
       add_t_b(menu,c_rect) then 
         with new_menu = insert_if_needed(parms,menu,content), 
         if get_size(content)(unique) is (manager_width,manager_height) then 
         if get_size(new_menu)(unique) is (menu_width,menu_height) then 
         if get_menu_position(receive_rectangle(mtb)(c_rect),
                              menu_width,menu_height,
                              manager_width,manager_height,
                              top_bottom(vdvar)) is (nmx,nmy) then 
         store_relative_position(new_menu,position(nmx,nmy)); 
         menu_list_v <- [new_menu . *menu_list_v]; 
         redraw([rect(nmx,nmy,nmx+menu_width,nmy+menu_height)])
     }.
   

   
   
   
   
   *** (3) Setting positions of childs. 
   
   The menus currently poped  up are the childs of the menu  manager.  Positions of childs
   are  already stored in  the childs.  Hence, we  use the  following standard  program (a
   similar function may be found in 'table.anubis').
   
define One
   set_menu_manager_childs_positions
     (
       WidgetPositionToolBox    ptb,
       List(Widget)             childs
     ) =
   if childs is 
     {
       [ ] then unique, 
       [c1 . cs] then  
         set_position(c1)(ptb,get_position(c1)(unique));
         set_menu_manager_childs_positions(ptb,cs)
     }.
   
   

   
    
   *** (4) Redrawing. 
   
define One
   redraw_menu_manager
     (
       WidgetDrawToolBox        dtb,
       List(Widget)             menus,
       Widget                   content,
       List(WidgetRectangle)    where           // where to redraw
     ) =
   if menus is 
     {
       [ ] then 
         forget(map((WidgetRectangle r) |-> redraw(content)(dtb,r),where)),
   
       [m1 . ms] then 
         if get_position(m1)(unique) is position(x1,y1) then 
         if get_size(m1)(unique) is (w1,h1) then 
         with r1 = (WidgetRectangle)rect(x1,y1,x1+w1,y1+h1),
         forget(map((WidgetRectangle r) |-> 
             if intersection(r,r1) is 
               {
                 failure then unique, 
                 success(rr1) then redraw(m1)(dtb,rr1)
               },where));
         redraw_menu_manager(dtb,ms,content,where-r1)
     }.
   

   
   
   *** (5) Normal events handler. 
   
define WidgetAnswer
   menu_manager_event_handler
     (
       WidgetEventToolBox      etb,
       WidgetNormalEvent       e,
       Var(MenuCommand)        command_v, 
       Var(List(Widget))       menu_list_v,
       List(Widget)            menus,
       List(Widget)            menus_seen, 
       Widget                  content,
       Var(Maybe(Widget))      last_impacted,
       WidgetAnswer            mg_answer
     ) =
   if menus is 
     {
        [ ] then 
          // outside any menu
          if *menu_list_v is 
            {
              [ ]     then join(main_event_handler(content)(etb,e),mg_answer), 
              [_._]   then 
                if e is 
                  {
                    mouse_gone             then join(handled([]),mg_answer),
                    mouse_move(ks,x,y)     then join(handled([]),mg_answer),
                    mouse_click(ks,mc,x,y) then 
                      command_v <- clear; 
                      join(handled([]),mg_answer)
                  }
            },
   
        [m1 . ms] then 
          if get_position(m1)(unique) is position(x1,y1) then 
          if get_size(m1)(unique) is (w1,h1) then 
          with xe = x(e), ye = y(e), 
          if (x1 =< xe & xe < x1+w1 & y1 =< ye & ye < y1+h1)
          then (
                 last_impacted <- success(m1); 
                 (if e is mouse_click(_,_,_,_) 
                    then menu_list_v <- menus
                    else unique); 
                 join(join(main_event_handler(m1)(etb,e),
                           mg_answer),
                      not_handled(get_area(menus_seen)))
               )
          else menu_manager_event_handler(etb,
                                          e,
                                          command_v,
                                          menu_list_v,
                                          ms,
                                          [m1 . menus_seen], 
                                          content,
                                          last_impacted,
                                          mg_answer)
     }.
   
   

   
   *** (6) Creating the menu manager. 
   
public define Widget
   create_menu_manager
     (
       WidgetParameters                parms,
       Var(MenuCommand)     command_variable,    // use 'clear' as the initial value
       Widget                        content
     ) =
   with menu_list_v = var((List(Widget))[]), 
              hdvar = var((HorizontalDirection)right),
              vdvar = var((VerticalDirection)bottom), 
      last_impacted = var((Maybe(Widget))failure), 
            monitor = (WidgetMonitoringToolBox mtb, 
                       List(WidgetRectangle) -> One redraw) |->
                        command_handler(parms,
                                        mtb, 
                                        redraw,
                                        *command_variable,
                                        content,
                                        menu_list_v,
                                        hdvar,
                                        vdvar), 
   create_widget
     (
       /* Setting positions of childs */ 
       (WidgetPositionToolBox ptb) |-> 
          set_menu_manager_childs_positions(ptb,*menu_list_v);
          set_position(content)(ptb,position(0,0)), 
   
       /* Getting size */ 
       get_size(content),
   
       /* Redrawing */ 
       (WidgetDrawToolBox dtb) |->
          redraw_menu_manager(dtb,*menu_list_v,content,[clipping_rectangle(dtb)]), 
   
       /* Duplicating */ 
       (One u) |-> create_menu_manager(parms,
                                       command_variable,
                                       duplicate(content)(unique)), 
   
       /* Changing size */
       (Int32 w, Int32 h) |-> unique, 
   
       /* Main event handler */ 
       (WidgetEventToolBox etb, WidgetNormalEvent e) |->
          with mg_answer = if *last_impacted is 
                             {
                               failure then handled([]), 
                               success(m) then 
                                 last_impacted <- failure;
                                 main_event_handler(m)(etb,mouse_gone)
                             },
          menu_manager_event_handler(etb,
                                     e,
                                     command_variable,
                                     menu_list_v,
                                     *menu_list_v,
                                     [], 
                                     content,
                                     last_impacted,
                                     mg_answer), 
   
       /* Registrations */ 
       [register(command_variable,monitor)]
     ). 

   

public define MenuCommand
   add_left_right
     (
       WidgetEventToolBox   etb, 
       Widget               new_menu,
       WidgetRectangle      r
     ) =
   add_l_r(new_menu,send_rectangle(etb)(r)). 
   
public define MenuCommand
   add_top_bottom
     (
       WidgetEventToolBox   etb, 
       Widget               new_menu,
       WidgetRectangle      r
     ) =
   add_t_b(new_menu,send_rectangle(etb)(r)).