ncurses 6.5 - patch 20240622

[ncurses.git] / man / curs_ins_wstr.3x

diff --git a/man/curs_ins_wstr.3x b/man/curs_ins_wstr.3x
index 12479b0d9306593371d521460b0e1bc6039f7500..37a583027f2786bc9c35a881ed5c30a5ccb49599 100644 (file)
--- a/man/curs_ins_wstr.3x
+++ b/man/curs_ins_wstr.3x
@@ -1,5 +1,6 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" Copyright (c) 2002-2010,2012 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            *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *


@@ -26,81 +27,128 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_ins_wstr.3x,v 1.7 2012/11/03 23:03:59 tom Exp $
-.TH curs_ins_wstr 3X ""
-.na
-.hy 0
+.\" $Id: curs_ins_wstr.3x,v 1.42 2024/06/08 21:04:04 tom Exp $
+.TH curs_ins_wstr 3X 2024-06-08 "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
 .SH NAME

-\fBins_wstr\fR,
-\fBins_nwstr\fR,
-\fBwins_wstr\fR,
-\fBwins_nwstr\fR,
-\fBmvins_wstr\fR,
-\fBmvins_nwstr\fR,
-\fBmvwins_wstr\fR,
-\fBmvwins_nwstr\fR \- insert a wide-character string into a curses window
-.ad
-.hy
+\fB\%ins_wstr\fP,
+\fB\%ins_nwstr\fP,
+\fB\%wins_wstr\fP,
+\fB\%wins_nwstr\fP,
+\fB\%mvins_wstr\fP,
+\fB\%mvins_nwstr\fP,
+\fB\%mvwins_wstr\fP,
+\fB\%mvwins_nwstr\fP \-
+insert a wide-character string in a \fIcurses\fR window

 .SH SYNOPSIS
 .nf
 .SH SYNOPSIS
 .nf

-\fB#include <curses.h>\fR
-.sp
-\fBint ins_wstr(const wchar_t *\fR\fIwstr);\fR
-.br
-\fBint ins_nwstr(const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint wins_wstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint wins_nwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvins_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint mvins_nwstr(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 mvwins_wstr(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 mvwins_nwstr(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
+\fB#include <curses.h>
+.PP
+\fBint ins_wstr(const wchar_t *\fIwstr\fP);
+\fBint ins_nwstr(const wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint wins_wstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP);
+\fBint wins_nwstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
+.PP
+\fBint mvins_wstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP);
+\fBint mvins_nwstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint mvwins_wstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP);
+\fBint mvwins_nwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);

 .fi
 .SH DESCRIPTION
 .fi
 .SH DESCRIPTION

-These routines insert a \fBwchar_t\fR character string
+These routines insert a \fBwchar_t\fP character string

 (as many characters as will fit on the line)
 (as many characters as will fit on the line)

-before the character under the cursor.
+before the character under the cursor,
+as if calling \fBwins_wch\fP(3X).

 All characters to the right of the cursor are shifted right,
 with the possibility of the rightmost characters on the line being lost.
 No wrapping is performed.
 All characters to the right of the cursor are shifted right,
 with the possibility of the rightmost characters on the line being lost.
 No wrapping is performed.

+.PP

 The cursor position does not change
 The cursor position does not change

-(after moving to \fIy\fR, \fIx\fR, if specified).
-The four routines with \fIn\fR as the last argument
-insert a leading substring of at most \fIn\fR \fBwchar_t\fR characters.
-If \fIn\fR is less than 1, the entire string is inserted.
+(after moving to \fIy\fP, \fIx\fP, if specified).

 .PP
 .PP

-If a character in \fIwstr\fR is a tab, newline, carriage return or
-backspace, the cursor is moved appropriately within the window.
-A newline also does a \fBclrtoeol\fR before moving.
-Tabs are considered to be at every eighth column.
-If a character in \fIwstr\fR is another control character,
-it is drawn in the \fB^\fR\fIX\fR notation.
-Calling \fBwin_wch\fR after adding a control character
-(and moving to it, if necessary)
-does not return the control character,
-but instead returns a character in the ^-representation
-of the control character.
-.SH NOTES
-Note that all but wins_nwstr may be macros.
+The functions with \fIn\fP as the last argument
+insert a leading substring of at most \fIn\fP \fBwchar_t\fP characters.
+If \fIn\fP is less than zero, the entire string is inserted
+(stopping on a L'\e0' character).

 .PP
 .PP

-If the first character in the string is a nonspacing character, these
-functions will fail.
-XSI does not define what will happen if a nonspacing character follows
-a control character.
+Special characters are handled as in \fBwadd_wch\fP(3X).

 .SH RETURN VALUE
 .SH RETURN VALUE

-Upon successful completion, these functions return OK.
-Otherwise, they return ERR.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
+.PP
+X/Open Curses does not specify any error conditions.
+In
+.IR \%ncurses ","
+they return
+.B ERR
+if
+.bP
+.I win
+is
+.BR NULL ","
+.bP
+.I wstr
+is
+.BR NULL ","
+or
+.bP
+an internal \fB\%wins_wch\fP(3X) call returns
+.BR ERR "."

 .PP
 .PP

-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.SH NOTES
+All of these functions except
+.B \%wins_nwstr
+may be implemented as macros.
+.PP
+If the first character in the string is a non-spacing character,
+these functions return
+.BR ERR "."
+X/Open Curses does not specify what happens
+if a non-spacing character follows a control character.
+.SH PORTABILITY
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+Issue 4 states that the entire string is inserted if
+.I n
+is less than 1.
+This is probably an error,
+because it is inconsistent with other functions,
+and differs from the SVr4
+.I curses
+and Solaris
+.I xcurses
+implementations.
+Nevertheless,
+Issue 7 retains it.

 .SH SEE ALSO
 .SH SEE ALSO

-\fBcurses\fR(3X),
-\fBcurs_insstr\fR(3X),
-\fBcurs_in_wch\fR(3X),
-\fBcurs_ins_wch\fR(3X).
+\fB\%curs_insstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_ins_wch\fP(3X),
+\fB\%curs_in_wch\fP(3X)