5 DUIM-Sheets Library

5.1 Overview

The elements that comprise a Graphical User Interface (GUI) are arranged in a hierarchical ordering of object classes. At the top level of the DUIM hierarchy there are three main classes, <sheet>, <gadget>, and <frame>, all of which are subclasses of <object>.

Sheets are the most basic visual GUI element, and can be any unique part of a window: either a control such as a gadget or pane, or a layout.

Sheets have a visual presence: size, drawing context and so on.
The essential component of a sheet is its region; the area of the screen that the sheet occupies.
In practice sheets always also have a transform that maps the coordinate system of the sheet's region to the coordinate system of its parent, because in practice all sheets maintain a pointer to a parent sheet.
Sheets can be output-only (labels, for example), input-output (most gadgets are like this) or even, in principle, input-only (for instance, you may need to provide some kind of simple drag'n'drop target).

Most of the sheet classes that you need to use on a day to day basis are exposed in the DUIM-Gadgets and DUIM-Layouts libraries. The DUIM-Sheets library contains the basic building blocks to implement these classes, as well as providing the necessary functionality for you to create and manipulate your own classes of sheet. In addition, DUIM-Sheets defines a portable model for handling events. These event handling routines are used by the DUIM-Frames, DUIM-Gadgets, and DUIM-Layouts libraries without the need for any special action on your part. However, if you need to define your own sheet classes, you will also need to handle events occurring within those classes.

The DUIM-Sheets library contains a single module, duim-sheets, from which all the interfaces described in this chapter are exposed. Section 5.3 on page 207 contains complete reference entries for each exposed interface.

A sheet is the basic unit in a DUIM window. Inside any window, sheets are nested in a parent-child hierarchy. All sheets have the following attributes:

sheet-region, expressed in the sheet's own coordinate system.
sheet-transform, which maps the sheet's coordinate system to the coordinate system of its parent.
sheet-parent, which is #f if the sheet has no parent.
sheet-mapped?, which tells if the sheet is visible on a display, ignoring issues of occluding windows.

The sheet-transform is an instance of a concrete subclass of <transform>. The sheet-region can be an instance of any concrete subclass of <region>, but is usually represented by the region class <bounding-box>.

Some sheets (menu bars, button boxes, or tool bars, for instance) also have single or multiple children, in which case they have additional attributes:

A sheet-children slot. This is a sequence of sheets. Each sheet in the sequence is a child of the current sheet.
Methods to add, remove, and replace a child.
Methods to map over children.

The functions that maintain the sheet's region and transform are part of the sheet-geometry protocol. Functions that maintain a sheet's parent and children are part of the sheet-genealogy protocol. Note that the sheet geometry and genealogy protocols are independent. Adding a child to a sheet that is larger than its parent does not cause the parent's region to grow. Shrinking the region of a parent does not cause the children to shrink. You must maintain the region yourself, either by explicitly setting the sheet's region and transform, or by using the layout facilities (compose-space and allocate-space).

As a convenience, there are some glue functions that mediate between geometry and layout: set-sheet-position, set-sheet-size, and set-sheet-edges.

Some classes of sheet can receive input. These have:

A sheet-event-queue slot.
Methods for <handle-event>.

Sheets that can be repainted have methods for handle-repaint.

Sheets that can do output, have a sheet-medium slot.

Some sheets act as controls such as push buttons, scroll bars, and sliders. These are represented by the <gadget> class and its subclasses.

Other sheets act as layout controls, which allow you to specify how the elements in a sheet are laid out, whether they are placed vertically or horizontally, whether they are left, right, or center-aligned, and so on. These are represented by the <layout> class and its subclasses, and are described in Chapter 7, "DUIM-Layouts Library".

A sheet can be associated with a <display>, which is an object that represents a single display (or screen) on some display server.

A display (and all the sheets attached to the display) is associated with a <port> that is a connection to a display server. The port manages:

a primary input device, such as a keyboard.
a pointing device, such as a mouse.
an event processor that dispatches events to the appropriate sheet.

There is a protocol for using the Windows clipboard. In order to manipulate the Windows clipboard from within DUIM, the clipboard needs to be locked, so that its contents can be manipulated. DUIM uses the functions open-clipboard and close-clipboard to create and free clipboard locks. The open-clipboard function creates an instance of the class <clipboard> which is used to hold the contents of the clipboard for the duration of the lock. For general use of the clipboard, use the macro with-clipboard, rather than calling open-clipboard and close-clipboard explicitly. This lets you manipulate the clipboard easily, sending the results of any code evaluated to the clipboard.

Once a clipboard lock has been created, you can use add-clipboard-data and add-clipboard-data-as to add data to the clipboard. Use get-clipboard-data-as to query the contents of the clipboard, and use clear-clipboard to empty the locked clipboard. Finally, use clipboard-data-available? to see if the clipboard contains data of a particular type.

You can put arbitrary Dylan objects onto the clipboard, and retrieve them within the same process. This gives you the ability to cut and paste more interesting pieces of an application within the application's own domain than would normally be possible.

The DUIM GUI test suite contains a demonstration of how to use the clipboard in DUIM, in the file

Examples\duim\duim-gui-test-suite\clipboard.dylan

in the Functional Developer installation directory.