doc/html/man/curs_attr.3x.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
   2 <!--
   3   * t
   4   ****************************************************************************
   5   * Copyright (c) 1998-2000,2002 Free Software Foundation, Inc.              *
   6   *                                                                          *
   7   * Permission is hereby granted, free of charge, to any person obtaining a  *
   8   * copy of this software and associated documentation files (the            *
   9   * "Software"), to deal in the Software without restriction, including      *
  10   * without limitation the rights to use, copy, modify, merge, publish,      *
  11   * distribute, distribute with modifications, sublicense, and/or sell       *
  12   * copies of the Software, and to permit persons to whom the Software is    *
  13   * furnished to do so, subject to the following conditions:                 *
  14   *                                                                          *
  15   * The above copyright notice and this permission notice shall be included  *
  16   * in all copies or substantial portions of the Software.                   *
  17   *                                                                          *
  18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  19   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  20   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  21   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  22   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  23   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  24   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  25   *                                                                          *
  26   * Except as contained in this notice, the name(s) of the above copyright   *
  27   * holders shall not be used in advertising or otherwise to promote the     *
  28   * sale, use or other dealings in this Software without prior written       *
  29   * authorization.                                                           *
  30   ****************************************************************************
  31   * @Id: curs_attr.3x,v 1.26 2002/09/21 19:50:06 tom Exp @
  32 -->
  33 <HTML>
  34 <HEAD>
  35 <TITLE>curs_attr 3x</TITLE>
  36 <link rev=made href="mailto:bug-ncurses@gnu.org">
  37 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  38 </HEAD>
  39 <BODY>
  40 <H1>curs_attr 3x</H1>
  41 <HR>
  42 <PRE>
  43 <!-- Manpage converted by man2html 3.0.1 -->
  44
  45 </PRE>
  46 <H2>NAME</H2><PRE>
  47        <STRONG>attroff</STRONG>,  <STRONG>wattroff</STRONG>,  <STRONG>attron</STRONG>,  <STRONG>wattron</STRONG>,  <STRONG>attrset</STRONG>, <STRONG>wattrset</STRONG>,
  48        <STRONG>color_set</STRONG>,  <STRONG>wcolor_set</STRONG>,  <STRONG>standend</STRONG>,  <STRONG>wstandend</STRONG>,   <STRONG>standout</STRONG>,
  49        <STRONG>wstandout</STRONG>,   <STRONG>attr_get</STRONG>,   <STRONG>wattr_get</STRONG>,  <STRONG>attr_off</STRONG>,  <STRONG>wattr_off</STRONG>,
  50        <STRONG>attr_on</STRONG>, <STRONG>wattr_on</STRONG>,  <STRONG>attr_set</STRONG>,  <STRONG>wattr_set</STRONG>,  <STRONG>chgat</STRONG>,  <STRONG>wchgat</STRONG>,
  51        <STRONG>mvchgat</STRONG>, <STRONG>mvwchgat</STRONG>, <STRONG>PAIR_NUMBER</STRONG> - <STRONG>curses</STRONG> character and win-
  52        dow attribute control routines
  53
  54
  55 </PRE>
  56 <H2>SYNOPSIS</H2><PRE>
  57        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  58        <STRONG>int</STRONG> <STRONG>attroff(int</STRONG> <STRONG>attrs);</STRONG>
  59        <STRONG>int</STRONG> <STRONG>wattroff(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>attrs);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>attron(int</STRONG> <STRONG>attrs);</STRONG>
  61        <STRONG>int</STRONG> <STRONG>wattron(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>attrs);</STRONG>
  62        <STRONG>int</STRONG> <STRONG>attrset(int</STRONG> <STRONG>attrs);</STRONG>
  63        <STRONG>int</STRONG> <STRONG>wattrset(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>attrs);</STRONG>
  64        <STRONG>int</STRONG> <STRONG>color_set(short</STRONG> <STRONG>color_pair_number,</STRONG> <STRONG>void*</STRONG> <STRONG>opts);</STRONG>
  65        <STRONG>int</STRONG> <STRONG>wcolor_set(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>short</STRONG> <STRONG>color_pair_number,</STRONG>
  66              <STRONG>void*</STRONG> <STRONG>opts);</STRONG>
  67        <STRONG>int</STRONG> <STRONG>standend(void);</STRONG>
  68        <STRONG>int</STRONG> <STRONG>wstandend(WINDOW</STRONG> <STRONG>*win);</STRONG>
  69        <STRONG>int</STRONG> <STRONG>standout(void);</STRONG>
  70        <STRONG>int</STRONG> <STRONG>wstandout(WINDOW</STRONG> <STRONG>*win);</STRONG>
  71        <STRONG>int</STRONG> <STRONG>attr_get(attr_t</STRONG> <STRONG>*attrs,</STRONG> <STRONG>short</STRONG> <STRONG>*pair,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
  72        <STRONG>int</STRONG> <STRONG>wattr_get(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>attr_t</STRONG> <STRONG>*attrs,</STRONG> <STRONG>short</STRONG> <STRONG>*pair,</STRONG>
  73               <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
  74        <STRONG>int</STRONG> <STRONG>attr_off(attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
  75        <STRONG>int</STRONG> <STRONG>wattr_off(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
  76        <STRONG>int</STRONG> <STRONG>attr_on(attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
  77        <STRONG>int</STRONG> <STRONG>wattr_on(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
  78        <STRONG>int</STRONG> <STRONG>attr_set(attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>short</STRONG> <STRONG>pair,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
  79        <STRONG>int</STRONG> <STRONG>wattr_set(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>short</STRONG> <STRONG>pair,</STRONG>  <STRONG>void</STRONG>
  80        <STRONG>*opts);</STRONG>
  81        <STRONG>int</STRONG> <STRONG>chgat(int</STRONG> <STRONG>n,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attr,</STRONG> <STRONG>short</STRONG> <STRONG>color,</STRONG>
  82              <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*opts)</STRONG>
  83        <STRONG>int</STRONG> <STRONG>wchgat(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>n,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attr,</STRONG>
  84              <STRONG>short</STRONG> <STRONG>color,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*opts)</STRONG>
  85        <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>
  86              <STRONG>short</STRONG> <STRONG>color,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*opts)</STRONG>
  87        <STRONG>int</STRONG> <STRONG>mvwchgat(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>int</STRONG> <STRONG>n,</STRONG>
  88              <STRONG>attr_t</STRONG> <STRONG>attr,</STRONG> <STRONG>short</STRONG> <STRONG>color,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*opts)</STRONG>
  89
  90
  91 </PRE>
  92 <H2>DESCRIPTION</H2><PRE>
  93        These  routines  manipulate  the current attributes of the
  94        named window.  The current attributes of a window apply to
  95        all  characters that are written into the window with <STRONG>wad-</STRONG>
  96        <STRONG>dch</STRONG>, <STRONG>waddstr</STRONG> and <STRONG>wprintw</STRONG>.  Attributes are  a  property  of
  97        the  character,  and  move  with the character through any
  98        scrolling and insert/delete line/character operations.  To
  99        the  extent  possible,  they  are displayed as appropriate
 100        modifications to the graphic rendition of  characters  put
 101        on the screen.
 102
 103        The  routine  <STRONG>attrset</STRONG>  sets  the current attributes of the
 104        given window to <EM>attrs</EM>.  The routine <STRONG>attroff</STRONG> turns off  the
 105        named  attributes  without turning any other attributes on
 106        or off.  The routine <STRONG>attron</STRONG> turns on the named  attributes
 107        without affecting any others.  The routine <STRONG>standout</STRONG> is the
 108        same as <STRONG>attron(A_STANDOUT)</STRONG>.  The routine <STRONG>standend</STRONG>  is  the
 109        same as <STRONG>attrset(A_NORMAL)</STRONG> or <STRONG>attrset(0)</STRONG>, that is, it turns
 110        off all attributes.
 111
 112        The  <STRONG>attrset</STRONG>  and  related  routines  do  not  affect  the
 113        attributes  used when erasing portions of the window.  See
 114        <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG> for functions which  modify  the  attributes
 115        used for erasing and clearing.
 116
 117        The  routine <STRONG>color_set</STRONG> sets the current color of the given
 118        window to the foreground/background combination  described
 119        by  the  color_pair_number. The parameter opts is reserved
 120        for future use, applications must supply a null pointer.
 121
 122        The routine <STRONG>wattr_get</STRONG> returns the  current  attribute  and
 123        color pair for the given window; <STRONG>attr_get</STRONG> returns the cur-
 124        rent attribute and color pair for <STRONG>stdscr</STRONG>.   The  remaining
 125        <STRONG>attr_</STRONG>*  functions  operate  exactly like the corresponding
 126        <STRONG>attr</STRONG>* functions, except that they take arguments  of  type
 127        <STRONG>attr_t</STRONG> rather than <STRONG>int</STRONG>.
 128
 129        The routine <STRONG>chgat</STRONG> changes the attributes of a given number
 130        of characters starting at the current cursor  location  of
 131        <STRONG>stdscr</STRONG>.   It  does not update the cursor and does not per-
 132        form wrapping.  A character count of -1  or  greater  than
 133        the  remaining window width means to change attributes all
 134        the way to the end of the current line.  The <STRONG>wchgat</STRONG>  func-
 135        tion generalizes this to any window; the <STRONG>mvwchgat</STRONG> function
 136        does a cursor move before acting.  In these functions, the
 137        color  argument  is  a  color-pair  index (as in the first
 138        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>
 139        argument  is  not  presently used, but is reserved for the
 140        future (leave it <STRONG>NULL</STRONG>).  Note that changing the attributes
 141        does  not  imply that a subsequent <STRONG>refresh</STRONG> will update the
 142        screen to match, since the character values are not  modi-
 143        fied.   Use  <STRONG>touchwin</STRONG>  to  force  the  screen to match the
 144        updated attributes.
 145
 146    <STRONG>Attributes</STRONG>
 147        The following video attributes, defined in <STRONG>&lt;curses.h&gt;</STRONG>, can
 148        be passed to the routines <STRONG>attron</STRONG>, <STRONG>attroff</STRONG>, and <STRONG>attrset</STRONG>, or
 149        OR'ed with the characters passed to <STRONG>addch</STRONG>.
 150
 151         <STRONG>A_NORMAL</STRONG>        Normal display (no highlight)
 152         <STRONG>A_STANDOUT</STRONG>      Best highlighting mode of the terminal.
 153         <STRONG>A_UNDERLINE</STRONG>     Underlining
 154         <STRONG>A_REVERSE</STRONG>       Reverse video
 155         <STRONG>A_BLINK</STRONG>         Blinking
 156         <STRONG>A_DIM</STRONG>           Half bright
 157
 158         <STRONG>A_BOLD</STRONG>          Extra bright or bold
 159         <STRONG>A_PROTECT</STRONG>       Protected mode
 160         <STRONG>A_INVIS</STRONG>         Invisible or blank mode
 161         <STRONG>A_ALTCHARSET</STRONG>    Alternate character set
 162         <STRONG>A_CHARTEXT</STRONG>      Bit-mask to extract a character
 163         <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG>   Color-pair number <EM>n</EM>
 164
 165        The following macro is the reverse of <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG>:
 166
 167        <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM>) Returns the pair number associated
 168                           with the <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> attribute.
 169
 170        The return values of many of these routines are not  mean-
 171        ingful (they are implemented as macro-expanded assignments
 172        and simply return their argument).  The SVr4  manual  page
 173        claims (falsely) that these routines always return <STRONG>1</STRONG>.
 174
 175
 176 </PRE>
 177 <H2>NOTES</H2><PRE>
 178        Note  that  <STRONG>attroff</STRONG>,  <STRONG>wattroff</STRONG>,  <STRONG>attron</STRONG>, <STRONG>wattron</STRONG>, <STRONG>attrset</STRONG>,
 179        <STRONG>wattrset</STRONG>, <STRONG>standend</STRONG> and <STRONG>standout</STRONG> may be macros.
 180
 181
 182 </PRE>
 183 <H2>PORTABILITY</H2><PRE>
 184        All these functions are supported in the XSI Curses  stan-
 185        dard,  Issue  4.   The standard defined the dedicated type
 186        for highlights, <STRONG>attr_t</STRONG>,  which  is  not  defined  in  SVr4
 187        curses. The functions taking <STRONG>attr_t</STRONG> arguments are not sup-
 188        ported under SVr4.
 189
 190        The XSI Curses standard states  that  whether  the  tradi-
 191        tional  functions  <STRONG>attron</STRONG>/<STRONG>attroff</STRONG>/<STRONG>attrset</STRONG>  can  manipulate
 192        attributes other than <STRONG>A_BLINK</STRONG>, <STRONG>A_BOLD</STRONG>,  <STRONG>A_DIM</STRONG>,  <STRONG>A_REVERSE</STRONG>,
 193        <STRONG>A_STANDOUT</STRONG>,  or  <STRONG>A_UNDERLINE</STRONG> is "unspecified".  Under this
 194        implementation as well as  SVr4  curses,  these  functions
 195        correctly  manipulate  all other highlights (specifically,
 196        <STRONG>A_ALTCHARSET</STRONG>, <STRONG>A_PROTECT</STRONG>, and <STRONG>A_INVIS</STRONG>).
 197
 198        XSI Curses added the new entry points, <STRONG>attr_get</STRONG>,  <STRONG>attr_on</STRONG>,
 199        <STRONG>attr_off</STRONG>,   <STRONG>attr_set</STRONG>,   <STRONG>wattr_on</STRONG>,   <STRONG>wattr_off</STRONG>,  <STRONG>wattr_get</STRONG>,
 200        <STRONG>wattr_set</STRONG>.  These are intended to work with a  new  series
 201        of highlight macros prefixed with <STRONG>WA_</STRONG>.
 202
 203         <STRONG>WA_NORMAL</STRONG>       Normal display (no highlight)
 204         <STRONG>WA_STANDOUT</STRONG>     Best highlighting mode of the terminal.
 205         <STRONG>WA_UNDERLINE</STRONG>    Underlining
 206         <STRONG>WA_REVERSE</STRONG>      Reverse video
 207         <STRONG>WA_BLINK</STRONG>        Blinking
 208         <STRONG>WA_DIM</STRONG>          Half bright
 209         <STRONG>WA_BOLD</STRONG>         Extra bright or bold
 210         <STRONG>WA_ALTCHARSET</STRONG>   Alternate character set
 211
 212        The XSI curses standard specifies that each pair of corre-
 213        sponding <STRONG>A_</STRONG> and <STRONG>WA_</STRONG>-using functions operates on  the  same
 214        current-highlight information.
 215
 216        The XSI standard extended conformance level adds new high-
 217        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>
 218        <STRONG>TICAL</STRONG>  (and  corresponding <STRONG>WA_</STRONG> macros for each) which this
 219        curses does not yet support.
 220
 221
 222 </PRE>
 223 <H2>SEE ALSO</H2><PRE>
 224        <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>,
 225        <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>, <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272 </PRE>
 273 <HR>
 274 <ADDRESS>
 275 Man(1) output converted with
 276 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 277 </ADDRESS>
 278 </BODY>
 279 </HTML>