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(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 ). The part to be redrawn may also be a union of rectangles: public define (Widget child, Int32 x, Int32 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, 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. The same one with a list of rectangles: public define (HostImage, Int32 x, Int32 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, 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: quit, // // 'Normal' mouse events: // mouse_move (KeyboardState ks, Int32 x, Int32 y), mouse_click (KeyboardState ks, MouseClick mc, Int32 x, Int32 y), mouse_wheel (KeyboardState ks, Int32 delta, 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))), keyboard_recaptured ((Var(One)) -> Bool), // // Events generated when a state variable is reassigned: // changed (List(Int32) l), // // Drag and drop events (see 'drag_and_drop.anubis') // could_drop (Int32 mx, Int32 my, Int32 com_var_id, Var(Bool)), want_to_drop (Int32 mx, Int32 my, Int32 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, 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. 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(Int32 min_width, Int32 min_height, Int32 max_width, Int32 max_height). Each widget must have the following two methods: One -> WidgetStretchCap get_stretch_cap (Int32 width, Int32 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 method must at least put a message on the console for signaling the problem, and 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 -> ((Int32 width, Int32 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, (Int32,Int32) -> One stretch_to, 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 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. --------------------------------------------------------------------------------------- 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( HostWindow, // hw 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 -> WidgetStretchCap, // get stretch capabilities (Int32,Int32) -> One, // stretching the 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))). public define (Widget child, Int32 x, Int32 y, List(WidgetRectangle) clip) -> One draw ( WidgetDrawToolBox dtb ) = (Widget child, Int32 x, Int32 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, 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). public define (HostImage, Int32 x, Int32 y, List(WidgetRectangle) eclip) -> One draw ( WidgetDrawToolBox dtb ) = (HostImage image, Int32 x, Int32 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 Int32 draw_string ( String text, Int32 i, Int32 chx, (Word8, 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, (Word8 ch, Int32 chx) |-> draw_system_character(buf, rect(cx-bx,cy-by,cu-bx,cv-by), sx+chx, sy, f, word8_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, (Word8 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, word8_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(hw,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(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(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 One -> WidgetStretchCap stretch_cap ( Widget w ) = if w is widget(sc,_,_,_,_,_) then sc. public define (Int32 width, Int32 height) -> One stretch_to ( Widget w ) = if w is widget(_,st,_,_,_,_) then st. public define Widget create_widget ( One -> WidgetStretchCap get_stretch_cap, (Int32,Int32) -> One stretch_to, One -> (Int32,Int32) 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(w,h,rgba(0,0,0,0)), widget ( get_stretch_cap, stretch_to, size, redraw, event_handler, registrations ).