X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_inch.3x;h=962e9dc868d444f72ea0ceeffa1f24a9513655c9;hb=HEAD;hp=db92f6dfd9ec5d71fc6a2d3c77f6cf12bdb2eb10;hpb=d90067f9008bb8338a77c1ed519bc108c275ed04;p=ncurses.git diff --git a/man/curs_inch.3x b/man/curs_inch.3x index db92f6df..edcc65cd 100644 --- a/man/curs_inch.3x +++ b/man/curs_inch.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * .\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inch.3x,v 1.41 2023/12/16 21:08:16 tom Exp $ -.TH curs_inch 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_inch.3x,v 1.60 2024/06/08 20:45:43 tom Exp $ +.TH curs_inch 3X 2024-06-08 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -56,73 +56,115 @@ get a \fIcurses\fR character from a window \fB#include .PP \fBchtype inch(void); -\fBchtype winch(WINDOW *\fIwin\fP); -.PP +\fBchtype winch(WINDOW * \fIwin\fP); \fBchtype mvinch(int \fIy\fP, int \fIx\fP); -\fBchtype mvwinch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP); +\fBchtype mvwinch(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP); .fi .SH DESCRIPTION -These routines return the character, of type \fBchtype\fP, at the current -position in the named window. -If any attributes are set for that position, -their values are OR'ed into the value returned. -Constants defined in -\fB\fP can be used with the \fB&\fP (logical AND) operator to -extract the character or attributes alone. -. -.SS Attributes -The following bit masks may be AND-ed with characters returned by \fBwinch\fP. -.PP -.TS -l l . -\fBA_CHARTEXT\fP Bit mask to extract character -\fBA_ATTRIBUTES\fP Bit mask to extract attributes -\fBA_COLOR\fP Bit mask to extract color pair field information -.TE +.B \%winch +returns the +.I curses +character, +including its attributes and color pair identifier, +at the cursor position in the window +.IR win "." +Subsection \*(``Video Attributes\*('' of \fB\%attron\fP(3X) explains +how to extract these data from a +.IR chtype "." +\fB\%ncurses\fP(3X) describes the variants of this function. .SH RETURN VALUE -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. +These functions return +.B OK +on success and +.B ERR +on failure. +.PP +In +.IR \%ncurses "," +.B \%winch +returns +.B ERR +if +.I win +is +.BR NULL "." .PP -The \fBwinch\fP function does not return an error if the window contains -characters larger than 8-bits (255). -Only the low-order 8 bits of the character are used by \fBwinch\fP. +Functions prefixed with \*(``mv\*('' first perform cursor movement and +fail if the position +.RI ( y , +.IR x ) +is outside the window boundaries. .SH NOTES -Note that all of these routines may be macros. -.SH PORTABILITY -These functions are described in the XSI Curses standard, Issue 4. +.BR \%inch , +.BR \%mvinch , +and +.B \%mvwinch +may be implemented as macros. .PP -Very old systems (before standardization) provide a different function -with the same name: -.bP -The \fBwinch\fP function was part of the original BSD curses library, -which stored a 7-bit character combined with the \fIstandout\fP attribute. -.IP -In BSD curses, \fBwinch\fP returned only the character (as an integer) -with the \fIstandout\fP attribute removed. -.bP -System V curses added support for several video attributes which -could be combined with characters in the window. -.IP -Reflecting this improvement, the function was altered to return the -character combined with all video attributes in a \fBchtype\fP value. +These functions do not fail if the window contains cells of +.I curses +complex characters; +that is, +if they contain characters with codes wider than eight bits +(or greater than 255 as an unsigned decimal integer). +They instead extract only the low-order eight bits of the character code +from the cell. +.SH PORTABILITY +X/Open Curses, +Issue 4 describes these functions. +It specifies no error conditions for them. +.SH HISTORY +The original +.I curses +in 4BSD (1980) defined +.I \%winch +as a macro accessing the +.I \%WINDOW +structure member representing character cell data, +at that time a +.IR char "," +containing only a 7-bit ASCII character code +and a \*(``standout\*(`` attribute bit, +the only one the library supported. .PP -X/Open Curses does not specify -the size and layout of attributes, color and character values in -\fBchtype\fP; it is implementation-dependent. -This implementation uses 8 bits for character values. -An application using more bits, e.g., a Unicode value, -should use the wide-character equivalents to these functions. +SVr2 +.I curses +(1984) +extended this approach, +widening the character code to eight bits +and permitting several attributes to be combined with it +by storing them together in a +.IR \%chtype "," +an alias of +.IR "unsigned short" "." +.\" ...indirectly through a preprocessor macro named CHTYPE, encouraging +.\" builders to change the typedef to `char` or `long` as desired. More +.\" innocent times with respect to ABI compatibility concerns... --GBR +Because a macro was used, +its value was not type-checked +as a function return value could have been. +Goodheart documented SVr3 (1987) +.I \%winch +as returning an +.IR int "." +.\" ...but the implementation remained unchanged. +SVr3.1's (1987) +.I \%chtype +became an alias of +.IR "unsigned long" "," +using 16 bits for the character code and +widening the type in practical terms to 32 bits, +as 64-bit Unix systems were not yet in wide use, +and fixed-width integral types would not be standard until ISO C99. +.\" Cray's UNICOS was 1985 (how many shops had Crays?). DEC OSF/1 for +.\" the Alpha arrived in 1993. --GBR +SVr3.2 (1988) +added a 6-bit color pair identifier alongside the attributes. .SH SEE ALSO -.TP -\fB\%curses\fP(3X) -gives an overview of the \fB\%WINDOW\fP and \fB\%chtype\fP data types. -.TP -\fB\%curs_attr\fP(3X) -goes into more detail, pointing out portability problems and -constraints on the use of \fB\%chtype\fP for returning window -information. -.TP -\fB\%curs_in_wch\fP(3X) -describes comparable functions for the wide-character (ncursesw) -library. +\fB\%curs_in_wch\fP(3X) describes comparable functions of the +.I \%ncurses +library in its wide-character configuration +.RI \%( ncursesw ). +.PP +\fB\%curses\fP(3X), +\fB\%curs_instr\fP(3X)