X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_addch.3x;h=338a6e27855f313be99f328e504589cca5fefdaa;hp=d502faabdb03521d40697f15450adbf7f45c77ac;hb=fae162795e065e5901068152e91f2962b6b247f3;hpb=17c5992a16be94247b83f2bbb9accdd9b7e7bb72 diff --git a/man/curs_addch.3x b/man/curs_addch.3x index d502faab..338a6e27 100644 --- a/man/curs_addch.3x +++ b/man/curs_addch.3x @@ -1,6 +1,7 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2017,2018 Free Software Foundation, Inc. * +.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 1998-2015,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 * @@ -27,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addch.3x,v 1.46 2018/07/28 21:02:35 tom Exp $ +.\" $Id: curs_addch.3x,v 1.55 2020/10/24 09:12:31 tom Exp $ .TH curs_addch 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -47,17 +48,17 @@ .SH SYNOPSIS \fB#include \fR .PP -\fBint addch(const chtype ch);\fR +\fBint addch(const chtype \fP\fIch\fP\fB);\fR .br -\fBint waddch(WINDOW *win, const chtype ch);\fR +\fBint waddch(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\fR .br -\fBint mvaddch(int y, int x, const chtype ch);\fR +\fBint mvaddch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype \fP\fIch\fP\fB);\fR .br -\fBint mvwaddch(WINDOW *win, int y, int x, const chtype ch);\fR +\fBint mvwaddch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype \fP\fIch\fP\fB);\fR +.sp +\fBint echochar(const chtype \fP\fIch\fP\fB);\fR .br -\fBint echochar(const chtype ch);\fR -.br -\fBint wechochar(WINDOW *win, const chtype ch);\fR +\fBint wechochar(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\fR .br .SH DESCRIPTION .SS Adding characters @@ -93,11 +94,12 @@ scrolling the window if on the last line. Tabs are considered to be at every eighth column. The tab interval may be altered by setting the \fBTABSIZE\fR variable. .PP -If \fIch\fR is any other control character, it -is drawn in \fB^\fR\fIX\fR notation. +If \fIch\fR is any other nonprintable character, +it is drawn in printable form, +i.e., the \fB^\fR\fIX\fR notation used by \fBunctrl\fR(3X). Calling \fBwinch\fR after adding a -control character does not return the character itself, but instead returns -the ^-representation of the control character. +nonprintable character does not return the character itself, +but instead returns the printable representation of the character. .PP Video attributes can be combined with a character argument passed to \fBaddch\fR or related functions by logical-ORing them into the character. @@ -174,6 +176,19 @@ unless otherwise noted in the preceding routine descriptions. 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. +.PP +If it is not possible to add a complete character, +an error is returned: +.bP +If \fBscrollok\fR is not enabled, +writing a character at the lower right margin succeeds. +However, an error is returned because +it is not possible to wrap to a new line +.bP +If an error is detected when converting a multibyte character to a sequence +of bytes, +or if it is not possible to add all of the resulting bytes in the window, +an error is returned. .SH NOTES Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and \fBechochar\fR may be macros. @@ -185,6 +200,31 @@ The defaults specified for forms-drawing characters apply in the POSIX locale. X/Open Curses states that the \fIACS_\fP definitions are \fBchar\fP constants. For the wide-character implementation (see \fBcurs_add_wch\fP), there are analogous \fIWACS_\fP definitions which are \fBcchar_t\fP constants. +Some implementations are problematic: +.bP +Some implementations define the ACS symbols to a constant +(such as Solaris), while others define those to entries in an array. +.IP +This implementation uses an array \fBacs_map\fP, as done in SVr4 curses. +NetBSD also uses an array, actually named \fB_acs_char\fP, with a \fB#define\fP +for compatibility. +.bP +HPUX curses equates some of the \fIACS_\fP symbols +to the analogous \fIWACS_\fP symbols as if the \fIACS_\fP symbols were +wide characters. +The misdefined symbols are the arrows +and other symbols which are not used for line-drawing. +.bP +X/Open Curses (issues 2 through 7) has a typographical error +for the ACS_LANTERN symbol, equating its \*(``VT100+ Character\*('' +to \fBI\fP (capital I), while the header files for SVr4 curses +and the various implementations use \fBi\fP (lowercase). +.IP +None of the terminal descriptions on Unix platforms use uppercase-I, +except for Solaris (i.e., \fIscreen\fP's terminal description, +apparently based on the X/Open documentation around 1995). +On the other hand, the terminal description \fIgs6300\fP +(AT&T PC6300 with EMOTS Terminal Emulator) uses lowercase-i. .LP Some ACS symbols (ACS_S3, @@ -224,7 +264,7 @@ that the non-character information (attributes and color) was separated from the character information which is packed in a \fBchtype\fP to pass to \fBwaddch\fP. .PP -In this implementation, \fBchtype\fP holds eight bits. +In this implementation, \fBchtype\fP holds an eight-bit character. But ncurses allows multibyte characters to be passed in a succession of calls to \fBwaddch\fP. The other implementations do not do this; @@ -252,8 +292,9 @@ before attempting call \fBwaddch\fP, and call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP. .SS TABSIZE .LP -The \fBTABSIZE\fR variable is implemented in some versions of curses, -but is not part of X/Open curses. +The \fBTABSIZE\fR variable is implemented in SVr4 and other versions of curses, +but is not part of X/Open curses +(see \fBcurs_variables\fR(3X) for more details). .LP If \fIch\fR is a carriage return, the cursor is moved to the beginning of the current row of the window.