X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_add_wch.3x;fp=man%2Fcurs_add_wch.3x;h=fae59ae0b6cdeac3142dc6471dbe5e1077c29ab0;hp=0000000000000000000000000000000000000000;hb=46722468f47c2b77b3987729b4bcf2321cccfd01;hpb=c633e5103a29a38532cf1925257b91cea33fd090 diff --git a/man/curs_add_wch.3x b/man/curs_add_wch.3x new file mode 100644 index 00000000..fae59ae0 --- /dev/null +++ b/man/curs_add_wch.3x @@ -0,0 +1,134 @@ +.\"*************************************************************************** +.\" Copyright (c) 2001,2002 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_add_wch.3x,v 1.4 2002/02/16 22:28:43 tom Exp $ +.TH curs_add_wch 3X "" +.SH NAME +\fBadd_wch\fP, +\fBwadd_wch\fP, +\fBmvadd_wch\fP, +\fBmvwadd_wch\fP, +\fBecho_wchar\fP, +\fBwecho_wchar\fP - add a complex character and rendition to a \fBcurses\fR window, then advance the cursor +.SH SYNOPSIS +.PP +\fB#include \fP +.sp +.B "int add_wch( const cchar_t *\fIwch\fB );" +.br +.B "int wadd_wch( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );" +.br +.B "int mvadd_wch( int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );" +.br +.B "int mvwadd_wch( WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );" +.br +.B "int echo_wchar( const cchar_t *\fIwch\fB );" +.br +.B "int wecho_wchar( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );" +.br +.SH DESCRIPTION +.PP +The +\fBadd_wch\fP, +\fBwadd_wch\fP, +\fBmvadd_wch\fP, and +\fBmvwadd_wch\fP +functions put the complex character \fIwch\fP into the given +window at its current position, +which is then advanced. +These functions perform +wrapping and special-character processing as follows: +.TP 5 +- +If \fIwch\fP refers to a spacing character, +then any previous character at that location is removed. +A new character specified by \fIwch\fP is +placed at that location with rendition specified by \fIwch\fP. +The cursor then advances to +the next spacing character on the screen. +.TP 5 +- +If \fIwch\fP refers to a non-spacing character, +all previous characters at that location are preserved. +The non-spacing characters of \fIwch\fP +are added to the spacing complex character, +and the rendition specified by \fIwch\fP is ignored. +.TP 5 +- +If the character part of \fIwch\fP is +a tab, newline, backspace or other control character, +the window is updated and the cursor moves as if \fBaddch\fR(3X) were called. +.PP +The \fBecho_wchar\fP +function is functionally equivalent to a call to +\fBadd_wch\fP +followed by a call to +\fBrefresh\fP. +Similarly, the +\fBwecho_wchar\fP +is functionally equivalent to a call to +\fBwadd_wch\fP +followed by a call to +\fBwrefresh\fP. +The knowledge +that only a single character is being output is taken into consideration and, +for non-control characters, a considerable performance gain might be seen +by using the *\fBecho\fP* functions instead of their equivalents. +.SH RETURN VALUES +.PP +All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success. +.SH NOTES +.PP +Note that +\fBadd_wch\fP, +\fBmvadd_wch\fP, +\fBmvwadd_wch\fP, and +\fBecho_wchar\fP +may be macros. +.SH PORTABILITY +.PP +All these functions are described in the XSI Curses standard, Issue 4. +The defaults specified for forms-drawing characters apply in the POSIX locale. +.PP +XSI documents constants beginning with \fBWACS_\fP which are used for +line-drawing. +Those are not currently implemented in \fBncurses\fP. +.SH SEE ALSO +.PP +\fBcurses\fR(3X), +\fBcurs_attr_get\fR(3X), +\fBcurs_clear\fR(3X), +\fBcurs_outopts\fR(3X), +\fBcurs_refresh\fR(3X), +\fBputwc\fR(3) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: