Ada95/html/panel.3x.html

   1 <HTML>
   2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
   3 <PRE>
   4        panel - panel stack extension for curses
   5
   6
   7 </PRE>
   8 <H2>SYNOPSIS</H2><PRE>
   9        <STRONG>#include</STRONG> <STRONG>&lt;panel.h&gt;</STRONG>
  10
  11        <STRONG>cc</STRONG> <STRONG>[flags]</STRONG> <STRONG>sourcefiles</STRONG> <STRONG>-lpanel</STRONG> <STRONG>-lncurses</STRONG>
  12
  13        <STRONG>PANEL</STRONG> <STRONG>*new_panel(WINDOW</STRONG> <STRONG>*win)</STRONG>
  14        <STRONG>int</STRONG> <STRONG>bottom_panel(PANEL</STRONG> <STRONG>*pan)</STRONG>
  15        <STRONG>int</STRONG> <STRONG>top_panel(PANEL</STRONG> <STRONG>*pan)</STRONG>
  16        <STRONG>int</STRONG> <STRONG>show_panel(PANEL</STRONG> <STRONG>*pan)</STRONG>
  17        <STRONG>void</STRONG> <STRONG>update_panels();</STRONG>
  18        <STRONG>int</STRONG> <STRONG>hide_panel(PANEL</STRONG> <STRONG>*pan)</STRONG>
  19        <STRONG>WINDOW</STRONG> <STRONG>*panel_window(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan)</STRONG>
  20        <STRONG>int</STRONG> <STRONG>replace_panel(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*window)</STRONG>
  21        <STRONG>int</STRONG> <STRONG>move_panel(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>int</STRONG> <STRONG>starty,</STRONG> <STRONG>int</STRONG> <STRONG>startx)</STRONG>
  22        <STRONG>int</STRONG> <STRONG>panel_hidden(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan)</STRONG>
  23        <STRONG>PANEL</STRONG> <STRONG>*panel_above(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan)</STRONG>
  24        <STRONG>PANEL</STRONG> <STRONG>*panel_below(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan)</STRONG>
  25        <STRONG>int</STRONG> <STRONG>set_panel_userptr(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*ptr)</STRONG>
  26        <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*panel_userptr(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan)</STRONG>
  27        <STRONG>int</STRONG> <STRONG>del_panel(PANEL</STRONG> <STRONG>*pan)</STRONG>
  28
  29
  30 </PRE>
  31 <H2>DESCRIPTION</H2><PRE>
  32        Panels  are  <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>  windows with the added feature of
  33        depth.  Panel functions allow the use of  stacked  windows
  34        and  ensure  the  proper  portions  of each window and the
  35        curses <STRONG>stdscr</STRONG> window are hidden or displayed  when  panels
  36        are  added,  moved,  modified or removed.  The set of cur-
  37        rently visible panels is the stack of panels.  The  <STRONG>stdscr</STRONG>
  38        window  is  beneath all panels, and is not considered part
  39        of the stack.
  40
  41        A window is associated with every panel.  The  panel  rou-
  42        tines  enable you to create, move, hides, and show panels,
  43        as well as position a panel at any desired location in the
  44        stack.
  45
  46        Panel routines are a functional layer added to <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>,
  47        make only high-level curses calls, and work anywhere  ter-
  48        minfo curses does.
  49
  50
  51 </PRE>
  52 <H2>FUNCTIONS</H2><PRE>
  53        <STRONG>new_panel(win)</STRONG>
  54               allocates   a   <STRONG>PANEL</STRONG> structure, associates it with
  55               <STRONG>win</STRONG>, places the panel  on  the  top  of  the  stack
  56               (causes   it  to   be   displayed  above  any other
  57               panel) and returns a pointer to the new panel.
  58
  59        <STRONG>void</STRONG> <STRONG>update_panels()</STRONG>
  60               refreshes the virtual screen to reflect  the  rela-
  61               tions between the panels in the stack, but does not
  62               update_panels() may be called more than once before
  63               a  call  to doupdate(), but doupdate() is the func-
  64               tion responsible for updating the physical  screen.
  65
  66        <STRONG>del_panel(pan)</STRONG>
  67               removes the given panel from the  stack and deallo-
  68               cates the <STRONG>PANEL</STRONG> structure (but not  its  associated
  69               window).
  70
  71        <STRONG>hide_panel(pan)</STRONG>
  72               removes  the  given  panel from the panel stack and
  73               thus hides it from view. The <STRONG>PANEL</STRONG> structure is not
  74               lost, merely removed from the stack.
  75
  76        <STRONG>show_panel(pan)</STRONG>
  77               makes  a  hidden panel visible by placing it on top
  78               of the panels in the panel stack. See COMPATIBILITY
  79               below.
  80
  81        <STRONG>top_panel(pan)</STRONG>
  82               puts  the  given visible panel on top of all panels
  83               in the stack.  See COMPATIBILITY below.
  84
  85        <STRONG>bottom_panel(pan)</STRONG>
  86               puts panel at the bottom of all panels.
  87
  88        <STRONG>move_panel(pan,starty,startx)</STRONG>
  89               moves the given panel window so that its upper-left
  90               corner  is  at  <STRONG>starty</STRONG>, <STRONG>startx</STRONG>.  It does not change
  91               the position of the panel in the stack.  Be sure to
  92               use  this  function,  not  <STRONG>mvwin()</STRONG>, to move a panel
  93               window.
  94
  95        <STRONG>replace_panel(pan,window)</STRONG>
  96               replaces the current window of  panel  with  <STRONG>window</STRONG>
  97               (useful, for example if you want to resize a panel;
  98               if you're using <STRONG>ncurses</STRONG>, you can call <STRONG>replace_panel</STRONG>
  99               on  the output of <STRONG><A HREF="wresize.3x.html">wresize(3X)</A></STRONG>).  It does not change
 100               the position of the panel in the stack.
 101
 102        <STRONG>panel_above(pan)</STRONG>
 103               returns a pointer to the panel above pan.   If  the
 104               panel  argument is <STRONG>(PANEL</STRONG> <STRONG>*)0</STRONG>, it returns a pointer
 105               to the bottom panel in the stack.
 106
 107        <STRONG>panel_below(pan)</STRONG>
 108               returns a pointer to the panel just below pan.   If
 109               the  panel  argument  is  <STRONG>(PANEL</STRONG>  <STRONG>*)0</STRONG>, it returns a
 110               pointer to the top panel in the stack.
 111
 112        <STRONG>set_panel_userptr(pan,ptr)</STRONG>
 113               sets the panel's user pointer.
 114               returns the user pointer for a given panel.
 115
 116        <STRONG>panel_window(pan)</STRONG>
 117               returns a pointer to the window of the given panel.
 118
 119
 120 </PRE>
 121 <H2>DIAGNOSTICS</H2><PRE>
 122        Each  routine  that  returns  a pointer returns <STRONG>NULL</STRONG> if an
 123        error occurs. Each  routine  that  returns  an  int  value
 124        returns <STRONG>OK</STRONG> if it executes successfully and <STRONG>ERR</STRONG> if not.
 125
 126
 127 </PRE>
 128 <H2>COMPATIBILITY</H2><PRE>
 129        Reasonable  care  has been taken to  ensure  compatibility
 130        with  the  native  panel  facility  introduced  in  SVr3.2
 131        (inspection of the SVr4 manual pages suggests the program-
 132        ming interface is unchanged).  The <STRONG>PANEL</STRONG>  data  structures
 133        are  merely   similar. The  programmer is cautioned not to
 134        directly use <STRONG>PANEL</STRONG> fields.
 135
 136        The functions <STRONG>show_panel()</STRONG> and <STRONG>top_panel()</STRONG>  are  identical
 137        in  this  implementation,  and work equally well with dis-
 138        played or hidden panels.  In the native System V implemen-
 139        tation, <STRONG>show_panel()</STRONG> is intended for making a hidden panel
 140        visible (at the top  of  the  stack)  and  <STRONG>top_panel()</STRONG>  is
 141        intended  for  making an already-visible panel move to the
 142        top of the stack. You are cautioned  to  use  the  correct
 143        function   to   ensure  compatibility  with  native  panel
 144        libraries.
 145
 146
 147 </PRE>
 148 <H2>NOTE</H2><PRE>
 149        In your library list, libpanel.a should  be  before  libn-
 150        curses.a;  that  is,  you want to say `-lpanel -lncurses',
 151        not the other way around (which  would  give  you  a  link
 152        error using GNU <STRONG><A HREF="ld.1.html">ld(1)</A></STRONG> and some other linkers).
 153
 154
 155 </PRE>
 156 <H2>FILES</H2><PRE>
 157        panel.h interface for the panels library
 158
 159        libpanel.a the panels library itself
 160
 161
 162 </PRE>
 163 <H2>SEE ALSO</H2><PRE>
 164        <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>
 165
 166
 167 </PRE>
 168 <H2>AUTHOR</H2><PRE>
 169        Originally   written   by   Warren  Tucker  &lt;wht@n4hgf.mt-
 170        park.ga.us&gt;, primarily to assist  in  porting  u386mon  to
 171        systems  without  a native panels library.  Repackaged for
 172        ncurses by Zeyd ben-Halim.
 173
 174
 175
 176
 177
 178 </PRE>
 179 </BODY>
 180 </HTML>