| 9srv Manual Collection/plan9/control(2) | 9srv Manual Collection/plan9/control(2) |
|---|
Controls are manipulated by reading and writing to the control channel, ctl, of their Controlset. Channels are defined in thread(2). Each Control has two output channels: Event delivers messages about actions within the control (such as a button press) and data delivers (if requested by an appropriate write to ctl) control-specific data such as the contents of a field.
The library provides a simple mechanism for automatic layout: the minimum and maximum sizes of each simple control can be specified. Boxbox, row, column and stack Controls then use these sizes to lay out their constituent Controls when called upon to do so. See the description of these grouping Controls for further details.
Messages sent to a Controlset are of the form,
The sender (and the colon following it) may be ommitted. For example, the initial field of a text entry control called entry could be set by sending the message,
to its Controlset's ctl file. This message contains the verb value and the single argument Hello, world!
To make it easy to write messages, the function chanprint (see thread(2)) can be used to print formatted text to a Controlset's channel.
The %q and %Q formats are convenient for properly quoting string arguments, as in
It is wise to use %q always instead of %s when sending messages, and avoid dealing with the quoting explicitly. In the other direction, tokenize (see getfields(2)) parses these messages and interprets the quotes correctly.
The destination of a message can be a named control, or a set of controls identified by name or type. The command
(note the quotation) sends the `show' command to the entry named entry and all controls of type slider. If there were a control whose name was slider that control would also be shown.
Note that we are still experimenting with destination names. One proposal is that a destination of the form "`name1 name2 ⋯ type1 type2 ⋯' selects all controls of the named types in the control hierarchies (of columns, rows and stacks) whose names precede the types.
Messages sent by a control on its event channel are of the form
The sender is the name of the control sending the message; the event describes the event. Its format can often be controlled by setting the Control's format string. For example, when the user types a newline at a text entry Control named entry, the control sends the message
Each control is represented by a Control data structure and is associated with a Controlset that groups a set of controls sharing mouse, keyboard, and display. Most applications will need only one Controlset; only those with multiple windows or unusual configurations will need more than one. The function newcontrolset creates a Controlset. Its arguments are the image (usually a window) on which its controls will appear, typically the screen variable in the draw library, and three channels: kc, a channel of Runes from the keyboard; mc, a channel of Mouse structures from the mouse; and rc, a channel of int that indicates when the window has been resized. Any of the channels may be nil, in which case newcontrolset will call initkeyboard and/or initmouse (see keyboard(2) and mouse(2)) to initialize the keyboard and mouse and connect them to the control set. The mouse and resize channels must both be nil or both be non-nil.
The function closecontrolset frees all the controls in the control set and tears down all the associated threads. It does not close the mouse and keyboard.
The public elements of a Controlset are the flag clicktotype, and the ctl and data channels.
Clicktotype is zero by default. If it is set to non-zero, the controls in the set will acquire `focus' by the click-to-type paradigm. Otherwise, focus is always given to the control under the mouse.
Commands for controls are sent through the Controlset's ctl channel. One special command is recognized by the Controlset itself: Sending the string sync to the ctl channel causes tha string to be echoed to the Controlset's data channel when all commands up to the sync command have been processed. The string is allocated and must be freed (see malloc(2)). Synchronization is necessary between sending a command, for example, to resize all controls, and using their rect fields.
The function resizecontrolset must be provided by the user. When the associated window is resized, the library will call resizecontrolset with the affected Controlset; the function should reconnect to and redraw the window.
If all windows are organized in a hierachy of boxboxes, columns, rows and stacks, and minimum and maximum sizes have already been supplied, only the top control needs to be resized (see the rect command below).
The function initcontrols establishes name bindings for all the colors mentioned in <draw.h>, such as black, white, red, yellow, etc., as well as masks transparent and opaque. It also sets the name font to refer to the default font variable set up by initdraw.
The function controlcalled returns a pointer to the Control with the given name, or nil if no such control exists.
Messages sent to the ctl channel are delivered to all controls that match the destination field. This field is a set of names separated by spaces, tabs or newlines. A control matches the destination if its name or its type is among the set.
The recipient of a message ignores the initial sender: field of the message, if present, making it possible to send messages generated on an event channel directly to another control's ctl channel.
To enable a control, call the activate function, which specifies that the Control c should respond to mouse and keyboard events; deactivate turns it off again.
Controls can be either revealed (default) or hidden. When a control is hidden, it will not receive mouse or keyboard events and state changes or show commands will be ignored until the control is once again revealed. Control hiding is particularly useful when different controls are overlayed, revealing only the `top' one.
The function controlwire permits rearrangement of the channels associated with a Control. The channel cname (one of "data" or "event") of Control c is reassigned to the channel ch. There are several uses for this operation: one may reassign all the event channels to a single channel, in effect multiplexing all the events onto a single channel; or connect the event channel of a slider to the ctl channel for delivery to a text display (after setting the format for the slider's messages to name the destination control and the appropriate syntax for the rest of the command) to let the slider act as a scroll bar for the text without rerouting the messages explicitly.
All controls accept the following messages:
Many messages are common between multiple Controls. Such messages are described in detail here to avoid repetition. In the individual descriptions, only the syntax is presented.
where nn is the hexadecimal value of the character. Mouse messages are sent in the format
where x, y, but, and msec are the various fields of the Mouse structure. The focus message is just
where n is 0 if the box has lost focus, 1 if it has acquired it.
The box displays within its rectangle an image, under mask, with specified alignment. The control messages it accepts are:
The button displays an image (which may of course be a simple color) and illuminates in the standard way when it is `on'. The control messages it accepts are:
with s the complete text of the entry box.
The cursor can be moved by clicking button 1; at the moment, there is no way to select characters, only a typing position. Some control characters have special actions: control-H (backspace) deletes the character before the cursor; control-U clears the line; and control-V pastes the snarf buffer at the typing position. Most important, carriage return sends the text to the event channel.
To enter passwords and other secret text without displaying the contents, set the font to one in which all characters are the same. The easiest way to do this is to make a font containing only one character, at position 0 (NUL), since that position is used to render all characters not otherwise defined in the font (see draw(2)). The file /lib/font/bit/lucm/passwd.9.font defines such a font.
The control messages the entry control accepts are:
where nn is the hexadecimal Unicode value of the character. Shift, control, and caps lock are handled by the keyboard control itself; shift and control affect only the next regular keystroke. The Alt key is unimplemented; it will become equivalent to the standard Plan 9 key for synthesizing non-ASCII characters.
There are two special keys, Scrib and Menu, which return values 0x10000 and 0x10001.
The image, mask, light rules are used to indicate that a key is pressed, but to aid clumsy fingers the keystroke is not generated until the key is released, so it is possible to slide the pointer to a different key to correct for bad aim.
The control messages the keyboard accepts are:
If no selection is made, no message is reported. Because it creates a window, programs using a menu must have their screen variable (see graphics(2) and window(2)) set up to be refreshed properly. The easiest way to do this is to call getwindow with refresh argument Refbackup (see graphics(2)); most programs use Refnone.
The control messages accepted by a menu are:
Buttons are added to the radio button using the add message; there is no way to remove them, although they may be turned off independently using deactivate. The index reported in the value is defined by the order in which the buttons are added. The constituent buttons should be configured and layed out in the usual way; the rectangle of the radiobutton is used only to `catch' mouse events and should almost always correspond to the bounding box of the constituent buttons. In other words, the geometry is not maintained automatically.
The control messages the radiobutton accepts are:
The control messages it accepts are:
The control messages it accepts are:
The control messages it accepts are:
The slider is a good candidate for connecting to another control by setting its format and rewiring its event channel to the other's ctl channel.
The geometry of the slider is defined by three numbers: max is a number representing the range of the slider; vis is a number representing how much of what is being controlled is visible; and value is a number representing the value of the slider within its range. For example, if the slider is managing a textual display of 1000 lines, with 18 visible, and the first visible line (numbered starting form 0) is 304, max will be 1000, vis will be 18, and value will be 304. The indicator is the visual representation of the vis portion of the controlled object.
The control messages the slider accepts are:
Control messages are
states that line n has changed its selection state to s, either zero (unselected) or non-zero (selected). The non-zero value encodes the mouse buttons that were down when the selection occurred.
The control messages the text control accepts are:
where n encodes the mouse buttons used to make the selection.
Like a regular button, the value of a textbutton is an integer; the text is the string that appears in the button. It uses the image, light, mask method of indicating its state; moreover, the color of the text can be set to change when the button is pressed. The control messages it accepts are:
The functions ctlmalloc, ctlrealloc, ctlstrdup, and ctlrunestrdup are packagings of the corresponding C library functions. They call ctlerror if they fail to allocate memory, and ctlmalloc zeros the memory it returns.
Finally, for debugging, if the global variable ctldeletequits is set to a non-zero value, typing a DEL will cause the program to call
One unusual design goal of this library was to make the controls themselves easy to implement. The reader is encouraged to create new controls by adapting the source to existing ones.
A richer variant couples a text entry box to a slider. Since the value of a slider is its numerical setting, as a decimal number, all that needs changing is the setup of bot:
The rest is the same. Of course, the value of the entry box is only meaningful to the slider if it is also a decimal number.
Finally, we can avoid processing events altogether by cross-coupling the controls. Replace the rest of threadmain with this:
| 9srv Manual Collection/plan9/control(2) | Rev: Sun Mar 30 22:48:25 BST 2008 |