doc/html/man/panel.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
   4   *                                                                          *
   5   * Permission is hereby granted, free of charge, to any person obtaining a  *
   6   * copy of this software and associated documentation files (the            *
   7   * "Software"), to deal in the Software without restriction, including      *
   8   * without limitation the rights to use, copy, modify, merge, publish,      *
   9   * distribute, distribute with modifications, sublicense, and/or sell       *
  10   * copies of the Software, and to permit persons to whom the Software is    *
  11   * furnished to do so, subject to the following conditions:                 *
  12   *                                                                          *
  13   * The above copyright notice and this permission notice shall be included  *
  14   * in all copies or substantial portions of the Software.                   *
  15   *                                                                          *
  16   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23   *                                                                          *
  24   * Except as contained in this notice, the name(s) of the above copyright   *
  25   * holders shall not be used in advertising or otherwise to promote the     *
  26   * sale, use or other dealings in this Software without prior written       *
  27   * authorization.                                                           *
  28   ****************************************************************************
  29   * @Id: panel.3x,v 1.21 2017/02/18 16:53:23 tom Exp @
  30 -->
  31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  32 <HTML>
  33 <HEAD>
  34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  35 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
  36 <TITLE>panel 3x</TITLE>
  37 <link rev=made href="mailto:bug-ncurses@gnu.org">
  38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  39 </HEAD>
  40 <BODY>
  41 <H1 class="no-header">panel 3x</H1>
  42 <PRE>
  43 <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>                                                            <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>
  44
  45
  46
  47
  48 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  49        panel - panel stack extension for curses
  50
  51
  52 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  53        <STRONG>#include</STRONG> <STRONG>&lt;panel.h&gt;</STRONG>
  54
  55        <STRONG>cc</STRONG> <STRONG>[flags]</STRONG> <STRONG>sourcefiles</STRONG> <STRONG>-lpanel</STRONG> <STRONG>-lncurses</STRONG>
  56
  57        <STRONG>PANEL</STRONG> <STRONG>*new_panel(WINDOW</STRONG> <STRONG>*win);</STRONG>
  58        <STRONG>int</STRONG> <STRONG>bottom_panel(PANEL</STRONG> <STRONG>*pan);</STRONG>
  59        <STRONG>int</STRONG> <STRONG>top_panel(PANEL</STRONG> <STRONG>*pan);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>show_panel(PANEL</STRONG> <STRONG>*pan);</STRONG>
  61        <STRONG>void</STRONG> <STRONG>update_panels();</STRONG>
  62        <STRONG>int</STRONG> <STRONG>hide_panel(PANEL</STRONG> <STRONG>*pan);</STRONG>
  63        <STRONG>WINDOW</STRONG> <STRONG>*panel_window(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG>
  64        <STRONG>int</STRONG> <STRONG>replace_panel(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*window);</STRONG>
  65        <STRONG>int</STRONG> <STRONG>move_panel(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>int</STRONG> <STRONG>starty,</STRONG> <STRONG>int</STRONG> <STRONG>startx);</STRONG>
  66        <STRONG>int</STRONG> <STRONG>panel_hidden(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG>
  67        <STRONG>PANEL</STRONG> <STRONG>*panel_above(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG>
  68        <STRONG>PANEL</STRONG> <STRONG>*panel_below(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG>
  69        <STRONG>int</STRONG> <STRONG>set_panel_userptr(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*ptr);</STRONG>
  70        <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*panel_userptr(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG>
  71        <STRONG>int</STRONG> <STRONG>del_panel(PANEL</STRONG> <STRONG>*pan);</STRONG>
  72
  73
  74 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  75        Panels  are  <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> windows with the added feature of depth.  Panel
  76        functions allow the use of stacked windows and ensure the  proper  por-
  77        tions  of  each  window and the curses <STRONG>stdscr</STRONG> window are hidden or dis-
  78        played when panels are added, moved, modified or removed.  The  set  of
  79        currently  visible panels is the stack of panels.  The <STRONG>stdscr</STRONG> window is
  80        beneath all panels, and is not considered part of the stack.
  81
  82        A window is associated with every panel. The panel routines enable  you
  83        to  create, move, hide, and show panels, as well as position a panel at
  84        any desired location in the stack.
  85
  86        Panel routines are a functional layer added to  <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,  make  only
  87        high-level curses calls, and work anywhere terminfo curses does.
  88
  89
  90 </PRE><H2><a name="h2-FUNCTIONS">FUNCTIONS</a></H2><PRE>
  91        <STRONG>new_panel(win)</STRONG>
  92               allocates   a   <STRONG>PANEL</STRONG>  structure, associates it with <STRONG>win</STRONG>, places
  93               the panel on the top of the stack  (causes  it to  be  displayed
  94               above any other panel) and returns a pointer to the new panel.
  95
  96        <STRONG>update_panels</STRONG>
  97               refreshes  the  virtual  screen to reflect the relations between
  98               the panels in the stack, but does not call <STRONG>doupdate</STRONG>  to  refresh
  99               the  physical  screen.   Use  this  function and not <STRONG>wrefresh</STRONG> or
 100               <STRONG>wnoutrefresh</STRONG>.  <STRONG>update_panels</STRONG> may be called more than once before
 101               a call to <STRONG>doupdate</STRONG>, but <STRONG>doupdate</STRONG> is the function responsible for
 102               updating the physical screen.
 103
 104        <STRONG>del_panel(pan)</STRONG>
 105               removes the given panel from  the   stack  and  deallocates  the
 106               <STRONG>PANEL</STRONG> structure (but not its associated window).
 107
 108        <STRONG>hide_panel(pan)</STRONG>
 109               removes  the  given panel from the panel stack and thus hides it
 110               from view. The <STRONG>PANEL</STRONG> structure is not lost, merely removed  from
 111               the stack.
 112
 113        <STRONG>panel_hidden(pan)</STRONG>
 114               returns  <STRONG>TRUE</STRONG> if the panel is in the panel stack, <STRONG>FALSE</STRONG> if it is
 115               not.  If the panel is a null pointer, return ERR.
 116
 117        <STRONG>show_panel(pan)</STRONG>
 118               makes a hidden panel visible by placing it on top of the  panels
 119               in the panel stack. See COMPATIBILITY below.
 120
 121        <STRONG>top_panel(pan)</STRONG>
 122               puts  the given visible panel on top of all panels in the stack.
 123               See COMPATIBILITY below.
 124
 125        <STRONG>bottom_panel(pan)</STRONG>
 126               puts panel at the bottom of all panels.
 127
 128        <STRONG>move_panel(pan,starty,startx)</STRONG>
 129               moves the given panel window so that its upper-left corner is at
 130               <STRONG>starty</STRONG>, <STRONG>startx</STRONG>.  It does not change the position of the panel in
 131               the stack.  Be sure to use this function, not <STRONG>mvwin</STRONG>, to  move  a
 132               panel window.
 133
 134        <STRONG>replace_panel(pan,window)</STRONG>
 135               replaces  the  current  window of panel with <STRONG>window</STRONG> (useful, for
 136               example if you want to resize a panel; if you're using  <STRONG>ncurses</STRONG>,
 137               you  can  call  <STRONG>replace_panel</STRONG> on the output of <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>).  It
 138               does not change the position of the panel in the stack.
 139
 140        <STRONG>panel_above(pan)</STRONG>
 141               returns a pointer to the panel above pan.  If the panel argument
 142               is  <STRONG>(PANEL</STRONG>  <STRONG>*)0</STRONG>, it returns a pointer to the bottom panel in the
 143               stack.
 144
 145        <STRONG>panel_below(pan)</STRONG>
 146               returns a pointer to the panel just below  pan.   If  the  panel
 147               argument is <STRONG>(PANEL</STRONG> <STRONG>*)0</STRONG>, it returns a pointer to the top panel in
 148               the stack.
 149
 150        <STRONG>set_panel_userptr(pan,ptr)</STRONG>
 151               sets the panel's user pointer.
 152
 153        <STRONG>panel_userptr(pan)</STRONG>
 154               returns the user pointer for a given panel.
 155
 156        <STRONG>panel_window(pan)</STRONG>
 157               returns a pointer to the window of the given panel.
 158
 159
 160 </PRE><H2><a name="h2-DIAGNOSTICS">DIAGNOSTICS</a></H2><PRE>
 161        Each routine that returns a pointer returns <STRONG>NULL</STRONG> if  an  error  occurs.
 162        Each  routine  that returns an int value returns <STRONG>OK</STRONG> if it executes suc-
 163        cessfully and <STRONG>ERR</STRONG> if not.
 164
 165
 166 </PRE><H2><a name="h2-COMPATIBILITY">COMPATIBILITY</a></H2><PRE>
 167        Reasonable care has been taken  to   ensure   compatibility  with   the
 168        native   panel  facility  introduced  in SVr3.2 (inspection of the SVr4
 169        manual pages suggests the programming  interface  is  unchanged).   The
 170        <STRONG>PANEL</STRONG> data structures are merely  similar. The  programmer is cautioned
 171        not to directly use <STRONG>PANEL</STRONG> fields.
 172
 173        The functions <STRONG>show_panel</STRONG> and <STRONG>top_panel</STRONG> are identical in this  implemen-
 174        tation,  and work equally well with displayed or hidden panels.  In the
 175        native System V implementation, <STRONG>show_panel</STRONG> is  intended  for  making  a
 176        hidden  panel  visible  (at  the  top  of  the  stack) and <STRONG>top_panel</STRONG> is
 177        intended for making an already-visible panel move to  the  top  of  the
 178        stack. You are cautioned to use the correct function to ensure compati-
 179        bility with native panel libraries.
 180
 181
 182 </PRE><H2><a name="h2-NOTE">NOTE</a></H2><PRE>
 183        In your library list, libpanel.a should be  before  libncurses.a;  that
 184        is, you should say "-lpanel -lncurses", not the other way around (which
 185        would give a link-error with static libraries).
 186
 187
 188 </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
 189        panel.h interface for the panels library
 190
 191        libpanel.a the panels library itself
 192
 193
 194 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 195        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
 196
 197        This describes <STRONG>ncurses</STRONG> version 6.0 (patch 20170603).
 198
 199
 200 </PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
 201        Originally written by Warren Tucker &lt;wht@n4hgf.mt-park.ga.us&gt;,  primar-
 202        ily  to  assist  in  porting u386mon to systems without a native panels
 203        library.  Repackaged for ncurses by Zeyd ben-Halim.
 204
 205
 206
 207                                                                      <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>
 208 </PRE>
 209 <div class="nav">
 210 <ul>
 211 <li><a href="#h2-NAME">NAME</a></li>
 212 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 213 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
 214 <li><a href="#h2-FUNCTIONS">FUNCTIONS</a></li>
 215 <li><a href="#h2-DIAGNOSTICS">DIAGNOSTICS</a></li>
 216 <li><a href="#h2-COMPATIBILITY">COMPATIBILITY</a></li>
 217 <li><a href="#h2-NOTE">NOTE</a></li>
 218 <li><a href="#h2-FILES">FILES</a></li>
 219 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 220 <li><a href="#h2-AUTHOR">AUTHOR</a></li>
 221 </ul>
 222 </div>
 223 </BODY>
 224 </HTML>