ncurses 6.0 - patch 20171118
[ncurses.git] / 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 20171118).
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>