--- name: "bottom_panel" section: "3ncurses" platform: "linux" package: "ncurses-doc" version: "6.5+20250216-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/panel/3ncurses" --- # bottom\_panel(3ncurses) manage overlapping curses windows Part of [panel(3ncurses)](/panel/3ncurses.md). ## NAME panel - manage overlapping *curses* windows ## SYNOPSIS ``` #include ``` **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 property of** **depth.** **Panel functions allow the use of stacked windows and ensure that 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 each panel.** **The panel routines enable you to create,** **move,** **hide,** **and show panels.** **You can relocate a panel to any desired position in the stack.** **Panel routines are a functional layer added to** *curses***,** **make only high-level** *curses* **calls,** **and work anywhere** *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**(3NCURSES), 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 **FALSE** if the panel *pan* is in the panel stack, and **TRUE** if it is not. If the panel is a null pointer, it returns **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 if, for example, 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 “PORTABILITY” below. ### top\_panel **top\_panel(***pan***)** puts the given visible panel *pan* on top of all panels in the stack. See “PORTABILITY” below. ### update\_panels **update\_panels()** refreshes the virtual screen to reflect the relations between the panels in the stack, but does not call **doupdate**(3NCURSES) to refresh the physical screen. Use this function and not **wrefresh**(3NCURSES) or **wnoutrefresh**(3NCURSES). **update\_panels** may be called more than once before a call to **doupdate**, but **doupdate** is the function responsible for updating the physical screen. ## RETURN VALUE 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 either is null, an error is returned. The **move\_panel** function uses **mvwin**(3NCURSES), and returns **ERR** if **mvwin** returns **ERR**. ## NOTES The header file *panel.h* itself includes the header file *curses.h*. ## PORTABILITY 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 never changed. 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 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 System V panel libraries. ## HISTORY A panel facility was documented in SVr4.2's *Character User Interface Programming* document. It is not part of X/Open Curses. A few implementations exist: - • Systems based on SVr4 source code, such as 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 is a public domain implementation by Warren Tucker published in *u386mon* 2.20 (1990). - According to Tucker, the System V 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, based on the System V documentation. ## AUTHORS Warren Tucker \ originally wrote this implementation, primarily to assist in porting *u386mon* to systems without a native panel library. Zeyd ben-Halim repackaged it for *ncurses*. Juergen Pfeifer and Thomas E. Dickey revised and improved the library. ## SEE ALSO **ncurses**(3NCURSES), **curses\_variables**(3NCURSES)