ncurses 6.0 - patch 20170318

[ncurses.git] / man / curs_slk.3x

diff --git a/man/curs_slk.3x b/man/curs_slk.3x
index 83de447bc1b7801acf024b469dbcb8c4c01e14d0..d1927a107a2927a09437966cfc84811b40b0a132 100644 (file)
--- a/man/curs_slk.3x
+++ b/man/curs_slk.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2010,2016 Free Software Foundation, Inc.              *
+.\" Copyright (c) 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            *
@@ -26,8 +26,11 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_slk.3x,v 1.23 2016/10/15 17:02:31 tom Exp $
+.\" $Id: curs_slk.3x,v 1.29 2017/03/18 01:00:30 tom Exp $
 .TH curs_slk 3X ""
+.de bP
+.IP \(bu 4
+..
 .na
 .hy 0
 .SH NAME
@@ -54,21 +57,23 @@
 \fB#include <curses.h>\fR
 .sp
 \fBint slk_init(int fmt);\fR
-.br
+.sp
 \fBint slk_set(int labnum, const char *label, int fmt);\fR
 .br
+\fBint slk_wset(int labnum, const wchar_t *label, int fmt);\fR
+.sp
+\fBchar *slk_label(int labnum);\fR
+.sp
 \fBint slk_refresh(void);\fR
 .br
 \fBint slk_noutrefresh(void);\fR
 .br
-\fBchar *slk_label(int labnum);\fR
-.br
 \fBint slk_clear(void);\fR
 .br
 \fBint slk_restore(void);\fR
 .br
 \fBint slk_touch(void);\fR
-.br
+.sp
 \fBint slk_attron(const chtype attrs);\fR
 .br
 \fBint slk_attroff(const chtype attrs);\fR
@@ -79,14 +84,11 @@
 .br
 \fBint slk_attr_off(const attr_t attrs, void * opts);\fR
 .br
-\fBint slk_attr_set(const attr_t attrs, short color_pair, void* opts);\fR
-.br
+\fBint slk_attr_set(const attr_t attrs, short pair, void* opts);\fR
+.sp
 \fBattr_t slk_attr(void);\fR
-.br
-\fBint slk_color(short color_pair);\fR
-.br
-\fBint slk_wset(int labnum, const wchar_t *label, int fmt);\fR
-.br
+.sp
+\fBint slk_color(short pair);\fR
 .SH DESCRIPTION
 The slk* functions manipulate the set of soft function-key labels that exist on
 many terminals.
@@ -98,18 +100,19 @@ labels of up to eight characters each.
 In addition to this, the ncurses
 implementation supports a mode where it simulates 12 labels of up to five
 characters each.
-This is useful for today's PC-like enduser devices.
+This is useful for PC-like enduser devices.
 ncurses simulates this mode by taking over up to two lines at
 the bottom of the screen;
 it does not try to use any hardware support for this
 mode.
+.SS Initialization
 .PP
 The \fBslk_init\fR routine must be called before \fBinitscr\fR or \fBnewterm\fR
 is called.
 If \fBinitscr\fR eventually uses a line from \fBstdscr\fR to
 emulate the soft labels,
 then \fIfmt\fR determines how the labels are arranged on the screen:
-.RS
+.RS 3
 .TP 3
 .B 0
 indicates a 3\-2\-3 arrangement of
@@ -126,11 +129,12 @@ is again the PC-like 4\-4\-4 mode,
 but in addition an index line is generated, helping the user to
 identify the key numbers easily.
 .RE
+.SS Labels
 .PP
 The \fBslk_set\fR routine
 (and the \fBslk_wset\fR routine for the wide-character library)
 has three parameters:
-.RS
+.RS 3
 .TP 5
 .I labnum
 is the label number, from \fB1\fR to \fB8\fR
@@ -150,11 +154,12 @@ left-justified, centered, or right-justified, respectively, within the
 label.
 .RE
 .PP
-The \fBslk_refresh\fR and \fBslk_noutrefresh\fR routines correspond to
-the \fBwrefresh\fR and \fBwnoutrefresh\fR routines.
-.PP
 The \fBslk_label\fR routine returns the current label for label number
 \fIlabnum\fR, with leading and trailing blanks stripped.
+.SS Screen updates
+.PP
+The \fBslk_refresh\fR and \fBslk_noutrefresh\fR routines correspond to
+the \fBwrefresh\fR and \fBwnoutrefresh\fR routines.
 .PP
 The \fBslk_clear\fR routine clears the soft labels from the screen.
 .PP
@@ -163,6 +168,7 @@ after a \fBslk_clear\fR has been performed.
 .PP
 The \fBslk_touch\fR routine forces all the soft labels to be output
 the next time a \fBslk_noutrefresh\fR is performed.
+.SS Video attributes
 .PP
 The \fBslk_attron\fR, \fBslk_attrset\fR, \fBslk_attroff\fR and \fBslk_attr\fR
 routines correspond to \fBattron\fR, \fBattrset\fR, \fBattroff\fR and \fBattr_get\fR.
@@ -170,6 +176,7 @@ They have an effect only if soft labels are simulated on the bottom line of
 the screen.
 The default highlight for soft keys is A_STANDOUT (as in
 System V curses, which does not document this fact).
+.SS Colors
 .PP
 The \fBslk_color\fR routine corresponds to \fBcolor_set\fR.
 It has an effect only
@@ -181,7 +188,7 @@ integer value other than \fBERR\fR") upon successful completion.
 .PP
 X/Open defines no error conditions.
 In this implementation
-.RS
+.RS 3
 .TP 5
 \fBslk_attr\fR
 returns the attribute used for the soft keys.
@@ -227,11 +234,22 @@ memory for the labels cannot be allocated.
 Most applications would use \fBslk_noutrefresh\fR because a
 \fBwrefresh\fR is likely to follow soon.
 .SH PORTABILITY
-The XSI Curses standard, Issue 4, describes these functions.
-It changes the
-argument type of the attribute-manipulation functions \fBslk_attron\fR,
-\fBslk_attroff\fR, \fBslk_attrset\fR to be \fBattr_t\fR, and adds \fBconst\fR
-qualifiers.
+The XSI Curses standard, Issue 4, described the soft-key functions,
+with some differences from SVr4 curses:
+.bP
+It
+added functions like the SVr4
+the attribute-manipulation functions \fBslk_attron\fR,
+\fBslk_attroff\fR, \fBslk_attrset\fR
+which use \fBattr_t\fR parameters,
+along with a reserved \fIopts\fP parameter.
+.IP
+One of these new functions (\fBslk_attr_set\fP) also has a color-pair parameter.
+.bP
+It added \fBconst\fR qualifiers to parameters (unnecessarily), and
+.bP
+It added \fBslk_color\fP.
+.PP
 The format codes \fB2\fR and \fB3\fR for \fBslk_init\fR and the
 function \fBslk_attr\fR are specific to ncurses.
 .SH SEE ALSO