diff options
Diffstat (limited to 'doc/html/man/panel.3x.html')
| -rw-r--r-- | doc/html/man/panel.3x.html | 312 |
1 files changed, 206 insertions, 106 deletions
diff --git a/doc/html/man/panel.3x.html b/doc/html/man/panel.3x.html index 2d44419..24d5087 100644 --- a/doc/html/man/panel.3x.html +++ b/doc/html/man/panel.3x.html @@ -1,4 +1,4 @@ -<!-- +<!-- **************************************************************************** * Copyright 2018-2019,2020 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * @@ -27,7 +27,24 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: panel.3x,v 1.28 2020/02/02 23:34:34 tom Exp @ + * @Id: panel.3x,v 1.39 2020/02/15 21:06:40 tom Exp @ + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- + * --------- --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> @@ -55,30 +72,39 @@ <STRONG>cc</STRONG> <STRONG>[flags]</STRONG> <STRONG>sourcefiles</STRONG> <STRONG>-lpanel</STRONG> <STRONG>-lncurses</STRONG> - <STRONG>PANEL</STRONG> <STRONG>*new_panel(WINDOW</STRONG> <STRONG>*win);</STRONG> - <STRONG>int</STRONG> <STRONG>bottom_panel(PANEL</STRONG> <STRONG>*pan);</STRONG> - <STRONG>int</STRONG> <STRONG>top_panel(PANEL</STRONG> <STRONG>*pan);</STRONG> - <STRONG>int</STRONG> <STRONG>show_panel(PANEL</STRONG> <STRONG>*pan);</STRONG> + <STRONG>PANEL</STRONG> <STRONG>*new_panel(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>bottom_panel(PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>top_panel(PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>show_panel(PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>);</STRONG> <STRONG>void</STRONG> <STRONG>update_panels(void);</STRONG> - <STRONG>int</STRONG> <STRONG>hide_panel(PANEL</STRONG> <STRONG>*pan);</STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*panel_window(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG> - <STRONG>int</STRONG> <STRONG>replace_panel(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*window);</STRONG> - <STRONG>int</STRONG> <STRONG>move_panel(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>int</STRONG> <STRONG>starty,</STRONG> <STRONG>int</STRONG> <STRONG>startx);</STRONG> - <STRONG>int</STRONG> <STRONG>panel_hidden(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG> - <STRONG>PANEL</STRONG> <STRONG>*panel_above(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG> - <STRONG>PANEL</STRONG> <STRONG>*panel_below(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG> - <STRONG>int</STRONG> <STRONG>set_panel_userptr(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*ptr);</STRONG> - <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*panel_userptr(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG> - <STRONG>int</STRONG> <STRONG>del_panel(PANEL</STRONG> <STRONG>*pan);</STRONG> + <STRONG>int</STRONG> <STRONG>hide_panel(PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>);</STRONG> + + <STRONG>WINDOW</STRONG> <STRONG>*panel_window(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>replace_panel(PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>,</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>window</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>move_panel(PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>starty</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>startx</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>panel_hidden(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>);</STRONG> + + <STRONG>PANEL</STRONG> <STRONG>*panel_above(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>);</STRONG> + <STRONG>PANEL</STRONG> <STRONG>*panel_below(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>set_panel_userptr(PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>ptr</EM><STRONG>);</STRONG> + <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*panel_userptr(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>del_panel(PANEL</STRONG> <STRONG>*</STRONG><EM>pan</EM><STRONG>);</STRONG> + + /* ncurses-extensions */ + <STRONG>PANEL</STRONG> <STRONG>*ground_panel(SCREEN</STRONG> <STRONG>*</STRONG><EM>sp</EM><STRONG>);</STRONG> + <STRONG>PANEL</STRONG> <STRONG>*ceiling_panel(SCREEN</STRONG> <STRONG>*</STRONG><EM>sp</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> Panels are <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> windows with the added feature of depth. Panel - functions allow the use of stacked windows and ensure the proper por- - tions of each window and the curses <STRONG>stdscr</STRONG> window are hidden or dis- - played when panels are added, moved, modified or removed. The set of - currently visible panels is the stack of panels. The <STRONG>stdscr</STRONG> window is - beneath all panels, and is not considered part of the stack. + functions allow the use of stacked windows and ensure the proper + portions of each window and the curses <STRONG>stdscr</STRONG> window are hidden or + displayed when panels are added, moved, modified or removed. The set + of currently visible panels is the stack of panels. The <STRONG>stdscr</STRONG> window + is beneath all panels, and is not considered part of the stack. A window is associated with every panel. The panel routines enable you to create, move, hide, and show panels, as well as position a panel at @@ -89,95 +115,128 @@ </PRE><H2><a name="h2-FUNCTIONS">FUNCTIONS</a></H2><PRE> - <STRONG>new_panel(win)</STRONG> - allocates a <STRONG>PANEL</STRONG> structure, associates it with <STRONG>win</STRONG>, places - the panel on the top of the stack (causes it to be displayed - above any other panel) and returns a pointer to the new panel. - - <STRONG>update_panels</STRONG> - refreshes the <EM>virtual</EM> <EM>screen</EM> to reflect the relations between - the panels in the stack, but does not call <STRONG>doupdate</STRONG> to refresh - the <EM>physical</EM> <EM>screen</EM>. Use this function and not <STRONG>wrefresh</STRONG> or - <STRONG>wnoutrefresh</STRONG>. <STRONG>update_panels</STRONG> may be called more than once before - a call to <STRONG>doupdate</STRONG>, but <STRONG>doupdate</STRONG> is the function responsible for - updating the <EM>physical</EM> <EM>screen</EM>. - - <STRONG>del_panel(pan)</STRONG> - removes the given panel from the stack and deallocates the - <STRONG>PANEL</STRONG> structure (but not its associated window). - - <STRONG>hide_panel(pan)</STRONG> - removes the given panel from the panel stack and thus hides it - from view. The <STRONG>PANEL</STRONG> structure is not lost, merely removed from - the stack. - - <STRONG>panel_hidden(pan)</STRONG> - returns <STRONG>TRUE</STRONG> if the panel is in the panel stack, <STRONG>FALSE</STRONG> if it is - not. If the panel is a null pointer, return <STRONG>ERR</STRONG>. - - <STRONG>show_panel(pan)</STRONG> - makes a hidden panel visible by placing it on top of the panels - in the panel stack. See COMPATIBILITY below. - - <STRONG>top_panel(pan)</STRONG> - puts the given visible panel on top of all panels in the stack. - See COMPATIBILITY below. - - <STRONG>bottom_panel(pan)</STRONG> - puts panel at the bottom of all panels. - - <STRONG>move_panel(pan,starty,startx)</STRONG> - moves the given panel window so that its upper-left corner is at - <STRONG>starty</STRONG>, <STRONG>startx</STRONG>. It does not change the position of the panel in - the stack. Be sure to use this function, not <STRONG>mvwin</STRONG>, to move a - panel window. - - <STRONG>replace_panel(pan,window)</STRONG> - replaces the current window of panel with <STRONG>window</STRONG> (useful, for - example if you want to resize a panel; if you're using <STRONG>ncurses</STRONG>, - you can call <STRONG>replace_panel</STRONG> on the output of <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>). It - does not change the position of the panel in the stack. - - <STRONG>panel_above(pan)</STRONG> - returns a pointer to the panel above pan. If the panel argument - is <STRONG>(PANEL</STRONG> <STRONG>*)0</STRONG>, it returns a pointer to the bottom panel in the - stack. - - <STRONG>panel_below(pan)</STRONG> - returns a pointer to the panel just below pan. If the panel - argument is <STRONG>(PANEL</STRONG> <STRONG>*)0</STRONG>, it returns a pointer to the top panel in - the stack. - - <STRONG>set_panel_userptr(pan,ptr)</STRONG> - sets the panel's user pointer. - - <STRONG>panel_userptr(pan)</STRONG> - returns the user pointer for a given panel. - - <STRONG>panel_window(pan)</STRONG> - returns a pointer to the window of the given panel. + +</PRE><H3><a name="h3-bottom_panel">bottom_panel</a></H3><PRE> + <STRONG>bottom_panel(</STRONG><EM>pan</EM><STRONG>)</STRONG> puts panel <EM>pan</EM> at the bottom of all panels. + + +</PRE><H3><a name="h3-ceiling_panel">ceiling_panel</a></H3><PRE> + <STRONG>ceiling_panel(</STRONG><EM>sp</EM><STRONG>)</STRONG> acts like <STRONG>panel_below(NULL)</STRONG>, for the given <STRONG>SCREEN</STRONG> <EM>sp</EM>. + + +</PRE><H3><a name="h3-del_panel">del_panel</a></H3><PRE> + <STRONG>del_panel(</STRONG><EM>pan</EM><STRONG>)</STRONG> removes the given panel <EM>pan</EM> from the stack and + deallocates the <STRONG>PANEL</STRONG> structure (but not its associated window). + + +</PRE><H3><a name="h3-ground_panel">ground_panel</a></H3><PRE> + <STRONG>ground_panel(</STRONG><EM>sp</EM><STRONG>)</STRONG> acts like <STRONG>panel_above(NULL)</STRONG>, for the given <STRONG>SCREEN</STRONG> <EM>sp</EM>. + + +</PRE><H3><a name="h3-hide_panel">hide_panel</a></H3><PRE> + <STRONG>hide_panel(</STRONG><EM>pan</EM><STRONG>)</STRONG> removes the given panel <EM>pan</EM> from the panel stack and + thus hides it from view. The <STRONG>PANEL</STRONG> structure is not lost, merely + removed from the stack. + + +</PRE><H3><a name="h3-move_panel">move_panel</a></H3><PRE> + <STRONG>move_panel(</STRONG><EM>pan</EM><STRONG>,</STRONG><EM>starty</EM><STRONG>,</STRONG><EM>startx</EM><STRONG>)</STRONG> moves the given panel <EM>pan</EM>'s window so + that its upper-left corner is at <EM>starty</EM>, <EM>startx</EM>. It does not change + the position of the panel in the stack. Be sure to use this function, + not <STRONG><A HREF="curs_window.3x.html">mvwin(3x)</A></STRONG>, to move a panel window. + + +</PRE><H3><a name="h3-new_panel">new_panel</a></H3><PRE> + <STRONG>new_panel(</STRONG><EM>win</EM><STRONG>)</STRONG> allocates a <STRONG>PANEL</STRONG> structure, associates it with <EM>win</EM>, + places the panel on the top of the stack (causes it to be displayed + above any other panel) and returns a pointer to the new panel. + + +</PRE><H3><a name="h3-panel_above">panel_above</a></H3><PRE> + <STRONG>panel_above(</STRONG><EM>pan</EM><STRONG>)</STRONG> returns a pointer to the panel above <EM>pan</EM>. If the + panel argument is <STRONG>(PANEL</STRONG> <STRONG>*)0</STRONG>, it returns a pointer to the bottom panel + in the stack. + + +</PRE><H3><a name="h3-panel_below">panel_below</a></H3><PRE> + <STRONG>panel_below(</STRONG><EM>pan</EM><STRONG>)</STRONG> returns a pointer to the panel just below <EM>pan</EM>. If the + panel argument is <STRONG>(PANEL</STRONG> <STRONG>*)0</STRONG>, it returns a pointer to the top panel in + the stack. + + +</PRE><H3><a name="h3-panel_hidden">panel_hidden</a></H3><PRE> + <STRONG>panel_hidden(</STRONG><EM>pan</EM><STRONG>)</STRONG> returns <STRONG>TRUE</STRONG> if the panel <EM>pan</EM> is in the panel stack, + <STRONG>FALSE</STRONG> if it is not. If the panel is a null pointer, return <STRONG>ERR</STRONG>. + + +</PRE><H3><a name="h3-panel_userptr">panel_userptr</a></H3><PRE> + <STRONG>panel_userptr(</STRONG><EM>pan</EM><STRONG>)</STRONG> returns the user pointer for a given panel <EM>pan</EM>. + + +</PRE><H3><a name="h3-panel_window">panel_window</a></H3><PRE> + <STRONG>panel_window(</STRONG><EM>pan</EM><STRONG>)</STRONG> returns a pointer to the window of the given panel + <EM>pan</EM>. + + +</PRE><H3><a name="h3-replace_panel">replace_panel</a></H3><PRE> + <STRONG>replace_panel(</STRONG><EM>pan</EM><STRONG>,</STRONG><EM>window</EM><STRONG>)</STRONG> replaces the current window of panel <EM>pan</EM> with + <EM>window</EM> This is useful, for example if you want to resize a panel. In + <STRONG>ncurses</STRONG>, you can call <STRONG>replace_panel</STRONG> to resize a panel using a window + resized with <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>. It does not change the position of the panel + in the stack. + + +</PRE><H3><a name="h3-set_panel_userptr">set_panel_userptr</a></H3><PRE> + <STRONG>set_panel_userptr(</STRONG><EM>pan</EM><STRONG>,</STRONG><EM>ptr</EM><STRONG>)</STRONG> sets the panel's user pointer. + + +</PRE><H3><a name="h3-show_panel">show_panel</a></H3><PRE> + <STRONG>show_panel(</STRONG><EM>pan</EM><STRONG>)</STRONG> makes a hidden panel visible by placing it on top of + the panels in the panel stack. See <STRONG>COMPATIBILITY</STRONG> below. + + +</PRE><H3><a name="h3-top_panel">top_panel</a></H3><PRE> + <STRONG>top_panel(</STRONG><EM>pan</EM><STRONG>)</STRONG> puts the given visible panel <EM>pan</EM> on top of all panels in + the stack. See <STRONG>COMPATIBILITY</STRONG> below. + + +</PRE><H3><a name="h3-update_panels">update_panels</a></H3><PRE> + <STRONG>update_panels()</STRONG> refreshes the <EM>virtual</EM> <EM>screen</EM> to reflect the relations + between the panels in the stack, but does not call <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> to + refresh the <EM>physical</EM> <EM>screen</EM>. Use this function and not <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG> or + <STRONG><A HREF="curs_refresh.3x.html">wnoutrefresh(3x)</A></STRONG>. + + <STRONG>update_panels</STRONG> may be called more than once before a call to <STRONG>doupdate</STRONG>, + but <STRONG>doupdate</STRONG> is the function responsible for updating the <EM>physical</EM> + <EM>screen</EM>. </PRE><H2><a name="h2-DIAGNOSTICS">DIAGNOSTICS</a></H2><PRE> Each routine that returns a pointer returns <STRONG>NULL</STRONG> if an error occurs. - Each routine that returns an int value returns <STRONG>OK</STRONG> if it executes suc- - cessfully and <STRONG>ERR</STRONG> if not. + Each routine that returns an int value returns <STRONG>OK</STRONG> if it executes + successfully and <STRONG>ERR</STRONG> if not. + + Except as noted, the <EM>pan</EM> and <EM>window</EM> parameters must be non-null. If + those are null, an error is returned. + + The <STRONG>move_panel</STRONG> function uses <STRONG><A HREF="curs_window.3x.html">mvwin(3x)</A></STRONG>, and will return an error if + <STRONG>mvwin</STRONG> returns an error. </PRE><H2><a name="h2-COMPATIBILITY">COMPATIBILITY</a></H2><PRE> Reasonable care has been taken to ensure compatibility with the native panel facility introduced in System V (inspection of the SVr4 manual pages suggests the programming interface is unchanged). The - <STRONG>PANEL</STRONG> data structures are merely similar. The programmer is cau- - tioned not to directly use <STRONG>PANEL</STRONG> fields. + <STRONG>PANEL</STRONG> data structures are merely similar. The programmer is + cautioned not to directly use <STRONG>PANEL</STRONG> fields. - The functions <STRONG>show_panel</STRONG> and <STRONG>top_panel</STRONG> are identical in this implemen- - tation, and work equally well with displayed or hidden panels. In the - native System V implementation, <STRONG>show_panel</STRONG> is intended for making a - hidden panel visible (at the top of the stack) and <STRONG>top_panel</STRONG> is - intended for making an already-visible panel move to the top of the - stack. You are cautioned to use the correct function to ensure compat- - ibility with native panel libraries. + The functions <STRONG>show_panel</STRONG> and <STRONG>top_panel</STRONG> are identical in this + implementation, and work equally well with displayed or hidden panels. + In the native System V implementation, <STRONG>show_panel</STRONG> is intended for + making a hidden panel visible (at the top of the stack) and <STRONG>top_panel</STRONG> + is intended for making an already-visible panel move to the top of the + stack. You are cautioned to use the correct function to ensure + compatibility with native panel libraries. </PRE><H2><a name="h2-NOTE">NOTE</a></H2><PRE> @@ -192,8 +251,25 @@ It is not part of X/Open Curses. - Aside from ncurses, only systems based on SVr4 source code, e.g., - Solaris provide this library. + A few implementations exist: + + <STRONG>o</STRONG> Systems based on SVr4 source code, e.g., Solaris, provide this + library. + + <STRONG>o</STRONG> <STRONG>ncurses</STRONG> (since version 0.6 in 1993) and <STRONG>PDCurses</STRONG> (since version 2.2 + in 1995) provide a panel library whose common ancestor was a public + domain implementation by Warren Tucker published in <EM>u386mon</EM> 2.20 + (1990). + + According to Tucker, the SystemV panel library was first released + in SVr3.2 (1988), and his implementation helped with a port to + SVr3.1 (1987). + + Several developers have improved each of these; they are no longer + the same as Tucker's implementation. + + <STRONG>o</STRONG> NetBSD 8 (2018) has a panel library begun by Valery Ushakov in + 2015. This is based on the AT&T documentation. </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE> @@ -205,13 +281,17 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, - This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20200212). + This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20211021). </PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE> - Originally written by Warren Tucker <wht@n4hgf.mt-park.ga.us>, primar- - ily to assist in porting u386mon to systems without a native panels - library. Repackaged for ncurses by Zeyd ben-Halim. + Originally written by Warren Tucker <wht@n4hgf.mt-park.ga.us>, + primarily to assist in porting <EM>u386mon</EM> to systems without a native + panels library. + + Repackaged for ncurses by Zeyd ben-Halim. + + Juergen Pfeifer and Thomas E. Dickey revised/improved the library. @@ -222,7 +302,27 @@ <li><a href="#h2-NAME">NAME</a></li> <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> -<li><a href="#h2-FUNCTIONS">FUNCTIONS</a></li> +<li><a href="#h2-FUNCTIONS">FUNCTIONS</a> +<ul> +<li><a href="#h3-bottom_panel">bottom_panel</a></li> +<li><a href="#h3-ceiling_panel">ceiling_panel</a></li> +<li><a href="#h3-del_panel">del_panel</a></li> +<li><a href="#h3-ground_panel">ground_panel</a></li> +<li><a href="#h3-hide_panel">hide_panel</a></li> +<li><a href="#h3-move_panel">move_panel</a></li> +<li><a href="#h3-new_panel">new_panel</a></li> +<li><a href="#h3-panel_above">panel_above</a></li> +<li><a href="#h3-panel_below">panel_below</a></li> +<li><a href="#h3-panel_hidden">panel_hidden</a></li> +<li><a href="#h3-panel_userptr">panel_userptr</a></li> +<li><a href="#h3-panel_window">panel_window</a></li> +<li><a href="#h3-replace_panel">replace_panel</a></li> +<li><a href="#h3-set_panel_userptr">set_panel_userptr</a></li> +<li><a href="#h3-show_panel">show_panel</a></li> +<li><a href="#h3-top_panel">top_panel</a></li> +<li><a href="#h3-update_panels">update_panels</a></li> +</ul> +</li> <li><a href="#h2-DIAGNOSTICS">DIAGNOSTICS</a></li> <li><a href="#h2-COMPATIBILITY">COMPATIBILITY</a></li> <li><a href="#h2-NOTE">NOTE</a></li> |