doc/html/man/panel.3x.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
   2 <!--
   3   ****************************************************************************
   4   * Copyright (c) 1998-2007,2010 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.17 2010/10/02 23:22:44 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 <STRONG>wrefresh</STRONG> or <STRONG>wnoutrefresh</STRONG>.
 110               <STRONG>update_panels</STRONG> may be called more than once before a
 111               call  to doupdate(), but doupdate() is the function
 112               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>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
 220
 221        This describes <STRONG>ncurses</STRONG> version 5.9 (patch 20120107).
 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>