--- name: "panel" section: "3x" platform: "macos" package: "ncurses" version: "79" release: "macOS 26.5" platforms: ["linux", "macos"] url: "https://new.carta.tech/panel/3x" --- # panel(3x) panel stack extension for curses ## 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();**\ **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)**\ ## DESCRIPTION Panels are **curses**(3X) 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 **curses**(3X), make only high-level curses calls, and work anywhere terminfo curses does. ## FUNCTIONS - **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. - **update\_panels()** refreshes the virtual screen to reflect the relations 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 function responsible for updating the physical screen. - **del\_panel(pan)** removes the given panel from the stack and deallocates the **PANEL** structure (but not its associated window). - **hide\_panel(pan)** removes the given panel from the panel stack and thus hides it from view. The **PANEL** structure is not lost, merely removed from the stack. - **panel\_hidden(pan)** returns **TRUE** if the panel is in the panel stack, **FALSE** if it is not. If the panel is a null pointer, return ERR. - **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(pan)** puts the given visible panel on top of all panels in the stack. See COMPATIBILITY below. - **bottom\_panel(pan)** puts panel at the bottom of all panels. - **move\_panel(pan,starty,startx)** moves the given panel 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()**, to move a panel window. - **replace\_panel(pan,window)** replaces the current window of panel with **window** (useful, for example if you want to resize a panel; if you're using **ncurses**, you can call **replace\_panel** on the output of **wresize**(3X)). It does not change the position of the panel in the stack. - **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(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. - **set\_panel\_userptr(pan,ptr)** sets the panel's user pointer. - **panel\_userptr(pan)** returns the user pointer for a given panel. - **panel\_window(pan)** returns a pointer to the window of the given panel. ## 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. ## COMPATIBILITY 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 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 want to say \`-lpanel -lncurses', not the other way around (which would usually give a link-error). ## FILES panel.h interface for the panels library libpanel.a the panels library itself ## SEE ALSO **curses**(3X), **curs\_variables**(3X), This describes **ncurses** version @NCURSES\_MAJOR@.@NCURSES\_MINOR@ (patch @NCURSES\_PATCH@). ## 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.