.\"***************************************************************************
-.\" 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 *
.\" 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
\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
.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.
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
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
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
.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.
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
.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.
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