term% cat index.txt PLBUTTON(2) System Calls Manual 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,
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 control plpack (see
plinit(2)). Arguments of type Icon* (a synonym 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. Plra‐
diobutton likewise creates a button with a check mark, but with
the additional feature 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 func‐
tions 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 passing a null hit func‐
tion pointer to the creation function.
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 plgroup does not.
pllabel
plmessage
These two functions create passive (insensitive to mouse or key‐
board events) panels. The pllabel entry draws a label contain‐
ing 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
multiple 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 function 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 but‐
ton 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 latter case, the mouse event's but‐
tons field has the OUT bit set.
pledit creates a panel that displays editable single-font text. Argu‐
ments are the minimum acceptable size for the panel, a pointer
to an array of Runes that initializes the panel, the number of
runes in the array, and a function to be called every time a se‐
lection is swept out with the mouse. The functions pleget, ple‐
len, plegetsel, plepaste, plesel, plescroll, and pleshowsel, de‐
scribed in plinit(2), manipulate the contents of edit panels.
plentry
creates a single-line text entry panel. Arguments are the mini‐
mum 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 func‐
tion'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 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 buttons. 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 tem‐
porarily 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 but‐
ton 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 fol‐
low 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 argument gives
the smallest acceptable size. If size.x>size.y the slider is
drawn horizontally, otherwise 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 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, otherwise 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 arguments 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 cre‐
ate the Rtext data structure that describes the text, are de‐
scribed in plinit(2).
SOURCE
/sys/src/libpanel
SEE ALSO
plinit(2), plinitbutton(2), graphics(2)
Tom Duff, ``A quick introduction to the panel library''.
PLBUTTON(2)