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'. ------------------------------------ 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' and 'mouse_click'. *** (4.1.2) 'mouse_gone'. *** (4.1.3) 'captured_mouse_move' and 'captured_mouse_liberated'. *** (4.1.4) 'key_down'. *** (4.1.5) 'changed'. *** (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) Making the union of two areas. *** (4.4.3) Transmitting areas between widgets. *** (5) Monitoring dynamic variables. *** (6) 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 event) 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, it optimizes the area into a disjoint union of 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 require 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. *** (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 rectangle (i.e. relative to your widget) are represented by the type: public type WidgetRectangle: rect(Int32 x, Int32 y, Int32 u, Int32 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 (Int32,Int32) // (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, Int32 x, Int32 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, Int32 x, Int32 y, 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, Int32 x, Int32 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 Int32 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, Int32 x, Int32 y, WidgetRectangle clip) -> One draw ( WidgetDrawToolBox dtb ). Again the rectangle 'clip' is relative to your widget. *** (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, Int32 x, Int32 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, Int32 x, Int32 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: // // 'Normal' events: // mouse_move (KeyboardState ks, Int32 x, Int32 y), mouse_click (KeyboardState ks, MouseClick mc, Int32 x, Int32 y), mouse_gone, // // Events generated when the mouse is captured: // captured_mouse_move ((Var(One),WidgetEventToolBox) -> Maybe((Int32,Int32))), captured_mouse_liberated ((Var(One),WidgetEventToolBox) -> Maybe((Int32,Int32))), // // Events generated when the keyboard is captured: // key_down ((Var(One)) -> Maybe((KeyboardState,KeyboardKey))), // // Events generated when a state variable is reassigned: // changed (List(Int32) l). 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' and 'mouse_click'. 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 its unique 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 coordinats 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 of its childs. *** (4.1.4) 'key_down'. 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. If your widget is not concerned by this event it must transmit it to all of its childs. *** (4.1.5) 'changed'. This event is generated by the widget system when dynamic variables registred at the widget system is reassigned. See below for more explanations. *** (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. This 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 alway the same one (for example, it may be created before the creation of your widget and be accessible to the event handler). '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, Int32 x, Int32 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. *** (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) 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.3) 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 possibility is used for example by the menu manager widget. *** (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 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 various 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) 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 -> (Int32,Int32) 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 you 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. --- 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. --------------------------------------------------------------------------------------- read tools/basis.anubis *** [1] Opaque types. public type WidgetDrawToolBox: draw_tool_box( HostImage, // 'double' buffer Int32, // bx (position of buffer in host window) Int32, // by Int32, // wx (position of widget in host window) Int32, // wy List(Rectangle)). // clipping area public type WidgetEventToolBox: event_tool_box( Int32, // wx (position of widget in host window) Int32, // wy Int32, // pmx (absolute mouse position in previous mouse event) Int32). // pmy public type WidgetArea: abs_area(List(Rectangle)). public type Widget: widget(One -> (Int32,Int32), // 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 (Int32,Int32) 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, Int32 x, Int32 y) -> One draw ( WidgetDrawToolBox dtb ) = (Widget child, Int32 x, Int32 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, Int32 x, Int32 y, WidgetRectangle clip) -> One draw ( WidgetDrawToolBox dtb ) = (Widget child, Int32 x, Int32 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))). *** [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, Int32 x, Int32 y) -> One draw ( WidgetDrawToolBox dtb ) = if dtb is draw_tool_box(buf,bx,by,wx,wy,clipa) then (HostImage image, Int32 x, Int32 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, Int32 x, Int32 y, WidgetRectangle eclip) -> One draw ( WidgetDrawToolBox dtb ) = if dtb is draw_tool_box(buf,bx,by,wx,wy,clipa) then (HostImage image, Int32 x, Int32 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). *** [3.4] Drawing a character string. An auxiliary function: define Int32 draw_string ( String text, Int32 i, Int32 chx, (Int8, Int32) -> Int32 draw_char ) = if nth(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, Int32 x, Int32 y) -> One draw ( WidgetDrawToolBox dtb ) = if dtb is draw_tool_box(buf,bx,by,wx,wy,clipa) then (String s, SystemFont f, RGB c, Int32 x, Int32 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, (Int8 ch, Int32 chx) |-> draw_system_character(buf, rect(cx-bx,cy-by,cu-bx,cv-by), sx+chx, sy, f, int8_to_int32(ch), c) ) ),clipa). public define (String s, SystemFont f, RGB c, Int32 x, Int32 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, Int32 x, Int32 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, (Int8 ch, Int32 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, int8_to_int32(ch), c) ) ),clipa). *** [4] Handling events. *** [4.1] Transmitting an event to a child. public define (Widget child, Int32 x, Int32 y, WidgetEvent) -> WidgetAnswer transmit ( WidgetEventToolBox etb ) = if etb is event_tool_box(wx,wy,pmx,pmy) then (Widget child, Int32 x, Int32 y, WidgetEvent e) |-> if child is widget(size,_,event_handler,_) then if size(unique) is (w,h) then with cetb = event_tool_box(wx+x,wy+y,pmx,pmy), u = x+w, v = y+h, rpmx = pmx-wx, rpmy = pmy-wy, if e is { 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_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), changed(l) then event_handler(cetb,e) }. *** [4.2] Creating an area. public define List(WidgetRectangle) -> WidgetArea area ( WidgetEventToolBox etb ) = if etb is event_tool_box(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)). *** [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). *** [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(Int32))' 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 ( Int32 -> One add_id, // add a new id to 'mv' One -> List(Int32) collect // get the list of ids and empty 'mv' ). define Maybe(List(Int32)) mv_tool ( Maybe(Int32) mb_n, Var(List(Int32)) 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(Int32)) mv ) = mv_tool_box ( (Int32 n) |-> if mv_tool(success(n),mv) is { failure then unique, success(_) then alert }, (One u) |-> if mv_tool(failure,mv) is { failure then alert, 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 Widget create_widget ( One -> (Int32,Int32) size, (WidgetDrawToolBox) -> One redraw, (WidgetEventToolBox,WidgetEvent) -> WidgetAnswer event_handler, One -> List(WidgetRegistration) registrations ) = widget ( size, redraw, event_handler, registrations ).