Anubis / Anubis

                                  The Anubis Project. 
   
                             A Widget System (4th version). 
                                 Creating new widgets. 
   
                            Copyright (c) Alain Proute' 2005. 
   
   
   Authors: Alain Proute'
   
   
   
   This file is the  entry point of this widget system if you want  to create new sorts of
   widgets.  If   you  just  want   to  use  already   existing  widgets,  see   the  file
   'widgets4/host_window.anubis' instead.
   
   
   
   ------------------------------------ Table of Contents --------------------------------
   
   *** (1) How widgets are working. 
   
   *** (2) Geometry. 
      *** (2.1) Absolute and relative coordinates. 
      *** (2.2) Absolute and relative rectangles. 
      *** (2.3) Widgets are rectangular. 
   
   *** (3) Drawing. 
      *** (3.1) The draw tool box. 
      *** (3.2) The 'draw method'. 
      *** (3.3) Drawing tools. 
         *** (3.3.1) Drawing a child widget. 
         *** (3.3.2) Drawing rectangles.
         *** (3.3.3) Drawing images.
         *** (3.3.4) Drawing character strings.
   
   *** (4) Handling events. 
      *** (4.1) Classification of events.
         *** (4.1.1) 'mouse_move', 'mouse_click' and 'mouse_wheel'. 
         *** (4.1.2) 'mouse_gone'. 
         *** (4.1.3) 'captured_mouse_move' and 'captured_mouse_liberated'. 
         *** (4.1.4) 'key_down' and 'keyboard_recaptured'. 
         *** (4.1.5) 'changed'.
         *** (4.1.6) 'could_drop' and 'want_to_drop'. 
      *** (4.2) Classification of answers. 
         *** (4.2.1) 'not_handled' and 'handled'. 
         *** (4.2.2) 'resized'. 
         *** (4.2.3) 'want_to_capture_mouse' and 'want_to_capture_keyboard'. 
      *** (4.3) Transmitting events to childs. 
      *** (4.4) Manipulating areas. 
         *** (4.4.1) Creating areas. 
         *** (4.4.2) Getting the rectangles from an area.
         *** (4.4.3) Making the union of two areas. 
         *** (4.4.4) Transmitting areas between widgets. 
         *** (4.4.5) Special actions. 
   
   *** (5) Monitoring dynamic variables. 
   
   *** (6) Stretching. 
   
   *** (7) Creating your widget.
   
   ---------------------------------------------------------------------------------------
   
   
   *** (1) How widgets are working. 
   
   A widget is  an 'object' (in the sens  of the Object Oriented Methodology)  by its very
   nature.   This essentially  means that  a widget  has an  internal state,  and contains
   methods (which are functions, more  precisely 'commands', because their execution is in
   general non deterministic).
   
   A widget may have  'child' widgets, so that widgets are organized  in tree form. When a
   host window  is opened, it receives  a widget which  is called the 'root'  widget. This
   widget may  have childs which may  themself have childs,  and so on. Hence,  the window
   always contains a tree or hierarchy of widgets.
   
   Widgets have two main  methods: the 'draw method' and the 'event  handler'. The role of
   the first one is to redraw the widget on  the screen, and the role of the second one is
   to handle events. Each widget is responsible of its own childs. When a widget receive a
   redraw order,  i.e. when  the draw  method of this  widget is  called, the  widget must
   redraw itself and also call the draw  methods of its childs.  Similarily, when a widget
   receives an event, it has the responsability  to decide if it should transmit the event
   to its childs or not.
   
   It is  important to  understand that  theses two methods  are completely  disjoint. The
   widget system transmits an event (mouse  event, keyboard event and other events) to the
   root widget  which eventually transmits it  to its childs  and so on. Each  widget must
   decide if the  event has been handled or not  (by itself or by one  of its childs), and
   must return  an answer.  The  widget may  have to combine  the answers returned  by its
   childs  in order  to  make its  own  answer. Handling  an event  does  not produce  any
   redrawing,  but  the  answer contains  informations  on  the  area  which needs  to  be
   redrawn. When the widget system receives  this answer (i.e. when the root widget itself
   returns its own answer), it optimizes this area into a union of disjoint rectangles and
   calls  the draw  method of  the root  widget with  this area  as one  of  the arguments
   (actually, if the  double buffer does not  cover the whole window, the  draw methods is
   called several  times, with the  double buffer at  different positions relative  to the
   window).
   
   Despite the  fact that widgets are  objects, their position  in the host window  is not
   part of their internal state. When a widget  needs to redraw a child widget, it calls a
   method which takes the relative position of the child widget (relative to itself) as an
   argument.  The same  is true for the  transmission of events.  Hence, a  widget has the
   responsability to know the positions of its childs relative to itself. If getting these
   positions requires heavy computation, the widget may store them into dynamic variables,
   but in this case, the widget also  has the responsability of keeping these variables up
   to date.
   
   Another  consequence of the  fact that  the position  of a  widget is  not part  of its
   internal state, is that widgets are  'ubiquitous'.  This means that the same widget may
   appear  at several  different  positions in  a host  window  or even  in distinct  host
   windows.   In order  to preserve  this  property, you  should never  violate the  rules
   explained below, in particular concerning absolute and relative coordinates.
   
   An  important  feature  is  the  possibility  of capturing  either  the  mouse  or  the
   keyboard. For  example, when a 'text input'  widget is clicked upon,  it should capture
   the  keyboard. To  that  end, the  widget creates  a  'capture ticket'  and returns  an
   appropriate 'keyboard  capture' answer, containing  this ticket.  The widget  must also
   keep the  ticket.  Later, when  a keyboard event  arrives, the widget  system transmits
   this event  in the form of  a function taking this  ticket as an  argument. Each widget
   which is supposed to be able to capture the keyboard, should apply this function to the
   ticket it has created. The function  returns either 'failure' if the ticket is invalid,
   or 'success(e)' if it is valid, where 'e' is the actual captured event. This event must
   be handled, and an answer must be returned, which will eventually induce a redrawing.

   The size (width,height) of a widget  is normally determined by the widget itself, maybe
   using  the sizes  of  its child  widgets.  However,  a  request to  stretch the  widget
   vertically  and/or horizontally  may  arise when  the  host window  is  resized by  the
   user. Each widget has its own stretching  strategy. In any case, it has a method giving
   its stretching  capabilities, i.e.  its minimal  and maximal width  and height. Another
   method asks the widget to stretch itself to some given size.
   
   
   
   
   *** (2) Geometry. 
   
   
      *** (2.1) Absolute and relative coordinates. 
   
   We use two  sorts of coordinates: absolute cordinates, which refer  to the host window,
   and relative  coordinates which refer to a  particular widget. In this  file, you learn
   how to  create a new  widget. This  widget will be  called 'your widget',  and relative
   coordinates are always relative to your widget.
   
   The 'x' coordinate grows  from left to right, and the 'y'  coordinate grows from top to
   bottom (the unit of mesure is the pixel):
   
   
      +------------------------> x
      |
      |
      |
      |
      |
      |
      |
      |
      V
      y

   
   The  leftmost-topmost pixel  of  the (client  part  of the)  host  window has  absolute
   coordinates (0,0). The  leftmost-topmost pixel of your widget  has relative coordinates
   (0,0). You don't  have to worry about  absolute coordinates. All the tools  you have to
   provide or  use for creating a  new widget use  coordinates which are relative  to your
   widget.
   
   
   
      *** (2.2) Absolute and relative rectangles. 
   
   As  for coordinates,  rectangles are  of two  sorts: absolute  rectangles  and relative
   rectangles.  Absolute  rectangles are  represented by the  type 'Rectangle'  defined in
   'predefined.anubis'.  Relative   rectangles  (i.e.    relative  to  your   widget)  are
   represented by the type:
   
public type WidgetRectangle:
   rect(Word32    x, 
        Word32    y, 
        Word32    u,
        Word32    v). 
   
   
   A  point   of  relative   coordinates  '(a,b)'  belongs   to  the   relative  rectangle
   'rect(x,y,u,v)' if and only if:
   
                                 x -=< a -< u   &   y -=< b -< v
   
   
   
   
      *** (2.3) Widgets are rectangular. 
   
   Widgets are rectangular.  Hence,  each widget has a width and a  height (which may vary
   during the lifetime of the widget). When a  widget of width 'w' and height 'h' is drawn
   at  some position  '(x,y)' in  the host  window, the  drawing is  performed  within the
   absolute rectangle:
   
                                     rect(x,y,x+w,y+h)
   
   Equivalently,  if  this widget  has  relative  coordinates  '(a,b)' (relative  to  your
   widget), the drawing occurs in  the relative rectangle 'rect(a,b,a+w,b+h)' (relative to
   your widget).
   
   As already mentioned,  your widget must know the relative positions  of its childs. The
   computation  of these  positions  will  in most  cases  make use  of  the  size of  the
   childs. To that end, this system provides a tool for getting the size (width,height) of
   a child widget:
   
public type Widget:...
   
public define (Word32,Word32)    // (width,height)
   size
     (
       Widget w
     ). 
   
   Note: 'Widget' is an opaque type. 
   
   

   *** (3) Drawing. 
   
      *** (3.1) The draw tool box. 
   
   Your widget must be able to redraw itself. This means that when you create your widget,
   you provide  a 'draw method'. When  it is called,  this method receives an  argument of
   type:
   
public type WidgetDrawToolBox:...
   
   This  is an  opaque  type. Data  of this  type  are used  to  hide all  the details  of
   conversions between  absolute and relative  coordinates, and several other  things that
   you don't need to manipulate directly.
   
   
   
      *** (3.2) The 'draw method'. 
   
   The draw method of your widget is a function of type:
   
                                 WidgetDrawToolBox -> One
   
   This means that when your widget receives  the order to redraw itself, it also receives
   an appropriate draw  tool box. A set of  tools are provided in this draw  tool box. All
   these tools have the same name: 'draw'. They are distinguished by their type. 
   
   So for example, if  the draw tool box is 'dtb', you can draw  a pink rectangle of width
   100 pixel and  height 20 pixels at  relative position (10,10) in your  widget, with the
   following command:
   
                             draw(dtb)(rect(10,10,110,30),pink)
   
   (which returns 'unique' of type 'One'). 
   
   There are similar  tools for drawing child widgets, images  and character strings. Here
   they are.
   
   
   
      *** (3.3) Drawing tools. 
   
   Now we  describe the tools that  you can use in  order to construct the  draw method of
   your widget.  All  these tools have the  same name: 'draw', and they  must be extracted
   from the draw tool box as follows:
   
                                             draw(dtb)
   
   if 'dtb' is the name of the draw tool box. 
   
   
   
         *** (3.3.1) Drawing a child widget. 
   
   When it is asked to redraw itself, your widget must also redraw its childs (if any). To
   redraw a child at a given relative position, use the following tool:
   
public define (Widget child, Word32 x, Word32 y) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ). 
   
   For example,  in order to redraw  the child 'c'  at position '(x,y)' (relative  to your
   widget), you must execute:
   
                                        draw(dtb)(c,x,y)
   
   You may also want to redraw only part of a child. This is clearly needed by the 'simple
   window' widget for example.
   
public define (Widget child, Word32 x, Word32 y, WidgetRectangle clip) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ). 
   
   The part to be redrawn may also be a union of rectangles:
   
public define (Widget child, Word32 x, Word32 y, List(WidgetRectangle) clip) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ). 
   
   
      
         *** (3.3.2) Drawing rectangles.
   
   If you want to draw a colored rectangle in your widget, use the following tool:
   
public define (WidgetRectangle,RGB) -> One   
   draw 
     (
       WidgetDrawToolBox dtb
     ). 
   
   For example, write:
   
                         draw(dtb)(rect(10,10,20,20),rgb(0,0,0))

   for drawing  a black  square 10 pixels  wide at  position (10,10). The  coordinates are
   relative to your widget as usual.
   
   
   
   
         *** (3.3.3) Drawing images.
   
   If you want to draw an image into your widget, use the following tool:
   
public define (HostImage, Word32 x, Word32 y) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ). 
   
   
   For example, 
   
                                       draw(dtb)(image,x,y)
   
   where 'image' is of type 'HostImage', where and 'x' and 'y' are of type Word32 will draw
   the image at  position (x,y) in your widget.  This means that the upper  left corner of
   the image will be drawn at (x,y). As usual, coordinates are relative to your widget. 

   You may also want to clip the image  before drawing it. In this case, use the following
   variant:
   
public define (HostImage, Word32 x, Word32 y, WidgetRectangle clip) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ). 
   
   Again the rectangle 'clip' is relative to your widget. 
   
   The same one with a list of rectangles:
   
public define (HostImage, Word32 x, Word32 y, List(WidgetRectangle) clip) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ). 
   
   
   
         *** (3.3.4) Drawing character strings.
   
   If you want to draw a character string into your widget, use the following tool:
   
public define (String s, SystemFont f, RGB c, Word32 x, Word32 y) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ). 
   
   For example the command:
   
                              draw(dtb)("gabuzomeu",f,c,10,10)
   
   will draw  the string "gabuzomeu"  at position (10,10)  in your widget using  the given
   font  'f' and  color 'c'.   Note that  (x,y) represents  the upper  left corner  of the
   drawing. If the height  of the font is 'h', the base point  of the first character will
   be at position (x,y+h).
   
   Notice  also that this  command does  not draw  any background.  Only the  pixels which
   belong to the body of the characters are drawn.
   
   You may also want to clip that drawing. In this case, use the following variant: 
   
public define (String s, SystemFont f, RGB c, Word32 x, Word32 y, 
               WidgetRectangle clip) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ). 
   
   In 'library/widgets4/tools.anubis'  you will find tools  for computing the  size of the
   printed representation of a character string.
   

   
   
   *** (4) Handling events. 
   
   Widgets must also handle events. We will have to use the following types:
   
public type WidgetEventToolBox:...
public type WidgetEvent:...
public type WidgetAnswer:...
   
   The first one is opaque, and  plays a role analogous to 'WidgetDrawToolBox'. The others
   are not opaque, and are discussed below.
   
   The event handler of your widget is a function of type:
   
                        (WidgetEventToolBox, WidgetEvent) -> WidgetAnswer
   
   That your widget 'receives' an event just  means that this function has been called (by
   its father widget, or  by the widget system itself if there is  no father, i.e. if your
   widget is the root widget).
   
   The  answer (of  type 'WidgetAnswer')  gives  informations on  how the  event has  been
   handled, and on which area of the host window should be redrawn as a consequence of the
   event.
   
   
   
      *** (4.1) Classification of events.
   
   The following type describes all the events a widget may have to handle.
   
public type WidgetEvent:
   quit, 
   //
   // 'Normal' mouse events:
   //
   mouse_move                  (KeyboardState ks, Word32 x, Word32 y), 
   mouse_click                 (KeyboardState ks, MouseClick mc, Word32 x, Word32 y), 
   mouse_wheel                 (KeyboardState ks, Word32 delta, Word32 x, Word32 y),
   mouse_gone,
   //
   //  Events generated when the mouse is captured:
   //
   captured_mouse_move         ((Var(One),WidgetEventToolBox) -> Maybe((Word32,Word32))), 
   captured_mouse_liberated    ((Var(One),WidgetEventToolBox) -> Maybe((Word32,Word32))),
   //
   //  Events generated when the keyboard is captured:
   //
   key_down                    ((Var(One)) -> Maybe((KeyboardState,KeyboardKey))),
   keyboard_recaptured         ((Var(One)) -> Bool), 
   //
   //  Events generated when a state variable is reassigned:
   //
   changed                     (List(Word32) l),
   //
   //  Drag and drop events (see 'drag_and_drop.anubis')
   //
   could_drop                  (Word32 mx, Word32 my, Word32 com_var_id, Var(Bool)),   
   want_to_drop                (Word32 mx, Word32 my, Word32 com_var_id).  
   
   The   types   'KeyboardState',   'KeyboardKey'   and  'MouseClick'   are   defined   in
   'predefined.anubis'.
   
   Recall that  your widget must eventually  transmit events to its  childs, and construct
   its answer  depending on  the answers received  from its  childs.  We now  describe the
   meanings of these events.
   
   
   
         *** (4.1.1) 'mouse_move', 'mouse_click' and 'mouse_wheel'. 
   
   A  widget is  concerned by  a 'mouse_move'  or 'mouse_click'  event only  if  the mouse
   pointer lies  inside the rectangle of  the widget. This is  a rule of  this system that
   your  widget  must  respect.   Hence,  when  your widget  receives  a  'mouse_move'  or
   'mouse_click' event, you may rely on  the hypothesis that the mouse pointer lies inside
   the rectangle of your widget.
   
   As  a consequence,  if your  widget has  one or  several childs,  it should  in general
   transmit  such events  to a  given child  only  if the  mouse pointer  lies within  the
   rectangle  of this child.   However, you  don't have  to worry  about that  in general,
   because the  widget system  checks this condition  before allowing the  transmission of
   'mouse_move'  and 'mouse_click'  events.  Hence,  you  may either  check the  condition
   yourself, or just  transmit such events to all childs.  Nevertheless, there are widgets
   which need to check  this condition, as for example the desktop  widget, because it may
   have  several childs whose  rectangles overlap.  The desktop  widget must  decide which
   child should  receive the event (using the  z-order), because the widget  system is not
   able to do it since it does not know anything about the z-order.
   
   Notice that if  the widget system blocks the  transmission of such an event  to a given
   child, it replaces it by a 'mouse_gone' event.
   
   
   
         *** (4.1.2) 'mouse_gone'. 

   If your  widget receives a  'mouse_gone' event, you  can deduce that the  mouse pointer
   does not  lie within the rectangle  of your widget. This  may be useful  for example to
   change the visual aspect of the widget when the mouse pointer is leaving the widget.
   
   Now, if  your widget has  child widgets, it  is responsible of  generating 'mouse_gone'
   event for its childs. Your widget must send at least one 'mouse_gone' event to a child,
   if the mouse pointer was within the rectangle  of the child at the time of the previous
   mouse event, and if this condition is no more true.  Hence, your widget must eventually
   keep that  information that  some child  contains the mouse  pointer in  some variable.
   This variable  may be for  example of type  'Maybe(Widget)'. If it  contains 'failure',
   this means that  no child contains the mouse pointer. If  it contains 'success(c)' this
   means that the child 'c' contains the mouse pointer. While you keep this variable up to
   date, you must also generate appropriate 'mouse_gone' events for your childs.
   
   Generating extra  'mouse_gone' events  (i.e. sending several  'mouse_gone' events  to a
   child  consecutively) is of  course a  waste of  time.  Nevertheless,  it has  no other
   inconvenient.   Also remember that  the system  replace 'mouse_move'  and 'mouse_click'
   events by 'mouse_gone'  events if they are transmitted to widgets  which do not contain
   the mouse pointer. This fact may simplify  the programming of the event handler of your
   widget.
   
   
  
         *** (4.1.3) 'captured_mouse_move' and 'captured_mouse_liberated'. 

   If your  widget has  captured the  mouse (how to  capture the  mouse will  be explained
   later),  it may  receive 'captured_mouse_move'  and  'captured_mouse_liberated' events.
   Such events are  not submitted to the same rules as  the 'mouse_move' and 'mouse_click'
   events.
   
   Your widget captured  the mouse using a  'ticket', which is a dynamic  variable of type
   'Var(One)'. When  a 'captured_mouse_move' or  'captured_mouse_liberated' event arrives,
   what you get is just a function taking such a ticket as an argument. The only thing you
   can do with this event is to apply the function to your ticket.
   
   If  the result  is 'failure',  this means  that your  widget is  not concerned  by this
   event. Actually, this  also implies that the capture your widget  initiated is over. If
   the result is 'success(p)', this means that  your widget is concerned by the event (the
   capture is still valid), and that 'p'  is the pair of coordinates for the mouse pointer
   (relative to your widget as usual).
   
   If your  widget is  not concerned  by such  an event, it  must transmit  it to  all its
   childs.
    
   
         *** (4.1.4) 'key_down' and 'keyboard_recaptured'. 
   
   This event works like  'captured_mouse_move' and 'captured_mouse_liberated' events. You
   must apply  the function to your  ticket in order to  know if you are  concerned by the
   event. If it  is the case you get  the keyboard state and the character  which has been
   entered.
   
   The   event  'keyboard_recaptured(f)'   means   that  the   keyboard   has  just   been
   recaptured. Your widget must apply 'f' to  its own ticket. If the result is 'true' your
   widget still has the keyboard. If it is 'false', your widget loosed the keyboard. 
   
   If your widget  is not concerned by one of  these event it must transmit  it to all its
   childs.
   
      
   
   
         *** (4.1.5) 'changed'.
   
   This event  is generated by the widget  system when dynamic variables  registred at the
   widget system are reassigned. See below for more explanations.
   
   
   
         *** (4.1.6) 'could_drop' and 'want_to_drop'. 
   
   These  events are  generated when  a widget  has given  something to  a 'drag  and drop
   manager' (generally after the user has  left clicked on some dragable thing). While the
   user keeps the left button of the mouse down, only 'could_drop' events are generated. A
   'want_to_drop' event is generated when the mouse button is released.
   
   These  events contain  the  coordinates of  the mouse,  the  id of  a dynamic  variable
   (containing  the thing  to be  dropped). Furthermore,  'could_drop' contains  a dynamic
   variable of type 'Bool'. This variable must be set by the widget handling the event. It
   must be set to 'false' if the  widget cannot accept dropping at the given position, and
   to 'true' if it can accept the dropping.  This may be used by the drag and drop manager
   for  informing the  user graphically  of  the possibility  of dropping  at the  current
   position.
   
   If  your widget  accepts the  dropping, it  gets the  dropped object  from  the dynamic
   variable whose id is given by the event. In this case, your widget knows this variable,
   because  it  received it  at  its  creation.   See 'drag_and_drop.anubis'  for  further
   information.
   
   
   
      *** (4.2) Classification of answers. 
   
   When a  widget receives an  event, it may  handle or not handle  the event, but  in all
   cases it must return  an answer.  An answer may contain an  'area' which represents the
   part of the host window which needs to be redrawn. Areas are represented as follows:
   
public type WidgetArea:...   
   
   We will give later several tools for manipulating areas.
   
   WidgetArea is a  opaque type, because we want to hide  all conversions between absolute
   and relative  coordinates.  As far as  you are concerned, you  manipulate only relative
   coordinates (and relative rectangles).
 
public type WidgetEventCompression:...   
   
   Answers are the following:
   
public type WidgetAnswer:
   not_handled               (WidgetArea), 
   handled                   (WidgetArea),
   resized, 
   ignored, 
   want_to_capture_mouse     (Var(One),
                              WidgetEventCompression,
                              WidgetArea), 
   want_to_capture_keyboard  (Var(One),
                              WidgetArea). 
   
   
   Now, we discuss the meaning of these answers.
   
   
  
         *** (4.2.1) 'not_handled' and 'handled'. 
   
   If your  widget handles  the event,  it should normally  return a  'handled(a)' answer,
   where 'a' is  the area within which redrawing must  occur.  'not_handled(a)' is similar
   but means that your widget did not handle the event. Nevertheless, even if the event is
   not handled, the redrawing of several rectangles may be needed.
   
   If your widget transmitted the event to one or several childs, it receives answers from
   these childs, and must  construct its own answer to be returned  to its father. How the
   answer of your widget  is constructed from the answers returned by  the childs may vary
   depending on the  behavior of your widget.  This is actually a central  point of widget
   programming and you should pay much attention to it.  Nevertheless, there is no special
   rule for this. This is up to you.
   
   
   
         *** (4.2.2) 'resized'. 
   
   This answer means that the event has been handled, and that it induced a change of size
   of the widget. If your widget receives such  an answer from one of its childs, it knows
   that the size of a childs has changed. This may induce a change of size of your widget,
   but not necessarily. For example, the size of the 'window' widget is independent of the
   size of its content.
   
   
   
   
         *** (4.2.3) 'want_to_capture_mouse' and 'want_to_capture_keyboard'. 
   
   Your widget must return one of these answers if it wants to capture either the mouse or
   the keyboard.   
   
   This  answer  requires  a component  of  type  'Var(One)'  that  we call  the  'capture
   ticket'. Your widget may either create a new such ticket at each capture, or use always
   the same one (for example, it may be  created before the creation of your widget and be
   accessible to the event handler). However, distinct widgets must use distinct tickets.
   
   'want_to_capture_mouse'  also requires  an event  compression mode.  The modes  are the
   following:
   
public type WidgetEventCompression:
   compress,            // mouse move events are compressed
   dont_compress.       // no compression at all
   
   In  normal usage,  you should  choose  'compress'. However,  there are  cases in  which
   'dont_compress'  is  better. For  example,  the  'paint_area'  widget produces  a  more
   continuous painting if there is no event compression is used. 
   
   This answer also contains an area, within which redrawing will occur. 
   
   The  widget  system  generates  'captured_mouse_move',  'captured_mouse_liberated'  and
   'key_down' events which are able to recognize your ticket.
   
   These two answers also contain the area within which redrawing must occur.
   
   
   
   
      *** (4.3) Transmitting events to childs. 
   
   Events are transmitted to childs using a tool extracted from the event tool box:
   
public define (Widget child, Word32 x, Word32 y, WidgetEvent) -> WidgetAnswer   
   transmit
     (
       WidgetEventToolBox etb
     ). 
   
   If your event tool box is 'etb', and if you want to transmit the event 'e' to the child
   'c', whose position relative to your widget is '(x,y)', use the following:
   
                                        transmit(etb)(c,x,y,e)
   
   The returned value is the answer of the child. 
   
   When you transmit a  mouse event to a child, do not  change the mouse coordinates. This
   will be done automatically by the system.
   
   You may have to transmit an event  to several childs. Each child returns an answer, but
   your widget must return  only one answer.  Depending on the nature  of your widget, you
   have to decide  how to compute your own  answer from the answers returns  by the childs
   (and maybe other informations).
   
   
   

   
      *** (4.4) Manipulating areas. 
   
   As  explained above the  type 'WidgetArea'  is opaque.  hence, we  need some  tools for
   manipulating areas.
   
   
         *** (4.4.1) Creating areas. 
   
   At least, you need to construct areas. This may be done as follows:
   
public define List(WidgetRectangle) -> WidgetArea
   area
     (
       WidgetEventToolBox etb
     ). 
   
   For example if the width of your widget is  'w', and its height is 'h', and if you want
   to redraw the whole widget after some event, you may construct its area as follows:
   
                               area(etb)([rect(0,0,w,h)])
   

   
         *** (4.4.2) Getting the rectangles from an area.

   This is the converse of the previous one. 
   
public define WidgetArea -> List(WidgetRectangle)
   rectangles
     (
       WidgetEventToolBox   etb
     ).
   
   
   
   
         *** (4.4.3) Making the union of two areas. 
   
   You may also need to  make the union of two areas. This may for  example be the case if
   several  childs of  your widget  return answers  containing areas.  The  following tool
   computes the union of two areas (the event tool box is not needed):
   
public define WidgetArea
   WidgetArea a + WidgetArea b. 
   
   
   
         *** (4.4.4) Transmitting areas between widgets. 
   
   Areas (of type 'WidgetArea') contain only  absolute coordinates. This is the reason why
   the  type 'WidgetArea'  is  opaque.  This  has also  the  advantage that  areas may  be
   transmitted from one widget to another one without any conversion. This feature is used
   for example by the menu manager widget.
   
   

   
         *** (4.4.5) Special actions. 
   
   Use the following for closing the host window. 
   
public define One
   close_host_window
     (
       WidgetEventToolBox etb
     ).
   
   
   
   
   
   *** (5) Monitoring dynamic variables. 
   
   Widgets need in general to monitor  dynamic variables, simply because they are by their
   very   nature   the  graphical   representation   of   the   current  state   of   some
   'machine'. However,  a reassignment of  such a variable  may induce a redrawing  of the
   widget,  and  even  worst, a  change  of  size,  implying  a  redrawing of  the  parent
   widgets. In  order to handle  such global redrawing,  the reassignment of  the variable
   must generate  a 'changed(n)' event.  That  way, the whole  tree of widgets is  able to
   handle the reassignment correctly.
   
   For   that  reason,   widgets   must   not  in   general   monitor  dynamic   variables
   themself. Dynamic variables must be monitored by  the widget system. In order to say to
   the widget system that a variable must be monitored, you have the following tool:
   
public type WidgetRegistration:... (an opaque type)
   
public define WidgetRegistration
   register
     (
       Var($T)   v
     ).
   
   Remark  that  despite  the presence  of  a  parameter  in  this declaration,  the  type
   'WidgetRegistration' does  not depend on a  parameter. This allows  the construction of
   lists of registrations for dynamic variables of different types.   
   
   If the widget system has been asked  to monitor a dynamic variable 'v', it generates an
   event 'changed(l)', whenever  this variable is reassigned, where  the list 'l' contains
   the identifier of the variable (a 'changed' event may concern several variables).  When
   your widget receives  this event, it must compare this integer  'n' with the identifier
   of the variable (say 'v') it depends on.  This comparison may be done as follows:
   
       if member(l,var_id(v))
       then ... do something ...
       else ... do nothing ...
   
   Of course, if your widget does not  depend on the variable, nothing should be done. But
   if it depends on the variable, it  may return an answer like 'handled(a)', where 'a' is
   the area to be redrawn. Needless to say, this test must be done with all variables your
   widget depends on.
   
   Several  widgets may  depend on  the same  variable. As  a consequence,  an  event like
   'changed(l)' must always be transmitted to all childs.
   
    

   *** (6) Stretching. 

   The stretching capabilities of a widget are recorded into: 
   
public type WidgetStretchCap:
   stretch_cap(Word32     min_width, 
               Word32     min_height,
               Word32     max_width,
               Word32     max_height). 
   
   Each widget must have the following two methods:
   
       One -> WidgetStretchCap                      get_stretch_cap
       (Word32 width, Word32 height) -> One         stretch_to
   
   The first one must return the stretching capabilities of the widget. The second one ask
   the widget to stretch to the given size. Normally, if all widgets are well behaved, the
   given size is compatible with the  stretching capabilities. However, if this is not the
   case, the widget should stretch to the best size compatible with its capabilities.
   
   Getting the two methods from a child is performed by:
   
       Widget -> (One -> WidgetStretchCap)                 stretch_cap
       Widget -> ((Word32 width, Word32 height) -> One)    stretch_to
   
   For most widgets, these two methods are quite simple. However, in the case of the table
   widget, this is quite complicated.
   
   
   
   
   *** (7) Creating your widget.
   
   The type  'Widget' is an opaque  type, but here is  the tool which enables  to create a
   widget.
   
public define Widget
   create_widget
     (
       One -> WidgetStretchCap                               get_stretch_cap,
       (Word32,Word32) -> One                                stretch_to,
       One -> (Word32,Word32)                                size, 
       (WidgetDrawToolBox) -> One                            redraw, 
       (WidgetEventToolBox,WidgetEvent) -> WidgetAnswer      event_handler,
       One -> List(WidgetRegistration)                       registrations
     ). 
   
   The function  'size' must return the  current size '(width,height)' of  your widget. Be
   careful that,  if this size is  going to change,  the function must return  the current
   size, not the initial size.

   The function 'registrations' must return the  list of registrations for your widget but
   also  for all  its  childs recursively.   Thus,  this function  must  call the  similar
   functions of  its childs and append  all the results  to its own registrations.   For a
   given child 'c' this function is  available as 'registrations(c)'. So, for example, the
   'simple_window'  widget has several  variables of  its own  but has  also a  child (the
   content of the  window). So the function given as the  last argument to 'create_widget'
   is:
   
         (One u) |-> [ register(width_v),
                       register(height_v),
                       register(x_scroll_v),
                       register(y_scroll_v)
                     . registrations(content)(u)]
   
   i.e. the 'simple_window' widget registers its own variables and those of its child. 
   
   
   
   
   
   --- That's all for the public part ! --------------------------------------------------
   
   
   

   
   
   
   ------------------------------------ Table of Contents --------------------------------
   
   *** [1] Opaque types. 
   
   *** [2] Tools.
      *** [2.1] Getting the size of a widget. 
      *** [2.2] Drawing a rectangle through clipping rectangles. 
   
   *** [3] Drawing. 
      *** [3.1] Drawing a child widget. 
      *** [3.2] Drawing a rectangle. 
      *** [3.3] Drawing an image.
      *** [3.4] Drawing a character string. 
   
   *** [4] Handling events. 
      *** [4.1] Transmitting an event to a child. 
      *** [4.2] Creating an area. 
      *** [4.3] Unions of areas. 
   
   *** [5] Registering dynamic variables. 
   
   *** [6] Creating the widget. 
      
   ---------------------------------------------------------------------------------------
   
   
   
public define Word32
   max
     (
       Word32 x, 
       Word32 y
     ) =
   if x -< y then y else x. 
   
public define Word32
   min
     (
       Word32 x, 
       Word32 y
     ) =
   if x -< y then x else y. 
   
   
  
   
   
   
   
   
read tools/basis.anubis   
   
   
   *** [1] Opaque types. 
   
public type WidgetDrawToolBox:
   draw_tool_box(
     HostImage,          // 'double' buffer 
     Word32,              // bx  (position of buffer in host window)
     Word32,              // by 
     Word32,              // wx  (position of widget in host window)
     Word32,              // wy
     List(Rectangle)).   // clipping area

     
public type WidgetEventToolBox:
   event_tool_box(
     HostWindow,         // hw
     Word32,              // wx  (position of widget in host window)
     Word32,              // wy
     Word32,              // pmx (absolute mouse position in previous mouse event)
     Word32).             // pmy
     
   
public type WidgetArea:
   abs_area(List(Rectangle)). 
   
public type Widget:
   widget(One -> WidgetStretchCap,                               // get stretch capabilities
          (Word32,Word32) -> One,                                  // stretching the widget
          One -> (Word32,Word32),                                  // get size of widget
          (WidgetDrawToolBox) -> One,                            // redraw
          (WidgetEventToolBox,WidgetEvent)  -> WidgetAnswer,     // event handler
          One -> List(WidgetRegistration)    registrations). 
   
   
   
   
   
   *** [2] Tools.
   
      *** [2.1] Getting the size of a widget. 
   
public define (Word32,Word32)
   size
     (
       Widget w
     ) =
   if w is widget(_,_,gs,_,_,_) then gs(unique). 
   
   
   
   
      *** [2.2] Drawing a rectangle through clipping rectangles. 
   

   
   *** [3] Drawing. 
   
      *** [3.1] Drawing a child widget. 
   
public define (Widget child, Word32 x, Word32 y) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ) =
   (Widget child, Word32 x, Word32 y) |-> 
     if dtb is draw_tool_box(buf,bx,by,wx,wy,clipa) then 
     if child is widget(_,_,_,redraw,_,_) then 
       redraw(draw_tool_box(buf,bx,by,wx+x,wy+y,clipa)). 
   

   The following  function 'intersection', defined in 'tools.anubis'  is (re)declared here
   because otherwise we have a 'read circularity' problem.
   
public define List(Rectangle) intersection(Rectangle r,List(Rectangle) l). 
   
   
public define (Widget child, Word32 x, Word32 y, WidgetRectangle clip) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ) =
   (Widget child, Word32 x, Word32 y, WidgetRectangle clip) |->
     if clip is rect(cx,cy,cu,cv) then 
     if dtb is draw_tool_box(buf,bx,by,wx,wy,clipa) then 
     if child is widget(_,_,_,redraw,_,_) then 
       redraw(draw_tool_box(buf,bx,by,wx+x,wy+y,
                            intersection(rect(wx+cx,wy+cy,wx+cu,wy+cv),
                                         clipa))). 
   
public define (Widget child, Word32 x, Word32 y, List(WidgetRectangle) clip) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ) =
   (Widget child, Word32 x, Word32 y, List(WidgetRectangle) clip) |->
     map_forget((WidgetRectangle r) |-> draw(dtb)(child,x,y,r),clip). 
   
   
   
   
      *** [3.2] Drawing a rectangle. 
   
public define (WidgetRectangle,RGB) -> One   
   draw 
     (
       WidgetDrawToolBox dtb
     ) =
   if dtb is draw_tool_box(buf,bx,by,wx,wy,clipa) then 
   (WidgetRectangle r, RGB c) |-> 
     if r is rect(x,y,u,v) then 
     map_forget((Rectangle clip) |-> 
       (
         if clip is rect(cx,cy,cu,cv) then 
         with ax = max(cx,x+wx), 
              ay = max(cy,y+wy), 
              au = min(cu,u+wx),
              av = min(cv,v+wy), 
           if (ax -< au & ay -< av)
           then paint_rectangle(buf,rect(ax-bx,ay-by,au-bx,av-by),c)
           else unique
       ),clipa). 
   
   
   
      *** [3.3] Drawing an image.
   
public define (HostImage, Word32 x, Word32 y) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ) =
   if dtb is draw_tool_box(buf,bx,by,wx,wy,clipa) then 
   (HostImage image, Word32 x, Word32 y) |-> 
      map_forget((Rectangle clip) |-> 
        (
          if clip is rect(cx,cy,cu,cv) then 
          with crop_x = cx-bx,
               crop_y = cy-by,
               crop_u = cu-bx, 
               crop_v = cv-by,
            if (crop_x -< crop_u & crop_y -< crop_v)
            then paint_image(buf,
                             rect(crop_x,crop_y,crop_u,crop_v), 
                             x+wx-bx,
                             y+wy-by,
                             image)
            else unique
        ),clipa). 
   
   
public define (HostImage, Word32 x, Word32 y, WidgetRectangle eclip) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ) =
   if dtb is draw_tool_box(buf,bx,by,wx,wy,clipa) then 
   (HostImage image, Word32 x, Word32 y, WidgetRectangle eclip) |-> 
      if eclip is rect(ecx,ecy,ecu,ecv) then 
      map_forget((Rectangle clip) |-> 
        (
          if clip is rect(cx,cy,cu,cv) then 
          with crop_x = max(cx,ecx+wx)-bx,
               crop_y = max(cy,ecy+wy)-by,
               crop_u = min(cu,ecu+wx)-bx, 
               crop_v = min(cv,ecv+wy)-by,
            if (crop_x -< crop_u & crop_y -< crop_v)
            then paint_image(buf,
                             rect(crop_x,crop_y,crop_u,crop_v), 
                             x+wx-bx,
                             y+wy-by,
                             image)
            else unique
        ),clipa). 
   
public define (HostImage, Word32 x, Word32 y, List(WidgetRectangle) eclip) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ) =
   (HostImage image, Word32 x, Word32 y, List(WidgetRectangle) eclip) |-> 
   map_forget((WidgetRectangle r) |-> draw(dtb)(image,x,y,r),
              eclip).
   
   
   
   
      *** [3.4] Drawing a character string. 
   
   An auxiliary function:
   
define Word32
   draw_string
     (
       String                  text, 
       Word32                   i, 
       Word32                   chx, 
       (Word8, Word32) -> Word32  draw_char
     ) =
   if nth(to_Int(i),text) is
     {
       failure then chx, 
       success(ch) then 
         with ch_width = draw_char(ch,chx), 
           draw_string(text,i+1,chx+ch_width,draw_char)
     }.
   
   
   
public define (String s, SystemFont f, RGB c, Word32 x, Word32 y) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ) =
   if dtb is draw_tool_box(buf,bx,by,wx,wy,clipa) then 
   (String s, SystemFont f, RGB c, Word32 x, Word32 y) |-> 
     map_forget((Rectangle clip) |-> 
       (
         if clip is rect(cx,cy,cu,cv) then 
         with sx = x+wx-bx, 
              sy = y+wy-by, 
           draw_string(s,0,0,
                       (Word8 ch, Word32 chx) |-> 
                         draw_system_character(buf,
                                               rect(cx-bx,cy-by,cu-bx,cv-by),
                                               sx+chx,
                                               sy,
                                               f,
                                               word32(word16(ch,0),0), //word8_to_Word32(ch),
                                               c)
                       )
       ),clipa). 
   
   
   
   
public define (String s, SystemFont f, RGB c, Word32 x, Word32 y, 
               WidgetRectangle eclip) -> One
   draw
     (
       WidgetDrawToolBox dtb
     ) =
   if dtb is draw_tool_box(buf,bx,by,wx,wy,clipa) then 
   (String s, SystemFont f, RGB c, Word32 x, Word32 y, WidgetRectangle eclip) |-> 
     if eclip is rect(ecx,ecy,ecu,ecv) then 
     map_forget((Rectangle clip) |-> 
       (
         if clip is rect(cx,cy,cu,cv) then 
         with sx = x+wx-bx, 
              sy = y+wy-by, 
           draw_string(s,0,0,
                       (Word8 ch, Word32 chx) |-> 
                         draw_system_character(buf,
                                               rect(max(cx,ecx+wx)-bx,
                                                    max(cy,ecy+wy)-by,
                                                    min(cu,ecu+wx)-bx,
                                                    min(cv,ecv+wy)-by),
                                               sx+chx,
                                               sy,
                                               f,
                                               word32(word16(ch,0),0), //word8_to_Word32(ch),
                                               c)
                       )
       ),clipa). 
        
   
   
   
   
   *** [4] Handling events. 
   
   
      *** [4.1] Transmitting an event to a child. 
   
   
public define (Widget child, Word32 x, Word32 y, WidgetEvent) -> WidgetAnswer   
   transmit
     (
       WidgetEventToolBox etb
     ) =
   if etb is event_tool_box(hw,wx,wy,pmx,pmy) then 
   (Widget child, Word32 x, Word32 y, WidgetEvent e) |->
     if child is widget(_,_,size,_,event_handler,_) then 
     if size(unique) is (w,h) then
     with cetb = event_tool_box(hw,wx+x,wy+y,pmx,pmy), 
             u = x+w,
             v = y+h,
          rpmx = pmx-wx,
          rpmy = pmy-wy,
       if e is 
         {
           quit then event_handler(cetb,e), 
   
           mouse_move(ks,mx,my) then 
               if (mx >=- x & my >=- y & mx -< u & my -< v)
               then event_handler(cetb,mouse_move(ks,mx-x,my-y))
               else if (rpmx >=- x & rpmy >=- y & rpmx -< u & rpmy -< v)
                    then event_handler(cetb,mouse_gone)
                    else ignored,
   
           mouse_click(ks,mc,mx,my) then 
               if (mx >=- x & my >=- y & mx -< u & my -< v)
               then event_handler(cetb,mouse_click(ks,mc,mx-x,my-y))
               else if (rpmx >=- x & rpmy >=- y & rpmx -< u & rpmy -< v)
                    then event_handler(cetb,mouse_gone)
                    else ignored,

           mouse_wheel(ks,delta,mx,my) then 
               if (mx >=- x & my >=- y & mx -< u & my -< v)
               then event_handler(cetb,mouse_wheel(ks,delta,mx-x,my-y))
               else if (rpmx >=- x & rpmy >=- y & rpmx -< u & rpmy -< v)
                    then event_handler(cetb,mouse_gone)
                    else ignored,
        
           mouse_gone then
               if (rpmx >=- x & rpmy >=- y & rpmx -< u & rpmy -< v)
               then event_handler(cetb,mouse_gone)
               else ignored,
               
   
           captured_mouse_move(f)       then event_handler(cetb,e),
           captured_mouse_liberated(f)  then event_handler(cetb,e),
           key_down(f)                  then event_handler(cetb,e),
           keyboard_recaptured(f)       then event_handler(cetb,e), 
           changed(l)                   then event_handler(cetb,e),
           could_drop(_,_,_,_)          then event_handler(cetb,e),
           want_to_drop(_,_,_)          then event_handler(cetb,e)
         }. 
   
   


   
   
      *** [4.2] Creating an area. 
   
public define List(WidgetRectangle) -> WidgetArea
   area
     (
       WidgetEventToolBox etb
     ) =
   if etb is event_tool_box(hw,wx,wy,pmx,pmy) then 
   (List(WidgetRectangle) l) |-> 
      abs_area(map((WidgetRectangle r) |-> 
                      if r is rect(x,y,u,v) then rect(x+wx,y+wy,u+wx,v+wy),
                   l)). 
   
   
public define WidgetArea -> List(WidgetRectangle)
   rectangles
     (
       WidgetEventToolBox etb
     ) =
   if etb is event_tool_box(hw,wx,wy,pmx,pmy) then 
   (WidgetArea a) |-> if a is abs_area(l) then
      map((Rectangle r) |-> 
              if r is rect(x,y,u,v) then rect(x-wx,y-wy,u-wx,v-wy),
          l).
   

   
public define Rectangle
   rectangle
     (
       WidgetEventToolBox           etb, 
       WidgetRectangle              r
     ) =
   if etb is event_tool_box(hw,wx,wy,_,_) then 
   if r is rect(x,y,u,v) then 
   rect(x+wx,y+wy,u+wx,v+wy). 
   
   
public define WidgetRectangle
   widget_rectangle
     (
       WidgetEventToolBox           etb, 
       Rectangle                    r
     ) =
   if etb is event_tool_box(hw,wx,wy,_,_) then 
   if r is rect(x,y,u,v) then 
   rect(x-wx,y-wy,u-wx,v-wy). 
   

   
   
   
      *** [4.3] Unions of areas. 
   
public define WidgetArea
   WidgetArea a + WidgetArea b
     =
   if a is abs_area(la) then 
   if b is abs_area(lb) then 
   abs_area(la+lb). 
   
   

   
   
public define One
   close_host_window
     (
       WidgetEventToolBox etb
     ) =
   if etb is event_tool_box(hw,wx,wy,pmx,pmy) then 
   forget(queue_event(hw,(HostWindowEvent(One))quit)). 
   
   
   
   
   
   
   *** [5] Registering dynamic variables. 

   The  variables which  contain the  state  of the  machine ('state  variables') must  be
   monitored so that widgets may stay up to date. This system works as follows.

   When a  host window is opened, a  variable of type 'Var(List(Word32))'  is created. This
   variable will be called the 'monitoring  variable' for this host window.  This variable
   contains  the list  of the  identifiers of  all state  variables which  have  just been
   reassigned. The  widget system does  not monitor this  variable.  On the  contrary, the
   variable is checked at  each 'tick' event (about 25 times per  second).  This method is
   called 'polling'.   If the variable  contains the empty  list, nothing is done.   If it
   contains  some non empty  list 'l',  the empty  list is  put into  the variable,  and a
   'changed(l)' event is generated (i.e. the  event handler of the root widget is executed
   on this  event).  Notice that  polling this variable  instead of monitoring it  has two
   consequences:  (1) reassignments  of several  state variables  may result  in  a single
   'changed(l)' event, (2) the event is handled by the virtual machine of the host window,
   not by the virtual machine which performed the assignment.

   The variable 'mv' must be protected so that for example, during the execution of 'mv <-
   [var_id(v) . *mv]' the value of 'mv' does not change between the execution of '*mv' and
   the assignment of 'mv'. For this reason, the variable 'mv' is accessible only through a
   'mv tool box', of type:
   
public type WidgetMVToolBox:
   mv_tool_box
     (
       Word32 -> One          add_id,         // add a new id to 'mv'
       One -> List(Word32)    collect         // get the list of ids and empty 'mv'
     ). 
   
define Maybe(List(Word32))
   mv_tool
     (
       Maybe(Word32)       mb_n,
       Var(List(Word32))   mv, 
     ) =
   protect
   if mb_n is 
     {
       failure then with r = *mv, 
                         mv <- []; 
                         success(r),
       success(n) then mv <- [n . *mv]; 
                       failure
     }. 
   
   
   
public define WidgetMVToolBox
   make_mv_tool_box
     (
       Var(List(Word32))   mv
     ) =
   mv_tool_box
     (
       (Word32 n) |-> if mv_tool(success(n),mv) is 
                       {
                         failure then unique, 
                         success(_) then should_not_happen(unique)
                       },
       (One u) |-> if mv_tool(failure,mv) is 
                       {
                         failure then should_not_happen([]), 
                         success(l) then l
                       }
     ).
   
public type WidgetRegistration:
   registration(WidgetMVToolBox -> One). 
   
   'add_id'  and   'collect'  are   just  interfaces  to   a  unique  function   which  is
   'protected'. Hence 'add_id' and 'collect' can never conflict. 
   
   When a state variable 'v' is reassigned, the  identifier of 'v' is added to the list in
   the monitoring variable 'mv', thanks to the following monitor:
   
                               (One u) |-> add_id(mvtb)(var_id(v))
   
   where 'mvtb' is the 'mv tool box'. 
   
   When the  host window is  opened, this monitor  must be attached  to 'v' (of  some type
   'Var($T)'),  and  the  monitoring  ticket  is  put into  some  variable  'tv'  of  type
   'Maybe(MonitoringTicket($T))' (one such variable per state variable and host window):
   
                    tv <- success(register_monitor(v,
                             (One u) |-> add_id(mvtb)(var_id(v))))
   
   Of course, this  must be done for  each registration in the registration  list. This is
   why the registration for the state variable 'v' is the function:
   
                   (WidgetMVToolBox mvtb) |-> 
                       tv <- success(register_monitor(v,
                          (One u) |-> add_id(mvtb)(var_id(v))))
   
   At the  time the  host window  is opened, this  function is  applied to  the monitoring
   variable 'mv'.
   
   As a consequence, the registration is performed as follows: 
   
public define WidgetRegistration
   register
     (
       Var($T)   v
     ) =
   with tv = var((Maybe(MonitoringTicket($T)))failure), 
   registration((WidgetMVToolBox mvtb) |-> 
     tv <- success(register_monitor(v,
       (One u) |-> add_id(mvtb)(var_id(v))))).
   
   Notice that if the host window keeps this regitration list, it also keeps references to
   the variables 'tv', hence to its  value, hence to the monitoring ticket. So, monitoring
   of the state variables will continue all the life time of the host window. 
   
   
   
   
   
   *** [6] Creating the widget. 

   
public define One -> WidgetStretchCap
   stretch_cap
     (
       Widget w
     ) =
   if w is widget(sc,_,_,_,_,_) then sc. 
   
public define (Word32 width, Word32 height) -> One
   stretch_to
     (
       Widget w
     ) =
   if w is widget(_,st,_,_,_,_) then st. 
   
   
   
   
   
public define Widget
   create_widget
     (
       One -> WidgetStretchCap                               get_stretch_cap,
       (Word32,Word32) -> One                                  stretch_to,
       One -> (Word32,Word32)                                  size, 
       (WidgetDrawToolBox) -> One                            redraw, 
       (WidgetEventToolBox,WidgetEvent) -> WidgetAnswer      event_handler,
       One -> List(WidgetRegistration)                       registrations
     ) =
   with up_to_date = var((Bool)false), 
         draw_buff = if size(unique) is (w,h) then create_rgba_image(to_Int(w),to_Int(h),rgba(0,0,0,0)), 
   widget
     (
       get_stretch_cap, 
       stretch_to, 
       size,
       redraw,
       event_handler,
       registrations
     ).