lib/libcurses/curses_background.3

   1 .\"     $NetBSD: curses_background.3,v 1.5 2006/01/15 11:45:54 wiz Exp $
   2 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to The NetBSD Foundation
   6 .\" by Julian Coleman.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  17 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  18 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  20 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26 .\" POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .Dd January 15, 2006
  29 .Dt CURSES_BACKGROUND 3
  30 .Os
  31 .Sh NAME
  32 .Nm curses_background ,
  33 .Nm bkgd ,
  34 .Nm bkgdset ,
  35 .Nm getbkgd ,
  36 .Nm wbkgd ,
  37 .Nm wbkgdset
  38 .Nd curses attribute manipulation routines
  39 .Sh LIBRARY
  40 .Lb libcurses
  41 .Sh SYNOPSIS
  42 .In curses.h
  43 .Ft int
  44 .Fn bkgd chtype
  45 .Ft int
  46 .Fn bkgdset chtype
  47 .Ft chtype
  48 .Fn getbkgd "WINDOW *"
  49 .Ft int
  50 .Fn wbkgd chtype
  51 .Ft int
  52 .Fn wbkgdset chtype
  53 .Sh DESCRIPTION
  54 These functions manipulate the background attributes on
  55 .Dv stdscr
  56 or on the specified window.
  57 .Pp
  58 The function
  59 .Fn wbkgdset win ch
  60 sets the background attributes of the specified window
  61 .Fa win
  62 to
  63 .Fa ch .
  64 .Pp
  65 When the background attributes are set on a window, characters are added to
  66 the window with the logical
  67 .Em OR
  68 of the background attributes and the character's attributes.
  69 If both the background attribute and the character attribute contain color,
  70 the color of the character attribute is rendered.
  71 If the background attribute contains a non-space character, then this
  72 character is added where the foreground character is a space character.
  73 .Pp
  74 Note that subwindows created from
  75 .Fa win
  76 inherit the background attributes of
  77 .Fa win .
  78 .Pp
  79 The function
  80 .Fn wbkgd win ch
  81 sets the background attributes of the specified window
  82 .Fa win
  83 to
  84 .Fa ch
  85 and also sets the rendition of every character position on that window,
  86 as if the characters had been newly added to
  87 .Fa win .
  88 The rendition of characters on subwindows of
  89 .Fa win
  90 is also set to
  91 .Fa ch .
  92 .Pp
  93 The functions
  94 .Fn bkgdset ch
  95 and
  96 .Fn bkgd ch
  97 are equivalent to
  98 .Fn wbkgdset stdscr ch
  99 and
 100 .Fn wbkgd stdscr ch ,
 101 respectively.
 102 .Pp
 103 The function
 104 .Fn getbkgd win
 105 returns the background attributes for the window
 106 .Fa win .
 107 .Sh RETURN VALUES
 108 The functions
 109 .Fn wbkgdset
 110 and
 111 .Fn wbkgd
 112 return OK on success and ERR on failure.
 113 .Sh SEE ALSO
 114 .Xr curses_attributes 3 ,
 115 .Xr curses_color 3 ,
 116 .Xr curses_window 3
 117 .Sh STANDARDS
 118 The
 119 .Nx
 120 Curses library complies with the X/Open Curses specification, part of the
 121 Single Unix Specification.
 122 .Sh HISTORY
 123 These functions first appeared in
 124 .Nx 1.6 .