--- name: "bottom_panel" section: "3curses" platform: "linux" package: "ncurses-doc" version: "6.4-4" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/panel/3curses" --- # bottom\_panel(3curses) panel stack extension for curses Part of [panel(3curses)](/panel/3curses.md). ## NAME panel - panel stack extension for curses ## SYNOPSIS **#include \** **cc \[flags\] sourcefiles -lpanel -lncurses** **PANEL \*new\_panel(WINDOW \****win***);** **int bottom\_panel(PANEL \****pan***);**\ **int top\_panel(PANEL \****pan***);**\ **int show\_panel(PANEL \****pan***);**\ **void update\_panels(void);**\ **int hide\_panel(PANEL \****pan***);** **WINDOW \*panel\_window(const PANEL \****pan***);**\ **int replace\_panel(PANEL \****pan***, WINDOW \****window***);**\ **int move\_panel(PANEL \****pan***, int** *starty***, int** *startx***);**\ **int panel\_hidden(const PANEL \****pan***);** **PANEL \*panel\_above(const PANEL \****pan***);**\ **PANEL \*panel\_below(const PANEL \****pan***);** **int set\_panel\_userptr(PANEL \****pan***, const void \****ptr***);**\ **const void \*panel\_userptr(const PANEL \****pan***);** **int del\_panel(PANEL \****pan***);** /\* ncurses-extensions \*/\ **PANEL \*ground\_panel(SCREEN \****sp***);**\ **PANEL \*ceiling\_panel(SCREEN \****sp***);**\ ## DESCRIPTION Panels are **ncurses**(3NCURSES) 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 curses **stdscr** 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 **stdscr** 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 any desired location in the stack. Panel routines are a functional layer added to **ncurses**(3NCURSES), make only high-level curses calls, and work anywhere terminfo curses does. ## FUNCTIONS ### bottom\_panel **bottom\_panel(***pan***)** puts panel *pan* at the bottom of all panels. ### ceiling\_panel **ceiling\_panel(***sp***)** acts like **panel\_below(NULL)**, for the given **SCREEN** *sp*. ### del\_panel **del\_panel(***pan***)** removes the given panel *pan* from the stack and deallocates the **PANEL** structure (but not its associated window). ### ground\_panel **ground\_panel(***sp***)** acts like **panel\_above(NULL)**, for the given **SCREEN** *sp*. ### hide\_panel **hide\_panel(***pan***)** removes the given panel *pan* from the panel stack and thus hides it from view. The **PANEL** structure is not lost, merely removed from the stack. ### move\_panel **move\_panel(***pan***,***starty***,***startx***)** moves the given panel *pan*'s window so that its upper-left corner is at *starty*, *startx*. It does not change the position of the panel in the stack. Be sure to use this function, not **mvwin**(3X), to move a panel window. ### new\_panel **new\_panel(***win***)** allocates a **PANEL** structure, associates it with *win*, 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. ### panel\_above **panel\_above(***pan***)** returns a pointer to the panel above *pan*. If the panel argument is **(PANEL \*)0**, it returns a pointer to the bottom panel in the stack. ### panel\_below **panel\_below(***pan***)** returns a pointer to the panel just below *pan*. If the panel argument is **(PANEL \*)0**, it returns a pointer to the top panel in the stack. ### panel\_hidden **panel\_hidden(***pan***)** returns **TRUE** if the panel *pan* is in the panel stack, **FALSE** if it is not. If the panel is a null pointer, return **ERR**. ### panel\_userptr **panel\_userptr(***pan***)** returns the user pointer for a given panel *pan*. ### panel\_window **panel\_window(***pan***)** returns a pointer to the window of the given panel *pan*. ### replace\_panel **replace\_panel(***pan***,***window***)** replaces the current window of panel *pan* with *window* This is useful, for example if you want to resize a panel. In **ncurses**, you can call **replace\_panel** to resize a panel using a window resized with **wresize**(3NCURSES). It does not change the position of the panel in the stack. ### set\_panel\_userptr **set\_panel\_userptr(***pan***,***ptr***)** sets the panel's user pointer. ### show\_panel **show\_panel(***pan***)** makes a hidden panel visible by placing it on top of the panels in the panel stack. See **COMPATIBILITY** below. ### top\_panel **top\_panel(***pan***)** puts the given visible panel *pan* on top of all panels in the stack. See **COMPATIBILITY** below. ### update\_panels **update\_panels()** refreshes the *virtual screen* to reflect the relations between the panels in the stack, but does not call **doupdate**(3X) to refresh the *physical screen*. Use this function and not **wrefresh**(3X) or **wnoutrefresh**(3X). **update\_panels** may be called more than once before a call to **doupdate**, but **doupdate** is the function responsible for updating the *physical screen*. ## DIAGNOSTICS Each routine that returns a pointer returns **NULL** if an error occurs. Each routine that returns an int value returns **OK** if it executes successfully and **ERR** if not. Except as noted, the *pan* and *window* parameters must be non-null. If those are null, an error is returned. The **move\_panel** function uses **mvwin**(3X), and will return an error if **mvwin** returns an error. ## COMPATIBILITY 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 **PANEL** data structures are merely similar. The programmer is cautioned not to directly use **PANEL** fields. The functions **show\_panel** and **top\_panel** are identical in this implementation, and work equally well with displayed or hidden panels. In the native System V implementation, **show\_panel** is intended for making a hidden panel visible (at the top of the stack) and **top\_panel** 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. ## NOTE In your library list, libpanel.a should be before libncurses.a; that is, you should say “-lpanel -lncurses”, not the other way around (which would give a link-error with static libraries). ## PORTABILITY The panel facility was documented in SVr4.2 in *Character User Interface Programming (UNIX SVR4.2)*. It is not part of X/Open Curses. A few implementations exist: - • Systems based on SVr4 source code, e.g., Solaris, provide this library. - • **ncurses** (since version 0.6 in 1993) and **PDCurses** (since version 2.2 in 1995) provide a panel library whose common ancestor was a public domain implementation by Warren Tucker published in *u386mon* 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. - • NetBSD 8 (2018) has a panel library begun by Valery Ushakov in 2015. This is based on the AT&T documentation. ## FILES panel.h interface for the panels library libpanel.a the panels library itself ## SEE ALSO **ncurses**(3NCURSES), **curses\_variables**(3NCURSES), This describes **ncurses** version 6.4 (patch 20221231). ## AUTHOR Originally written by Warren Tucker \, primarily to assist in porting *u386mon* to systems without a native panels library. Repackaged for ncurses by Zeyd ben-Halim. Juergen Pfeifer and Thomas E. Dickey revised/improved the library.