glenda.party
term% ls -F
term% cat index.txt
PLINIT(2)                     System Calls Manual                    PLINIT(2)



NAME
       Panel, Rtext, plpack, plmove, pldraw, plfree, plgrabkb, plkeyboard, pl‐
       mouse, plscroll, plentryval, plsetbutton, plsetslider, pleget,  plelen,
       plegetsel,   plepaste,  plesel,  plescroll,  plgetscroll,  plsetscroll,
       plplacelabel,  plrtstr,  plrtbitmap,  plrtpanel,  plrtfree,   plgetpos‐
       textview, plsetpostextview - Panel manipulation functions

SYNOPSIS
       #include <u.h>
       #include <libg.h>
       #include <panel.h>

       int plinit(int ldepth)

       int plpack(Panel *p, Rectangle r)

       void plmove(Panel *p, Point loc)

       void pldraw(Panel *p, Bitmap *b)

       void plfree(Panel *p)

       void plgrabkb(Panel *p)

       void plkeyboard(Rune c)

       void plmouse(Panel *p, Mouse m)

       void plscroll(Panel *scrollee, Panel *xscroller, Panel *yscroller)

       char *plentryval(Panel *entry)

       void plsetbutton(Panel *button, int value)

       void plsetslider(Panel *slider, int value, int range)

       Rune *pleget(Panel *edit)

       int plelen(Panel *edit)

       void plegetsel(Panel *edit, int *start, int *end)

       void plepaste(Panel *edit, Rune *text, int ntext)

       void plesel(Panel *edit, int start, int end)

       void plescroll(Panel *edit, int index)

       Scroll plgetscroll(Panel *p)

       void plsetscroll(Panel *p, Scroll s)

       void plplacelabel(Panel *p, int loc)

       Rtext *plrtstr(Rtext **head, int space, int indent,
                      Font *font, char *str, int hot, void *user)

       Rtext *plrtbitmap(Rtext **head, int space, int indent,
                         Bitmap *image, int hot, void *user)

       Rtext *plrtpanel(Rtext **head, int space, int indent,
                        Panel *panel, int hot, void *user)

       void plrtfree(Rtext *text)

       Rtext *plgetpostextview(Panel *view)

       void plsetpostextview(Panel *view, Rtext *text)

DESCRIPTION
       The panel library assists in making simple graphical control panels for
       interactive applications.  As drawn on the screen, a panel is a collec‐
       tion  of  nested rectangles with things drawn in them, representing la‐
       bels, buttons, editable text displays, scroll bars, and other user  in‐
       terface  features.   Corresponding  to  the  nest of boxes is a tree of
       Panel structures.  A node's children are drawn nested inside their par‐
       ent.  The publicly visible part of a Panel structure looks like this

              typedef struct Panel Panel;
              struct Panel{
                   Point ipad, pad; /* extra space inside and outside */
                   Point fixedsize; /* size of Panel, if FIXED */
                   int user;        /* available for user */
                   void *userp;     /* available for user */
                   Rectangle r;     /* where the Panel goes */
                   ...              /* more private fields follow */
              };

       Rectangle  r  is  the  box containing this Panel node and its children.
       Its value is computed by plpack.  The user and  userp  fields  are  not
       used by the panel library.  They are provided so that user code can at‐
       tach data to a Panel node.  The Points ipad, pad, and fixedsize may  be
       set by user code and are examined by plpack.

       This  manual  page  catalogs those panel library functions not directly
       concerned with creating or reinitializing Panel data  structures.   See
       plbutton(2)  and  plinitbutton(2) for those.  The Panel library memo in
       Volume 2 of this manual contains a more detailed description  of  these
       functions, illustrated with examples.

       The plinit function initializes panel library data structures.  Its ar‐
       gument is the ldepth of the bitmaps on which panels will be drawn.  The
       panel  library  draws  things differently on one-bit and multi-bit-per-
       pixel displays.

       There is usually no need to specify exact sizes and screen locations of
       Panel nodes.

       Screen layout is computed by plpack, whose arguments are a pointer to a
       Panel tree and a Rectangle in which the layout should fit.  Plpack  re‐
       turns  1  if  it  could  fit everything into the rectangle, and 0 if it
       could not.  Briefly, plpack processes a Panel tree in two passes.   The
       first,  bottom-up  pass  computes the amount of space required to house
       the children of each panel.  The second pass proceeds top-down and  di‐
       vides  the  space  available  to  each panel among its children.  Every
       Panel has some minimum space requirement — for example, a  button  must
       be  big  enough to fit its label inside its border, and a group must be
       large enough to hold its children.  Space is  allocated  to  a  Panel's
       children  in eldest to youngest order by slicing an appropriately sized
       piece off one of the four sides of the available rectangle.  Each Panel
       has  a  flag  word  (specified  when  the Panel is created — see plbut‐
       ton(2)), one of whose fields can have the value PACKN, PACKE, PACKS  or
       PACKW  (default  PACKN),  specifying  from which side to cut the piece.
       Other flags are:

       FILLX FILLY
              The rectangle that plpack slices off for a Panel may  be  larger
              than the Panel needs.  For example, if a small button with PACKW
              set is packed inside a large rectangle, plpack will slice off  a
              piece  that fits snugly in the x direction, but that will likely
              be too big in the y direction.  Specifying  instead  PACKW|FILLY
              will grow the button in the y direction to fill the extra space.

       PLACECEN PLACES PLACEE PLACEW PLACEN
       PLACENE PLACENW PLACESE PLACESW
              If  a  Panel  is not expanded to fill the slack, these flags can
              specify where in the available space to place it.   The  default
              is  PLACECEN, which centers the panel in the space allocated for
              it.  The other PLACE flags place the Panel at one of  the  eight
              compass points.

       FIXED FIXEDX FIXEDY
              A user's code can override whatever size calculation plpack per‐
              forms by setting the FIXED flag  and  storing  a  value  in  the
              Panel's fixedsize field.  FIXED is the conjunction of FIXEDX and
              FIXEDY, which fix a Panel's horizontal and vertical extent inde‐
              pendently.

       MAXX MAXY
              If  either  of  these  flags is set, the Panel's x or y size re‐
              quirement is increased to be equal to that of its  largest  sib‐
              ling.

       Once a Panel tree is packed, it can be moved to a different location by
       calling plmove, whose arguments are the panel to be moved and the upper
       left-hand corner of its destination.

       Pldraw  displays  its  Panel  argument in the given Bitmap.  Since each
       Panel's children are drawn nested inside it, programs  can  do  partial
       screen  updates  by  calling  pldraw on interior nodes of a Panel tree.
       For example, after calling plinitlabel to change the text of  a  label,
       calling pldraw on the label will redisplay it, without having to update
       the rest of the display.  An application that wishes to discard a Panel
       tree should pass it to plfree to release the storage.

       Three functions control how a Panel processes mouse and keyboard input:

       plmouse
              takes  two  arguments,  a Panel pointer and a Mouse structure as
              returned by emouse (see  event(2)).   Plmouse  determines  which
              node  of the Panel tree should receive the mouse event and calls
              panel-specific code to process the event.  That code may in turn
              call  back  to  user-supplied functions to register button hits,
              slider movement, etc.  Hit routines are generally specified when
              panel-creation functions are called.

       plgrabkb
              takes one argument, a pointer to a Panel to which keyboard input
              should be directed.  We say that this panel ``has  the  keyboard
              focus.''   Passing  a null pointer to plgrabkb causes subsequent
              keyboard input to be ignored.

       plkeyboard
              takes one argument, a Rune, presumably obtained from ekbd or its
              equivalent  and  sends it to the panel that has the keyboard fo‐
              cus, if any.

       Programs that use scroll  bars  created  with  plscrollbar  to  control
       scrollable  panels  (currently  pledit,  pllist, and pltextview panels)
       must call plscroll to indicate to the panel library  which  scroll  bar
       adjusts  which  panel.  Its arguments are three pointers to panels: the
       panel to be scrolled, the panel that scrolls it in the x direction, and
       the panel that scrolls it in the y direction.  Either of the latter two
       may be null, indicating no control in  that  direction.   Currently  no
       panel responds to scrolling in x; that option is for future expansion.

       The  rest  of  the functions test or set values hidden in certain Panel
       types or perform other miscellaneous manipulations such as  saving  and
       restoring scroll points.

       The  plentryval  entry  returns  a pointer to the string entered into a
       plentry panel (q.v.).  Its argument is the panel in question.

       Plsetbutton takes two arguments.  The first must point to a plcheckbut‐
       ton  or  plradiobutton panel.  The function sets or clears the button's
       checkmark, depending on whether its second argument is 0 or 1.

       Plsetslider adjusts the position of the  slider,  its  first  argument.
       The  value argument gives the setting, in units such that the range ar‐
       gument gives full scale.  For example

              plsetslider(s, 50, 100);
              plsetslider(s, 1, 2);
              plsetslider(s, 17, 34);

       each set slider s to the 50% mark.

       The following functions all manipulate the editable text panels created
       by pledit.  The first argument of each is a pointer to the edit panel.

       pleget returns  a pointer to an array of Runes containing the edit win‐
              dow's text.

       plelen returns the number of Runes in the text.

       plegetsel
              stores in *start and *end the endpoints  of  the  edit  window's
              current selection.

       plepaste
              replaces the current selection with the text pointed to by text,
              whose length is ntext Runes.

       plesel sets the endpoints of the selection to start and end.

       plescroll
              scrolls the edit window so that the  line  containing  the  Rune
              with the given index is at the top of the screen.

       The  arguments of plplacelabel are a pointer to a pllabel panel and one
       of the flags PLACECEN, PLACES, PLACEE, PLACEW,  PLACEN,  PLACENE,  PLA‐
       CENW,  PLACESE, or PLACESW.  This function indicates where in the space
       allocated for the label the label's text should be drawn.  The text  is
       centered by default.

       The  argument  of  plgetscroll should point to a scrollable Panel.  The
       return value is a magic cookie (of type Scroll) that indicates where it
       is  scrolled  to.   When the panel pointer and the cookie are passed to
       plsetscroll, it will scroll the panel back to the place it was at  when
       plgetscroll  was  called.  The magic cookie encodes the scroll position
       on a percentage basis, so all bets are off if the contents of the panel
       are different at the calls to plgetscroll and plsetscroll.

       Plgetpostextview  and  plsetpostextview perform a similar function, but
       they only work on pltextview panels.  However,  since  plgetpostextview
       returns a pointer to the Rtext that is displayed in the upper left-hand
       corner of the panel and plsetpostextview scrolls the given  Rtext  back
       to  the upper left-hand corner, the caveat mentioned above does not ap‐
       ply.

       Finally, there is a group of functions that create the Rtext lists that
       are displayed by pltextview panels.  Line breaks can occur only between
       the members of an Rtext list.  An individual Rtext structure  describes
       a  bitmap,  or  a string of text to be drawn in a single call to string
       (see bitblt(2)), or a Panel to be drawn inline.  The  publicly  visible
       parts of an Rtext look like this:

              typedef struct Rtext Rtext;
              struct Rtext{
                   int hot;     /* responds to hits? */
                   void *user;  /* user data */
                   int space;   /* how much space before, if no break */
                   int indent;  /* how much space before, after a break */
                   Bitmap *b;   /* what to display, if nonzero */
                   Panel *p;    /* what to display, if nonzero and b==0 */
                   Font *font;  /* font in which to draw text */
                   char *text;  /* what to display, if b==0 and p==0 */
                   Rtext *next; /* next piece */
                   ...          /* more private fields follow */
              };

       The fields are:

       hot    indicates whether or not this Rtext is sensitive to mouse hits.

       user   points  to  user  data not used by the panel library.  User code
              may use this pointer to annotate an Rtext.

       space  how much space to leave to the left of this Rtext if it  appears
              on  the  same line as the previous one.  To allow the display of
              words with internal font changes, if space is zero,  there  will
              never be a line break between this Rtext and the previous one.

       indent How  much space to leave between this Rtext and the left margin,
              if it is the first one on the line.

       b      a bitmap to be displayed, if non-null.

       p      a panel to be displayed, if non-null and b==0.

       font   the font in which text is to be drawn.

       text   the string to be displayed, if b==0 and p==0.

       next   the next Rtext on the list.

       The functions plrtstr, plrtbitmap, and plrtpanel  create  nodes  in  an
       Rtext  list,  returning  a  pointer to the newly created node.  For all
       three functions, the space, indent, hot, and user arguments  initialize
       the  corresponding  field of the Rtext, and head points to a pointer to
       the head of the list, which the functions  will  update  appropriately.
       The pointer in *head should be initialized to a null pointer before the
       first call to any of these functions.

       The plrtfree function will dispose of a Rtext list that  is  no  longer
       needed.   The  user's  code  is responsible for discarding any strings,
       bitmaps, panels, or user data that the list may point to.

SOURCE
       /sys/src/libpanel

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



                                                                     PLINIT(2)