tmdate(2): correct example in manpage

[plan9front.git] / sys / man / 2 / control

.TH CONTROL 2
.SH NAME
Control,
Controlset,
activate,
closecontrol,
closecontrolset,
controlcalled,
controlwire,
createbox,
createboxbox,
createbutton,
createcolumn,
createentry,
createkeyboard,
createlabel,
createmenu,
createradiobutton,
createrow,
createscribble,
createslider,
createstack,
createtab,
createtext,
createtextbutton,
ctlerror,
ctlmalloc,
ctlrealloc,
ctlstrdup,
ctlprint,
deactivate,
freectlfont,
freectlimage,
initcontrols,
namectlfont,
namectlimage,
newcontrolset,
resizecontrolset
\- interactive graphical controls
.SH SYNOPSIS
.EX
.ta 4n +4n +4n +4n +4n +4n +4n
#include <u.h>
#include <libc.h>
#include <draw.h>
#include <thread.h>
#include <keyboard.h>
#include <mouse.h>
#include <control.h>
.sp 0.3
typedef struct Control Control;
typedef struct Controlset Controlset;
.sp 0.3
struct Control
{
        char            *name;
        Rectangle       rect;   /* area on screen */
        Rectangle       size;   /* min/max Dx, Dy (not a rect) */
        Channel *event; /* chan(char*) to client */
        Channel *data;  /* chan(char*) to client */
        \&...
};
.sp 0.3
struct Controlset
{
        \&...
        Channel         *ctl;
        Channel         *data;
        \&...
        int     clicktotype;
        \&...
};
.sp 0.3
void            initcontrols(void)
.sp 0.3
Controlset*     newcontrolset(Image *i, Channel *kc, Channel *mc, Channel *rc)
.sp 0.3
void            closecontrolset(Controlset *cs)
.sp 0.3
int             namectlfont(Font *font, char *name)
.sp 0.3
int             freectlfont(char *name)
.sp 0.3
int             namectlimage(Image *image, char *name)
.sp 0.3
int             freectlimage(char *name)
.sp 0.3
Control*        createbox(Controlset *cs, char *name)
.sp 0.3
Control*        createboxbox(Controlset *cs, char *name)
.sp 0.3
Control*        createbutton(Controlset *cs, char *name)
.sp 0.3
Control*        createcolumn(Controlset*, char*)
.sp 0.3
Control*        createentry(Controlset *cs, char *name)
.sp 0.3
Control*        createkeyboard(Controlset *cs, char *name)
.sp 0.3
Control*        createlabel(Controlset *cs, char *name)
.sp 0.3
Control*        createmenu(Controlset *cs, char *name)
.sp 0.3
Control*        createradiobutton(Controlset *cs, char *name)
.sp 0.3
Control*        createrow(Controlset*, char*)
.sp 0.3
Control*        createscribble(Controlset *cs, char *name)
.sp 0.3
Control*        createslider(Controlset *cs, char *name)
.sp 0.3
Control*        createstack(Controlset*, char*)
.sp 0.3
Control*        createtab(Controlset*, char *)
.sp 0.3
Control*        createtext(Controlset *cs, char *name)
.sp 0.3
Control*        createtextbutton(Controlset *cs, char *name)
.sp 0.3
void            closecontrol(Control *c)
.sp 0.3
int             ctlprint(Control*, char*, ...);
.sp 0.3
void            ctlerror(char *fmt, ...)
.sp 0.3
Control*        controlcalled(char *name)
.sp 0.3
void            controlwire(Control *c, char *cname, Channel *ch)
.sp 0.3
void            activate(Control *c)
.sp 0.3
void            deactivate(Control *c)
.sp 0.3
void            resizecontrolset(Controlset *cs)
.sp 0.3
void*           ctlmalloc(uint n)
.sp 0.3
void*           ctlrealloc(void *p, uint n)
.sp 0.3
char*           ctlstrdup(char *s)
.sp 0.3
int             ctldeletequits;
.EE
.SH DESCRIPTION
This library provides a set of interactive
controls for graphical displays: buttons, sliders, text entry boxes, and so on.
It also provides aggregator
.BR Control s:
boxes, columns, rows and stacks of
.BR Control s.
A stack is a collection of co-located
.BR Control s,
of which one is normally visible.
A
.B Controlset
collects a group of
.BR Control s
that share mouse and keyboard.  Each
.B Controlset
has a separate thread of control that processes keyboard and mouse events as
well as commands to be passed on to the
.BR Control s.
Since each
.B Controlset
uses a thread, programs using the control library must
be linked with the thread library,
.IR thread (2).
.PP
.BR Control s
are manipulated by reading and writing to the control channel,
.BR ctl ,
of their
.BR Controlset .
.BR Channel s
are defined in
.IR thread (2).
Each
.B Control
has two output channels:
.B Event
delivers messages about actions within the control (such as a button press) and
.B data
delivers (if requested by an appropriate write to
.BR ctl )
control-specific data such as the contents of a field.
.PP
The library provides a simple mechanism for automatic layout:
the minimum and maximum sizes of each simple control can be specified.
.BR Boxbox ,
.BR row ,
.B column
and
.B stack
.BR Control s
then use these sizes to lay out their constituent
.BR Control s
when called upon
to do so.  See the description of these grouping
.BR Control s
for further details.
.SS "Message format
All messages are represented as
.SM UTF\c
-8
text.
Numbers are formatted in decimal, and strings are transmitted in the
quoted form of
.IR quote (2).
.PP
Messages sent to a
.B Controlset
are of the form,
.IP
.IR sender :
.I destination
.I verb
.RI [ argument
\&... ]
.LP
The sender (and the colon following it) may be omitted.
For example, the initial field of a text entry control called
.I entry
could be set by sending the message,
.IP
.B "entry value 'Hello, world!'
.PP
to its
.BR Controlset 's
.B ctl
file.
This message contains the verb
.B value
and the single argument
.B "Hello, world!"
.PP
To make it easy to write messages, the function
.IR chanprint
(see
.IR thread (2))
can be used to print formatted text to a
.BR Controlset 's
channel.
.PP
The
.B %q
and
.B %Q
formats are convenient for properly quoting string arguments,
as in
.IP
.EX
chanprint(e->event, "value %q", "Don't touch!");
.EE
.PP
It is wise to use
.B %q
always instead of
.BR %s
when sending messages, and avoid dealing with the quoting explicitly.
In the other direction,
.B tokenize
(see
.IR getfields (2))
parses these messages and interprets the quotes correctly.
.PP
The destination of a message can be a named control, or a set of controls identified
by name or type.  The command
.IP
.B "'entry slider' show
.PP
(note the quotation) sends the `show' command to the entry named
.I entry
and all controls of type
.IR slider .
If there were a control whose name was
.I slider
that control would also be shown.
.LP
\f2
Note that we are still experimenting with destination names.
One proposal is that
a destination of the form
\fR"`name1 name2 ⋯ type1 type2 ⋯'\fP
selects all controls of the named types in the control hierarchies (of columns, rows and
stacks) whose names precede the types.
.LP
Messages sent by a control on its
.B event
channel are of the form
.IP
.IB sender :
.IB event
.PP
The
.I sender
is the name of the control sending the message;
the
.I event
describes the event.  Its format can often be controlled by setting the
.BR Control 's
.IR "format string" .
For example, when the user types a newline at a text entry
.B Control
named
.BR entry,
the control sends the message
.IP
.B entry:\ value\ 'Hello\ again!'
on its
.B event
channel.
.SS "Initialization and Control sets
After
.B initdraw
(see
.IR graphics (2))
is called,
the function
.I initcontrols
should be called to initialize the library.
It calls
.I quotefmtinstall
to install the
.B %q
and
.B %Q
formats; see
.IR quote (2).
.PP
Each control is represented by a
.B Control
data structure and is associated with a
.B Controlset
that groups a set of controls sharing mouse, keyboard, and display.
Most applications will need only one
.BR Controlset ;
only those with multiple windows or unusual configurations will need
more than one.
The function
.I newcontrolset
creates a
.BR Controlset .
Its arguments are the image (usually a window)
on which its controls will appear, typically the
.B screen
variable in the draw library, and three channels:
.BR kc ,
a channel of
.B Runes
from the keyboard;
.BR mc ,
a channel of
.B Mouse
structures from the mouse;
and
.BR rc ,
a channel of
.B int
that indicates when the window has been resized.
Any of the channels may be nil,
in which case
.I newcontrolset
will call
.B initkeyboard
and/or
.B initmouse
(see
.IR keyboard (2)
and
.IR 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.
.PP
The function
.I closecontrolset
frees all the controls in the control set and tears down all the associated threads.
It does not close the mouse and keyboard.
.PP
The public elements of a
.B Controlset
are the flag
.BR clicktotype ,
and the
.I ctl
and
.I data
channels.
.PP
.I 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.
.PP
Commands for controls are sent through the
.BR Controlset 's
.I ctl
channel.
One special command is recognized by the
.B Controlset
itself:  Sending
the string
.B sync
to the
.I ctl
channel causes that string to be echoed to the
.BR Controlset 's
.I data
channel when all commands up to the
.I sync
command have been processed.  The string is
allocated and must be freed (see
.IR malloc (2)).
Synchronization is necessary between sending a command, for example, to resize
all controls, and using their
.I rect
fields.
.PP
The function
.I resizecontrolset
must be provided by the user.
When the associated window is resized, the library will call
.I resizecontrolset
with the affected
.BR Controlset ;
the function should reconnect to and redraw the window.
.PP
If all windows are organized in a hierachy of
.IR boxboxes ,
.IR columns ,
.I rows
and
.IR stacks ,
and minimum and maximum sizes have already been supplied, only
the top control needs to be resized (see the
.I rect
command below).
.SS "Fonts and images
Fonts and images must be given names so they may be referenced
in messages.
The functions
.I namectlfont
and
.I namectlimage
associate a (unique) name with the specified font or image.
The association is removed by
.I freectlfont
and
.IR freectlimage .
The font or image is not freed by these functions, however.
.PP
The function
.I initcontrols
establishes name bindings for all the colors mentioned in
.BR <draw.h> ,
such as
.BR black ,
.BR white ,
.BR red ,
.BR yellow ,
etc., as well as masks
.B transparent
and
.BR opaque .
It also sets the name
.B font
to refer to the default
.B font
variable set up by
.BR initdraw .
.SS Creation
Each type of control has an associated creation function:
.IR createbutton ,
.IR createentry ,
etc.,
whose arguments are the
.B Controlset
to attach it to and a globally unique name for it.
A control may be destroyed by calling
.IR closecontrol .
.PP
The function
.I controlcalled
returns a pointer to the
.B Control
with the given
.IR name ,
or nil if no such control exists.
.SS Configuration
After a control is created, it must be configured using the control-specific
commands documented below.
Commands are sent to the
.B ctl
channel of the
.BR Controlset .
Multiple commands may be sent in a single message; newline characters
separate commands.
For an example, see the implementation of
.I resizecontrolset
in the
.B EXAMPLES
section.
Note that newline is a separator, not a terminator; the final command
does not need a newline.
.PP
Messages sent to the
.I ctl
channel are delivered to all controls that match the
.I 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.
.PP
The recipient of a message ignores the initial
.IB sender :
field of the message, if present,
making it possible to send messages generated on an
.B event
channel directly to another control's
.B ctl
channel.
.SS Activation
When they are created, controls are disabled: they do not respond to
user input.
Not all controls need to be responsive;
for example, labels are static and a text display
might show a log of messages but not be useful to edit.
But buttons, entry boxes, and other text displays should be active.
.PP
To enable a control, call the
.I activate
function, which
specifies that the
.B Control
.I c
should respond to mouse and keyboard events;
.I deactivate
turns it off again.
.PP
Controls can be either
.I revealed
(default) or
.IR hidden .
When a control is hidden, it will not receive mouse or keyboard events
and state changes or
.I show
commands will be ignored until the control is once again
.IR revealed .
Control hiding is particularly useful when different controls are overlayed,
revealing only the `top' one.
.PP
The function
.I controlwire
permits rearrangement of the channels associated with a
.BR Control .
The channel
.I cname
(one of
\f5"data"\fP
or
\f5"event"\fP)
of
.B Control
.I c
is reassigned to the channel
.IR ch .
There are several uses for this operation:
one may reassign all the
.B event
channels to a single channel, in effect multiplexing all the events onto
a single channel;
or connect the
.B event
channel of a slider to the
.B 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.
.SS Controls
The following sections document the individual controls in alphabetical order.
The layout of each section is a brief description of the control's behavior,
followed by the messages it sends on
.BR event ,
followed by the messages it accepts via the
.B ctl
channel.
The
.B event
messages are triggered
.I only
by mouse or keyboard action; messages to the
.B ctl
file do not cause events to be generated.
.PP
All controls accept the following messages:
.TF \fLreveal
.TP
.BI rect " minx miny maxx maxy
Set the bounding rectangle for the control on the display.
The syntax generated by the
.B %R
print format of the draw library is also acceptable for the coordinates.
.TP
.BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ]
Set the minimum and maximum size for automatic layout in
.IR columns ,
.I rows
and
.IR stacks .
Without its four arguments, this command is ignored by primitive controls
and used by grouping controls to calculate their minimum and maximum sizes
by examining those of their constituent members.
If all primitive controls have been assigned a size, a single size request addressed
to the top of a layout hierarchy will assign sizes to all grouping
.BR Control s.
.TP
.B hide
Disable drawing of the control and ignore mouse and keyboard events
until the control is once again revealed.
Grouping
.BR Control s
(\f2column\fP, \f2row\fP, and \f2stack\fP) pass the
request down to their constituent
.BR Control s.
.TP
.B reveal
This is the opposite of
.BR hide :
the
.B Control
is displayed and mouse and keyboard operations resume.
Grouping
.BR Control s
(\f2column\fP, \f2row\fP, and \f2stack\fP) pass the
request down to their constituent
.BR Control s.
The
.B reveal
command for
.I stacks
takes an optional argument naming the
.B Control
to be revealed; all
other
.BR Control s
will be hidden.
.TP
.B show
Display the
.B Control
on its screen if not hidden.
Some actions will also cause the
.BR Control s
to show themselves automatically
(but never when the
.B control
is hidden).
Grouping
.BR Control s
(\f2column\fP, \f2row\fP, and \f2stack\fP) pass the
request down to their constituent
.BR Control s.
.PD
.PP
Many messages are common between multiple
.BR Control s.
Such messages are described in detail here to avoid repetition.
In the individual descriptions, only the syntax is presented.
.TF "\fLformat fmt"
.TP
.BI align " n
Specify the alignment of (some part of) the
.BR Control 's
display within its rectangle.
For textual
.BR control s,
the alignment specifies where the text should appear.
For multiline text, the alignment refers to each line within its box,
and only the
horizontal part is honored.
For other
.BR Control s,
the alignment affects the appearance of the display in
a reasonable way.
The valid alignments are words with obvious interpretations:
.BR upperleft ,
.BR uppercenter ,
.BR upperright ,
.BR centerleft ,
.BR center ,
.BR centerright ,
.BR lowerleft, 
.BR lowercenter ,
and
.BR lowerright .
.TP
.BI border " n
Inset the
.B Control
(or separate constituent
.BR Control s
in
.IR boxbox ,
.I column
and
.I row
.BR Control s
after the next
.I rect
command) within its rectangle by
.I n
pixels, default zero.
.TP
.BI bordercolor " name
Paint the border of the control with the named color, default black.
.TP
.BI focus " n
The
.B Control
now has (if
.I n
is non-zero) or does not have ( if
.I n
is zero) focus.
Most
.BR Control s
ignore the message; there are plans to make them react.
.TP
.BI format " fmt
Set the format of `value' messages sent on the
.B event
channel.
By default, the format is
.B \&"%q: value %q"
for string-valued
.BR Control s,
.B \&"%q: value %d"
for integer-valued
.B Control s
such as buttons,
and
.B \&"%q: value 0x%x"
for the keyboard and scribble
.BR Control s.
The
.B %q
prints the name of the
.BR Control ;
the rest the value.
Any supplied format string must be type-equivalent to the default for that
.BR Control . 
.TP
.BI image " name
.TP
.BI light " name
.TP
.BI mask " name
Many controls set a background image or color for display.
The
.B image
message sets the image.
The
.B mask
and
.B light
images together specify how the
.B Control
shows it is enabled:
the
.B light
is printed through the
.B mask
when the state is `on' or `pressed'.
Otherwise, the image appears unmodified.
The default image is white; mask opaque; light yellow.
.TP
.BI font " name
.TP
.BI textcolor " name
These commands set the font and color for displaying text.
The defaults are the default
.B font
set up by the draw library, and black.
.TP
.BI value " v
Set the value of the
.BR Control .
Textual images accept an arbitrary string;
others an integral value.
.SS Box
A box is a trivial control that does nothing more than pass keyboard, mouse,
and focus messages back on its
.B event
channel.
Keyboard characters are sent in the format
.IP
.EX
boxname: key 0x\f2nn
.EE
.PP
where
.I nn
is the hexadecimal value of the character.
Mouse messages are sent in the format
.IP
.EX
boxname: mouse [\f2x\fP \f2y\fP] \f2but\fP \f2msec\fP
.EE
.PP
where
.IR x ,
.IR y ,
.IR but ,
and
.I msec
are the various fields of the
.B Mouse
structure.
The focus message is just
.IP
.EX
boxname: focus \f2n\f1
.EE
.PP
where
.I n
is 0 if the box has lost focus, 1 if it has acquired it.
.PP
The box displays within its rectangle
an image, under mask, with specified alignment.
The control messages it accepts are:
.TF "\fLalign a"
.TP
.BI align " a
Controls the placement of the image in the rectangle (unimplemented).
.TP
.BI border " b
.TP
.BI bordercolor " name
.TP
.BI focus " n
.TP
.BI hide
.TP
.BI image " name
.TP
.BI rect " minx miny maxx maxy
.TP
.BI reveal
.TP
.BI show
.TP
.BI size " minΔx minΔy maxΔx maxΔy
.PD
.SS Boxbox
A
.B boxbox
allows a set of controls (``boxes'')
to be displayed in rows and columns within the
rectangle of the
.IR boxbox .
The maximum of the minimum heights of the constituent controls determines the
number of rows to be displayed.  The number of columns is the minimum that
allows all
.BR Control s
to be displayed.  This aggregator works well for collections
of buttons, labels, or textbuttons that all have a fixed height.
.TF "\fLadd name ..."
.TP
.BI add " name ...
adds the named control to the box of controls.  The display order
is determined by the order of adding.  The first named control is top left,
the second goes below it, etc.
It is possible to add one control to multiple grouping controls but
the layout of the result will be quite unpredictable.
.TP
.BI border " width
.TP
.BI bordercolor " color
.TP
.B hide
This command is passed on to the member controls.
.TP
.BR image " color
Background color displayed between member controls.
.TP
.B reveal
This command is passed on to the member controls.
.TP
.BI separation " width
Set the separation between member controls to
.I n
pixels.
.TP
.BI rect " minx miny maxx maxy
The member controls are layed out within the given rectangle according to
the minimum and maximum sizes given.  If the rectangle is not large enough
for the minimum a fatal error is currently generated.
If the controls at their maximum size are not big enough to fit, they are top-left justified
at their maximum size in the space given.
Otherwise, controls will get their minimum size and be enlarged proportional
to the extra size given by the maximum until they fit given rectangle.
The members are separated by borders of the width established by
.IR borderwidth .
.TP
.BI remove " name
Remove the named
control from the box.
.TP
.B show
This command is passed on to the member controls.
Show also (re)displays background and borders.
.TP
.BR size " \f2minΔx minΔy maxΔx maxΔy\fP
.PD
.SS Button
A button is a simple control that toggles its state when mouse button 1 is pressed on its rectangle.
Each state change triggers an event message:
.IP
.EX
buttonname: value \f2n\fP
.EE
where
.I n
encodes the mouse buttons used to make the selection.
.PP
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:
.TF "\fLborder b"
.TP
.BI align " a
Controls the placement of the image in the rectangle (unimplemented).
.TP
.BI border " b
.TP
.BI bordercolor " name
.TP
.BI focus " n
.TP
.BI format " fmt
.TP
.BI hide
.TP
.BI image " name
.TP
.BI light " name
.TP
.BI mask " name
.TP
.BI rect " minx miny maxx maxy
.TP
.BI reveal
.TP
.B show
.TP
.BI size " minΔx minΔy maxΔx maxΔy
.TP
.BI value " n
Set the button to `on' (if
.I n
is non-zero) or `off' (if
.I n
is zero).
.PD
.SS Column
A column is a grouping control which lays out its members vertically,
from top to bottom.  Currently, columns ignore mouse and keyboard
events, but there are plans to allow dragging the borders (when they
have non-zero width) between constituent members.
.TF "\fLadd name .."
.TP
.BI add " name ...
adds the named control to the column of controls.  The vertical order
is determined by the order of adding.  The first named control goes at
the top.  It is possible to add one control to multiple grouping controls but
the layout of the result will be quite unpredictable.
.TP
.BI border " width
Set the border between members to the width given.
.TP
.BI bordercolor " color
.TP
.B hide
.TP
.BR image " color
Background color displayed between member controls.
.TP
.B reveal
.TP
.BI separation " width
Set the separation between member controls to
.I n
pixels.
.TP
.B show
These three commands are passed on to the member controls.
Show also (re)displays the borders between members.
.TP
.BI rect " minx miny maxx maxy
The member controls are layed out within the given rectangle according to
the minimum and maximum sizes given.  If the rectangle is not large enough
for the minimum a fatal error is currently generated.  However, see the example
at the end of this man page.
If the controls at their maximum size are not big enough to fit, they are centered
at their maximum size in the space given.
Otherwise, controls will get their minimum size and be enlarged proportional
to the extra size given by the maximum until they fit given rectangle.
The members are separated by borders of the width established by
.IR borderwidth .
.TP
.BI remove " name
Remove the named control from the column.
.TP
.BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ]
Without arguments, this command computes the minimum and
maximum size of a column by adding the minimum and maximum
heights to set
.I minΔy
and
.IR maxΔy ,
and it finds the largest minimum and maximum widths to set
.I minΔy
and
.IR maxΔy .
When called with arguments, it simply sets the minimum and maximum
sizes to those given.
.PD
.SS Entry
The entry control manages a single line of editable text.
When the user hits a carriage return anywhere
in the text, the control generates the event message,
.IP
.EX
entryname: value \f2s\fP
.EE
.PP
with
.I s
the complete text of the entry box.
.PP
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.
.PP
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
.IR draw (2)).
The file
.B /lib/font/bit/lucm/passwd.9.font
defines such a font.
.PP
The control messages the entry control accepts are:
.TF "\fLborder b"
.TP
.BI align " a
Controls the placement of the text in the rectangle.
.TP
.BI border " b
.TP
.BI bordercolor " name
.TP
.BI data
After receiving this message, the entry will send its value to its
.B data
channel as an unadorned, unquoted string.
.TP
.BI focus " n
When it receives focus, the entry box displays a typing cursor.
When it does not have focus, the cursor is not displayed.
.TP
.BI font " name
.TP
.BI format " fmt
.TP
.BI hide
.TP
.BI image " name
.TP
.BI rect " minx miny maxx maxy
.TP
.B reveal
.TP
.B show
.TP
.BI size " minΔx minΔy maxΔx maxΔy
.TP
.BI textcolor " name
.TP
.BI value " s
Set the string displayed in the entry box.
.PD
.SS Keyboard
The keyboard control implements a simulated keyboard useful on palmtop devices.
Keystrokes, generated by mouse button 1 on the simulated keys,
are sent as event messages:
.IP
.EX
keyboardname: value 0x\f2nn\f1
.EE
.PP
where
.I 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.
.PP
There are two special keys,
.B Scrib
and
.BR Menu ,
which return values
.B 0x10000
and
.BR 0x10001 .
.PP
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.
.PP
The control messages the keyboard accepts are:
.TF "\fLfont"
.TP
.BI border " b
.TP
.BI bordercolor " name
.TP
.BI focus " n
.TP
.BI font " name1 name2
Sets the font for the keys.
If only one font is named, it is used for all keys.
If two are named, the second is used for key caps with special names such
as Shift and Enter.
(Good choices on the Bitsy are
.B /lib/font/bit/lucidasans/boldlatin1.6.font
for the first and
.B /lib/font/bit/lucidasans/unicode.6.font
for the second argument.)
If neither is specified, both will be set to the default global font.
.TP
.BI format " fmt
.TP
.BI hide
.TP
.BI image " name
.TP
.BI light " name
.TP
.BI mask " name
.TP
.BI rect " minx miny maxx maxy
.TP
.BI reveal
.TP
.B show
.TP
.BI size " minx miny maxx maxy
.PD
.SS Label
A label is like a textbutton
.RI ( q.v. )
that does not react, but whose value is the text it displays.
The control messages it accepts are:
.TF "\fLvalue s"
.TP
.BI align " a
Controls the placement of the image in the rectangle.
.TP
.BI border " b
.TP
.BI bordercolor " name
.TP
.BI focus " n
.TP
.BI font " name
.TP
.BI hide
.TP
.BI image " name
.TP
.BI rect " minx miny maxx maxy
.TP
.BI reveal
.TP
.B show
.TP
.BI size " minx miny maxx maxy
.TP
.BI textcolor " name
.TP
.BI value " s
The value is a string that can be modified only by sending this message to the
.B ctl
file.
.PD
.SS Menu
A menu is a pop-up window containing a set of textual selections.
When a selection is made, it removes itself from the screen and reports the selection
by value:
.IP
.EX
menuname: value \f2n\fP
.EE
.PP
If no selection is made, no message is reported.
Because it creates a window, programs using a menu must have their
.B screen
variable (see
.IR graphics (2)
and
.IR window (2))
set up to be refreshed properly.
The easiest way to do this is to call
.B getwindow
with refresh argument
.B Refbackup
(see
.IR graphics (2));
most programs use
.BR Refnone .
.PP
The control messages accepted by a menu are:
.TF "\fLwindow n"
.TP
.BI add " text
Add a line of
.I text
to the end of the menu.
.TP
.BI align " a
Controls the left-right placement of the text in its rectangle.
.TP
.BI border " b
.TP
.BI bordercolor " name
.TP
.BI focus " n
.TP
.BI font " name
.TP
.BI format " fmt
.TP
.BI hide
.TP
.BI image " name
.TP
.BI rect " minx miny maxx maxy
.TP
.BI reveal
.TP
.BI size " minx miny maxx maxy
Only the origin of the rectangle is significant; menus calculate the appropriate size.
.TP
.BI selectcolor " name
Set the color in which to highlight selected lines; default yellow.
.TP
.BI selecttextcolor " name
Set the color in which to draw the text in selected lines; default black.
.TP
.B show
Display the menu. Not usually needed unless the menu is changed while visible; use
.I window
instead.
.TP
.B window
.TP
.BI window " n
With no arguments, toggle the menu's visibility; otherwise make it visible (1) or invisible (0).
When the selection is made, the menu will remove its window automatically.
.PD
.SS Radiobutton
The radiobutton assembles a group of buttons or textbuttons into a
single control with a numeric value.
Its value is \-1 if none of the constituent buttons is pressed; otherwise
it is the index, starting at zero, of the button that is pressed.
Only one button may be pressed; the radiobutton manipulates its
buttons to guarantee this.
State changes trigger an event message:
.IP
.EX
radiobuttonname: value \f2n\fP
.EE
.PP
Buttons are added to the radio button using the
.B add
message; there is no way to remove them, although they may be turned off
independently using
.IR 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.
.PP
The control messages the radiobutton accepts are:
.TF "\fLadd name"
.TP
.BI add " name
Add the control with the specified
.I name
to the radiobutton.
.TP
.BI focus " n
.TP
.BI format " fmt
.TP
.BI hide
.TP
.BI rect " minx miny maxx maxy
.TP
.BI reveal
.TP
.BI size " minx miny maxx maxy
.TP
.B show
.TP
.BI value " n
.PD
.SS Row
A row groups a number of member controls left to right in a rectangle.
Rows behave exactly like columns with the roles of
.I x
and
.I y
interchanged.
.PP
The control messages it accepts are:
.TF "\fLfont"
.TP
.BI add " name ...
.TP
.BI border " width
.TP
.BI bordercolor " color
.TP
.BI hide
.TP
.BR image " color
.TP
.BI rect " minx miny maxx maxy
.TP
.BI remove " name
.TP
.BI reveal
.TP
.BI separation " width
.TP
.BI show
.TP
.BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ]
.PD
.SS Scribble
The scribble control provides a region in which strokes drawn with mouse button
1 are interpreted as characters in the manner of
.IR scribble (2).
In most respects, including the format of its event messages, it is equivalent
to a keyboard control.
.PP
The control messages it accepts are:
.TF "\fLlinecolor \fIname\f(CW "
.TP
.BI align " a
Controls the placement of the image in the rectangle (unimplemented).
.TP
.BI border " b
.TP
.BI bordercolor " name
.TP
.BI focus " n
.TP
.BI font " name
Used to display the indicia.
.TP
.BI hide
.TP
.BI image " name
.TP
.BI linecolor " name
The color in which to draw the strokes; default black.
.TP
.BI rect " minx miny maxx maxy
.TP
.BI reveal
.TP
.BI size " minx miny maxx maxy
.TP
.B show
.PD
.SS Stack
A stack groups a number of member controls in the same shared rectangle.
Only one of these controls will be visible (revealed), the others are hidden.
.PP
The control messages it accepts are:
.TF "\fLreveal [\f2n\fP]"
.TP
.BI hide
.TP
.BI rect " minx miny maxx maxy
.TP
.BI remove " name
.TP
.BR reveal " [ \f2n\fP ]
Without argument,
.B reveal
is the opposite of
.BR hide :
it makes its selected control visible after it was hidden.
With an argument, it makes the
.IR n 'th
added control visible, hiding all others.
.TP
.BI show
.TP
.BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ]
Without argument,
.I size
computes the maximum of the minimum and maximum sizes of
its constituent controls.  With arguments, it sets the size to the
given values.
.PD
.SS Slider
A slider controls an integer value by dragging the mouse with a button.
Configured appropriately, it can serve as a scroll bar with the standard
Plan 9 behavior.
When the value changes, an event message is sent:
.IP
.EX
slidername: value \f2n\f1
.EE
.PP
The slider is a good candidate for connecting to another control
by setting its format and rewiring its
.B event
channel to the other's
.B ctl
channel.
.PP
The geometry of the slider is defined by three numbers:
.B max
is a number representing the range of the slider;
.B vis
is a number representing how much of what is being controlled is visible;
and
.B 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,
.B max
will be 1000,
.B vis
will be 18, and
.B value
will be 304.
The
.I indicator
is the visual representation of the
.I vis
portion of the controlled object.
.PP
The control messages the slider accepts are:
.TF "\fLabsolute n"
.TP
.BI absolute " n
If
.I n
is zero,
the slider behaves like a Plan 9 scroll bar:
button 2 sets absolute position, button 1 decreases the value,
and button 3 increases it.
If
.I n
is non-zero, all buttons behave like button 2, setting the absolute value.
.TP
.BI border " b
.TP
.BI bordercolor " name
.TP
.BI clamp " end n
The
.I end
is either the word
.B high
or
.BR low ;
.I n
sets whether that end is clamped or not.
If it is clamped, that end of the indicator is always at its supremum.
A standard scroll bar has neither end clamped; a volume slider would
have its low end clamped.
If the low end is clamped, the value of the slider is represented by the
high end of the indicator; otherwise it is represented by the low end.
.TP
.BI focus " n
.TP
.BI format " fmt
.TP
.BI hide
.TP
.BI image " name
.TP
.BI indicatorcolor " name
Set the color in which to draw the indicator; default black.
.TP
.BI max " n
Set the maximum value of the range covered by the slider.
.TP
.BI orient " dir
The string
.I dir
begins either
.B hor
or
.B ver
to specify the orientation of the slider.
The default is vertical.
The value always increases to the right for horizontal sliders and
downwards for vertical sliders.
.TP
.BI rect " minx miny maxx maxy
.TP
.BI reveal
.TP
.BI size " minx miny maxx maxy
.TP
.B show
.TP
.BI value " n
.TP
.BI vis " n
Set the visible area shown by the indicator.
.PD
.SS Tab
A tab control combines radiobottuns with a stack of windows giving the
appearance of tabbed controls.  Currently, the tabs are positioned at the
top of the stack.  The radiobutton consists of textbuttons, the stack
can be composed of any type of control.
.PP
Control messages are
.TF "\fLformat fmt"
.TP
.BI add " button control button control ...
Adds a button to the radiobutton, and an associated control to the stack.
Buttons and controls are numbered in the order of addition.  There is
no remove operation.
.TP
.BI border " b
.TP
.BI bordercolor " color
.TP
.BI focus " n
.TP
.BI format " fmt
When a format string is defined, the tab control reports which tab
is selected using the format string (which must print a
.B char*
and an
.BR int ). 
.TP
.BI image " color
Color between member controls.
.TP
.BI separation " n
Spacing between buttons in the radiobutton and between the row of
buttons and the stack below it.
.TP
.BI rect " n n n n
.TP
.B hide
.TP
.B reveal
.TP
.BI size " n n n n
.TP
.B show
.TP
.BI value " n
Value must be an integer indicating which tab to bring to the top.
.PD
.SS Text
A text control presents a set of lines of text.
The text cannot be edited with the keyboard, but can be
changed by control messages.
(A more interactive text control will be created eventually.)
The mouse can be used to select lines of text.
The only event message reports a state change in the selection of a line:
.IP
.EX
textname: select \f2n\f1 \f2s\f1
.EE
.PP
states that line
.I n
has changed its selection state to
.IR s ,
either zero (unselected) or non-zero (selected).
The non-zero value encodes the mouse buttons that were down
when the selection occurred.
.PP
The control messages the text control accepts are:
.TF "\fLselectmode \fIs\fP "
.TP
.BI accumulate " s
.TP
.BI accumulate " n s
.TP
.BI add " s
.TP
.BI add " n s
With one argument, append the string
.I s
as a new last line of the control; if
.I n
is specified, add the line
.I before
the current line
.IR n ,
making the new line number
.IR n.
The lines are zero indexed and
.I n
can be no greater than the current number of lines.
.I Add
refreshes the display, but
.I accumulate
does not, to avoid n-squared behavior when assembling a piece of text.
.TP
.BI align " a
Controls the placement of each line of text left-to-right in its rectangle.
Vertically, lines are tightly packed with separation set by the font's interline
spacing.
.TP
.BI border " b
.TP
.BI bordercolor " name
.TP
.BI clear
Delete all text.
.TP
.BI delete " n
Delete line
.IR n .
.TP
.BI focus " n
.TP
.BI font " name
.TP
.BI image " name
.TP
.BI rect " minx miny maxx maxy
.TP
.BI replace " n s
Replace line
.I n
by the string
.IR s .
.TP
.BI reveal
.TP
.BI scroll " n
If
.I n
is non-zero, the text will automatically scroll so the last line is always visible
when new text is added.
.TP
.BI select " n m
Set the selection state of line
.I n
to
.IR m .
.TP
.BI selectcolor " name
Set the color in which to highlight selected lines; default yellow.
.TP
.BI selectmode " s
The string
.I s
is either
.B single
or
.BR multi .
If
.BR single ,
the default,
only one line may be selected at a time; when a line is selected,
other lines are unselected.
If
.BR multi ,
the selection state of individual lines can be toggled independently.
.TP
.BI size " minx miny maxx maxy
.TP
.B show
.TP
.BI textcolor " name
.TP
.BI topline " n
Scroll the text so the top visible line is number
.IR n .
.TP
.BI value " s
Delete all the text in the control and then add the single line
.IR s .
.PD
.SS Textbutton
A textbutton is a textual variant of a plain button.
Each state change triggers an event message:
.IP
.EX
textbuttonname: value \f2n\fP
.EE
.LP
where
.I n
encodes the mouse buttons used to make the selection.
.PP
Like a regular button, the value of a textbutton is an integer; the
.I 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:
.TF "\fLalign a"
.TP
.BI align " a
Controls the placement of the text in the rectangle.
.TP
.BI border " b
.TP
.BI bordercolor " name
.TP
.BI focus " n
.TP
.BI font " name
.TP
.BI format " fmt
.TP
.B hide
.TP
.BI image " name
.TP
.BI light " name
.TP
.BI mask " name
.TP
.BI pressedtextcolor " name
Set the color in which to display text when the textbutton is pressed.
.TP
.BI rect " minx miny maxx maxy
.TP
.B reveal
.TP
.BI size " minx miny maxx maxy
.TP
.B show
.TP
.BI text " s
Set the text displayed in the button.
.TP
.BI textcolor " name
.TP
.BI value " n
Set the button to `on' (if
.I n
is non-zero) or `off' (if
.I n
is zero).
.SS "Helper functions
The function
.I ctlerror
is called when the library encounters an error.
It prints the formatted message and exits the program.
.PP
The functions
.IR ctlmalloc ,
.IR ctlrealloc ,
.IR ctlstrdup ,
and
.I ctlrunestrdup
are packagings of the corresponding C library functions.
They call
.I ctlerror
if they fail to allocate memory, and
.I ctlmalloc
zeros the memory it returns.
.PP
Finally, for debugging, if the global variable
.I ctldeletequits
is set to a non-zero value, typing a
.SM DEL
will cause the program to call
.IP
.EX
ctlerror("delete");
.EE
.SS Caveat
This library is very new and is still missing a number of important features.
The details are all subject to change.
Another level of library that handles geometry and has sensible default
appearances for the controls would be useful.
.PP
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.
.SH EXAMPLES
This example creates two entry boxes,
.BR top
and
.BR bot ,
and copies the contents of one to the other whenever a newline is typed.
.PP
.EX
#include <u.h>
#include <libc.h>
#include <thread.h>
#include <draw.h>
#include <mouse.h>
#include <keyboard.h>
#include <control.h>
.sp 0.4v
Controlset *cs;
.sp 0.4v
int ctldeletequits = 1;
.sp 0.4v
void
resizecontrolset(Controlset*)
{
        int i;
        Rectangle r, r1, r2;
.sp 0.4v
        if(getwindow(display, Refnone) < 0)
                sysfatal("resize failed: %r");
        r = insetrect(screen->r, 10);
        r1 = r;
        r2 = r;
        r1.max.y = r1.min.y+1+font->height+1;
        r2.min.y = r1.max.y+10;
        r2.max.y = r2.min.y+1+font->height+1;
        chanprint(cs->ctl, "top rect %R\entop show", r1);
        chanprint(cs->ctl, "bot rect %R\enbot show", r2);
}
.sp 0.4v
void
threadmain(int argc, char *argv[])
{
        char *s, *args[3];
        Channel *c;
        Control *top, *bot;
        int n;
.sp 0.4v
        initdraw(0, 0, "example");
        initcontrols();
        cs = newcontrolset(screen, nil, nil, nil);
        cs->clicktotype = 1;
.sp 0.4v
        top = createentry(cs, "top");
        chanprint(cs->ctl, "top image paleyellow");
        chanprint(cs->ctl, "top border 1");
        bot = createentry(cs, "bot");
        chanprint(cs->ctl, "bot image paleyellow");
        chanprint(cs->ctl, "bot border 1");
.sp 0.4v
        c = chancreate(sizeof(char*), 0);
        controlwire(top, "event", c);
        controlwire(bot, "event", c);
.sp 0.4v
        activate(top);
        activate(bot);
        resizecontrolset(cs);
.sp 0.4v
        for(;;){
                s = recvp(c);
                n = tokenize(s, args, nelem(args));
                if(n==3 && strcmp(args[1], "value")==0){
                        if(strcmp(args[0], "top:") == 0)
                                chanprint(cs->ctl, "bot value %q", args[2]);
                        else
                                chanprint(cs->ctl, "top value %q", args[2]);
                }
        }
        threadexitsall(nil);
}
.EE
.PP
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
.BR bot :
.PP
.EX
        bot = createslider(cs, "bot");
        chanprint(cs->ctl, "bot border 1");
        chanprint(cs->ctl, "bot image paleyellow");
        chanprint(cs->ctl, "bot indicatorcolor red");
        chanprint(cs->ctl, "bot max 100");
        chanprint(cs->ctl, "bot clamp low 1");
        chanprint(cs->ctl, "bot orient horizontal");
.EE
.PP
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.
.PP
Finally, we can avoid processing events altogether by cross-coupling
the controls.  Replace the rest of
.B threadmain
with this:
.PP
.EX
        chanprint(cs->ctl, "bot format %q", "%q: top value %q");
        chanprint(cs->ctl, "top format %q", "%q: bot value %q");
.sp 0.4v
        controlwire(top, "event", cs->ctl);
        controlwire(bot, "event", cs->ctl);
.sp 0.4v
        activate(top);
        activate(bot);
        resizecontrolset(cs);
.sp 0.4v
        for(;;)
                yield();
        threadexitsall(nil);
.EE
.SH SOURCE
.B /sys/src/libcontrol
.SH SEE ALSO
.IR draw (2),
.IR frame (2),
.IR graphics (2),
.IR quote (2),
.IR thread (2)
.SH BUGS
The library is strict about matters of formatting, argument count in messages,
etc., and calls
.I ctlerror
in situations where it may be fine to ignore the error and continue.