.\"***************************************************************************
-.\" Copyright (c) 1998-2018,2020 Free Software Foundation, Inc. *
+.\" Copyright 2018-2022,2023 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_slk.3x,v 1.35 2020/01/18 22:49:38 tom Exp $
-.TH curs_slk 3X ""
+.\" $Id: curs_slk.3x,v 1.62 2023/09/30 20:13:18 tom Exp $
+.TH curs_slk 3X 2023-09-30 "ncurses 6.4" "Library calls"
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.na
-.hy 0
.SH NAME
-\fBslk_init\fR,
-\fBslk_set\fR,
-\fBslk_wset\fR,
-\fBslk_refresh\fR,
-\fBslk_noutrefresh\fR,
-\fBslk_label\fR,
-\fBslk_clear\fR,
-\fBslk_restore\fR,
-\fBslk_touch\fR,
-\fBslk_attron\fR,
-\fBslk_attrset\fR,
-\fBslk_attroff\fR,
-\fBslk_attr_on\fR,
-\fBslk_attr_set\fR,
-\fBslk_attr_off\fR,
-\fBslk_attr\fR,
-\fBslk_color\fR,
-\fBextended_slk_color\fR \- \fBcurses\fR soft label routines
-.ad
-.hy
+\fB\%slk_init\fP,
+\fB\%slk_set\fP,
+\fB\%slk_wset\fP,
+\fB\%slk_refresh\fP,
+\fB\%slk_noutrefresh\fP,
+\fB\%slk_label\fP,
+\fB\%slk_clear\fP,
+\fB\%slk_restore\fP,
+\fB\%slk_touch\fP,
+\fB\%slk_attron\fP,
+\fB\%slk_attrset\fP,
+\fB\%slk_attroff\fP,
+\fB\%slk_attr_on\fP,
+\fB\%slk_attr_set\fP,
+\fB\%slk_attr_off\fP,
+\fB\%slk_attr\fP,
+\fB\%slk_color\fP,
+\fB\%extended_slk_color\fP \-
+\fIcurses\fR soft label key routines
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint slk_init(int \fP\fIfmt\fP\fB);\fR
-.sp
-\fBint slk_set(int \fP\fIlabnum\fP\fB, const char *\fP\fIlabel\fP\fB, int \fP\fIfmt\fP\fB);\fR
-.br
-\fBint slk_wset(int \fP\fIlabnum\fP\fB, const wchar_t *\fP\fIlabel\fP\fB, int \fP\fIfmt\fP\fB);\fR
-.sp
-\fBchar *slk_label(int \fP\fIlabnum\fP\fB);\fR
-.sp
-\fBint slk_refresh(void);\fR
-.br
-\fBint slk_noutrefresh(void);\fR
-.br
-\fBint slk_clear(void);\fR
-.br
-\fBint slk_restore(void);\fR
-.br
-\fBint slk_touch(void);\fR
-.sp
-\fBint slk_attron(const chtype \fP\fIattrs\fP\fB);\fR
-.br
-\fBint slk_attroff(const chtype \fP\fIattrs\fP\fB);\fR
-.br
-\fBint slk_attrset(const chtype \fP\fIattrs\fP\fB);\fR
-.br
-\fBint slk_attr_on(attr_t \fP\fIattrs\fP\fB, void* \fP\fIopts\fP\fB);\fR
-.br
-\fBint slk_attr_off(const attr_t \fP\fIattrs\fP\fB, void * \fP\fIopts\fP\fB);\fR
-.br
-\fBint slk_attr_set(const attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void* \fP\fIopts\fP\fB);\fR
-.sp
-\fBattr_t slk_attr(void);\fR
-.sp
-\fBint slk_color(short \fP\fIpair\fP\fB);\fR
-.br
-/* extension */
-.br
-\fBint extended_slk_color(int \fP\fIpair\fP\fB);\fR
+.nf
+\fB#include <curses.h>\fP
+.PP
+\fBint slk_init(int \fIfmt\fB);\fR
+.PP
+\fBint slk_set(int \fIlabnum\fB, const char *\fIlabel\fB, int \fIfmt\fB);\fR
+\fBint slk_wset(int \fIlabnum\fB, const wchar_t *\fIlabel\fB, int \fIfmt\fB);\fR
+.PP
+\fBchar *slk_label(int \fIlabnum\fB);\fR
+.PP
+\fBint slk_refresh(void);\fP
+\fBint slk_noutrefresh(void);\fP
+\fBint slk_clear(void);\fP
+\fBint slk_restore(void);\fP
+\fBint slk_touch(void);\fP
+.PP
+\fBint slk_attron(const chtype \fIattrs\fB);\fR
+\fBint slk_attroff(const chtype \fIattrs\fB);\fR
+\fBint slk_attrset(const chtype \fIattrs\fB);\fR
+\fBint slk_attr_on(attr_t \fIattrs\fB, void* \fIopts\fB);\fR
+\fBint slk_attr_off(const attr_t \fIattrs\fB, void * \fIopts\fB);\fR
+\fBint slk_attr_set(const attr_t \fIattrs\fB, short \fIpair\fB, void* \fIopts\fB);\fR
+\fI/* extension */\fP
+\fBattr_t slk_attr(void);\fP
+.PP
+\fBint slk_color(short \fIpair\fB);\fR
+\fI/* extension */\fP
+\fBint extended_slk_color(int \fIpair\fB);\fR
+.fi
.SH DESCRIPTION
-The slk* functions manipulate the set of soft function-key labels that exist on
+The \fBslk\fP* functions manipulate the set of soft function-key labels that exist on
many terminals.
For those terminals that do not have soft labels,
-\fBcurses\fR takes over the bottom line of \fBstdscr\fR, reducing the size of
-\fBstdscr\fR and the variable \fBLINES\fR.
-\fBcurses\fR standardizes on eight
+\fIcurses\fP takes over the bottom line of \fB\%stdscr\fP, reducing the size of
+\fB\%stdscr\fP and the variable \fBLINES\fP.
+\fIcurses\fP standardizes on eight
labels of up to eight characters each.
-In addition to this, the ncurses
+In addition to this, the \fIncurses\fP
implementation supports a mode where it simulates 12 labels of up to five
characters each.
This is useful for PC-like enduser devices.
-ncurses simulates this mode by taking over up to two lines at
+\fIncurses\fP 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
+The \fB\%slk_init\fP routine must be called before \fB\%initscr\fP or \fB\%newterm\fP
is called.
-If \fBinitscr\fR eventually uses a line from \fBstdscr\fR to
+If \fB\%initscr\fP eventually uses a line from \fB\%stdscr\fP to
emulate the soft labels,
-then \fIfmt\fR determines how the labels are arranged on the screen:
+then \fIfmt\fP determines how the labels are arranged on the screen:
.RS 3
.TP 3
.B 0
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)
+The \fB\%slk_set\fP routine
+(and the \fB\%slk_wset\fP routine for the wide-character library)
has three parameters:
.RS 3
.TP 5
.I labnum
-is the label number, from \fB1\fR to \fB8\fR
-(12 for \fIfmt\fP in \fBslk_init\fP is \fB2\fP or \fB3\fP);
+is the label number, from \fB1\fP to \fB8\fP
+(12 if \fIfmt\fP in \fB\%slk_init\fP is \fB2\fP or \fB3\fP);
.TP
.I label
is be the string to put on the label,
up to eight
-(five for \fIfmt\fP in \fBslk_init\fP is \fB2\fP or \fB3\fP)
+(five if \fIfmt\fP in \fB\%slk_init\fP is \fB2\fP or \fB3\fP)
characters in length.
A null string or a null pointer sets up a blank label.
.TP
.I fmt
is either
-\fB0\fR, \fB1\fR, or \fB2\fR, indicating whether the label is to be
+\fB0\fP, \fB1\fP, or \fB2\fP, indicating whether the label is to be
left-justified, centered, or right-justified, respectively, within the
label.
.RE
.PP
-The \fBslk_label\fR routine returns the current label for label number
-\fIlabnum\fR, with leading and trailing blanks stripped.
+The \fB\%slk_label\fP routine returns the current label for label number
+\fIlabnum\fP, with leading and trailing blanks stripped.
.SS Screen updates
+The \fB\%slk_refresh\fP and \fB\%slk_noutrefresh\fP routines correspond to
+the \fB\%wrefresh\fP and \fB\%wnoutrefresh\fP routines.
.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.
+The \fB\%slk_clear\fP routine clears the soft labels from the screen.
.PP
-The \fBslk_restore\fR routine restores the soft labels to the screen
-after a \fBslk_clear\fR has been performed.
+The \fB\%slk_restore\fP routine restores the soft labels to the screen
+after a \fB\%slk_clear\fP 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.
+The \fB\%slk_touch\fP routine forces all the soft labels to be output
+the next time a \fB\%slk_noutrefresh\fP is performed.
.SS Video attributes
-.PP
The
-\fBslk_attron\fR, \fBslk_attrset\fR, \fBslk_attroff\fR and \fBslk_attr\fR
+\fB\%slk_attron\fP, \fB\%slk_attrset\fP, \fB\%slk_attroff\fP and \fB\%slk_attr\fP
routines correspond to
-\fBattron\fR, \fBattrset\fR, \fBattroff\fR and \fBattr_get\fR, respectively.
+\fB\%attron\fP, \fB\%attrset\fP, \fB\%attroff\fP and \fB\%attr_get\fP, respectively.
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).
+System V \fIcurses\fP, which does not document this fact).
.SS Colors
-.PP
-The \fBslk_color\fR routine corresponds to \fBcolor_set\fR.
+The \fB\%slk_color\fP routine corresponds to \fB\%color_set\fP.
It has an effect only
if soft labels are simulated on the bottom line of the screen.
.PP
-Because \fBslk_color\fR accepts only \fBshort\fP (signed 16-bit integer) values,
-this implementation provides
-\fBextended_slk_color\fR which accepts an integer value, e.g., 32-bits.
+Because \fB\%slk_color\fP accepts only \fBshort\fP (signed 16-bit integer) values,
+this implementation provides
+\fB\%extended_slk_color\fP which accepts an integer value, e.g., 32-bits.
.
.SH RETURN VALUE
-These routines return \fBERR\fR upon failure
-and \fBOK\fP (SVr4 specifies only "an integer value other than \fBERR\fR")
+These routines return \fBERR\fP upon failure
+and \fBOK\fP (SVr4 specifies only "an integer value other than \fBERR\fP")
upon successful completion.
.PP
X/Open defines no error conditions.
In this implementation
.RS 3
.TP 5
-\fBslk_attr\fR
+\fBslk_attr\fP
returns the attribute used for the soft keys.
.TP 5
-.na
-.hy 0
\fBslk_attroff\fP, \fBslk_attron\fP, \fBslk_clear\fP, \fBslk_noutrefresh\fP, \fBslk_refresh\fP, \fBslk_touch\fP
-.ad
-.hy
return an error
if the terminal or the softkeys were not initialized.
.TP 5
\fBslk_attr_set\fP
returns an error
if the terminal or the softkeys were not initialized, or
-the color pair is outside the range 0..COLOR_PAIRS\-1.
+the color pair is outside the range 0..\fBCOLOR_PAIRS\fP\-1.
.TP 5
\fBslk_color\fP
returns an error
if the terminal or the softkeys were not initialized, or
-the color pair is outside the range 0..COLOR_PAIRS\-1.
+the color pair is outside the range 0..\fBCOLOR_PAIRS\fP\-1.
.TP 5
-\fBslk_init\fR
+\fBslk_init\fP
returns an error
if the format parameter is outside the range 0..3.
.TP 5
-\fBslk_label\fR
-returns \fBNULL\fR on error.
+\fBslk_label\fP
+returns \fBNULL\fP on error.
.TP 5
\fBslk_set\fP
returns an error
.RE
.SH HISTORY
SVr3 introduced these functions:
- slk_clear
- slk_init
- slk_label
- slk_noutrefresh
- slk_refresh
- slk_restore
- slk_set
- slk_touch
+ \fBslk_clear\fP
+ \fBslk_init\fP
+ \fBslk_label\fP
+ \fBslk_noutrefresh\fP
+ \fBslk_refresh\fP
+ \fBslk_restore\fP
+ \fBslk_set\fP
+ \fBslk_touch\fP
.PP
SVr4 added these functions:
- slk_attroff
- slk_attron
- slk_attrset
- slk_start
+ \fBslk_attroff\fP
+ \fBslk_attron\fP
+ \fBslk_attrset\fP
+ \fBslk_start\fP
.PP
-X/Open Curses added these:
- slk_attr_off
- slk_attr_on
- slk_attr_set
- slk_color
- slk_wset
+X/Open \fIcurses\fP added these:
+ \fBslk_attr_off\fP
+ \fBslk_attr_on\fP
+ \fBslk_attr_set\fP
+ \fBslk_color\fP
+ \fBslk_wset\fP
.SH EXTENSIONS
-.PP
-X/Open Curses documents the \fIopts\fP argument as reserved for future use,
+X/Open \fIcurses\fP documents the \fIopts\fP argument as reserved for future use,
saying that it must be null.
-This implementation
+This implementation
uses that parameter in ABI 6 for the functions which have a color-pair
parameter to support extended color pairs.
.PP
-For functions which modify the color, e.g., \fBslk_attr_set\fP,
+For functions which modify the color, e.g., \fB\%slk_attr_set\fP,
if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
and used to set the color pair instead of the \fBshort\fP pair parameter.
.SH NOTES
-Most applications would use \fBslk_noutrefresh\fR because a
-\fBwrefresh\fR is likely to follow soon.
+Most applications would use \fB\%slk_noutrefresh\fP because a
+\fB\%wrefresh\fP is likely to follow soon.
.SH PORTABILITY
-The XSI Curses standard, Issue 4, described the soft-key functions,
-with some differences from SVr4 curses:
+The XSI \fIcurses\fP standard, Issue 4, described the soft-key functions,
+with some differences from SVr4 \fIcurses\fP:
.bP
It added functions like the SVr4
-attribute-manipulation functions \fBslk_attron\fR,
-\fBslk_attroff\fR, \fBslk_attrset\fR,
-but which use \fBattr_t\fR parameters (rather than \fBchtype\fP),
+attribute-manipulation functions \fB\%slk_attron\fP,
+\fB\%slk_attroff\fP, \fB\%slk_attrset\fP,
+but which use \fBattr_t\fP parameters (rather than \fB\%chtype\fP),
along with a reserved \fIopts\fP parameter.
.IP
Two of these new functions (unlike the SVr4 functions) have no provision
-for color: \fBslk_attr_on\fP and \fBslk_attr_off\fP.
+for color: \fB\%slk_attr_on\fP and \fB\%slk_attr_off\fP.
.IP
-The third function (\fBslk_attr_set\fP) has a color-pair parameter.
+The third function \%(\fBslk_attr_set\fP) has a color-pair parameter.
.bP
-It added \fBconst\fR qualifiers to parameters (unnecessarily), and
+It added \fBconst\fP qualifiers to parameters (unnecessarily), and
+.bP
+It added \fB\%slk_color\fP.
+.PP
+Although \fB\%slk_start\fP is declared in the \fIcurses\fP header file,
+it was not documented by SVr4 other than its presence in a list
+of libtermlib.so.1 symbols.
+Reading the source code (i.e., Illumos):
+.bP
+\fB\%slk_start\fP has two parameters:
+.RS
+.bP
+\fIng\fP (number of groups) and
+.bP
+\fIgp\fP (group pointer).
+.RE
+.bP
+Soft-key groups are an array of \fIng\fP integers.
+.bP
+In SVr4, \fB\%slk_init\fP calls \fB\%slk_start\fP passing a null for \fIgp\fP.
+For this case, \fB\%slk_start\fP uses the number of groups \fIng\fP
+(3 for the 3-2-3 layout, 2 for the 4-4 layout) which \fB\%slk_init\fP provided.
+.IP
+If \fIng\fP is neither 2 or 3,
+\fB\%slk_start\fP checks the terminfo \fBfln\fP (label_format) capability,
+interpreting that as a comma-separated list of numbers,
+e.g., \*(``3,2,3\*('' for the 3-2-3 layout.
+.IP
+Finally, if there is no \fBfln\fP capability, \fB\%slk_start\fP returns \fBERR\fP.
+.bP
+If \fB\%slk_start\fP is given a non-null \fIgp\fP,
+it copies the \fIng\fP elements of the group of soft-keys, up to 16.
+.IP
+If there are more than 16 elements, \fB\%slk_start\fP returns an error.
.bP
-It added \fBslk_color\fP.
+The format codes \fB2\fP and \fB3\fP for \fB\%slk_init\fP
+were added by \fIncurses\fP in 1996.
+PDCurses 2.4 added this feature in 2001.
.PP
-The format codes \fB2\fR and \fB3\fR for \fBslk_init\fR and the
-function \fBslk_attr\fR are specific to ncurses.
+The function \fB\%slk_attr\fP was added by \fIncurses\fP in 1996.
.PP
-X/Open Curses does not specify a limit for the number of colors and
+X/Open \fIcurses\fP does not specify a limit for the number of colors and
color pairs which a terminal can support.
However, in its use of \fBshort\fP for the parameters,
it carries over SVr4's implementation detail for the compiled
terminfo database, which uses signed 16-bit numbers.
This implementation provides extended versions of those functions
-which use \fBshort\fP parameters,
+which use \fBint\fP parameters,
allowing applications to use larger color- and pair-numbers.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_attr\fR(3X),
-\fBcurs_initscr\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_variables\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_attr\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_variables\fP(3X)
projects / ncurses.git / blobdiff