Subversion Repositories planix.SVN

.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 ommitted.

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 tha 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