]> ncurses.scripts.mit.edu Git - ncurses.git/blobdiff - doc/html/man/panel.3x.html
ncurses 6.0 - patch 20170114
[ncurses.git] / doc / html / man / panel.3x.html
index a07930d54334384ac64d2f95b58d28458a682de2..15684b994a3aa387d69b8fc43c0c077e21044ca5 100644 (file)
+<!-- 
+  ****************************************************************************
+  * Copyright (c) 1998-2015,2016 Free Software Foundation, Inc.              *
+  *                                                                          *
+  * Permission is hereby granted, free of charge, to any person obtaining a  *
+  * copy of this software and associated documentation files (the            *
+  * "Software"), to deal in the Software without restriction, including      *
+  * without limitation the rights to use, copy, modify, merge, publish,      *
+  * distribute, distribute with modifications, sublicense, and/or sell       *
+  * copies of the Software, and to permit persons to whom the Software is    *
+  * furnished to do so, subject to the following conditions:                 *
+  *                                                                          *
+  * The above copyright notice and this permission notice shall be included  *
+  * in all copies or substantial portions of the Software.                   *
+  *                                                                          *
+  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+  *                                                                          *
+  * Except as contained in this notice, the name(s) of the above copyright   *
+  * holders shall not be used in advertising or otherwise to promote the     *
+  * sale, use or other dealings in this Software without prior written       *
+  * authorization.                                                           *
+  ****************************************************************************
+  * @Id: panel.3x,v 1.20 2016/10/15 17:02:31 tom Exp @
+-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 <HTML>
+<HEAD>
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+<meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
+<TITLE>panel 3x</TITLE>
+<link rev=made href="mailto:bug-ncurses@gnu.org">
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+</HEAD>
 <BODY>
 <BODY>
+<H1 class="no-header">panel 3x</H1>
 <PRE>
 <PRE>
-<!-- Manpage converted by man2html 3.0.1 -->
+<STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>                                                     <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>
 
 
-</PRE>
-<H2>NAME</H2><PRE>
+
+
+
+</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
        panel - panel stack extension for curses
 
 
        panel - panel stack extension for curses
 
 
-</PRE>
-<H2>SYNOPSIS</H2><PRE>
-       <B>#include</B> <B>&lt;panel.h&gt;</B>
-
-       <B>cc</B> <B>[flags]</B> <B>sourcefiles</B> <B>-lpanel</B> <B>-lncurses</B>
-
-       <B>PANEL</B> <B>*new_panel(WINDOW</B> <B>*win)</B>
-       <B>int</B> <B>bottom_panel(PANEL</B> <B>*pan)</B>
-       <B>int</B> <B>top_panel(PANEL</B> <B>*pan)</B>
-       <B>int</B> <B>show_panel(PANEL</B> <B>*pan)</B>
-       <B>void</B> <B>update_panels();</B>
-       <B>int</B> <B>hide_panel(PANEL</B> <B>*pan)</B>
-       <B>WINDOW</B> <B>*panel_window(const</B> <B>PANEL</B> <B>*pan)</B>
-       <B>int</B> <B>replace_panel(PANEL</B> <B>*pan,</B> <B>WINDOW</B> <B>*window)</B>
-       <B>int</B> <B>move_panel(PANEL</B> <B>*pan,</B> <B>int</B> <B>starty,</B> <B>int</B> <B>startx)</B>
-       <B>int</B> <B>panel_hidden(const</B> <B>PANEL</B> <B>*pan)</B>
-       <B>PANEL</B> <B>*panel_above(const</B> <B>PANEL</B> <B>*pan)</B>
-       <B>PANEL</B> <B>*panel_below(const</B> <B>PANEL</B> <B>*pan)</B>
-       <B>int</B> <B>set_panel_userptr(PANEL</B> <B>*pan,</B> <B>const</B> <B>void</B> <B>*ptr)</B>
-       <B>const</B> <B>void</B> <B>*panel_userptr(const</B> <B>PANEL</B> <B>*pan)</B>
-       <B>int</B> <B>del_panel(PANEL</B> <B>*pan)</B>
+</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
+       <STRONG>#include</STRONG> <STRONG>&lt;panel.h&gt;</STRONG>
 
 
+       <STRONG>cc</STRONG> <STRONG>[flags]</STRONG> <STRONG>sourcefiles</STRONG> <STRONG>-lpanel</STRONG> <STRONG>-lncurses</STRONG>
 
 
-</PRE>
-<H2>DESCRIPTION</H2><PRE>
-       Panels  are  <B><A HREF="ncurses.3x.html">curses(3x)</A></B>  windows with the added feature of
+       <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>void</STRONG> <STRONG>update_panels();</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>
+
+
+</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  portions  of each window and the
        depth.  Panel functions allow the use of  stacked  windows
        and  ensure  the  proper  portions  of each window and the
-       curses <B>stdscr</B> window are hidden or displayed  when  panels
+       curses <STRONG>stdscr</STRONG> window are hidden or displayed  when  panels
        are  added,  moved,  modified or removed.  The set of cur-
        are  added,  moved,  modified or removed.  The set of cur-
-       rently visible panels is the stack of panels.  The  <B>stdscr</B>
+       rently 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  rou-
        window  is  beneath all panels, and is not considered part
        of the stack.
 
        A window is associated with every panel.  The  panel  rou-
-       tines  enable you to create, move, hides, and show panels,
+       tines  enable  you to create, move, hide, and show panels,
        as well as position a panel at any desired location in the
        stack.
 
        as well as position a panel at any desired location in the
        stack.
 
-       Panel routines are a functional layer added to <B><A HREF="ncurses.3x.html">curses(3x)</A></B>,
+       Panel routines are a functional layer added to <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,
        make only high-level curses calls, and work anywhere  ter-
        minfo curses does.
 
 
        make only high-level curses calls, and work anywhere  ter-
        minfo curses does.
 
 
-</PRE>
-<H2>FUNCTIONS</H2><PRE>
-       <B>new_panel(win)</B>
-              allocates   a   <B>PANEL</B> structure, associates it with
-              <B>win</B>, places the panel  on  the  top  of  the  stack
+</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.
 
               (causes   it  to   be   displayed  above  any other
               panel) and returns a pointer to the new panel.
 
-       <B>void</B> <B>update_panels()</B>
+       <STRONG>update_panels</STRONG>
               refreshes the virtual screen to reflect  the  rela-
               tions between the panels in the stack, but does not
               refreshes the virtual screen to reflect  the  rela-
               tions between the panels in the stack, but does not
-              call doupdate() to  refresh  the  physical  screen.
-              Use this function and not wrefresh or wnoutrefresh.
-              update_panels() may be called more than once before
-              a  call  to doupdate(), but doupdate() is the func-
-              tion responsible for updating the physical  screen.
+              call <STRONG>doupdate</STRONG> to refresh the physical screen.   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 physical screen.
 
 
-       <B>del_panel(pan)</B>
+       <STRONG>del_panel(pan)</STRONG>
               removes the given panel from the  stack and deallo-
               removes the given panel from the  stack and deallo-
-              cates the <B>PANEL</B> structure (but not  its  associated
+              cates  the  <STRONG>PANEL</STRONG> structure (but not its associated
               window).
 
               window).
 
-       <B>hide_panel(pan)</B>
-              removes  the  given  panel from the panel stack and
-              thus hides it from view. The <B>PANEL</B> structure is not
+       <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.
 
               lost, merely removed from the stack.
 
-       <B>show_panel(pan)</B>
-              makes  a  hidden panel visible by placing it on top
+       <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 ERR.
+
+       <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.
 
               of the panels in the panel stack. See COMPATIBILITY
               below.
 
-       <B>top_panel(pan)</B>
-              puts  the  given visible panel on top of all panels
+       <STRONG>top_panel(pan)</STRONG>
+              puts the given visible panel on top of  all  panels
               in the stack.  See COMPATIBILITY below.
 
               in the stack.  See COMPATIBILITY below.
 
-       <B>bottom_panel(pan)</B>
+       <STRONG>bottom_panel(pan)</STRONG>
               puts panel at the bottom of all panels.
 
               puts panel at the bottom of all panels.
 
-       <B>move_panel(pan,starty,startx)</B>
+       <STRONG>move_panel(pan,starty,startx)</STRONG>
               moves the given panel window so that its upper-left
               moves the given panel window so that its upper-left
-              corner  is  at  <B>starty</B>, <B>startx</B>.  It does not change
+              corner is at <STRONG>starty</STRONG>, <STRONG>startx</STRONG>.  It  does  not  change
               the position of the panel in the stack.  Be sure to
               the position of the panel in the stack.  Be sure to
-              use  this  function,  not  <B>mvwin()</B>, to move a panel
-              window.
+              use this function, not <STRONG>mvwin</STRONG>, to move a panel  win-
+              dow.
 
 
-       <B>replace_panel(pan,window)</B>
-              replaces the current window of  panel  with  <B>window</B>
+       <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;
               (useful, for example if you want to resize a panel;
-              if you're using <B>ncurses</B>, you can call <B>replace_panel</B>
-              on  the output of <B><A HREF="wresize.3x.html">wresize(3x)</A></B>).  It does not change
+              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.
 
               the position of the panel in the stack.
 
-       <B>panel_above(pan)</B>
-              returns a pointer to the panel above pan.   If  the
-              panel  argument is <B>(PANEL</B> <B>*)0</B>, it returns a pointer
+       <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.
 
               to the bottom panel in the stack.
 
-       <B>panel_below(pan)</B>
-              returns a pointer to the panel just below pan.   If
-              the  panel  argument  is  <B>(PANEL</B>  <B>*)0</B>, it returns a
+       <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.
 
               pointer to the top panel in the stack.
 
-       <B>set_panel_userptr(pan,ptr)</B>
+       <STRONG>set_panel_userptr(pan,ptr)</STRONG>
               sets the panel's user pointer.
 
               sets the panel's user pointer.
 
-       <B>panel_userptr(pan)</B>
+       <STRONG>panel_userptr(pan)</STRONG>
               returns the user pointer for a given panel.
 
               returns the user pointer for a given panel.
 
-       <B>panel_window(pan)</B>
+       <STRONG>panel_window(pan)</STRONG>
               returns a pointer to the window of the given panel.
 
 
               returns a pointer to the window of the given panel.
 
 
-</PRE>
-<H2>DIAGNOSTICS</H2><PRE>
-       Each  routine  that  returns  a pointer returns <B>NULL</B> if an
+</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
        error occurs. Each  routine  that  returns  an  int  value
-       returns <B>OK</B> if it executes successfully and <B>ERR</B> if not.
+       returns <STRONG>OK</STRONG> if it executes successfully and <STRONG>ERR</STRONG> if not.
 
 
 
 
-</PRE>
-<H2>COMPATIBILITY</H2><PRE>
+</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  SVr3.2
        (inspection of the SVr4 manual pages suggests the program-
        Reasonable  care  has been taken to  ensure  compatibility
        with  the  native  panel  facility  introduced  in  SVr3.2
        (inspection of the SVr4 manual pages suggests the program-
-       ming interface is unchanged).  The <B>PANEL</B>  data  structures
+       ming interface is unchanged).  The <STRONG>PANEL</STRONG>  data  structures
        are  merely   similar. The  programmer is cautioned not to
        are  merely   similar. The  programmer is cautioned not to
-       directly use <B>PANEL</B> fields.
+       directly use <STRONG>PANEL</STRONG> fields.
 
 
-       The functions <B>show_panel()</B> and <B>top_panel()</B>  are  identical
-       in  this  implementation,  and work equally well with dis-
-       played or hidden panels.  In the native System V implemen-
-       tation, <B>show_panel()</B> is intended for making a hidden panel
-       visible (at the top  of  the  stack)  and  <B>top_panel()</B>  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.
+       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>NOTE</H2><PRE>
-       In your library list, libpanel.a should  be  before  libn-
-       curses.a;  that  is,  you want to say `-lpanel -lncurses',
-       not the other way around (which  would  give  you  a  link
-       error using GNU <B><A HREF="ld.1.html">ld(1)</A></B> and some other linkers).
+</PRE><H2><a name="h2-NOTE">NOTE</a></H2><PRE>
+       In  your  library  list, libpanel.a should be before libn-
+       curses.a; that is, you want to  say  `-lpanel  -lncurses',
+       not the other way around (which would usually give a link-
+       error).
 
 
 
 
-</PRE>
-<H2>FILES</H2><PRE>
+</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
        panel.h interface for the panels library
 
        libpanel.a the panels library itself
 
 
        panel.h interface for the panels library
 
        libpanel.a the panels library itself
 
 
-</PRE>
-<H2>SEE ALSO</H2><PRE>
-       <B><A HREF="ncurses.3x.html">curses(3x)</A></B>
-
-
-</PRE>
-<H2>AUTHOR</H2><PRE>
-       Originally   written   by   Warren  Tucker  &lt;wht@n4hgf.mt-
-       park.ga.us&gt;, primarily to assist  in  porting  u386mon  to
-       systems  without  a native panels library.  Repackaged for
-       ncurses by Zeyd ben-Halim.
+</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.0 (patch 20170114).
 
 
 
 
+</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
+       Originally  written  by   Warren   Tucker   &lt;wht@n4hgf.mt-
+       park.ga.us&gt;,  primarily  to  assist  in porting u386mon to
+       systems without a native panels library.   Repackaged  for
+       ncurses by Zeyd ben-Halim.
 
 
 
 
 
 
+                                                              <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>
 </PRE>
 </PRE>
-<HR>
-<ADDRESS>
-Man(1) output converted with
-<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
-</ADDRESS>
+<div class="nav">
+<ul>
+<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-DIAGNOSTICS">DIAGNOSTICS</a></li>
+<li><a href="#h2-COMPATIBILITY">COMPATIBILITY</a></li>
+<li><a href="#h2-NOTE">NOTE</a></li>
+<li><a href="#h2-FILES">FILES</a></li>
+<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
+<li><a href="#h2-AUTHOR">AUTHOR</a></li>
+</ul>
+</div>
 </BODY>
 </HTML>
 </BODY>
 </HTML>