ncurses 4.2
[ncurses.git] / Ada95 / html / man / panel.3x.html
1 <HTML>
2 <BODY>
3 <PRE>
4        panel - panel stack extension for curses
5
6
7 </PRE>
8 <H2>SYNOPSIS</H2><PRE>
9        <STRONG>#include</STRONG> <STRONG><panel.h></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  <wht@n4hgf.mt-
170        park.ga.us>, 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>