PLBUTTON(2) PLBUTTON(2)
NAME
plbutton, plcanvas, plcheckbutton, pledit, plentry, plframe,
plgroup, plidollist, pllabel, pllist, plmenu, plmenubar,
plmessage, plpopup, plpulldown, plradiobutton, plscrollbar,
plslider, pltextview - panel-creation functions
SYNOPSIS
#include <u.h>
#include <libg.h>
#include <panel.h>
Panel *plbutton(Panel *parent, int flags, Icon *label,
void (*hit)(Panel *pl, int))
Panel *plcanvas(Panel *parent, int flags,
void (*draw)(Panel*), void (*hit)(Panel*, Mouse*))
Panel *plcheckbutton(Panel *parent, int flags, Icon *label,
void (hit*)(Panel*, int, int))
Panel *pledit(Panel *parent, int flags, Point size, Rune *text,
int ntext, void (*hit)(Panel*))
Panel *plentry(Panel *parent, int flags, int width, char *text,
void (*enter)(Panel*, char*))
Panel *plframe(Panel *parent, int flags)
Panel *plgroup(Panel *parent, int flags)
Panel *pllabel(Panel *parent, int flags, Icon *label)
Panel *pllist(Panel *parent, int flags, char *(*gen)(int),
int length, void(*hit)(Panel*, int, int))
Panel *plmenu(Panel *parent, int flags, Icon **items,
int itemflags, void (*hit)(int, int))
Panel *plmenubar(Panel *parent, int flags, int itemflags,
Icon *label1, Panel *p1, Icon *label2, ...)
Panel *plmessage(Panel *parent, int flags, int width, char *text)
Panel *plpopup(Panel *parent, int flags,
Panel *left, Panel *middle, Panel *right)
Panel *plpulldown(Panel *parent, int flags,
Icon *label, Panel *pull, int side)
Panel *plradiobutton(Panel *parent, int flags, Icon *label,
Page 1 Plan 9 (printed 12/22/24)
PLBUTTON(2) PLBUTTON(2)
void (*hit)(Panel*, int, int))
Panel *plscrollbar(Panel *parent, int flags)
Panel *plslider(Panel *parent, int flags, Point size,
void(*hit)(Panel*, int, int, int))
Panel *pltextview(Panel *parent, int flags, Point size,
Rtext *text, void (*hit)(Panel*, int, Rtext*))
DESCRIPTION
Each of these functions creates and initializes a new node
of a Panel tree and returns a pointer to the newly created
panel. Existing panels may be reinitialized (for example to
change the label on a button) by functions enumerated in
plinitbutton(2).
The first two arguments of each panel-creation function are
a pointer to the new panel's parent and the flags that con-
trol plpack (see plinit(2)). Arguments of type Icon* (a syn-
onym for void*) are either Bitmap or text labels. If the
BITMAP bit of the flag word is set, they are of type
Bitmap*. Otherwise, their type is char*.
plbutton
plcheckbutton
plradiobutton
These three functions create pushbuttons. Plbutton
creates an ordinary button. Plcheckbutton creates a
button with a check mark that toggles on and off when
the button is hit. Plradiobutton likewise creates a
button with a check mark, but with the additional fea-
ture that toggling the check mark on toggles off the
checks of its siblings in the Panel tree. All three
take similar arguments: label is the text or bitmap
drawn on the button, and hit is the function called
when a hit is registered on the button. Its arguments
are a pointer to the button and the mouse buttons
active when the hit occurred. The hit functions of
plcheckbutton and plradiobutton take a third argument
that indicates the state of the button's check mark.
Occasionally, a button or other panel may wish to take
no action on sensing a hit. This is indicated by pass-
ing a null hit function pointer to the creation func-
tion.
plframe
plgroup
These two functions create compound panels that enclose
their children in a rectangular area. The difference
is that plframe draws a frame around its children, but
Page 2 Plan 9 (printed 12/22/24)
PLBUTTON(2) PLBUTTON(2)
plgroup does not.
pllabel
plmessage
These two functions create passive (insensitive to
mouse or keyboard events) panels. The pllabel entry
draws a label containing a text string or a Bitmap.
Plmessage draws longer messages. Its arguments are the
desired width of the panel, in pixels, and a pointer to
the text to be drawn. The text is displayed on multi-
ple lines, wrapping around at word boundaries.
plcanvas
creates an empty rectangle in a panel tree. The draw
argument is a function to be called by the panel
library to redraw the panel. Draw's argument points to
the canvas to be drawn on. The hit argument is a func-
tion called whenever a mouse event is registered in the
panel. Its arguments are a pointer to the panel and a
pointer to the mouse event. Hit receives all mouse
events with points within the canvas's rectangle and
with a button down. In addition, an event is sent when
the buttons are released over the canvas, or when the
mouse moves out of the canvas's rectangle. In the lat-
ter case, the mouse event's buttons field has the OUT
bit set.
pledit
creates a panel that displays editable single-font
text. Arguments are the minimum acceptable size for
the panel, a pointer to an array of Runes that initial-
izes the panel, the number of runes in the array, and a
function to be called every time a selection is swept
out with the mouse. The functions pleget, plelen,
plegetsel, plepaste, plesel, plescroll, and pleshowsel,
described in plinit(2), manipulate the contents of edit
panels.
plentry
creates a single-line text entry panel. Arguments are
the minimum acceptable width of the panel, in pixels, a
string that is the initial contents of the panel, and a
hit function to be called whenever a newline is typed
in the panel. The hit function's arguments are a
pointer to the panel and a pointer to the string
entered. Clicking the mouse over an entry makes it the
keyboard focus (the recipient of typed characters), as
does calling plgrabkb (described in plinit(2)).
pllist
creates a panel containing a scrollable list of text
items. Its arguments are gen, a pointer to a function
Page 3 Plan 9 (printed 12/22/24)
PLBUTTON(2) PLBUTTON(2)
that, when passed an integer argument, returns the text
of the appropriate list item, length, the minimum
acceptable number of items to be displayed on the
screen, and hit, a function to be called when an item
is selected with the mouse. Hit's arguments are a
pointer to the panel, which mouse buttons were used to
make the selection, and the number of the item
selected.
plmenu
calls plgroup and plbutton to create an array of but-
tons. The items argument points to an array of strings
or Bitmap pointers, one per button. A null pointer
ends the list. Itemflags is the flag argument used to
create each button. The hit function's arguments are
the mouse buttons pressed to register the hit and the
button's index in items.
plpopup
creates a group, as in plgroup, except that where
plgroup always passes mouse events on to its children,
plpopup may instead temporarily pop up a new panel and
divert mouse events to it. The arguments left, middle,
and right are pointers to panels to be popped up when
the corresponding mouse button is pushed. A null
pointer causes events to pass through to plpopup's
children.
plpulldown
plmenubar
Plpulldown creates a button that, when triggered by a
mouse button push, temporarily pops up a new panel.
The label argument points to a Bitmap or text label,
pull points to the panel that appears when the button
is pushed, and side is a flag whose value is one of
PACKN, PACKE, PACKS, or PACKW, indicating the side of
the button on which the pulled-down menu should appear.
The plmenubar entry calls plgroup and plpulldown to
create an array of pull-down buttons. Its itemflags
argument gives the flags to be used when creating each
pull-down button. Then follow an indefinite number of
pairs giving the labels and pulled-down panels of the
buttons. The list ends with a null label pointer.
plslider
creates a continuously variable slider. The size argu-
ment gives the smallest acceptable size. If
size.x>size.y the slider is drawn horizontally, other-
wise vertically. The hit function is called whenever a
mouse event changes the slider's value. Its arguments
are a pointer to the slider, the mouse buttons, the
slider's value, and the possible range of values. The
Page 4 Plan 9 (printed 12/22/24)
PLBUTTON(2) PLBUTTON(2)
value is always between 0 and the range.
plscrollbar
creates a scroll bar. If the flags argument has PACKE
or PACKW set, the scroll bar slides vertically, other-
wise horizontally. Scroll bars are associated with the
panels that they scroll by a call to plscroll,
described in plinit(2).
pltextview
creates a panel containing hit-sensitive formatted
multi-font text with bitmap illustrations. Its argu-
ments are the minimum acceptable size of the panel, in
pixels, a pointer to a data structure describing the
text to be displayed, and a function to be called upon
registering a mouse hit. The arguments of the hit
function are a pointer to the panel, the mouse buttons
that caused the hit, and a pointer to the text element
that the mouse pointed at. The functions plrtstring
and plrtbitmap, which create the Rtext data structure
that describes the text, are described in plinit(2).
SOURCE
/sys/src/libpanel
SEE ALSO
plinit(2), plinitbutton(2), graphics(2)
Tom Duff, ``A quick introduction to the panel library''.
Page 5 Plan 9 (printed 12/22/24)