X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_addch.3x;h=d502faabdb03521d40697f15450adbf7f45c77ac;hp=151c3160c4c8d1322b956a8fdab8f7228807cf16;hb=321b81e6b3fa425daddac02420d862100dc3aac8;hpb=ed646e3f683083e787c6ba773364401dc9fa9d40 diff --git a/man/curs_addch.3x b/man/curs_addch.3x index 151c3160..d502faab 100644 --- a/man/curs_addch.3x +++ b/man/curs_addch.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2015,2017 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2017,2018 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,14 +27,15 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addch.3x,v 1.41 2017/05/05 18:15:29 tom Exp $ +.\" $Id: curs_addch.3x,v 1.46 2018/07/28 21:02:35 tom Exp $ .TH curs_addch 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` .ie \n(.g .ds '' \(rq .el .ds '' '' .de bP -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. .SH NAME \fBaddch\fR, @@ -62,7 +63,8 @@ .SS Adding characters The \fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR and \fBmvwaddch\fR routines put the character \fIch\fR into the given window at its current window position, -which is then advanced. They are analogous to \fBputchar\fR(3) in \fBstdio\fR(3). +which is then advanced. +They are analogous to \fBputchar\fR(3) in \fBstdio\fR(3). If the advance is at the right margin: .bP The cursor automatically wraps to the beginning of the next line. @@ -92,7 +94,8 @@ 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. Calling \fBwinch\fR after adding a +is drawn in \fB^\fR\fIX\fR notation. +Calling \fBwinch\fR after adding a control character does not return the character itself, but instead returns the ^-representation of the control character. .PP @@ -106,13 +109,15 @@ into characters. .PP The \fBechochar\fR and \fBwechochar\fR routines are equivalent to a call to \fBaddch\fR followed by a call to \fBrefresh\fR(3X), or a call to \fBwaddch\fR -followed by a call to \fBwrefresh\fR. The knowledge that only a single +followed by a call to \fBwrefresh\fR. +The knowledge that only a single character is being output is used and, for non-control characters, a considerable performance gain may be seen by using these routines instead of their equivalents. .SS Line Graphics The following variables may be used to add line drawing characters to the -screen with routines of the \fBaddch\fR family. The default character listed +screen with routines of the \fBaddch\fR family. +The default character listed below is used if the \fBacsc\fR capability does not define a terminal-specific replacement for it, or if the terminal and locale configuration requires Unicode but the @@ -175,6 +180,7 @@ Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and .SH PORTABILITY All these functions are described in the XSI Curses standard, Issue 4. The defaults specified for forms-drawing characters apply in the POSIX locale. +.SS ACS Symbols .LP X/Open Curses states that the \fIACS_\fP definitions are \fBchar\fP constants. For the wide-character implementation (see \fBcurs_add_wch\fP), @@ -189,10 +195,12 @@ ACS_PI, ACS_NEQUAL, ACS_STERLING) were not documented in -any publicly released System V. However, many publicly available terminfos +any publicly released System V. +However, many publicly available terminfos include \fBacsc\fR strings in which their key characters (pryz{|}) are embedded, and a second-hand list of their character descriptions has come -to light. The ACS-prefixed names for them were invented for \fBncurses\fR(3X). +to light. +The ACS-prefixed names for them were invented for \fBncurses\fR(3X). .LP The \fIdisplayed\fP values for the \fIACS_\fP and \fIWACS_\fP constants depend on @@ -205,6 +213,44 @@ whether the \fIlocale\fP uses UTF-8 encoding. In certain cases, the terminal is unable to display line-drawing characters except by using UTF-8 (see the discussion of \fBNCURSES_NO_UTF8_ACS\fP in ncurses(3X)). +.SS Character Set +X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains +a single character. +As discussed in \fBcurs_attr\fP(3X), that character may have been +more than eight bits in an SVr3 or SVr4 implementation, +but in the X/Open Curses model, the details are not given. +The important distinction between SVr4 curses and X/Open Curses is +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. +But ncurses allows multibyte characters to be passed in a succession +of calls to \fBwaddch\fP. +The other implementations do not do this; +a call to \fBwaddch\fP passes exactly one character +which may be rendered as one or more cells on the screen +depending on whether it is printable. +.PP +Depending on the locale settings, +ncurses will inspect the byte passed in each call to \fBwaddch\fP, +and check if the latest call will continue a multibyte sequence. +When a character is \fIcomplete\fP, +ncurses displays the character and moves to the next position in the screen. +.PP +If the calling application interrupts the succession of bytes in +a multibyte character by moving the current location (e.g., using \fBwmove\fP), +ncurses discards the partially built character, +starting over again. +.PP +For portability to other implementations, +do not rely upon this behavior: +.bP +check if a character can be represented as a single byte in the current locale +before attempting call \fBwaddch\fP, and +.bP +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.