Anubis / Anubis

                                  The Anubis Project. 
   
                              A Widget System (4th version). 
                                   The 'button' widget.
   
                             Copyright (c) Alain Proute' 2005. 
   
   
   Authors: Alain Proute'
            Olivier Duvernois

   Last revision: Oct 21 2005   
   
   In this  file the  'button' widget is  defined.  Notice  that hypertext links  are just
   buttons with a special aspect.

   
   --------------------------- Table of Contents -----------------------------------------
   
   *** (1) Action. 
   *** (2) Aspect when rolled over. 
   *** (3) Variable state reflexion. 
   *** (4) Monitoring variables.
   *** (5) Button's decoration. 
   *** (6) Button's styles. 
   *** (7) Inhibition and blocking behavior. 
   *** (8) Creating a button. 
   
   ---------------------------------------------------------------------------------------
   

read tools/basis.anubis
   
read widget.anubis
read tools.anubis   
   
   
   *** (1) Action. 
   
   The role of  a button is to perform  an action when it is clicked  upon. Actually, this
   action is not performed when the left button of the mouse is pushed down, but only when
   it is  released, and  under the  condition that the  mouse cursor  is still  within the
   button. That way the user still has the possibility to renounce to the action.
      
   
   *** (2) Aspect when rolled over. 
   
   Buttons also change their aspect not only when left clicked on, but also when the mouse
   cursor rolls over them. This is an important ergonomic feature, because the user better
   understands the possible consequences of the  action of the button.  This may also help
   to detect the presence of the button, which may sometimes not be so obvious.
   
   Summarizing, a button has 3 aspects:
   
     - normal:         the mouse cursor is outside the area of the button
     - rolled over:    the mouse cursor is within the area of the button but not left 
                         clicked
     - clicked:        the mouse cursor is within the area of the button and left clicked

   
   *** (3) Variable state reflexion. 
   
   A button may reflect the state of  one or several variables.  For example, a button may
   be a flip-flop, and  change the state of some variable at each  click. In this case, it
   is a good idea that the button  has differents decorations depending on the state.  For
   that reason, the decoration of the  button is not constant, but recomputed when needed.
   Also, since these decorations  may not have the same size, the  size of the button does
   not depend on them.  This is also preferable for making tables  of buttons. That way we
   may ensure that the size of the buttons do not depend on their current decoration.
   
   
   *** (4) Monitoring variables.
   
   Since a  button may  reflect a  'state', the button  must eventually  monitor a  set of
   variables, so that its decoration is always  up to date.  The following tool enables to
   monitor such a variable without having to create a monitor.

public type WidgetButtonRegistration:...    (an opaque type)
      
public define WidgetButtonRegistration
   register
     (
       Var($T) variable
     ). 
   
   For example, if the  state (hence the decoration) of your button  depends on the values
   of the variables 'v1', 'v2' and 'v3'  (whose types may be different), use the following
   list as the last argument of 'button' creation function:
   
        [
          register(v1),
          register(v2),
          register(v3)
        ]
   
   That way you ensure that if the value of any of these variables changes, the decoration
   of your button changes accordingly in (almost) real time.
   
   
   *** (5) Button's decoration. 
      
   We  propose the following  sorts of  decorations for  buttons.  Decorations  are always
   vertically centered, but may be either  left justified or horizontally centered. In the
   case of image and text together, the image is placed on the left of the text.
   
public type WidgetButtonDecoration:
   center_text             (String        text,
                            SystemFont    font,
                            RGB           color_of_text), 
   
   left_text               (Int32         left_margin, 
                            String        text,
                            SystemFont    font,
                            RGB           color_of_text), 
   
   center_image            (HostImage     image),
   
   left_image              (Int32         left_margin, 
                            HostImage     image),
   
   center_image_and_text   (HostImage     image,
                            Int32         glue,       // between image and text
                            String        text,
                            SystemFont    font,
                            RGB           color_of_text),
   
   left_image_and_text     (Int32         left_margin,
                            HostImage     image,
                            Int32         glue,       // between image and text
                            String        text,
                            SystemFont    font,
                            RGB           color_of_text). 
   

   
   *** (6) Button's styles. 
   
   We propose the following styles of presentation for buttons:
   
public type WidgetButtonStyle:
   link  // hypertext link    
     (String         text,            // text of link
      SystemFont     font,            // font for text
      RGB            off_color,       // color when mouse pointer off
      RGB            on_color),       // color when mouse pointer on
   
   push_down // standard 'push down' aspect
     (Int32          width,           // total width of button
      Int32          height,          // total height of button
      WidgetButtonDecoration,         // decoration of button
      RGB            button_color),   // main color of button
   
   phantom // has a relief only when rolled over
     (Int32          width,           // total width of button
      Int32          height,          // total height of button
      WidgetButtonDecoration,         // decoration of button
      RGB button_color).              // main color of button
   
   Typically, 'link'  buttons are used for  making hypertext links,  'phantom' buttons are
   used for making menu items.
   

   *** (7) Inhibition and blocking behavior. 
   
   A button may be  temporarily inhibited. When a button is inhibited,  it does not react,
   and has a  special 'inhibited' aspect.  The  action executed by the button  may also be
   blocking or non bloking. If it is,  nothing happens in the host window until the action
   has finished. Otherwise, the action is  executed in a separate virtual machine, and the
   widgets in the host window continue to work. 
   
public type WidgetButtonBehavior:
   blocking,        // execution of action will block other widgets in this host window
   non_blocking,    // execution of action will not block other widgets in this host window
   inhibited.       // action is not executed

   
   
   *** (8) Creating a button. 
   
   A button is created by:   

public define Widget
   button
     (
       One -> WidgetButtonStyle          style,         // style of drawing for the button
       One -> WidgetButtonBehavior       behavior,      // getting the behavior
       One -> One                        action,        // action performed by the button
       List(WidgetButtonRegistration)    registrations  // variables to be monitored 
     ). 

   Below is a variant for the case the action needs the current event tool box. 
   
public define Widget
   button
     (
       One -> WidgetButtonStyle          style,         // style of drawing for the button
       One -> WidgetButtonBehavior       behavior,      // getting the behavior
       WidgetEventToolBox -> One         action,        // action performed by the button
       List(WidgetButtonRegistration)    registrations  // variables to be monitored 
     ). 

   
   
   --- That's all for the public part ! --------------------------------------------------
   

   
   
   
   
   --------------------------- Table of Contents -----------------------------------------
   
   *** [1] Tools. 
      *** [1.1] Minor state. 
      *** [1.2] Managing registrations. 
   *** [2] Drawing the button. 
      *** [2.1] Drawing the 'text' part of the decoration. 
      *** [2.2] Drawing the whole decoration. 
      *** [2.3] Drawing a 'nude' button. 
      *** [2.4] Drawing a 'push down' button. 
      *** [2.5] Drawing a 'phantom' button. 
      *** [2.5] Drawing the whole button. 
   *** [3] Handling events. 
      *** [3.1] Handling 'mouse_move' events. 
      *** [3.2] Handling 'mouse_click' events. 
      *** [3.3] Handling 'mouse_gone' events. 
      *** [3.4] Handling 'changed' events. 
      *** [3.5] The event handler. 
   *** [4] Creating the 'button' widget.
   
   ---------------------------------------------------------------------------------------
   

    
   *** [1] Tools. 
   
   
      *** [1.1] Minor state. 
   
   Above we  have discussed a notion  of state for a  button. This notion  arises from the
   fact  that  the button's  action  and  decoration may  depend  on  the  values of  some
   variables. This will be called the 'major state' of the button. 
   
   Now, the button has another sort of state, the 'minor state', described by:
   
type MinorState:   
   up,                  // the mouse cursor is not on the button
   rolled_over,         // the mouse cursor is on the button, which is still up
   down.                // the button is down (has been left clicked)
   
   
   
      *** [1.2] Managing registrations. 
   
public type WidgetButtonRegistration:
   breg(Int32                 id,         // id of variable
        WidgetRegistration    wreg).      // registration for the widget system
   
   
define WidgetButtonRegistration
   register
     (
       Var($T)    v
     ) =
   breg(var_id(v),register(v)). 
   

   
define (List(Int32),List(WidgetRegistration))
   separate
     (
       List(WidgetButtonRegistration) l
     ) =
   if l is 
     {
       [ ] then ([ ],[ ]), 
       [h . t] then 
         if h is breg(id_1,regis_1) then 
         if separate(t) is (other_ids,other_regis) then 
           ([id_1 . other_ids],[regis_1 . other_regis])
     }. 
   

   
define One -> (Int32,Int32)
   get_size
     (
       One -> WidgetButtonStyle   style
     ) =
   (One u) |-> if style(unique) is 
                 {
                   link(t,f,_,_) then 
                     with info = get_font_info(f), 
                             h = int8_to_int32(height(info)),
                             d = int8_to_int32(depth(info)), 
                             w = printed_text_width(f,t), 
                       (w,h+d), 
                   push_down(w,h,_,_) then (w,h)
                   phantom(w,h,_,_) then (w,h)
                 }. 
   
   
   
   *** [2] Drawing the button. 
   
   Drawing the  button depends on the  style of the  button (nude, push down,...)   on the
   nature of the decoration (text, image,...) and  on its minor state.  We have a function
   for drawing the decoration, and an auxiliary functions for each style of button.
   
   
   
      *** [2.1] Drawing the 'text' part of the decoration. 
   
   The function  belows draws the text  part of the  decoration of the button  at position
   '(x,y)'  where 'x'  is  given  and 'y'  is  computed so  that  the  text is  vertically
   centered. If the button is inhibited, the text appear as 'hollow'.
   
define One
   draw_text
     (
       WidgetDrawToolBox   dtb, 
       String              t,
       SystemFont          font, 
       Bool                inhibited, 
       RGB                 button_color, 
       RGB                 text_color, 
       Int32               button_width, 
       Int32               button_height,
       Int32               font_height, 
       Int32               x,
       Int32               th,
       WidgetRectangle     clip
     ) =
   with    dark_color = darken(button_color), 
          light_color = lighten(button_color), 
                    y = (Int32)(font_height+((button_height-th)/2)), 
   draw(dtb)
     (t,
      font,
      if inhibited then dark_color else text_color,
      x,y, 
      clip);
   if inhibited
   then draw(dtb)(t,
                  font,
                  light_color,
                  x+1,y+1, 
                  clip)
   else unique. 
   
   
   
      *** [2.2] Drawing the whole decoration. 
   
define One
   draw_decoration
     (
       WidgetDrawToolBox      dtb,    
       WidgetButtonDecoration       decoration,
       Bool                   inhibited, 
       RGB                    button_color, 
       Int32                  button_width,
       Int32                  button_height,
       WidgetRectangle        clip            // clipping rectangle for decoration
     ) =
   if decoration is 
     {
       center_text(t,font,text_color) then 
         with      info = get_font_info(font),
            font_height = int8_to_int32(height(info)), 
                     th = font_height+int8_to_int32(depth(info)), 
                     tw = printed_text_width(font,t), 
         draw_text(dtb,t,font,inhibited,
                   button_color,text_color,
                   button_width,button_height,font_height,
                   (button_width-tw)/2,th,clip),   
           
       left_text(margin,t,font,text_color) then 
         with      info = get_font_info(font),
            font_height = int8_to_int32(height(info)), 
                     th = font_height+int8_to_int32(depth(info)), 
                     tw = printed_text_width(font,t), 
         draw_text(dtb,t,font,inhibited,
                   button_color,text_color,
                   button_width,button_height,font_height,
                   margin,th,clip),
   
       center_image(i) then 
         if size(i) is (iw,ih) then
         draw(dtb)(i,
                   (button_width-iw)/2,
                   (button_height-ih)/2,
                   clip), 
   
       left_image(margin,i) then 
         if size(i) is (iw,ih) then
         draw(dtb)(i,
                   margin,
                   (button_height-ih)/2,
                   clip), 
   
       center_image_and_text(i,glue,t,font,text_color) then 
         if size(i) is (iw,ih) then
         with      info = get_font_info(font),
            font_height = int8_to_int32(height(info)), 
                     th = font_height+int8_to_int32(depth(info)), 
                     tw = printed_text_width(font,t), 
                    itw = iw+glue+tw,
         draw(dtb)(i,
                   (button_width-itw)/2,
                   (button_height-ih)/2,
                   clip);
            draw_text(dtb,t,font,inhibited,
                      button_color,text_color,
                      button_width,button_height,font_height,
                      ((button_width-itw)/2)+glue+iw,th,clip),

       left_image_and_text(margin,i,glue,t,font,text_color) then 
         if size(i) is (iw,ih) then
         with      info = get_font_info(font),
            font_height = int8_to_int32(height(info)), 
                     th = font_height+int8_to_int32(depth(info)), 
                     tw = printed_text_width(font,t), 
                    itw = iw+glue+tw,
         draw(dtb)(i,
                   margin,
                   (button_height-ih)/2,
                   clip);
            draw_text(dtb,t,font,inhibited,
                      button_color,text_color,
                      button_width,button_height,font_height,
                      margin+iw+glue,th,clip),              
     }.
   
   
   
      *** [2.3] Drawing a 'nude' button. 
   
   Only the decoration has to be drawn. 
   
define One
   draw_link_button
     (
       WidgetDrawToolBox          dtb, 
       String                       t,
       SystemFont                font,
       RGB                  off_color,
       RGB                   on_color,
       MinorState              mstate,
     ) =
   with info = get_font_info(font), 
           w = printed_text_width(font,t),
           h = int8_to_int32(height(info)), 
   (if mstate is up 
    then unique
    else draw(dtb)(rect(0,h+1,w,h+2),on_color));
   draw(dtb)(t,
             font,
             if mstate is up then off_color else on_color,
             0, 
             h).
   
   
   
      *** [2.4] Drawing a 'push down' button. 
   
define One   
   draw_push_down_button  
     (
       WidgetDrawToolBox        dtb,
       Int32                    width,   // of button
       Int32                    height,
       RGB                      button_color,
       MinorState               mstate,
       WidgetButtonDecoration   decoration,
       Bool                     inhibited
     ) =
   draw(dtb)(rect(2,2,width-2,height-2),button_color);
   with       black = rgb(0,0,0), 
        light_color = lighten(button_color), 
         dark_color = darken(button_color), 
     draw_relief_edge(dtb,1,rect(0,0,width,height),black,black); 
   if mstate is 
     {
       up then 
         draw_relief_edge(dtb,1,rect(1,1,width-1,height-1),light_color,dark_color),
   
       rolled_over then 
         draw_relief_edge(dtb,1,rect(1,1,width-1,height-1),light_color,dark_color),
   
       down then 
         draw_relief_edge(dtb,1,rect(1,1,width-1,height-1),dark_color,dark_color)
     };
   draw_decoration(dtb,decoration,inhibited,
                   button_color,
                   width,height,rect(3,3,width-3,height-3)). 
   
   
   
   
   
      *** [2.5] Drawing a 'phantom' button. 
   
define One   
   draw_phantom_button    
     (
       WidgetDrawToolBox         dtb,
       Int32                   width,
       Int32                  height,
       RGB              button_color,
       MinorState             mstate,
       WidgetButtonDecoration   decoration,
       Bool                inhibited
     ) =
   //draw(dtb)(rect(0,0,width,height),button_color); 
   with   light_color = lighten(button_color), 
           dark_color = darken(button_color), 
   if mstate is 
     {
       up then 
         unique, 
   
       rolled_over then 
         draw_relief_edge(dtb,1,rect(0,0,width,height),light_color,dark_color),
   
       down then 
         draw_hollow_edge(dtb,1,rect(0,0,width,height),light_color,dark_color),   
     };
   draw_decoration(dtb,decoration,inhibited,
                   button_color,
                   width,height,rect(3,3,width-3,height-3)). 
   
   
   
   
   
      *** [2.5] Drawing the whole button. 
   
define One
   draw_button
     (
       One -> WidgetButtonStyle     style, 
       WidgetDrawToolBox            dtb,
       MinorState                   mstate,
       Bool                         inhibited
     ) =
   if style(unique) is 
     {
       link(t,font,off_c,on_c) then 
         draw_link_button(dtb,t,font,off_c,on_c,mstate), 
   
       push_down(width,height,decoration,button_color) then 
         draw_push_down_button(dtb,
                               width,height,
                               button_color,
                               mstate,
                               decoration,inhibited),
   
       phantom(width,height,decoration,button_color) then 
         draw_phantom_button(dtb,
                             width,height,
                             button_color,
                             mstate,
                             decoration,inhibited)
     }. 
   
   
   


   
   *** [3] Handling events. 
   
   
   
      *** [3.1] Handling 'mouse_move' events. 
   
   When the mouse is  not captured, and the mouse pointer is  rolling over the button, the
   minor state becomes 'rolled_over'.
   
define WidgetAnswer
   handle_mouse_move
     (
       WidgetEventToolBox    etb, 
       Int32                 width, 
       Int32                 height, 
       Var(MinorState)       mstate_v,
       KeyboardState         ks
     ) =
   if *mstate_v is rolled_over
   then ignored
   else mstate_v <- rolled_over; 
        handled(area(etb)([rect(0,0,width,height)])). 
   
     
   
      *** [3.2] Handling 'mouse_click' events. 
   
   When the button is  up and left clicked, the minor state becomes  'down'. If it is down
   and  the left  button of  the mouse  is released,  it becomes  'up' and  the  action is
   executed.
   
define WidgetAnswer
   handle_mouse_click
     (
       WidgetEventToolBox            etb, 
       Int32                         width, 
       Int32                         height, 
       Var(MinorState)               mstate_v, 
       KeyboardState                 ks, 
       MouseClick                    mc,
       WidgetEventToolBox -> One     action,
       One -> WidgetButtonBehavior   behavior
     ) =
   if mc is 
     {   
       left_down    then if *mstate_v is down
                         then ignored
                         else mstate_v <- down; 
                              handled(area(etb)([rect(0,0,width,height)])), 
   
       left_up      then if *mstate_v is down
                         then mstate_v <- rolled_over; 
                              if behavior(unique) is
                                {
                                  blocking     then action(etb), 
                                  non_blocking then delegate action(etb), unique, 
                                  inhibited    then alert
                                };
                              handled(area(etb)([rect(0,0,width,height)]))
                         else ignored, 
   
       middle_down  then ignored,
       middle_up    then ignored,
       right_down   then ignored,
       right_up     then ignored
     }. 
   
   
      *** [3.3] Handling 'mouse_gone' events. 
   
   If the button is either 'down' or 'rolled_over', it becomes 'up'. 
   
define WidgetAnswer
   handle_mouse_gone
     (
       WidgetEventToolBox   etb, 
       Var(MinorState)      mstate_v,
       Int32                width, 
       Int32                height
     ) =
   mstate_v <- up; 
   handled(area(etb)([rect(0,0,width,height)])).
   
   
   if *mstate_v is 
     {
       up           then ignored, 
       rolled_over  then mstate_v <- up; 
                         handled(area(etb)([rect(0,0,width,height)])),
       down         then mstate_v <- up; 
                         handled(area(etb)([rect(0,0,width,height)]))
     }. 
   
   
      *** [3.4] Handling 'changed' events. 
   
   
define WidgetAnswer
   handle_changed
     (
       WidgetEventToolBox            etb, 
       Var(MinorState)               mstate_v,
       Int32                         width, 
       Int32                         height,
       One -> WidgetButtonStyle      style, 
       List(Int32)                   l,
       List(Int32)                   my_var_ids
     ) =
   if intersect(l,my_var_ids)
   then if style(unique) is link(_,_,_,_)
        then resized
        else handled(area(etb)([rect(0,0,width,height)]))
   else ignored. 
   
   
      *** [3.5] The event handler. 
   
define (WidgetEventToolBox,WidgetEvent) -> WidgetAnswer
   event_handler
     (
       Var(MinorState)               mstate_v, 
       WidgetEventToolBox -> One     action,
       One -> WidgetButtonBehavior   behavior,
       One -> WidgetButtonStyle      style, 
       List(Int32)                   my_var_ids
     ) =
   (WidgetEventToolBox etb, WidgetEvent e) |->
   if get_size(style)(unique) is (width,height) then 
     if behavior(unique) is inhibited then ignored else
     if e is
       {
         mouse_move(ks,x,y)          then handle_mouse_move(etb,width,height,mstate_v,ks),  
         mouse_click(ks,mc,x,y)      then handle_mouse_click(etb,width,height,mstate_v,
                                                             ks,mc,action,behavior), 
         mouse_wheel(ks,d,x,y)       then ignored, 
         mouse_gone                  then handle_mouse_gone(etb,mstate_v,width,height), 
         captured_mouse_move(f)      then ignored, 
         captured_mouse_liberated(f) then ignored
         key_down(f)                 then ignored, 
         keyboard_recaptured(f)      then ignored, 
         changed(l)                  then handle_changed(etb,mstate_v,width,height,style,l,my_var_ids)
       }. 
   
   
   
   
   *** [4] Creating the 'button' widget.
   
public define Widget
   button
     (
       One -> WidgetButtonStyle          style,         // style of drawing for the button
       One -> WidgetButtonBehavior       behavior,      // getting the behavior
       WidgetEventToolBox -> One         action,        // action performed by the button
       List(WidgetButtonRegistration)    registrations  // list of variables monitored 
                                                        //   by the button
     ) = 
   with     mstate_v = var((MinorState)up), 
   
   if separate(registrations) is (my_var_ids,wregs) then 
   
   create_widget
     (
       /* get size */ 
       get_size(style), 
   
       /* redraw */ 
       (WidgetDrawToolBox dtb) |-> 
          draw_button(style,dtb,
                      *mstate_v,
                      behavior(unique) = inhibited),
   
       /* handle events */ 
       event_handler(mstate_v,action,behavior,style,my_var_ids), 
    
       /* register variables */ 
       (One u) |-> wregs
     ). 
   
   
public define Widget
   button
     (
       One -> WidgetButtonStyle          style,         // style of drawing for the button
       One -> WidgetButtonBehavior       behavior,      // getting the behavior
       One -> One                        action,        // action performed by the button
       List(WidgetButtonRegistration)    registrations  // variables to be monitored 
     ) =
   button(style,behavior,
          (WidgetEventToolBox etb) |-> action(unique),
          registrations).