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