term% ls -F
term% cat index.txt
PLBUTTON(2)                   System Calls Manual                  PLBUTTON(2)

       plbutton,  plcanvas,  plcheckbutton, pledit, plentry, plframe, plgroup,
       plidollist, pllabel, pllist,  plmenu,  plmenubar,  plmessage,  plpopup,
       plpulldown,  plradiobutton,  plscrollbar, plslider, pltextview - panel-
       creation functions

       #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*))

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

              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.

              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.

              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.

              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.

              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.

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

              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.

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

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


       plinit(2), plinitbutton(2), graphics(2)
       Tom Duff, ``A quick introduction to the panel library''.