| 1 |
.\"*************************************************************************** |
| 2 |
.\" Copyright 2018-2024,2025 Thomas E. Dickey * |
| 3 |
.\" Copyright 2010-2015,2017 Free Software Foundation, Inc. * |
| 4 |
.\" * |
| 5 |
.\" Permission is hereby granted, free of charge, to any person obtaining a * |
| 6 |
.\" copy of this software and associated documentation files (the * |
| 7 |
.\" "Software"), to deal in the Software without restriction, including * |
| 8 |
.\" without limitation the rights to use, copy, modify, merge, publish, * |
| 9 |
.\" distribute, distribute with modifications, sublicense, and/or sell * |
| 10 |
.\" copies of the Software, and to permit persons to whom the Software is * |
| 11 |
.\" furnished to do so, subject to the following conditions: * |
| 12 |
.\" * |
| 13 |
.\" The above copyright notice and this permission notice shall be included * |
| 14 |
.\" in all copies or substantial portions of the Software. * |
| 15 |
.\" * |
| 16 |
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| 17 |
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| 18 |
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| 19 |
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| 20 |
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| 21 |
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| 22 |
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| 23 |
.\" * |
| 24 |
.\" Except as contained in this notice, the name(s) of the above copyright * |
| 25 |
.\" holders shall not be used in advertising or otherwise to promote the * |
| 26 |
.\" sale, use or other dealings in this Software without prior written * |
| 27 |
.\" authorization. * |
| 28 |
.\"*************************************************************************** |
| 29 |
.\" |
| 30 |
.\" $Id: curs_sp_funcs.3x,v 1.57 2025/02/01 22:47:44 tom Exp $ |
| 31 |
.TH sp_funcs 3NCURSES 2025-02-01 "ncurses 6.6" "Library calls" |
| 32 |
.ie \n(.g \{\ |
| 33 |
.ds `` \(lq |
| 34 |
.ds '' \(rq |
| 35 |
.\} |
| 36 |
.el \{\ |
| 37 |
.ie t .ds `` `` |
| 38 |
.el .ds `` "" |
| 39 |
.ie t .ds '' '' |
| 40 |
.el .ds '' "" |
| 41 |
.\} |
| 42 |
.SH NAME |
| 43 |
\fB\%curs_sp_funcs\fP \- |
| 44 |
\fIcurses\fR screen-pointer extension |
| 45 |
.SH SYNOPSIS |
| 46 |
.nf |
| 47 |
\fB#include <curses.h> |
| 48 |
.PP |
| 49 |
\fBint alloc_pair_sp(SCREEN * \fIsp\fP, int \fIfg\fP, int \fIbg\fP); |
| 50 |
\fBint assume_default_colors_sp(SCREEN * \fIsp\fP, int \fIfg\fP, int \fIbg\fP); |
| 51 |
\fBint baudrate_sp(SCREEN * \fIsp\fP); |
| 52 |
\fBint beep_sp(SCREEN * \fIsp\fP); |
| 53 |
\fBbool can_change_color_sp(SCREEN * \fIsp\fP); |
| 54 |
\fBint cbreak_sp(SCREEN * \fIsp\fP); |
| 55 |
\fBint color_content_sp(SCREEN * \fIsp\fP, short \fIcolor\fP, short * \fIr\fP, short * \fIg\fP, short * \fIb\fP); |
| 56 |
\fBint curs_set_sp(SCREEN * \fIsp\fP, int \fIvisibility\fP); |
| 57 |
\fBint def_prog_mode_sp(SCREEN * \fIsp\fP); |
| 58 |
\fBint def_shell_mode_sp(SCREEN * \fIsp\fP); |
| 59 |
.PP |
| 60 |
\fBint define_key_sp(SCREEN * \fIsp\fP, const char * \fIdefinition\fP, int \fIkeycode\fP); |
| 61 |
\fBint delay_output_sp(SCREEN * \fIsp\fP, int \fIms\fP); |
| 62 |
\fBint doupdate_sp(SCREEN * \fIsp\fP); |
| 63 |
\fBint echo_sp(SCREEN * \fIsp\fP); |
| 64 |
\fBint endwin_sp(SCREEN * \fIsp\fP); |
| 65 |
\fBchar erasechar_sp(SCREEN * \fIsp\fP); |
| 66 |
\fBint erasewchar_sp(SCREEN * \fIsp\fP, wchar_t *\fIwc\fP); |
| 67 |
\fBint extended_color_content_sp(SCREEN * \fIsp\fP, int \fIcolor\fP, int * \fIr\fP, int * \fIg\fP, int * \fIb\fP); |
| 68 |
\fBint extended_pair_content_sp(SCREEN * \fIsp\fP, int \fIpair\fP, int * \fIfg\fP, int * \fIbg\fP); |
| 69 |
\fBint extended_slk_color_sp(SCREEN * \fIsp\fP, int \fIpair\fP); |
| 70 |
.PP |
| 71 |
\fBvoid filter_sp(SCREEN * \fIsp\fP); |
| 72 |
\fBint find_pair_sp(SCREEN * \fIsp\fP, int \fIfg\fP, int \fIbg\fP); |
| 73 |
\fBint flash_sp(SCREEN * \fIsp\fP); |
| 74 |
\fBint flushinp_sp(SCREEN * \fIsp\fP); |
| 75 |
\fBint free_pair_sp(SCREEN * \fIsp\fP, int \fIpair\fP); |
| 76 |
\fBint get_escdelay_sp(SCREEN * \fIsp\fP); |
| 77 |
\fBint getmouse_sp(SCREEN * \fIsp\fP, MEVENT * \fIevent\fP); |
| 78 |
\fBWINDOW * getwin_sp(SCREEN * \fIsp\fP, FILE * \fIfilep\fP); |
| 79 |
\fBint halfdelay_sp(SCREEN * \fIsp\fP, int \fItenths\fP); |
| 80 |
\fBbool has_colors_sp(SCREEN * \fIsp\fP); |
| 81 |
.PP |
| 82 |
\fBbool has_ic_sp(SCREEN * \fIsp\fP); |
| 83 |
\fBbool has_il_sp(SCREEN * \fIsp\fP); |
| 84 |
\fBint has_key_sp(SCREEN * \fIsp\fP, int \fIc\fP); |
| 85 |
\fBbool has_mouse_sp(SCREEN * \fIsp\fP); |
| 86 |
\fBint init_color_sp(SCREEN * \fIsp\fP, short \fIcolor\fP, short \fIr\fP, short \fIg\fP, short \fIb\fP); |
| 87 |
\fBint init_extended_color_sp(SCREEN * \fIsp\fP, int \fIcolor\fP, int \fIr\fP, int \fIg\fP, int \fIb\fP); |
| 88 |
\fBint init_extended_pair_sp(SCREEN * \fIsp\fP, int \fIpair\fP, int \fIfg\fP, int \fIbg\fP); |
| 89 |
\fBint init_pair_sp(SCREEN * \fIsp\fP, short \fIpair\fP, short \fIfg\fP, short \fIbg\fP); |
| 90 |
\fBint intrflush_sp(SCREEN * \fIsp\fP, WINDOW * \fIwin\fP, bool \fIbf\fP); |
| 91 |
\fBint is_cbreak_sp(SCREEN * \fIsp\fP); |
| 92 |
.PP |
| 93 |
\fBint is_echo_sp(SCREEN * \fIsp\fP); |
| 94 |
\fBint is_nl_sp(SCREEN * \fIsp\fP); |
| 95 |
\fBint is_raw_sp(SCREEN * \fIsp\fP); |
| 96 |
\fBbool is_term_resized_sp(SCREEN * \fIsp\fP, int \fIlines\fP, int \fIcolumns\fP); |
| 97 |
\fBbool isendwin_sp(SCREEN * \fIsp\fP); |
| 98 |
\fBint key_defined_sp(SCREEN * \fIsp\fP, const char *\fIdefinition\fP); |
| 99 |
\fBchar * keybound_sp(SCREEN * \fIsp\fP, int \fIkeycode\fP, int \fIcount\fP); |
| 100 |
\fBNCURSES_CONST char * keyname_sp(SCREEN * \fIsp\fP, int \fIc\fP); |
| 101 |
\fBint keyok_sp(SCREEN * \fIsp\fP, int \fIkeycode\fP, bool \fIenable\fP); |
| 102 |
\fBchar killchar_sp(SCREEN * \fIsp\fP); |
| 103 |
.PP |
| 104 |
\fBint killwchar_sp(SCREEN * \fIsp\fP, wchar_t *\fIwc\fP); |
| 105 |
\fBchar * longname_sp(SCREEN * \fIsp\fP); |
| 106 |
\fBint mcprint_sp(SCREEN * \fIsp\fP, char *\fIdata\fP, int \fIlen\fP); |
| 107 |
\fBint mouseinterval_sp(SCREEN * \fIsp\fP, int \fIerval\fP); |
| 108 |
\fBmmask_t mousemask_sp(SCREEN * \fIsp\fP, mmask_t \fInewmask\fP, mmask_t *\fIoldmask\fP); |
| 109 |
\fBint mvcur_sp(SCREEN * \fIsp\fP, int \fIoldrow\fP, int \fIoldcol\fP, int \fInewrow\fP, int \fInewcol\fP); |
| 110 |
\fBint napms_sp(SCREEN * \fIsp\fP, int \fIms\fP); |
| 111 |
\fBWINDOW * newpad_sp(SCREEN * \fIsp\fP, int \fInrows\fP, int \fIncols\fP); |
| 112 |
\fBSCREEN * new_prescr(void); |
| 113 |
\fBSCREEN * newterm_sp(SCREEN * \fIsp\fP, const char *\fItype\fP, FILE *\fIoutf\fP, FILE *\fIinf\fP); |
| 114 |
.PP |
| 115 |
\fBWINDOW * newwin_sp(SCREEN * \fIsp\fP, int \fInlines\fP, int \fIncols\fP, int \fIbegin_y\fP, int \fIbegin_x\fP); |
| 116 |
\fBint nl_sp(SCREEN * \fIsp\fP); |
| 117 |
\fBint nocbreak_sp(SCREEN * \fIsp\fP); |
| 118 |
\fBint noecho_sp(SCREEN * \fIsp\fP); |
| 119 |
\fBvoid nofilter_sp(SCREEN * \fIsp\fP); |
| 120 |
\fBint nonl_sp(SCREEN * \fIsp\fP); |
| 121 |
\fBvoid noqiflush_sp(SCREEN * \fIsp\fP); |
| 122 |
\fBint noraw_sp(SCREEN * \fIsp\fP); |
| 123 |
\fBint pair_content_sp(SCREEN * \fIsp\fP, short \fIpair\fP, short * \fIfg\fP, short * \fIbg\fP); |
| 124 |
\fBvoid qiflush_sp(SCREEN * \fIsp\fP); |
| 125 |
.PP |
| 126 |
\fBint raw_sp(SCREEN * \fIsp\fP); |
| 127 |
\fBvoid reset_color_pairs_sp(SCREEN * \fIsp\fP); |
| 128 |
\fBint reset_prog_mode_sp(SCREEN * \fIsp\fP); |
| 129 |
\fBint reset_shell_mode_sp(SCREEN * \fIsp\fP); |
| 130 |
\fBint resetty_sp(SCREEN * \fIsp\fP); |
| 131 |
\fBint resize_term_sp(SCREEN * \fIsp\fP, int \fIlines\fP, int \fIcolumns\fP); |
| 132 |
\fBint resizeterm_sp(SCREEN * \fIsp\fP, int \fIlines\fP, int \fIcolumns\fP); |
| 133 |
\fBint ripoffline_sp(SCREEN * \fIsp\fP, int \fIline\fP, int (*\fIinit\fP)(WINDOW * \fIwin\fP, int \fIfmt\fP)); |
| 134 |
\fBint savetty_sp(SCREEN * \fIsp\fP); |
| 135 |
\fBint scr_init_sp(SCREEN * \fIsp\fP, const char *\fIfilename\fP); |
| 136 |
.PP |
| 137 |
\fBint scr_restore_sp(SCREEN * \fIsp\fP, const char *\fIfilename\fP); |
| 138 |
\fBint scr_set_sp(SCREEN * \fIsp\fP, const char *\fIfilename\fP); |
| 139 |
\fBint set_escdelay_sp(SCREEN * \fIsp\fP, int \fIms\fP); |
| 140 |
\fBint set_tabsize_sp(SCREEN * \fIsp\fP, int \fIcols\fP); |
| 141 |
\fBint slk_attrset_sp(SCREEN * \fIsp\fP, const chtype \fIa\fP); |
| 142 |
\fBint slk_attr_set_sp(SCREEN * \fIsp\fP, const attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP); |
| 143 |
\fBint slk_attroff_sp(SCREEN * \fIsp\fP, const chtype \fIa\fP); |
| 144 |
\fBint slk_attron_sp(SCREEN * \fIsp\fP, const chtype \fIa\fP); |
| 145 |
\fBattr_t slk_attr_sp(SCREEN * \fIsp\fP); |
| 146 |
\fBint slk_clear_sp(SCREEN * \fIsp\fP); |
| 147 |
.PP |
| 148 |
\fBint slk_color_sp(SCREEN * \fIsp\fP, short \fIpair\fP); |
| 149 |
\fBint slk_init_sp(SCREEN * \fIsp\fP, int \fIfmt\fP); |
| 150 |
\fBchar * slk_label_sp(SCREEN * \fIsp\fP, int \fIlabnum\fP); |
| 151 |
\fBint slk_noutrefresh_sp(SCREEN * \fIsp\fP); |
| 152 |
\fBint slk_refresh_sp(SCREEN * \fIsp\fP); |
| 153 |
\fBint slk_restore_sp(SCREEN * \fIsp\fP); |
| 154 |
\fBint slk_set_sp(SCREEN * \fIsp\fP, int \fIlabnum\fP, const char * \fIlabel\fP, int \fIfmt\fP); |
| 155 |
\fBint slk_touch_sp(SCREEN * \fIsp\fP); |
| 156 |
\fBint start_color_sp(SCREEN * \fIsp\fP); |
| 157 |
\fBattr_t term_attrs_sp(SCREEN * \fIsp\fP); |
| 158 |
.PP |
| 159 |
\fBchtype termattrs_sp(SCREEN * \fIsp\fP); |
| 160 |
\fBchar * termname_sp(SCREEN * \fIsp\fP); |
| 161 |
\fBint typeahead_sp(SCREEN * \fIsp\fP, int \fIfd\fP); |
| 162 |
\fBint unget_wch_sp(SCREEN * \fIsp\fP, const wchar_t \fIwc\fP); |
| 163 |
\fBint ungetch_sp(SCREEN * \fIsp\fP, int \fIc\fP); |
| 164 |
\fBint ungetmouse_sp(SCREEN * \fIsp\fP, MEVENT * \fIevent\fP); |
| 165 |
\fBint use_default_colors_sp(SCREEN * \fIsp\fP); |
| 166 |
\fBvoid use_env_sp(SCREEN * \fIsp\fP, bool \fIbf\fP); |
| 167 |
\fBint use_legacy_coding_sp(SCREEN * \fIsp\fP, int \fIlevel\fP); |
| 168 |
\fBvoid use_tioctl_sp(SCREEN *\fIsp\fP, bool \fIbf\fP); |
| 169 |
.PP |
| 170 |
\fBint vid_attr_sp(SCREEN * \fIsp\fP, attr_t \fIattrs\fP, short \fIpair\fP, void * \fIopts\fP); |
| 171 |
\fBint vid_puts_sp(SCREEN * \fIsp\fP, attr_t \fIattrs\fP, short \fIpair\fP, void * \fIopts\fP, NCURSES_SP_OUTC \fIputc\fP); |
| 172 |
\fBint vidattr_sp(SCREEN * \fIsp\fP, chtype \fIattrs\fP); |
| 173 |
\fBint vidputs_sp(SCREEN * \fIsp\fP, chtype \fIattrs\fP, NCURSES_SP_OUTC \fIputc\fP); |
| 174 |
\fBwchar_t * wunctrl_sp(SCREEN * \fIsp\fP, cchar_t *\fIwch\fP); |
| 175 |
.PP |
| 176 |
\fB#include <form.h> |
| 177 |
.PP |
| 178 |
\fBFORM * new_form_sp(SCREEN * \fIsp\fP, FIELD **\fIfields\fP); |
| 179 |
.PP |
| 180 |
\fB#include <menu.h> |
| 181 |
.PP |
| 182 |
\fBMENU * new_menu_sp(SCREEN * \fIsp\fP, ITEM **\fIitems\fP); |
| 183 |
.PP |
| 184 |
\fB#include <panel.h> |
| 185 |
.PP |
| 186 |
\fBPANEL * ceiling_panel(SCREEN * \fIsp\fP); |
| 187 |
\fBPANEL * ground_panel(SCREEN * \fIsp\fP); |
| 188 |
\fBvoid update_panels_sp(SCREEN * \fIsp\fP); |
| 189 |
.PP |
| 190 |
\fB#include <term.h> |
| 191 |
.PP |
| 192 |
\fBint del_curterm_sp(SCREEN * \fIsp\fP, TERMINAL *\fIoterm\fP); |
| 193 |
\fBint putp_sp(SCREEN * \fIsp\fP, const char *\fIstr\fP); |
| 194 |
\fBint restartterm_sp(SCREEN * \fIsp\fP, NCURSES_CONST char *\fIterm\fP, int \fIfiledes\fP, int *\fIerrret\fP); |
| 195 |
\fBTERMINAL * set_curterm_sp(SCREEN * \fIsp\fP, TERMINAL *\fInterm\fP); |
| 196 |
\fBint tgetent_sp(SCREEN * \fIsp\fP, char *\fIbp\fP, const char *\fIname\fP); |
| 197 |
\fBint tgetflag_sp(SCREEN * \fIsp\fP, const char *\fIcapname\fP); |
| 198 |
\fBint tgetnum_sp(SCREEN * \fIsp\fP, const char *\fIcapname\fP); |
| 199 |
\fBchar * tgetstr_sp(SCREEN * \fIsp\fP, const char *\fIcapname\fP, char **\fIarea\fP); |
| 200 |
\fBchar * tgoto_sp(SCREEN * \fIsp\fP, const char *\fIcapname\fP, int \fIcol\fP, int \fIrow\fP); |
| 201 |
\fBint tigetflag_sp(SCREEN * \fIsp\fP, const char *\fIcapname\fP); |
| 202 |
.PP |
| 203 |
\fBint tigetnum_sp(SCREEN * \fIsp\fP, const char *\fIcapname\fP); |
| 204 |
\fBchar * tigetstr_sp(SCREEN * \fIsp\fP, const char *\fIcapname\fP); |
| 205 |
\fI/* tparm_sp may use 9 long parameters rather than being variadic */ |
| 206 |
\fBchar * tparm_sp(SCREEN * \fIsp\fP, const char *\fIstr\fP, ...); |
| 207 |
\fBint tputs_sp(SCREEN * \fIsp\fP, const char *\fIstr\fP, int \fIaffcnt\fP, NCURSES_SP_OUTC \fIputc\fP); |
| 208 |
.PP |
| 209 |
\fB#include <unctrl.h> |
| 210 |
.PP |
| 211 |
\fBNCURSES_CONST char * unctrl_sp(SCREEN * \fIsp\fP, chtype \fIch\fP); |
| 212 |
.fi |
| 213 |
.SH DESCRIPTION |
| 214 |
This implementation can be configured to provide a set of functions which |
| 215 |
improve the ability to manage multiple screens. |
| 216 |
This feature can be added to any of the configurations supported by |
| 217 |
\fI\%ncurses\fP; |
| 218 |
it adds new symbols |
| 219 |
without changing the meaning of any of the existing ones. |
| 220 |
.\" *************************************************************************** |
| 221 |
.SS "Improved Functions" |
| 222 |
Most of the functions are new versions of existing functions. |
| 223 |
A parameter is added at the front of the parameter list. |
| 224 |
It is a \fISCREEN\fP pointer. |
| 225 |
.PP |
| 226 |
The existing functions all use the current screen, |
| 227 |
which is a static variable. |
| 228 |
The extended functions use the specified screen, |
| 229 |
thereby reducing the number of variables which must be modified |
| 230 |
to update multiple screens. |
| 231 |
.\" *************************************************************************** |
| 232 |
.SS "New Functions" |
| 233 |
Here are the new functions: |
| 234 |
.TP 5 |
| 235 |
ceiling_panel |
| 236 |
this returns a pointer to the topmost panel in the given screen. |
| 237 |
.TP 5 |
| 238 |
ground_panel |
| 239 |
this returns a pointer to the lowest panel in the given screen. |
| 240 |
.TP 5 |
| 241 |
new_prescr |
| 242 |
when creating a new screen, the library uses static variables which |
| 243 |
have been preset, e.g., by \fBuse_env\fP(3NCURSES), \fBfilter\fP(3NCURSES), etc. |
| 244 |
With the screen-pointer extension, |
| 245 |
there are situations where it must create a current screen before |
| 246 |
the unextended library does. |
| 247 |
The \fBnew_prescr\fP function is used internally to handle these cases. |
| 248 |
It is also provided to allow applications to customize library |
| 249 |
initialization. |
| 250 |
.\" *************************************************************************** |
| 251 |
.SH NOTES |
| 252 |
This extension introduces some new names: |
| 253 |
.TP 5 |
| 254 |
NCURSES_SP_FUNCS |
| 255 |
This is set to the library patch-level number. |
| 256 |
In the unextended library, this is zero (0), |
| 257 |
to make it useful for checking if the extension is provided. |
| 258 |
.TP 5 |
| 259 |
NCURSES_SP_NAME |
| 260 |
The new functions are named using the macro \fINCURSES_SP_NAME\fP, |
| 261 |
which hides the actual implementation. |
| 262 |
Currently this adds a \*(``_sp\*('' suffix |
| 263 |
to the name of the unextended function. |
| 264 |
This manual page indexes the extensions showing the full name. |
| 265 |
However the proper usage of these functions uses the macro, |
| 266 |
to provide for the possibility of changing the naming convention |
| 267 |
for specific library configurations. |
| 268 |
.TP 5 |
| 269 |
NCURSES_SP_OUTC |
| 270 |
This is a new function-pointer type to use in the screen-pointer functions |
| 271 |
where an \fINCURSES_OUTC\fP is used in the unextended library. |
| 272 |
.TP 5 |
| 273 |
NCURSES_OUTC |
| 274 |
This is a function-pointer type used for the cases where a function passes |
| 275 |
characters to the output stream, e.g., \fBvidputs\fP(3NCURSES). |
| 276 |
.SH PORTABILITY |
| 277 |
These routines are specific to \fI\%ncurses\fP. |
| 278 |
They were not supported on Version 7, BSD or System V implementations. |
| 279 |
It is recommended that any code depending on \fI\%ncurses\fP extensions |
| 280 |
be conditioned using \fINCURSES_SP_FUNCS\fP. |
| 281 |
.SH SEE ALSO |
| 282 |
\fB\%ncurses\fP(3NCURSES), |
| 283 |
\fB\%opaque\fP(3NCURSES), |
| 284 |
\fB\%threads\fP(3NCURSES) |