X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_inch.3x.html;h=d10727a5a1751327abc4cd7f0fd3a9b84eff16da;hb=HEAD;hp=ab5035e720d3468deb7fd14bdf08ecd722a1875b;hpb=17c5992a16be94247b83f2bbb9accdd9b7e7bb72;p=ncurses.git diff --git a/doc/html/man/curs_inch.3x.html b/doc/html/man/curs_inch.3x.html index ab5035e7..0e8a2c22 100644 --- a/doc/html/man/curs_inch.3x.html +++ b/doc/html/man/curs_inch.3x.html @@ -1,7 +1,8 @@ - -curs_inch 3x - - +curs_inch 3x 2024-06-08 ncurses 6.5 Library calls + + -

curs_inch 3x

curs_inch 3x 2024-06-08 ncurses 6.5 Library calls

-curs_inch(3x)                                                    curs_inch(3x)
+curs_inch(3x)                    Library calls                   curs_inch(3x)

NAME

-       inch,  winch,  mvinch,  mvwinch - get a character and attributes from a
-       curses window
+       inch, winch, mvinch, mvwinch - get a curses character from a window

SYNOPSIS

        #include <curses.h>
 
        chtype inch(void);
-       chtype winch(WINDOW *win);
-       chtype mvinch(int y, int x);
-       chtype mvwinch(WINDOW *win, int y, int x);
+       chtype winch(WINDOW * win);
+       chtype mvinch(int y, int x);
+       chtype mvwinch(WINDOW * win, int y, int x);

DESCRIPTION

-       These routines return the character, of type  chtype,  at  the  current
-       position in the named window.  If any attributes are set for that posi-
-       tion, their values  are  OR'ed  into  the  value  returned.   Constants
-       defined  in <curses.h> can be used with the & (logical AND) operator to
-       extract the character or attributes alone.
-
-
-

Attributes

-       The following bit-masks may  be  AND-ed  with  characters  returned  by
-       winch.
-
-       A_CHARTEXT     Bit-mask to extract character
-       A_ATTRIBUTES   Bit-mask to extract attributes
-       A_COLOR        Bit-mask to extract color-pair field information
+       winch  returns the curses character, including its attributes and color
+       pair identifier, at the cursor position in the window win.   Subsection
+       "Video  Attributes"  of  attron(3x)  explains how to extract these data
+       from a chtype.  ncurses(3x) describes the variants of this function.

RETURN VALUE

-       Functions  with  a  "mv"  prefix  first perform a cursor movement using
-       wmove, and return an error if the position is outside the window, or if
-       the window pointer is null.
-
-       The  winch  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 winch.
+       These functions return OK on success and ERR on failure.
 
+       In ncurses, winch returns ERR if win is NULL.
 
-

NOTES

-       Note that all of these routines may be macros.
+       Functions prefixed with "mv" first perform cursor movement and fail  if
+       the position (y, x) is outside the window boundaries.
 
 
-

PORTABILITY

-       These functions are described in the XSI Curses standard, Issue 4.
+

NOTES

+       inch, mvinch, and mvwinch may be implemented as macros.
 
-       Very  old systems (before standardization) provide a different function
-       with the same name:
+       These  functions  do  not  fail  if the window contains cells of 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.
 
-       o   The winch function was part of the  original  BSD  curses  library,
-           which   stored   a  7-bit  character  combined  with  the  standout
-           attribute.
 
-           In BSD curses, winch returned only the character  (as  an  integer)
-           with the standout attribute removed.
+

PORTABILITY

+       X/Open  Curses,  Issue  4  describes  these functions.  It specifies no
+       error conditions for them.
 
-       o   System  V  curses  added support for several video attributes which
-           could be combined with characters in the window.
 
-           Reflecting this improvement, the function was altered to return the
-           character combined with all video attributes in a chtype value.
+

HISTORY

+       The original curses in 4BSD (1980) defined winch as a  macro  accessing
+       the  WINDOW  structure member representing character cell data, at that
+       time a char, containing  only  a  7-bit  ASCII  character  code  and  a
+       "standout" attribute bit, the only one the library supported.
 
-       X/Open Curses does not specify the size and layout of attributes, color
-       and character values in chtype; 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 equiva-
-       lents to these functions.
+       SVr2  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  chtype, an alias of unsigned short.
+       Because a macro was used, its value was not type-checked as a  function
+       return  value  could have been.  Goodheart documented SVr3 (1987) winch
+       as returning an  int.   SVr3.1's  (1987)  chtype  became  an  alias  of
+       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.  SVr3.2 (1988) added a 6-bit color pair  identifier  alongside
+       the attributes.