X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_addwstr.3x;h=6f7c3dbe17f7d10d548c3d4f56607f9424567581;hp=4091b3627657e6de50e9eb134c345513cbbef03f;hb=HEAD;hpb=a8987e73ec254703634802b4f7ee30d3a485524d diff --git a/man/curs_addwstr.3x b/man/curs_addwstr.3x index 4091b362..0f96afb2 100644 --- a/man/curs_addwstr.3x +++ b/man/curs_addwstr.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 2002,2003 Free Software Foundation, Inc. * +.\" Copyright 2019-2023,2024 Thomas E. Dickey * +.\" Copyright 2002-2012,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 * @@ -26,66 +27,122 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addwstr.3x,v 1.3 2003/12/27 18:51:01 tom Exp $ -.TH curs_addwstr 3X "" +.\" $Id: curs_addwstr.3x,v 1.35 2024/04/13 22:14:06 tom Exp $ +.TH curs_addwstr 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .SH NAME -\fBaddwstr\fR, -\fBaddnwstr\fR, -\fBwaddwstr\fR, -\fBwaddnwstr\fR, -\fBmvaddwstr\fR, -\fBmvaddnwstr\fR, -\fBmvwaddwstr\fR, -\fBmvwaddnwstr\fR \- add a string of wide characters to a \fBcurses\fR window and advance cursor +\fB\%addwstr\fP, +\fB\%addnwstr\fP, +\fB\%waddwstr\fP, +\fB\%waddnwstr\fP, +\fB\%mvaddwstr\fP, +\fB\%mvaddnwstr\fP, +\fB\%mvwaddwstr\fP, +\fB\%mvwaddnwstr\fP \- +add a wide-character string to a \fIcurses\fR window and advance the cursor .SH SYNOPSIS .nf -\fB#include \fR +\fB#include .PP -\fBint addwstr(const wchar_t *\fR\fIwstr\fR\fB);\fR -.br -\fBint addnwstr(const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR -.br -\fBint waddwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR -.br -\fBint waddnwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR -.br -\fBint mvaddwstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR -.br -\fBint mvaddnwstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR -.br -\fBint mvwaddwstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR -.br -\fBint mvwaddnwstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +\fBint addwstr(const wchar_t *\fIwstr\fP); +\fBint mvaddwstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP); +\fBint mvwaddwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP); +\fBint waddwstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP); +.PP +\fBint addnwstr(const wchar_t *\fIwstr\fP, int \fIn\fP); +\fBint mvaddnwstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP); +\fBint mvwaddnwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP); +\fBint waddnwstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP, int \fIn\fP); .fi .SH DESCRIPTION -These routines write the characters of the (null-terminated) \fBwchar_t\fRcharacter string -\fIwstr\fR on the given window. -It is similar to constructing a \fBcchar_t\fR for each wchar_t in the string, -then calling \fBwadd_wch\fR for the resulting \fBcchar_t\fR. +.B waddwstr +writes the characters of the (wide-null-terminated) wide-character +string +.I wstr +to the window +.IR win . +Its process is similar to constructing a +.I cchar_t +for each +.I wchar_t +in +.IR wstr , +then calling \fB\%wadd_wch\fP(3X) with the resulting +.IR cchar_t . +.bP +Spacing and non-spacing characters in the string +are processed one at a time, +and +.bP +control characters are processed as in \fB\%wadd_wch\fP(3X). +.PP +.B waddnwstr +writes at most +.I n +wide characters, +or until a terminating wide null character occurs in +.IR wstr . +If +.I n +is \-1, +.B +.B waddnwstr +writes the entire wide string. +.PP +\fB\%ncurses\fP(3X) describes the variants of these functions. +.SH RETURN VALUE +These functions return +.B OK +on success and +.B ERR +on failure. .PP -The \fImv\fR routines perform cursor movement once, before writing any -characters. -Thereafter, the cursor is advanced as a side-effect of writing to the window. +X/Open Curses does not specify any error conditions. +.I \%ncurses +returns an error +.bP +if the window pointer is +.BR NULL , +.bP +if the string pointer is +.BR NULL , +or +.bP +if an internal \fB\%wadd_wch\fP(3X) call returns an error. .PP -The four routines with \fIn\fR as the last argument -write at most \fIn\fR \fBwchar_t\fR characters. -If \fIn\fR is -1, then the entire string will be added, -up to the maximum number of characters that will fit on the line, -or until a terminating null is reached. -.SH RETURN VALUES -All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success. +Functions with a \*(``mv\*('' prefix first perform cursor movement using +\fB\%wmove\fP(3X) and fail if the position is outside the window, +or +(for \*(``mvw\*('' functions) +if the +.I \%WINDOW +pointer is null. .SH NOTES -Note that all of these routines except \fBwaddnwstr\fR may be macros. +All of these functions except +.B waddnwstr +may be implemented as macros. .SH PORTABILITY -All these entry points are described in the XSI Curses standard, Issue 4. +X/Open Curses, +Issue 4 describes these functions. .SH SEE ALSO +\fB\%curs_addstr\fP(3X) describes comparable functions of the +.I \%ncurses +library in its non-wide-character configuration. .PP -Functions: -\fBcurses\fR(3X), -\fBcurs_add_wch\fR(3X) -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +\fB\%curses\fP(3X), +\fB\%curs_add_wch\fP(3X), +\fB\%curs_add_wchstr\fP(3X)