slk_attroff, slk_attr_off, slk_attron, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset, Subroutine

Purpose

Soft label subroutines.

Library

Curses Library (libcurses.a)

Syntax

#include <curses.h>

int slk_attroff
(const chtype attrs);

int slk_attr_off
(const attr_t attrs,
void *opts);

int slk_attron
(const chtype attrs);

int slk_attr_on
(const attr_t attrs,
void *opts);

int slk_attrset
(const chtype attrs);

int slk_attr_set
(const attr_t attrs,
short color_pair_number,
void *opts);

int slk_clear
(void);

int slk_color
(short color_pair_number);

int slk_init
(int fmt);

char *slk_label
(int labnum);

int slk_noutrefresh
(void);

int slk_refresh
(void);

int slk_restore
(void);

int slk_set
(int labnum,
const char *label,
int justify);

int slk_touch
(void);

int slk_wset
(int labnum,
const wchar_t *label,
int justify);

Description

The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have sort labels, Curses takes over the bottom line of stdscr, reducing the size of stdscr and the value of the LINES external variable. There can be up to eight labels of up to eight display columns each.

To use soft labels, the slk_init subroutine must be called before initscr, newterm, or ripoffline is called. If initscr eventually uses a line from stdscr to emulate the soft labels, then fmt determines how the labels are arranged on the screen. Setting fmt to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for fmt are unspecified.

The slk_init subroutine has the effect of calling the ripoffline subroutine to reserve one screen line to accommodate the requested format.

The slk_set and slk_wset subroutines specify the text of soft label number labnum, within the range from 1 to and including 8. The label argument is the string to be put on the label. With slk_set and slk_wset, the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The justify argument can have the following values to indicate how to justify label within the space reserved for it:

The slk_refresh and slk_noutrefresh subroutines correspond to the wrefresh and wnoutrefresh subroutines.

The slk_label subroutine obtains soft label number labnum.

The slk_clear subroutine immediately clears the soft labels from the screen.

The slk_touch subroutine forces all the soft labels to be output the next time slk_noutrefresh or slk_refresh subroutines is called.

The slk_attron, slk_attrset and slk_attroff subroutines correspond to the attron, attrset, and attroff subroutines. They have an effect only if soft labels are simulated on the bottom line of the screen.

The slk_attr_off, slk_attr_on, slk_sttr_set, and slk_attroff subroutines correspond to the slk_attroff, slk_attron, slk_attrset, and color_set and thus support the attribute constants with the WA_prefix and color.

The opts argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as opts.

Parameters

Examples

For the slk_init subroutine:

To initialize soft labels on a terminal that does not support soft labels internally, do the following:

slk_init(1);

This example arranges the labels so that four labels appear on the right of the screen and four appear on the left.

For the slk_label subroutine:

To obtain the label name for soft label 3, use:

char *label_name;
label_name = slk_label(3);

For the slk_noutrefresh subroutine:

To refresh soft label 8 on the virtual screen but not on the physical screen, use:

slk_set(8, "Insert", 1);
slk_noutrefresh();

For the slk_refresh subroutine:

To set and left-justify the soft labels and then refresh the physical screen, use:

slk_init(0);
initscr();
slk_set(1, "Insert", 0);
slk_set(2, "Quit", 0);
slk_set(3, "Add", 0);
slk_set(4, "Delete", 0);
slk_set(5, "Undo", 0);
slk_set(6, "Search", 0);
slk_set(7, "Replace", 0);
slk_set(8, "Save", 0);
slk_refresh();

For the slk_set subroutine:

slk_set(2, "Quit", 1);

Return Values

Upon successful completion, the slk_label subroutine returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer.

Upon successful completion, the other subroutines return OK. Otherwise, they return ERR.