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

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
   2 <!--
   3   ****************************************************************************
   4   * Copyright (c) 1998-2006,2007 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.14 2007/05/12 20:45:20 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 wrefresh or wnoutrefresh.
 110               update_panels() may be called more than once before
 111               a  call  to doupdate(), but doupdate() is the func-
 112               tion 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>
 220
 221        This describes <STRONG>ncurses</STRONG> version 5.6 (patch 20081011).
 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>