2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
4 panel - panel stack extension for curses
9 <STRONG>#include</STRONG> <STRONG><panel.h></STRONG>
11 <STRONG>cc</STRONG> <STRONG>[flags]</STRONG> <STRONG>sourcefiles</STRONG> <STRONG>-lpanel</STRONG> <STRONG>-lncurses</STRONG>
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>
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
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
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-
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.
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.
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
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.
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
81 <STRONG>top_panel(pan)</STRONG>
82 puts the given visible panel on top of all panels
83 in the stack. See COMPATIBILITY below.
85 <STRONG>bottom_panel(pan)</STRONG>
86 puts panel at the bottom of all panels.
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
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.
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.
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.
112 <STRONG>set_panel_userptr(pan,ptr)</STRONG>
113 sets the panel's user pointer.
114 returns the user pointer for a given panel.
116 <STRONG>panel_window(pan)</STRONG>
117 returns a pointer to the window of the given panel.
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.
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.
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
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).
157 panel.h interface for the panels library
159 libpanel.a the panels library itself
163 <H2>SEE ALSO</H2><PRE>
164 <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>
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.