ncurses 4.2
[ncurses.git] / Ada95 / html / curs_attr.3x.html
1 <HTML>
2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
3 <PRE>
4        <STRONG>attroff</STRONG>,  <STRONG>wattroff</STRONG>,  <STRONG>attron</STRONG>,  <STRONG>wattron</STRONG>,  <STRONG>attrset</STRONG>, <STRONG>wattrset</STRONG>,
5        <STRONG>standend</STRONG>, <STRONG>wstandend</STRONG>, <STRONG>standout</STRONG>, <STRONG>wstandout</STRONG> - <STRONG>curses</STRONG>  charac-
6        ter and window attribute control routines
7
8
9 </PRE>
10 <H2>SYNOPSIS</H2><PRE>
11        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
12        <STRONG>int</STRONG> <STRONG>attroff(int</STRONG> <STRONG>attrs);</STRONG>
13        <STRONG>int</STRONG> <STRONG>wattroff(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>attrs);</STRONG>
14        <STRONG>int</STRONG> <STRONG>attron(int</STRONG> <STRONG>attrs);</STRONG>
15        <STRONG>int</STRONG> <STRONG>wattron(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>attrs);</STRONG>
16        <STRONG>int</STRONG> <STRONG>attrset(int</STRONG> <STRONG>attrs);</STRONG>
17        <STRONG>int</STRONG> <STRONG>wattrset(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>attrs);</STRONG>
18        <STRONG>int</STRONG> <STRONG>standend(void);</STRONG>
19        <STRONG>int</STRONG> <STRONG>wstandend(WINDOW</STRONG> <STRONG>*win);</STRONG>
20        <STRONG>int</STRONG> <STRONG>standout(void);</STRONG>
21        <STRONG>int</STRONG> <STRONG>wstandout(WINDOW</STRONG> <STRONG>*win);</STRONG>
22        <STRONG>attr_t</STRONG> <STRONG>attr_get(void);</STRONG>
23        <STRONG>attr_t</STRONG> <STRONG>wattr_get(WINDOW</STRONG> <STRONG>*);</STRONG>
24        <STRONG>int</STRONG> <STRONG>attr_off(attr_t</STRONG> <STRONG>attrs);</STRONG>
25        <STRONG>int</STRONG> <STRONG>wattr_off(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs);</STRONG>
26        <STRONG>int</STRONG> <STRONG>attr_on(attr_t</STRONG> <STRONG>attrs);</STRONG>
27        <STRONG>int</STRONG> <STRONG>wattr_on(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs);</STRONG>
28        <STRONG>int</STRONG> <STRONG>attr_set(attr_t</STRONG> <STRONG>attrs);</STRONG>
29        <STRONG>int</STRONG> <STRONG>wattr_set(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs);</STRONG>
30        <STRONG>int</STRONG>  <STRONG>chgat(int</STRONG>  <STRONG>n,</STRONG>  <STRONG>attr_t</STRONG>  <STRONG>attr,</STRONG>  <STRONG>short</STRONG> <STRONG>color,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG>
31        <STRONG>*opts)</STRONG>
32        <STRONG>int</STRONG> <STRONG>wchgat(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>int</STRONG> <STRONG>n,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attr,</STRONG>
33              <STRONG>short</STRONG> <STRONG>color,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*opts)</STRONG>
34        <STRONG>int</STRONG> <STRONG>mvchgat(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>int</STRONG> <STRONG>n,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attr,</STRONG>
35              <STRONG>short</STRONG> <STRONG>color,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*opts)</STRONG>
36        <STRONG>int</STRONG> <STRONG>mvwchgat(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>int</STRONG> <STRONG>n,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attr,</STRONG>
37              <STRONG>short</STRONG> <STRONG>color,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*opts)</STRONG>
38
39
40 </PRE>
41 <H2>DESCRIPTION</H2><PRE>
42        These routines manipulate the current  attributes  of  the
43        named window.  The current attributes of a window apply to
44        all characters that are written into the window with  <STRONG>wad-</STRONG>
45        <STRONG>dch</STRONG>,  <STRONG>waddstr</STRONG>  and  <STRONG>wprintw</STRONG>.  Attributes are a property of
46        the character, and move with  the  character  through  any
47        scrolling and insert/delete line/character operations.  To
48        the extent possible, they  are  displayed  as  appropriate
49        modifications  to  the graphic rendition of characters put
50        on the screen.
51
52        The routine <STRONG>attrset</STRONG> sets the  current  attributes  of  the
53        given  window to <EM>attrs</EM>.  The routine <STRONG>attroff</STRONG> turns off the
54        named attributes without turning any other  attributes  on
55        or  off.  The routine <STRONG>attron</STRONG> turns on the named attributes
56        without affecting any others.  The routine <STRONG>standout</STRONG> is the
57        same  as  <STRONG>attron(A_STANDOUT)</STRONG>.  The routine <STRONG>standend</STRONG> is the
58        same as <STRONG>attrset(A_NORMAL)</STRONG> or <STRONG>attrset(0)</STRONG>, that is, it turns
59        off all attributes.
60        the given window; <STRONG>attr_get</STRONG> returns the  current  attribute
61        for   <STRONG>stdscr</STRONG>.   The  remaining  <STRONG>attr_</STRONG>*  functions  operate
62        exactly like the  corresponding  <STRONG>attr</STRONG>*  functions,  except
63        that they take arguments of type <STRONG>attr_t</STRONG> rather than <STRONG>int</STRONG>.
64
65        The routine <STRONG>chgat</STRONG> changes the attributes of a given number
66        of characters starting at the current cursor  location  of
67        <STRONG>stdscr</STRONG>.   It  does not update the cursor and does not per-
68        form wrapping.  A character count of -1  or  greater  than
69        the  remaining window width means to change attributes all
70        the way to the end of the current line.  The <STRONG>wchgat</STRONG>  func-
71        tion generalizes this to any window; the <STRONG>mvwchgat</STRONG> function
72        does a cursor move before acting.  In these functions, the
73        color  argument  is  a  color-pair  index (as in the first
74        argument of  <EM>init</EM><STRONG>_</STRONG><EM>pair</EM>,  see  <STRONG><A HREF="curs_color.3x.html">curs_color(3X)</A></STRONG>).   The  <STRONG>opts</STRONG>
75        argument  is  not  presently used, but is reserved for the
76        future (leave it <STRONG>NULL</STRONG>).
77
78    <STRONG>Attributes</STRONG>
79        The following video attributes, defined in <STRONG>&lt;curses.h&gt;</STRONG>, can
80        be passed to the routines <STRONG>attron</STRONG>, <STRONG>attroff</STRONG>, and <STRONG>attrset</STRONG>, or
81        OR'ed with the characters passed to <STRONG>addch</STRONG>.
82
83        center ; l l .  <STRONG>A_NORMAL</STRONG>  Normal  display  (no  highlight)
84        <STRONG>A_STANDOUT</STRONG>     Best  highlighting  mode  of  the terminal.
85        <STRONG>A_UNDERLINE</STRONG>    Underlining     <STRONG>A_REVERSE</STRONG> Reverse     video
86        <STRONG>A_BLINK</STRONG>   Blinking  <STRONG>A_DIM</STRONG>     Half  bright <STRONG>A_BOLD</STRONG>    Extra
87        bright or bold <STRONG>A_PROTECT</STRONG> Protected mode  <STRONG>A_INVIS</STRONG>   Invisi-
88        ble  or  blank mode <STRONG>A_ALTCHARSET</STRONG>   Alternate character set
89        <STRONG>A_CHARTEXT</STRONG>     Bit-mask    to    extract    a    character
90        <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG>  Color-pair number <EM>n</EM>
91
92        The following macro is the reverse of <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG>:
93
94        <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM>) Returns the pair number associated
95                           with the <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> attribute.
96
97        The  return values of many of these routines are not mean-
98        ingful (they are implemented as macro-expanded assignments
99        and  simply  return their argument).  The SVr4 manual page
100        claims (falsely) that these routines always return <STRONG>1</STRONG>.
101
102
103
104 </PRE>
105 <H2>NOTES</H2><PRE>
106        Note that <STRONG>attroff</STRONG>,  <STRONG>wattroff</STRONG>,  <STRONG>attron</STRONG>,  <STRONG>wattron</STRONG>,  <STRONG>attrset</STRONG>,
107        <STRONG>wattrset</STRONG>, <STRONG>standend</STRONG> and <STRONG>standout</STRONG> may be macros.
108
109
110 </PRE>
111 <H2>PORTABILITY</H2><PRE>
112        All  these functions are supported in the XSI Curses stan-
113        dard, Issue 4.  The standard defined  the  dedicated  type
114        for  highlights,  <STRONG>attr_t</STRONG>,  which  is  not  defined in SVr4
115        curses. The functions taking <STRONG>attr_t</STRONG> arguments are not sup-
116        tional  functions  <STRONG>attron</STRONG>/<STRONG>attroff</STRONG>/<STRONG>attrset</STRONG>  can  manipulate
117        attributes  other  than <STRONG>A_BLINK</STRONG>, <STRONG>A_BOLD</STRONG>, <STRONG>A_DIM</STRONG>, <STRONG>A_REVERSE</STRONG>,
118        <STRONG>A_STANDOUT</STRONG>, or <STRONG>A_UNDERLINE</STRONG> is "unspecified".   Under  this
119        implementation  as  well  as  SVr4 curses, these functions
120        correctly manipulate all other  highlights  (specifically,
121        <STRONG>A_ALTCHARSET</STRONG>, <STRONG>A_PROTECT</STRONG>, and <STRONG>A_INVIS</STRONG>).
122
123        XSI  Curses added the new entry points, <STRONG>attr_get</STRONG>, <STRONG>attr_on</STRONG>,
124        <STRONG>attr_off</STRONG>,  <STRONG>attr_set</STRONG>,   <STRONG>wattr_on</STRONG>,   <STRONG>wattr_off</STRONG>,   <STRONG>wattr_get</STRONG>,
125        <STRONG>wattr_set</STRONG>.   These  are intended to work with a new series
126        of highlight macros prefixed with <STRONG>WA_</STRONG>.
127
128        center ; l l .  <STRONG>WA_NORMAL</STRONG> Normal  display  (no  highlight)
129        <STRONG>WA_STANDOUT</STRONG>    Best  highlighting  mode  of  the terminal.
130        <STRONG>WA_UNDERLINE</STRONG>   Underlining  <STRONG>WA_REVERSE</STRONG>     Reverse   video
131        <STRONG>WA_BLINK</STRONG>  Blinking  <STRONG>WA_DIM</STRONG>    Half  bright <STRONG>WA_BOLD</STRONG>   Extra
132        bright or bold <STRONG>WA_ALTCHARSET</STRONG>  Alternate character set
133
134        The XSI curses standard specifies that each pair of corre-
135        sponding  <STRONG>A_</STRONG>  and <STRONG>WA_</STRONG>-using functions operates on the same
136        current-highlight information.
137
138        The XSI standard extended conformance level adds new high-
139        lights <STRONG>A_HORIZONTAL</STRONG>, <STRONG>A_LEFT</STRONG>, <STRONG>A_LOW</STRONG>, <STRONG>A_RIGHT</STRONG>, <STRONG>A_TOP</STRONG>, <STRONG>A_VER-</STRONG>
140        <STRONG>TICAL</STRONG> (and corresponding <STRONG>WA_</STRONG> macros for each)  which  this
141        curses does not yet support.
142
143
144 </PRE>
145 <H2>SEE ALSO</H2><PRE>
146        <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>,        <STRONG><A HREF="curs_addch.3x.html">curs_addch(3X)</A></STRONG>,        <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3X)</A></STRONG>,
147        <STRONG><A HREF="curs_printw.3x.html">curs_printw(3X)</A></STRONG>
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170 </PRE>
171 </BODY>
172 </HTML>