.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_slk.3x,v 1.66 2023/11/25 14:31:07 tom Exp $
-.TH curs_slk 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_slk.3x,v 1.67 2023/12/16 21:18:45 tom Exp $
+.TH curs_slk 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.PP
\fBint slk_init(int \fIfmt\fP);
.PP
-\fBint slk_set(int \fIlabnum\fP, const char *\fIlabel\fP, int \fIfmt\fP);
-\fBint slk_wset(int \fIlabnum\fP, const wchar_t *\fIlabel\fP, int \fIfmt\fP);
+\fBint slk_set(int \fIlabnum\fP, const char *\fIlabel\fP, int \fIalign\fP);
+\fBint slk_wset(int \fIlabnum\fP, const wchar_t *\fIlabel\fP, int \fIalign\fP);
.PP
\fBchar *slk_label(int \fIlabnum\fP);
.PP
\fBint slk_attron(const chtype \fIattrs\fP);
\fBint slk_attroff(const chtype \fIattrs\fP);
\fBint slk_attrset(const chtype \fIattrs\fP);
-\fBint slk_attr_on(attr_t \fIattrs\fP, void* \fIopts\fP);
-\fBint slk_attr_off(const attr_t \fIattrs\fP, void * \fIopts\fP);
-\fBint slk_attr_set(const attr_t \fIattrs\fP, short \fIpair\fP, void* \fIopts\fP);
+\fBint slk_attr_on(attr_t \fIattrs\fP, void *\fIopts\fP);
+\fBint slk_attr_off(const attr_t \fIattrs\fP, void *\fIopts\fP);
+\fBint slk_attr_set(const attr_t \fIattrs\fP, short \fIpair\fP, void*\fIopts\fP);
\fI/* extension */
\fBattr_t slk_attr(void);
.PP
\fBint extended_slk_color(int \fIpair\fP);
.fi
.SH DESCRIPTION
-The \fBslk\fP* functions manipulate the set
-of soft function-key labels that exist on many terminals.
+These functions manipulate the soft function key labels that some
+hardware terminals support.
For those terminals that do not have soft labels,
-\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 \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.
-\fIncurses\fP simulates this mode by taking over up to two lines at
+\fIcurses\fP takes over the bottom line of \fB\%stdscr\fP,
+reducing its vertical size and the value of \fBLINES\fP by one.
+By default,
+\fIcurses\fP uses eight labels of up to eight characters each.
+.PP
+\fI\%ncurses\fP
+furthermore supports a mode comprising twelve labels of up to five
+characters each,
+following a convention associated with the IBM PC/AT keyboard.
+\fI\%ncurses\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
-The \fB\%slk_init\fP routine must be called
-before \fB\%initscr\fP or \fB\%newterm\fP
-is called.
+\fB\%slk_init\fP must be called before \fB\%initscr\fP or
+\fB\%newterm\fP.
If \fB\%initscr\fP eventually uses a line from \fB\%stdscr\fP to
emulate the soft labels,
-then \fIfmt\fP determines how the labels are arranged on the screen:
-.RS 3
+then \fIfmt\fP determines how the labels are arranged on the screen.
.TP 3
.B 0
indicates a 3\-2\-3 arrangement of
.TP 3
.B 3
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
+but in addition an index line is generated,
+helping the user to associate each label with its numbered function key.
+\fBLINES\fP and the vertical size of \fB\%stdscr\fP are further reduced.
.SS Labels
-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
+Populate the labels with normal strings
+(\fB\%slk_set\fP)
+or wide-character strings
+(\fB\%slk_wset\fP).
+Each function takes three parameters.
+.TP 8 \" "labnum" + 2n
.I labnum
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);
up to eight
(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.
+A empty string or a null pointer sets up a blank label.
.TP
-.I fmt
-is either
-\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
+.I align
+is
+.BR 0 ,
+.BR 1 ,
+or
+.BR 2 ,
+aligning
+.I label
+to the left,
+center,
+or right,
+respectively,
+within the 8 (5) character cells housing it.
.PP
-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.
+\fB\%slk_label\fP obtains the string assigned to label number
+\fIlabnum\fP,
+with any leading and trailing blanks stripped.
+.SS "Screen Updates"
+\fB\%slk_refresh\fP and \fB\%slk_noutrefresh\fP affect the soft key
+label lines as \fB\%wrefresh\fP and \fB\%wnoutrefresh\fP do the
+.I curses
+window.
.PP
The \fB\%slk_clear\fP routine clears the soft labels from the screen.
.PP
.PP
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
+.SS "Video Attributes"
The
-\fB\%slk_attron\fP, \fB\%slk_attrset\fP, \fB\%slk_attroff\fP and \fB\%slk_attr\fP
+\fB\%slk_attron\fP,
+\fB\%slk_attrset\fP,
+\fB\%slk_attroff\fP,
+and
+\fB\%slk_attr\fP
routines correspond to
-\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 \fIcurses\fP, which does not document this fact).
+\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 key labels is \fB\%A_STANDOUT\fP
+(as in System\ V \fIcurses\fP,
+which does not document this fact).
.SS Colors
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 \fB\%slk_color\fP accepts
-only \fBshort\fP (signed 16-bit integer) values,
+only \fIshort\fP
+(signed 16-bit integer)
+values,
this implementation provides
-\fB\%extended_slk_color\fP which accepts an integer value, e.g., 32-bits.
-.
+\fB\%extended_slk_color\fP,
+which accepts an \fIint\fP value of at least 32 bits.
.SH RETURN VALUE
-These routines return \fBERR\fP upon failure
-and \fBOK\fP (SVr4 specifies only "an integer value other than \fBERR\fP")
+Routines that return an integer 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.
+X/Open Curses defines no error conditions.
+.PP
In this implementation
.RS 3
.TP 5
Most applications would use \fB\%slk_noutrefresh\fP because a
\fB\%wrefresh\fP is likely to follow soon.
.SH EXTENSIONS
-X/Open \fIcurses\fP documents the \fIopts\fP argument
+X/Open Curses documents the \fIopts\fP argument
as reserved for future use,
saying that it must be null.
This implementation
-uses that parameter in ABI 6 for the functions which have a color-pair
+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., \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.
+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 \fIint\fP,
+and used to set the color pair instead of the \fIshort\fP pair
+parameter.
.SH PORTABILITY
-The XSI \fIcurses\fP standard, Issue 4, described the soft-key functions,
+X/Open Curses, Issue 4, describes these functions,
with some differences from SVr4 \fIcurses\fP:
.bP
-It added functions like the SVr4
-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),
+X/Open added functions like the SVr4 attribute-manipulation functions
+\fB\%slk_attron\fP,
+\fB\%slk_attroff\fP,
+and
+\fB\%slk_attrset\fP,
+but which use \fI\%attr_t\fP parameters
+(rather than \fI\%chtype\fP),
along with a reserved \fIopts\fP parameter.
.IP
-Two of these new functions (unlike the SVr4 functions) have no provision
-for color: \fB\%slk_attr_on\fP and \fB\%slk_attr_off\fP.
+Two of these new functions
+(unlike the SVr4 functions)
+have no provision 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\fP qualifiers to parameters (unnecessarily), and
+It added \fIconst\fP qualifiers to parameters (unnecessarily),
+and
.bP
It added \fB\%slk_color\fP.
.PP
If there are more than 16 elements, \fB\%slk_start\fP returns an error.
.bP
The format codes \fB2\fP and \fB3\fP for \fB\%slk_init\fP
-were added by \fIncurses\fP in 1996.
+were added by \fI\%ncurses\fP in 1996.
PDCurses 2.4 added this feature in 2001.
.PP
-The function \fB\%slk_attr\fP was added by \fIncurses\fP in 1996.
+The function \fB\%slk_attr\fP was added by \fI\%ncurses\fP in 1996.
.PP
-X/Open \fIcurses\fP does not specify a limit for the number of colors and
+X/Open Curses 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,
+However, in its use of \fIshort\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 \fBint\fP parameters,
+which use \fIint\fP parameters,
allowing applications to use larger color- and pair-numbers.
.SH HISTORY
SVr3 introduced these functions:
\fBslk_attrset\fP
\fBslk_start\fP
.PP
-X/Open \fIcurses\fP added these:
+X/Open Curses added these:
\fBslk_attr_off\fP
\fBslk_attr_on\fP
\fBslk_attr_set\fP
projects / ncurses.git / blobdiff