vasilito
ff4ff35918
Red Bear OS is a full fork. All sources must be available from git clone with zero network access. Removed gitignore rules that excluded fetched source trees under recipes/*/source/, local/recipes/kde/*/source/, local/recipes/qt/*/source/, and vendor source trees. Build artifacts (target/, build/, source.tar, *.o, *.so) remain excluded. 127291 files added — kernel, relibc, base, bootloader, pkgar, all KDE/Qt frameworks, mesa, wayland, DRM drivers, and every other recipe source.
300 lines
10 KiB
Plaintext
300 lines
10 KiB
Plaintext
.\"***************************************************************************
|
|
.\" Copyright 2018-2023,2024 Thomas E. Dickey *
|
|
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
|
|
.\" *
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining a *
|
|
.\" copy of this software and associated documentation files (the *
|
|
.\" "Software"), to deal in the Software without restriction, including *
|
|
.\" without limitation the rights to use, copy, modify, merge, publish, *
|
|
.\" distribute, distribute with modifications, sublicense, and/or sell *
|
|
.\" copies of the Software, and to permit persons to whom the Software is *
|
|
.\" furnished to do so, subject to the following conditions: *
|
|
.\" *
|
|
.\" The above copyright notice and this permission notice shall be included *
|
|
.\" in all copies or substantial portions of the Software. *
|
|
.\" *
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
|
|
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
|
|
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
|
|
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
|
|
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|
.\" *
|
|
.\" Except as contained in this notice, the name(s) of the above copyright *
|
|
.\" holders shall not be used in advertising or otherwise to promote the *
|
|
.\" sale, use or other dealings in this Software without prior written *
|
|
.\" authorization. *
|
|
.\"***************************************************************************
|
|
.\"
|
|
.\" $Id: panel.3x,v 1.68 2024/12/28 21:26:21 tom Exp $
|
|
.TH panel 3X 2024-12-28 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
|
|
.ie \n(.g \{\
|
|
.ds `` \(lq
|
|
.ds '' \(rq
|
|
.\}
|
|
.el \{\
|
|
.ie t .ds `` ``
|
|
.el .ds `` ""
|
|
.ie t .ds '' ''
|
|
.el .ds '' ""
|
|
.\}
|
|
.
|
|
.de bP
|
|
.ie n .IP \(bu 4
|
|
.el .IP \(bu 2
|
|
..
|
|
.SH NAME
|
|
panel \-
|
|
manage overlapping \fIcurses\fP windows
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <panel.h>
|
|
.PP
|
|
\fBPANEL *new_panel(WINDOW *\fIwin\fP);
|
|
.PP
|
|
\fBint bottom_panel(PANEL *\fIpan\fP);
|
|
\fBint top_panel(PANEL *\fIpan\fP);
|
|
\fBint show_panel(PANEL *\fIpan\fP);
|
|
\fBvoid update_panels(void);
|
|
\fBint hide_panel(PANEL *\fIpan\fP);
|
|
.PP
|
|
\fBWINDOW *panel_window(const PANEL *\fIpan\fP);
|
|
\fBint replace_panel(PANEL *\fIpan\fP, WINDOW *\fIwindow\fP);
|
|
\fBint move_panel(PANEL *\fIpan\fP, int \fIstarty\fP, int \fIstartx\fP);
|
|
\fBint panel_hidden(const PANEL *\fIpan\fP);
|
|
.PP
|
|
\fBPANEL *panel_above(const PANEL *\fIpan\fP);
|
|
\fBPANEL *panel_below(const PANEL *\fIpan\fP);
|
|
.PP
|
|
\fBint set_panel_userptr(PANEL *\fIpan\fP, const void *\fIptr\fP);
|
|
\fBconst void *panel_userptr(const PANEL *\fIpan\fP);
|
|
.PP
|
|
\fBint del_panel(PANEL *\fIpan\fP);
|
|
.PP
|
|
\fI/* ncurses extensions */\fP
|
|
\fBPANEL *ground_panel(SCREEN *\fIsp\fP);
|
|
\fBPANEL *ceiling_panel(SCREEN *\fIsp\fP);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
Panels are \fBcurses\fP(3X) 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 \fIcurses\fP \fB\%stdscr\fP
|
|
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
|
|
\fB\%stdscr\fP window is beneath all panels,
|
|
and is not considered part of the stack.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Panel routines are a functional layer added to \fIcurses\fP,
|
|
make only high-level \fIcurses\fP calls,
|
|
and work anywhere \fIcurses\fP does.
|
|
.SH FUNCTIONS
|
|
.\" ---------
|
|
.SS bottom_panel
|
|
\fB\%bottom_panel(\fIpan\fB)\fR
|
|
puts panel \fIpan\fP at the bottom of all panels.
|
|
.\" ---------
|
|
.SS ceiling_panel
|
|
\fB\%ceiling_panel(\fIsp\fB)\fR
|
|
acts like \fB\%panel_below(NULL)\fP
|
|
for the given \fISCREEN\fP \fIsp\fP.
|
|
.\" ---------
|
|
.SS del_panel
|
|
\fB\%del_panel(\fIpan\fB)\fR
|
|
removes the given panel \fIpan\fP from the stack and deallocates the
|
|
\fI\%PANEL\fP structure (but not its associated window).
|
|
.\" ---------
|
|
.SS ground_panel
|
|
\fB\%ground_panel(\fIsp\fB)\fR
|
|
acts like \fB\%panel_above(NULL)\fP
|
|
for the given \fISCREEN\fP \fIsp\fP.
|
|
.\" ---------
|
|
.SS hide_panel
|
|
\fB\%hide_panel(\fIpan\fB)\fR
|
|
removes the given panel \fIpan\fP from the panel stack
|
|
and thus hides it from view.
|
|
The \fI\%PANEL\fP structure is not lost,
|
|
merely removed from the stack.
|
|
.\" ---------
|
|
.SS move_panel
|
|
\fB\%move_panel(\fIpan\fB, \fIstarty\fB, \fIstartx\fB)\fR
|
|
moves the given panel \fIpan\fP's window so that its upper-left corner
|
|
is at
|
|
\fIstarty\fP,
|
|
\fIstartx\fP.
|
|
It does not change the position of the panel in the stack.
|
|
Be sure to use this function,
|
|
not \fB\%mvwin\fP(3X),
|
|
to move a panel window.
|
|
.\" ---------
|
|
.SS new_panel
|
|
\fB\%new_panel(\fIwin\fB)\fR allocates a \fI\%PANEL\fR structure,
|
|
associates it with \fIwin\fP,
|
|
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.
|
|
.\" ---------
|
|
.SS panel_above
|
|
\fB\%panel_above(\fIpan\fB)\fR
|
|
returns a pointer to the panel above \fIpan\fP.
|
|
If the panel argument is
|
|
\*(``\fB(PANEL *)0\fP\*('',
|
|
it returns a pointer to the bottom panel in the stack.
|
|
.\" ---------
|
|
.SS panel_below
|
|
\fB\%panel_below(\fIpan\fB)\fR
|
|
returns a pointer to the panel just below \fIpan\fP.
|
|
If the panel argument is
|
|
\*(``\fB(PANEL *)0\fP\*('',
|
|
it returns a pointer to the top panel in the stack.
|
|
.\" ---------
|
|
.SS panel_hidden
|
|
\fB\%panel_hidden(\fIpan\fB)\fR
|
|
returns \fBFALSE\fP if the panel \fIpan\fP is in the panel stack,
|
|
and \fBTRUE\fP if it is not.
|
|
If the panel is a null pointer,
|
|
it returns \fBERR\fP.
|
|
.\" ---------
|
|
.SS panel_userptr
|
|
\fB\%panel_userptr(\fIpan\fB)\fR
|
|
returns the user pointer for a given panel \fIpan\fP.
|
|
.\" ---------
|
|
.SS panel_window
|
|
\fB\%panel_window(\fIpan\fB)\fR
|
|
returns a pointer to the window of the given panel \fIpan\fP.
|
|
.\" ---------
|
|
.SS replace_panel
|
|
\fB\%replace_panel(\fIpan\fB, \fIwindow\fB)\fR
|
|
replaces the current window of panel \fIpan\fP with \fIwindow\fP
|
|
This is useful if,
|
|
for example,
|
|
you want to resize a panel.
|
|
In \fI\%ncurses\fP,
|
|
you can call \fB\%replace_panel\fP
|
|
to resize a panel using a window resized with \fB\%wresize\fP(3X).
|
|
It does not change the position of the panel in the stack.
|
|
.\" ---------
|
|
.SS set_panel_userptr
|
|
\fB\%set_panel_userptr(\fIpan\fB, \fIptr\fB)\fR
|
|
sets the panel's user pointer.
|
|
.\" ---------
|
|
.SS show_panel
|
|
\fB\%show_panel(\fIpan\fB)\fR
|
|
makes a hidden panel visible by placing it on top of the panels in the
|
|
panel stack.
|
|
See \*(``PORTABILITY\*('' below.
|
|
.\" ---------
|
|
.SS top_panel
|
|
\fB\%top_panel(\fIpan\fB)\fR
|
|
puts the given visible panel \fIpan\fP on top of all panels in the
|
|
stack.
|
|
See \*(``PORTABILITY\*('' below.
|
|
.\" ---------
|
|
.SS update_panels
|
|
\fB\%update_panels()\fR
|
|
refreshes the virtual screen to reflect the relations between the panels
|
|
in the stack,
|
|
but does not call \fB\%doupdate\fP(3X) to refresh the physical screen.
|
|
Use this function and not \fB\%wrefresh\fP(3X) or
|
|
\fB\%wnoutrefresh\fP(3X).
|
|
.PP
|
|
\fB\%update_panels\fP may be called more than once before a call to
|
|
\fB\%doupdate\fP,
|
|
but \fB\%doupdate\fP is the function responsible for updating
|
|
the physical screen.
|
|
.SH "RETURN VALUE"
|
|
Each routine that returns a pointer returns
|
|
.I NULL
|
|
if an error occurs.
|
|
Each routine that returns an int value returns \fBOK\fP if it
|
|
executes successfully and \fBERR\fP if not.
|
|
.PP
|
|
Except as noted,
|
|
the \fIpan\fP and \fIwindow\fP parameters must be non-null.
|
|
If either is null,
|
|
an error is returned.
|
|
.PP
|
|
The \fB\%move_panel\fP function uses \fBmvwin\fP(3X),
|
|
and returns
|
|
.B ERR
|
|
if \fB\%mvwin\fP returns
|
|
.BR ERR "."
|
|
.SH NOTES
|
|
The header file \fI\%panel.h\fP itself includes the header file
|
|
\fI\%curses.h\fP.
|
|
.SH 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 \fI\%PANEL\fP data structures are merely similar.
|
|
The programmer is cautioned not to directly use \fI\%PANEL\fP fields.
|
|
.PP
|
|
The functions \fB\%show_panel\fP and \fB\%top_panel\fP are identical
|
|
in this implementation,
|
|
and work equally well with displayed or hidden panels.
|
|
In the System\ V implementation,
|
|
\fB\%show_panel\fP is intended for making a hidden panel visible
|
|
(at the top of the stack)
|
|
and \fB\%top_panel\fP 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.
|
|
.SH HISTORY
|
|
A panel facility was documented in SVr4.2's
|
|
\fICharacter User Interface Programming\fP document.
|
|
.PP
|
|
It is not part of X/Open Curses.
|
|
.PP
|
|
A few implementations exist:
|
|
.bP
|
|
Systems based on SVr4 source code,
|
|
such as Solaris,
|
|
provide this library.
|
|
.bP
|
|
.I \%ncurses
|
|
(since version 0.6 in 1993)
|
|
and
|
|
.I \%PDCurses
|
|
(since version 2.2 in 1995)
|
|
provide a
|
|
.I panel
|
|
library whose common ancestor
|
|
is a public domain implementation by Warren Tucker
|
|
published in \fIu386mon\fP 2.20 (1990).
|
|
.IP
|
|
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).
|
|
.IP
|
|
Several developers have improved each of these;
|
|
they are no longer the same as Tucker's implementation.
|
|
.bP
|
|
NetBSD 8 (2018)
|
|
has a panel library begun by Valery Ushakov in 2015,
|
|
based on the System\ V documentation.
|
|
.SH AUTHORS
|
|
Warren Tucker <wht@n4hgf.mt\-park.ga.us> originally wrote this
|
|
implementation,
|
|
primarily to assist in porting \fI\%u386mon\fP to systems without a
|
|
native panel library.
|
|
.PP
|
|
Zeyd ben-Halim repackaged it for \fI\%ncurses\fP.
|
|
.PP
|
|
Juergen Pfeifer and Thomas E. Dickey revised and improved the library.
|
|
.SH SEE ALSO
|
|
\fB\%curses\fP(3X),
|
|
\fB\%curs_variables\fP(3X)
|