[src/trunk]: src/lib/libpanel Provide descriptions of panel functions.

[uwe <uwe%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/4bca0aaeeffc
branches:  trunk
changeset: 341254:4bca0aaeeffc
user:      uwe <uwe%NetBSD.org@localhost>
date:      Wed Oct 28 02:23:50 2015 +0000

description:
Provide descriptions of panel functions.

diffstat:

 lib/libpanel/move_panel.3    |  30 ++++++++++++++++++++++++-
 lib/libpanel/new_panel.3     |  31 +++++++++++++++++++++++++-
 lib/libpanel/panel_above.3   |  45 +++++++++++++++++++++++++++++++++++++-
 lib/libpanel/panel_hidden.3  |  51 ++++++++++++++++++++++++++++++++++++++++++-
 lib/libpanel/panel_userptr.3 |  22 +++++++++++++++++-
 5 files changed, 169 insertions(+), 10 deletions(-)

diffs (244 lines):

diff -r 62a93efae82e -r 4bca0aaeeffc lib/libpanel/move_panel.3
--- a/lib/libpanel/move_panel.3 Wed Oct 28 01:54:10 2015 +0000
+++ b/lib/libpanel/move_panel.3 Wed Oct 28 02:23:50 2015 +0000
@@ -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
diff -r 62a93efae82e -r 4bca0aaeeffc lib/libpanel/new_panel.3
--- a/lib/libpanel/new_panel.3  Wed Oct 28 01:54:10 2015 +0000
+++ b/lib/libpanel/new_panel.3  Wed Oct 28 02:23:50 2015 +0000
@@ -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
diff -r 62a93efae82e -r 4bca0aaeeffc lib/libpanel/panel_above.3
--- a/lib/libpanel/panel_above.3        Wed Oct 28 01:54:10 2015 +0000
+++ b/lib/libpanel/panel_above.3        Wed Oct 28 02:23:50 2015 +0000
@@ -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
diff -r 62a93efae82e -r 4bca0aaeeffc lib/libpanel/panel_hidden.3
--- a/lib/libpanel/panel_hidden.3       Wed Oct 28 01:54:10 2015 +0000
+++ b/lib/libpanel/panel_hidden.3       Wed Oct 28 02:23:50 2015 +0000
@@ -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
diff -r 62a93efae82e -r 4bca0aaeeffc lib/libpanel/panel_userptr.3
--- a/lib/libpanel/panel_userptr.3      Wed Oct 28 01:54:10 2015 +0000
+++ b/lib/libpanel/panel_userptr.3      Wed Oct 28 02:23:50 2015 +0000
@@ -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