ncurses 5.6 - patch 20080621
[ncurses.git] / doc / html / man / panel.3x.html
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2 <!-- 
3   ****************************************************************************
4   * Copyright (c) 1998-2006,2007 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.14 2007/05/12 20:45:20 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 wrefresh or wnoutrefresh.
110               update_panels() may be called more than once before
111               a  call  to doupdate(), but doupdate() is the func-
112               tion 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>
220
221        This describes <STRONG>ncurses</STRONG> version 5.6 (patch 20080621).
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>