Module Name: src
Committed By: uwe
Date: Wed Oct 28 02:23:50 UTC 2015
Modified Files:
src/lib/libpanel: move_panel.3 new_panel.3 panel_above.3 panel_hidden.3
panel_userptr.3
Log Message:
Provide descriptions of panel functions.
To generate a diff of this commit:
cvs rdiff -u -r1.1 -r1.2 src/lib/libpanel/move_panel.3 \
src/lib/libpanel/new_panel.3 src/lib/libpanel/panel_above.3 \
src/lib/libpanel/panel_hidden.3 src/lib/libpanel/panel_userptr.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libpanel/move_panel.3
diff -u src/lib/libpanel/move_panel.3:1.1 src/lib/libpanel/move_panel.3:1.2
--- src/lib/libpanel/move_panel.3:1.1 Tue Oct 27 23:42:55 2015
+++ src/lib/libpanel/move_panel.3 Wed Oct 28 02:23:50 2015
@@ -1,4 +1,4 @@
-.\" $NetBSD: move_panel.3,v 1.1 2015/10/27 23:42:55 uwe Exp $
+.\" $NetBSD: move_panel.3,v 1.2 2015/10/28 02:23:50 uwe Exp $
.\"
.\" Copyright (c) 2015 Valery Ushakov
.\" All rights reserved.
@@ -38,6 +38,32 @@
.Fn move_panel "PANEL *p" "int y" "int x"
.\"
.Sh DESCRIPTION
-Change panel position on screen...
+A panel can be moved to a new position by calling the
+.Fn move_panel
+function.
+The
+.Fa y
+and
+.Fa x
+positions are the new origin of the panel on the screen.
+.Pp
+This function is panel library counterpart of curses
+.Xr mvwin 3 .
+Curses
+.Fn mvwin
+must never be directly used on a window associated with a panel.
+.Sh RETURN VALUES
+The
+.Fn move_panel
+function will return one of the following
+values:
+.Pp
+.Bl -tag -width ".Dv ERR" -compact
+.It Dv OK
+The function completed successfully.
+.It Dv ERR
+An error occurred in the function.
+.El
.Sh SEE ALSO
+.Xr mvwin 3 ,
.Xr panel 3
Index: src/lib/libpanel/new_panel.3
diff -u src/lib/libpanel/new_panel.3:1.1 src/lib/libpanel/new_panel.3:1.2
--- src/lib/libpanel/new_panel.3:1.1 Tue Oct 27 23:42:55 2015
+++ src/lib/libpanel/new_panel.3 Wed Oct 28 02:23:50 2015
@@ -1,4 +1,4 @@
-.\" $NetBSD: new_panel.3,v 1.1 2015/10/27 23:42:55 uwe Exp $
+.\" $NetBSD: new_panel.3,v 1.2 2015/10/28 02:23:50 uwe Exp $
.\"
.\" Copyright (c) 2015 Valery Ushakov
.\" All rights reserved.
@@ -50,6 +50,33 @@
.Fn del_panel "PANEL *p"
.\"
.Sh DESCRIPTION
-Routines to manage panels and associated curses windows...
+The funcion
+.Fn new_panel
+creates a new panel associated with the curses window
+.Fa win .
+The new panel is visible and is placed at the top of the deck.
+.Pp
+Curses window associated with a panel may be obtained with
+.Fn panel_window
+and changed with
+.Fn replace_panel .
+.Pp
+The funcion
+.Fn del_panel
+hides the panel and deletes it.
+Note, that the curses window associated with the panel is not deleted.
+.Sh RETURN VALUES
+Functions returning pointers will return
+.Dv NULL
+if an error is detected.
+The functions that return an int will return one of the following
+values:
+.Pp
+.Bl -tag -width ".Dv ERR" -compact
+.It Dv OK
+The function completed successfully.
+.It Dv ERR
+An error occurred in the function.
+.El
.Sh SEE ALSO
.Xr panel 3
Index: src/lib/libpanel/panel_above.3
diff -u src/lib/libpanel/panel_above.3:1.1 src/lib/libpanel/panel_above.3:1.2
--- src/lib/libpanel/panel_above.3:1.1 Tue Oct 27 23:42:55 2015
+++ src/lib/libpanel/panel_above.3 Wed Oct 28 02:23:50 2015
@@ -1,4 +1,4 @@
-.\" $NetBSD: panel_above.3,v 1.1 2015/10/27 23:42:55 uwe Exp $
+.\" $NetBSD: panel_above.3,v 1.2 2015/10/28 02:23:50 uwe Exp $
.\"
.\" Copyright (c) 2015 Valery Ushakov
.\" All rights reserved.
@@ -50,6 +50,47 @@
.Fn panel_below "PANEL *p"
.\"
.Sh DESCRIPTION
-Routines to manage z-order of panels...
+Newly created panels are placed at the top of the deck.
+Z-order of a visible panel can be changed with the functions
+.Fn top_panel
+and
+.Fn bottom_panel
+that move it to the top and bottom of the deck respectively.
+.Pp
+For a visible panel its neighbors in the deck can be obtained with
+.Fn panel_above
+and
+.Fn panel_below .
+.Sh IMPLEMENTATION NOTES
+The
+.Fn top_panel
+function will return an error if the panel is currently hidden.
+Use
+.Xr show_panel 3
+to make a hidden panel visible again and put it at the top of the deck.
+This is the behaviour specified by the original
+.At V
+panel library.
+.Pp
+In the ncurses implementation of the panel library
+.Fn show_panel
+and
+.Fn top_panel
+are identical and handle both visible and hidden panels.
+This may be a source of bugs in programs tested only against ncurses.
+.Sh RETURN VALUES
+Functions returning pointers will return
+.Dv NULL
+if an error is detected.
+The functions that return an int will return one of the following
+values:
+.Pp
+.Bl -tag -width ".Dv ERR" -compact
+.It Dv OK
+The function completed successfully.
+.It Dv ERR
+An error occurred in the function.
+.El
+
.Sh SEE ALSO
.Xr panel 3
Index: src/lib/libpanel/panel_hidden.3
diff -u src/lib/libpanel/panel_hidden.3:1.1 src/lib/libpanel/panel_hidden.3:1.2
--- src/lib/libpanel/panel_hidden.3:1.1 Tue Oct 27 23:42:55 2015
+++ src/lib/libpanel/panel_hidden.3 Wed Oct 28 02:23:50 2015
@@ -1,4 +1,4 @@
-.\" $NetBSD: panel_hidden.3,v 1.1 2015/10/27 23:42:55 uwe Exp $
+.\" $NetBSD: panel_hidden.3,v 1.2 2015/10/28 02:23:50 uwe Exp $
.\"
.\" Copyright (c) 2015 Valery Ushakov
.\" All rights reserved.
@@ -46,6 +46,53 @@
.Fn panel_hidden "PANEL *p"
.\"
.Sh DESCRIPTION
-Routines to manage visibility of panels...
+Panels are initialy created visible.
+The function
+.Fn hide_panel
+can be used to hide a panel.
+The panel is removed from the deck.
+.Pp
+A panel can be made visible again with a call to
+.Fn show_panel .
+The panel is returned to the top of the deck.
+.Pp
+Current visibility status of a panel can be queried with
+.Fn panel_hidden .
+.Sh IMPLEMENTATION NOTES
+The
+.Fn show_panel
+function will return an error if the panel is already visible.
+Use
+.Xr top_panel 3
+to change z-order of an already visible panel.
+This is the behaviour specified by the original
+.At V
+panel library.
+.Pp
+In the ncurses implementation of the panel library
+.Fn show_panel
+and
+.Fn top_panel
+are identical and handle both visible and hidden panels.
+This may be a source of bugs in programs tested only against ncurses.
+.Sh RETURN VALUES
+The
+.Fn panel_hidden
+function returns
+.Dv TRUE
+or
+.Dv FALSE .
+It will return
+.Dv ERR
+if passed a null pointer.
+.Pp
+Other functions will return one of the following values:
+.Pp
+.Bl -tag -width ".Dv ERR" -compact
+.It Dv OK
+The function completed successfully.
+.It Dv ERR
+An error occurred in the function.
+.El
.Sh SEE ALSO
.Xr panel 3
Index: src/lib/libpanel/panel_userptr.3
diff -u src/lib/libpanel/panel_userptr.3:1.1 src/lib/libpanel/panel_userptr.3:1.2
--- src/lib/libpanel/panel_userptr.3:1.1 Tue Oct 27 23:42:55 2015
+++ src/lib/libpanel/panel_userptr.3 Wed Oct 28 02:23:50 2015
@@ -1,4 +1,4 @@
-.\" $NetBSD: panel_userptr.3,v 1.1 2015/10/27 23:42:55 uwe Exp $
+.\" $NetBSD: panel_userptr.3,v 1.2 2015/10/28 02:23:50 uwe Exp $
.\"
.\" Copyright (c) 2015 Valery Ushakov
.\" All rights reserved.
@@ -42,6 +42,24 @@
.Fn panel_userptr "PANEL *p"
.\"
.Sh DESCRIPTION
-Routines to manage user data associated with panels...
+The function
+.Fn set_panel_userptr
+can be used to associate arbitrary user data with a panel.
+.Pp
+The data associated with a panel can be obtained with
+.Fn panel_userptr .
+.Sh RETURN VALUES
+Functions returning pointers will return
+.Dv NULL
+if an error is detected.
+The functions that return an int will return one of the following
+values:
+.Pp
+.Bl -tag -width ".Dv ERR" -compact
+.It Dv OK
+The function completed successfully.
+.It Dv ERR
+An error occurred in the function.
+.El
.Sh SEE ALSO
.Xr panel 3
