Dos Widgets: Reference Manual

Version 10.10
December 2003

Contents

Introduction
Installation
Basic Elements and Structures
Text
Windows
Event Trapping
Your First Program
Debugging
Extending Widgets
Reference
Constants
Variables
Routines
Widgets

Introduction

The package is a simple event driven environment for DOS in graphics modes. It is easy to use, compact and reasonably stable.
The widgets are a hierarchical system that contains a range of basic elements as well as many of the most common controls.
Among its primitives are text widgets, lines, frames, colored panes, timers and, of course, the omnipresent scr (screen widget).
The controls include all sorts of buttons, check boxes, spinners, scrollers, SLEs, MLEs and menus.
These predefined elements can be, in turn, used to engineer new, more complex widgets. Some of those are also included in the package: basic windows and message boxes, a simple file selector, generic displayers with scrollers and a system color selector.

Installation

Simple: unzip the package into the euphoria directory. Make sure your unzip program preserves directory structures, and a new directory called widgets will be created! Just copy core.e and widgets.e into your include directory, and you are ready to go...

Basic Elements and Structures

First of all, let's get some basic terms right, so that we talk roughly the same language.
A primitive is a widget, whose definition does not depend on any other widget; it is defined, so to speak, from 'the first principles'. (Just a taxonomic distinction anyway - functionally all widgets are equal.)
When I talk about a widget, it can be one of two things: usually I would be referring to an instant, represented by the actual widget's handle, an integer. Only occasionally it would be a widget's 'class' (using the infamous OO speak), effectively the widget's defining function.

All widgets have exactly eight fields. Each field is contained in a separate, appropriately named sequence.
When a widget is created, all these sequences are appended by a single field, so that they are always of the same length. This length, effectively an index of the widget's property fields, becomes its permanent, unique handle. It can be, of course, assigned to a variable, or a constant, preferably with a meaningful identifier.

The first seven fields below are quite specific containers. The last one is a general, all-purpose data holder for colors, patterns, images, edges, kinds of anything, outputs, etc. More specifically data fields of text widgets are used to store the pen information.

• name: a descriptive string, giving, in most cases, the whole pedigree of the widget
• host: an integer, the handle of the host
• flag: an integer, a collection of various flags
• dim : a sequence of dimensions, the first two are always x,y coordinates
• part: a plain sequence of widget's components
• show: a routine_id related to the display procedure, or a sequence of such ids to be executed consecutively
• trap: a special sequence that associates widget's events with built-in as well as user supplied routine_ids (methods)
• data: general storage

Quite often fields contain default values, which, of course, can easily be overwritten. Also, not every widget uses all the fields; the unused fields remain filled with default or dummy values, and are simply ignored.

The pile is another simple, very important structure. The system needs it to display all currently used widgets in the required order: the bottommost first, and the top one as the last item of the pile sequence. Also, only events of the top widget (together with timers and the universal escape key, of course) are constantly monitored.

The menu stack, mpile, is a minor auxiliary structure that keeps track of displayed submenus to facilitate their collapse on exit.
Similarly, wpile is also a minor auxiliary structure recording the hierarchy of displayed modal windows.

Text

The text widget is certainly a complex primitive, but it is also very versatile.
Directly, you can specify not just the position and the dimensions of the text box, but also placement of the text in it through the use of margins as well as any of eight different combinations of horizontal and vertical justifications.
The text data field is a property sequence with ten standard elements. For easy access, each has a predefined two letter combination (see pen properties in the constants section below).

Windows

There are only two kinds of windows to worry about. The non-modal variety (with a host other than nil) takes care of itself, it behaves the same way as any other non-modal widget.
The modal windows are a bit trickier. First of all, they are not displayed automatically. They have to be either inserted into the pile manually before the program starts, or invoked through a control using the open_window routine.
Both kinds of windows can be repositioned manually on the screen, dragged around by their title bars. But they are not, currently anyway, resizable.

Event Trapping

Your First Program

Let's start with something really simple!

As a rule, each widget type/class has a separate defining function. The following four lines form a complete (non-sensical) program:

	
        include widgets.e
        constant b = button(scr, {20,50,100,20}, "e&xit", PLAIN, routine_id("quit"))
        screen("simple example",257,blue)
        go()
    

It puts a labelled button on the screen:

b is a handle, an integer.
button() is a class function, a widget generator.
The first parameter, scr, is a pre-defined widget, the underlying graphics screen, a sort of 'universal' host.
The {20, 50, 100, 20} sequence will be stored in the above mentioned dim field. It marks the top left corner, width and height of the newly generated control.
The label will have a highlighted 'x', the 'hot' key.
By the way, there are three types of buttons to choose from: PLAIN, TOOGLE and FAST. (The FAST ones have a built-in accelerated repeat action!)
The last parameter associates new button's standard events (the left mouse button click and the hot key) with the system 'abort' routine.
The screen() routine is used to specify the screen title, graphics mode (640x480x256 in this case) and the color of the screen.
The go() command initializes the rat, generates necessary event tracking structures, displays the widgets and, eventually, enters the main event loop.

Debugging

There are quite a few debugging tools defined in the last section of core.e, but by far the most useful one is the dump routine. Use it early and use often in the development cycle! It gives you an honest as well as a very complete snapshot of your creation, with all linkages clearly exposed.

The dump routine creates a text file, also called dump (very sensibly!), in the current working directory. A short excerpt from the beginning of a real dump follows:

    pile   = {1}
    wpile  = {}
    mpile  = {}
    self   = 6

    fonts: {"tahoma16.f", "vga8x16.f"}

    key1trap = {115}
    key2trap = {{6,{8,6},-1}}
    rattrap = {{11,-1,{11,9},-1,626,2,638,14},{6,-1,{7,6},-1,100,40,149,60}}

    1:
      name : "screen"
      host : 0
      flag : 0
      part : {2,5,6,9}
      dim  : {0,0,640,480}
      trap : {}
      show : 0
      data : {4,18}

    2:
      name : "shower"
      host : 1
      flag : 0
      part : {3,4}
      dim  : {0,0}
      trap : {}
      show : 1
      data : {" 20: 36: 43"}

You can insert the routine as many times as you wish, and in any part of your code; every time it just appends a fresh snapshot to the output file.

Extending Widgets

Reference

Constants

    core.e:
        false   = 0
        nil     = 0
        true    = 1
        esc     = 27

        lbp                 -- left button pressed                
        mbp                 -- middle button pressed                
        rbp                 -- right button pressed

        scr                 -- pre-defined widget, automatically placed on pile

        compiled rat pointers:
            RAT_ARROW
            RAT_ARROW1
            RAT_TRIANGLE
            RAT_CROSS
            RAT_IBEAM
            RAT_LTRB        -- left top to right bottom diagonal arrows
            RAT_RTLB        -- right top to left bottom diagonal arrows
            RAT_LR          -- left to right arrows
            RAT_TB          -- top to bottom arrows
            RAT_PENCIL
            RAT_HGLASS
            RAT_NOGO
            RAT_RESIZE
            RAT_HAND
            RAT_HAND1

        masks for use with kbd function:
            RSHIFT      = 1
            LSHIFT      = 2
            SHIFT       = 3
            CONTROL     = 4
            ALT         = 8
            SCROLL_LOCK = 16
            NUM_LOCK    = 32
            CAPS_LOCK   = 64
            INSERT      = 128

        system colors:
            black   = 0     -- text                       
            sc1     = 1     -- dark shadows               
            sc2     = 2     -- light shadows              
            sc3     = 3     -- dark face                       
            sc4     = 4     -- light face 
            sc5     = 5     -- highlights                 
            sc6     = 6     -- 'paper'color
            white   = 7                                        
            brown   = 8          
            blue    = 9
            green   = 10
            cyan    = 11
            red     = 12
            magenta = 13
            yellow  = 14
            orange  = 15

            RGB     = {49,49,42}    -- default rgb mix for sc4

        flag field masks: 
            GLOBAL  = 0
            INACTIVE= 1 
            HIDDEN  = 2
            LOCAL   = 4 
            SELECTED= 8
            MULTI   = 16     -- allows multiple selection (default for lbox)
            TILDE   = 32    -- text: show tildes (default 0)
            AMPER   = 64    -- text: show ampersands (default 0)
        
        font fields: 
            FI  = 1         -- font filename 
            RL  = 2         -- run-length encoded char images
            WI  = 3         -- char widths
            HE  = 4         -- font nominal height
            BH  = 5         -- font nominal base height

        pen properties in data field of a text widget: 
            ST  = 1         -- string
            FO  = 2         -- font widget, handle
            FC  = 3         -- foreground color
            PC  = 4         -- paper color
            HC  = 5         -- hilite color
            SC  = 6         -- shadow color
            JU  = 7         -- justification
            EC  = 8         -- extra char pitch
            EL  = 9         -- extra line pitch
            SO  = 10        -- shadow offsets

    widgets.e:
        CLEAR   = -1        -- transparent background for text widget
        EDGE    = {{{5},{5},{2},{2}}, {{2},{2},{5},{5}}} -- default edge         
        FAST    = 2         -- button type
        HORIZONTAL = 1      -- group orientation
        PLAIN   = 0         -- button type
        PUT     = -1        -- display kind (using display_image) for pic widget
        TOGGLE  = 1         -- button type
        VERTICAL= 0         -- group orientation

        justification:
            LE = 0          -- left
            HO = 1          -- horizontally centered
            RI = 2          -- right
            VE = 4          -- vertically centered
            BO = 8          -- bottom

            LT = 0          -- left, top
            HT = 1          -- horizontally centered, top
            RT = 2          -- right, top
            LV = 4          -- left, vertically centered
            HV = 5          -- horizontally centered, vertically centered
            RV = 6          -- right, vertically centered
            LB = 8          -- left, bottom
            HB = 9          -- horizontally centered, bottom
            RB = 10         -- right, bottom

Variables

    core.e:
        sequence 
            default_pointer -- default compiled rat pointer  
            fonts           -- contains all currently loaded fonts
            mpile           -- keeps track of all currently opened submenus
            pile            -- holds all host widgets
                            -- only the last one (top) is monitored
            rgb             -- holds current rgb mix of sc4; default is RGB

        integer
            rat_event       -- rat moved or a rat button is pressed
            ratx            -- current rat horizontal coordinate
            raty            -- current rat vertical coordinate
            rat_visible     -- boolean, rat pointer visible or hidden (1 or 0)

            burr_flag       -- 0: burr off, 1: burr on
            default_font    -- holds default font handle
            exit_flag       -- when true, the main loop is exited
            mflag           -- when true, collapse_menu routine is called 
            self            -- contains widget associated with the last trapped event

    widgets.e:
        integer
            xsize           -- horizontal dimension of screen
            ysize           -- vertical dimension of screen

Routines

    core.e:
        abs                 -- return absolute value of ab object
        align               -- converts relative x,y coordinates of specified widget
                            -- into absolute using host's x,y coordinates as offsets
        bar                 -- draw filled rectangle
        box                 -- draw rectangular frame
        burr                -- emit aural warning that an illegal operation is attempted
        call_hook           -- creates a hook for a user routine
        clear_flag          -- clear flag in the flag field of widget
        collapse_menu       -- routine to remove submenus
        confine_rat         -- rectangular rat cage
        display             -- recursive routine to display widget as well as all its parts
        dp                  -- debug: dump pretty print of any euphoria oject  
        dump                -- debug: formatted system print
        dw                  -- debug: dump print of widget or sequence of widgets
        flip_flag           -- flip flag in the flag field of widget
        get_flag            -- return current value of flag 
        get_palette         -- return 3-element sequence containing rgb values (0..63)
        go                  -- main system routine
        hide_rat            -- hide rat pointer
        hook                -- associate event of widget with user routine_id rid
        kbd                 -- return true if a special key is activated
        load_font           -- load font from file, return font handle
        loop                -- the main event monitoring loop inside go
        max                 -- return maximal value from one-dimensional sequence
        merge_image         -- display 2-d sequence with nominated 'transparent' color
        min                 -- return minimal value from one-dimensional sequence 
        modal               -- return true if window or mbox is modal
        new                 -- create a new widget and return its handle
        pp                  -- debug: pretty print: any object, with strings in quotes
        quit                -- causes exit from the main loop
        rat                 -- update mouse
        rename              -- rename widget
        replicate           -- return a sequence generated by pattern repetition
        round               -- return value of object rounded towards the nearest integer
        set_flag            -- set flag in the flag field of widget
        set_palette         -- change single color
        set_palettes        -- set contiguous range of colors
        set_system_colors   -- set the first 16 colors as system colors
        shift               -- translates widget by indicated number of pixels in 
                            -- both principal directions 
        show_rat
        strip               -- return sequence stripped of all occurrences of an integer
        sw                  -- debug: screen print of widget or sequence of widgets
        tile                -- return 2-d image of area tiled with given pattern
        track               -- compile rat and key events of widget at top of pile
        track_one           -- special version of track to keep track of specific widget
        wait_while          -- loop while a specified rat event is happening
        when                -- associate event of widget with user routine_id
        when_any            -- associate all events of widget with user routine_id

    widgets.e:
        close_window        -- erase window and remove it from pile
        lengths             -- return sequence of lengths, in pixels, of substrings of text
        open_mbox           -- put mbox on top of pile and display it
        open_window         -- put window on top of pile and display it
        read_file           -- read text file and return it as single text sequence 
        reload_lbox         -- reload lbox with new sequence of strings 
        rewrite             -- reload text widget with a new string and show it
        screen              -- invokes graphics mode
        set_rbutton         -- select rbutton currently deselected
        start_timer         -- insert timer into monitored event queue
        stop_timer          -- remove timer from monitored event queue
        text_dim            -- return text image's over-all dimensions
        text_height         -- return total text image height
        text_image          -- return 2-d image sequence of text 
        text_width          -- return total text image width
        toggle_button       -- default state: 'popped'
        toggle_cbox         -- default: unchecked
        toggle_pbutton      -- default: unchecked

    pal.e:
        free_front          -- return bitmap with unused colors moved to front of palette
        unused              -- return sequence of unused colors in a bitmap

Widgets