diff options
Diffstat (limited to 'man/curs_add_wchstr.3x')
| -rw-r--r-- | man/curs_add_wchstr.3x | 139 |
1 files changed, 93 insertions, 46 deletions
diff --git a/man/curs_add_wchstr.3x b/man/curs_add_wchstr.3x index 5dd3e8f4e131..b5d30e60521b 100644 --- a/man/curs_add_wchstr.3x +++ b/man/curs_add_wchstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2019-2023,2024 Thomas E. Dickey * +.\" Copyright 2019-2024,2025 Thomas E. Dickey * .\" Copyright 2002-2012,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_add_wchstr.3x,v 1.39 2024/04/20 21:20:07 tom Exp $ -.TH curs_add_wchstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.\" $Id: curs_add_wchstr.3x,v 1.61 2025/10/21 00:06:34 tom Exp $ +.TH curs_add_wchstr 3X 2025-10-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -46,68 +46,91 @@ .. .SH NAME \fB\%add_wchstr\fP, -\fB\%add_wchnstr\fP, \fB\%wadd_wchstr\fP, -\fB\%wadd_wchnstr\fP, \fB\%mvadd_wchstr\fP, -\fB\%mvadd_wchnstr\fP, \fB\%mvwadd_wchstr\fP, +\fB\%add_wchnstr\fP, +\fB\%wadd_wchnstr\fP, +\fB\%mvadd_wchnstr\fP, \fB\%mvwadd_wchnstr\fP \- add a \fIcurses\fR complex character string to a window .SH SYNOPSIS .nf \fB#include <curses.h> .PP -\fBint add_wchstr(const cchar_t *\fIwchstr\fP); -\fBint wadd_wchstr(WINDOW * \fIwin\fP, const cchar_t *\fIwchstr\fP); -\fBint mvadd_wchstr(int \fIy\fP, int \fIx\fP, const cchar_t *\fIwchstr\fP); -\fBint mvwadd_wchstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwchstr\fP); +\fBint add_wchstr(const cchar_t * \fIwchstr\fP); +\fBint wadd_wchstr(WINDOW * \fIwin\fP, const cchar_t * \fIwchstr\fP); +\fBint mvadd_wchstr(int \fIy\fP, int \fIx\fP, const cchar_t * \fIwchstr\fP); +\fBint mvwadd_wchstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t * \fIwchstr\fP); .PP -\fBint add_wchnstr(const cchar_t *\fIwchstr\fP, int \fIn\fP); -\fBint wadd_wchnstr(WINDOW * \fIwin\fP, const cchar_t *\fIwchstr\fP, int \fIn\fP); -\fBint mvadd_wchnstr(int \fIy\fP, int \fIx\fP, const cchar_t *\fIwchstr\fP, int \fIn\fP); -\fBint mvwadd_wchnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwchstr\fP, int \fIn\fP); +\fBint add_wchnstr(const cchar_t * \fIwchstr\fP, int \fIn\fP); +\fBint wadd_wchnstr(WINDOW * \fIwin\fP, const cchar_t * \fIwchstr\fP, int \fIn\fP); +\fBint mvadd_wchnstr(int \fIy\fP, int \fIx\fP, const cchar_t * \fIwchstr\fP, int \fIn\fP); +\fBint mvwadd_wchnstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, + const cchar_t * \fIwchstr\fP, int \fIn\fP); .fi .SH DESCRIPTION -These functions copy the (null-terminated) -array of complex characters \fIwchstr\fP -into the window image structure -starting at the current cursor position. -.PP -The four functions with \fIn\fP as the last -argument copy at most \fIn\fP elements, -but no more than will fit on the line. -If \fBn\fP=\fB\-1\fP then the whole array is copied, -to the maximum number of characters that will fit on the line. +.B \%wadd_wchstr +copies the string of complex characters +.I \%wchstr +to the window +.IR win "." +A null complex character terminates the string. +If a complex character does not completely fit at the end of the line, +.I curses +fills its remaining cells with the window's background character; +see \fB\%bkgrnd\fP(3X). +.B \%wadd_wchnstr +does the same, +but copies at most +.I n +characters, +or as many as possible if +.I n +is +.BR \-1 "." +\fB\%ncurses\fP(3X) describes the variants of these functions. .PP -The window cursor is \fInot\fP advanced. -These functions are faster than \fBwaddnstr\fP. -On the other hand: +Because these functions do not call \fB\%wadd_wch\fP(3X) internally, +they are faster than \fB\%waddwstr\fP(3X) and \fB\%waddnwstr\fP(3X). +On the other hand, +they .bP -they do not perform checking -(such as for the newline, backspace, or carriage return characters), +do not treat the backspace, +carriage return, +or line feed characters specially; .bP -they do not advance the current cursor position, +do not represent unprintable characters with \fB\%wunctrl\fP(3X); .bP -they do not expand other control characters to ^-escapes, and +do not update the cursor position to follow the last character written; +and .bP -they truncate the string if it crosses the right margin, -rather than wrapping it around to the new line. -.PP -These functions end successfully -on encountering a null \fBcchar_t\fP, or -when they have filled the current line. -If a complex character cannot completely fit at the end of the current line, -the remaining columns are filled with the background character and rendition. +truncate the string at the window's right margin, +rather than wrapping it to the next line and potentially scrolling. .SH RETURN VALUE -All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success. +These functions return +.B OK +on success and +.B ERR +on failure. .PP -X/Open Curses does not specify any error conditions. -This implementation returns an error +In +.IR \%ncurses "," +these functions fail if +.bP +the +.I curses +screen has not been initialized, .bP -if the \fIwin\fP parameter is null or +.I wchstr +is a null pointer, +or .bP -if the \fIwchstr\fP parameter is null. +(for functions taking a +.I \%WINDOW +pointer argument) +.I win +is a null pointer. .PP Functions prefixed with \*(``mv\*('' first perform cursor movement and fail if the position @@ -115,9 +138,33 @@ fail if the position .IR x ) is outside the window boundaries. .SH NOTES -All functions except \fBwadd_wchnstr\fP may be macros. +All of these functions except +.B \%wadd_wchnstr +may be implemented as macros. .SH PORTABILITY -These functions are described in X/Open Curses, Issue 4. +X/Open Curses Issue\ 4 describes these functions. +It specifies no error conditions for them. +.SH HISTORY +X/Open Curses Issue\ 4 (1995) initially specified these functions. +The System\ V Interface Definition Version\ 4 +of the same year +specified functions named +.I \%waddwchstr +and +.I \%waddwchnstr +(and the usual variants). +.\" SVID 4, vol 3., p. 477 +These were later additions to +.RI SVr4. x , +not appearing in the first SVr4 (1989). +They differed from X/Open's later +.I \%wadd_wchstr +and +.I \%wadd_wchnstr +in that they each took an argument of type +.I \%wchar_t +instead of +.IR \%cchar_t "." .SH SEE ALSO \fB\%curs_addchstr\fP(3X) describes comparable functions of the .I \%ncurses |