man/XCreateFontCursor.man

   1 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining
   4 .\" a copy of this software and associated documentation files (the
   5 .\" "Software"), to deal in the Software without restriction, including
   6 .\" without limitation the rights to use, copy, modify, merge, publish,
   7 .\" distribute, sublicense, and/or sell copies of the Software, and to
   8 .\" permit persons to whom the Software is furnished to do so, subject to
   9 .\" the following conditions:
  10 .\"
  11 .\" The above copyright notice and this permission notice shall be included
  12 .\" in all copies or substantial portions of the Software.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  15 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  17 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
  18 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  19 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  20 .\" OTHER DEALINGS IN THE SOFTWARE.
  21 .\"
  22 .\" Except as contained in this notice, the name of the X Consortium shall
  23 .\" not be used in advertising or otherwise to promote the sale, use or
  24 .\" other dealings in this Software without prior written authorization
  25 .\" from the X Consortium.
  26 .\"
  27 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
  28 .\" Digital Equipment Corporation
  29 .\"
  30 .\" Portions Copyright \(co 1990, 1991 by
  31 .\" Tektronix, Inc.
  32 .\"
  33 .\" Permission to use, copy, modify and distribute this documentation for
  34 .\" any purpose and without fee is hereby granted, provided that the above
  35 .\" copyright notice appears in all copies and that both that copyright notice
  36 .\" and this permission notice appear in all copies, and that the names of
  37 .\" Digital and Tektronix not be used in in advertising or publicity pertaining
  38 .\" to this documentation without specific, written prior permission.
  39 .\" Digital and Tektronix makes no representations about the suitability
  40 .\" of this documentation for any purpose.
  41 .\" It is provided ``as is'' without express or implied warranty.
  42 .\"
  43 .\"
  44 .ds xT X Toolkit Intrinsics \- C Language Interface
  45 .ds xW Athena X Widgets \- C Language X Toolkit Interface
  46 .ds xL Xlib \- C Language X Interface
  47 .ds xC Inter-Client Communication Conventions Manual
  48 .na
  49 .de Ds
  50 .nf
  51 .\\$1D \\$2 \\$1
  52 .ft CW
  53 .\".ps \\n(PS
  54 .\".if \\n(VS>=40 .vs \\n(VSu
  55 .\".if \\n(VS<=39 .vs \\n(VSp
  56 ..
  57 .de De
  58 .ce 0
  59 .if \\n(BD .DF
  60 .nr BD 0
  61 .in \\n(OIu
  62 .if \\n(TM .ls 2
  63 .sp \\n(DDu
  64 .fi
  65 ..
  66 .de IN          \" send an index entry to the stderr
  67 ..
  68 .de Pn
  69 .ie t \\$1\fB\^\\$2\^\fR\\$3
  70 .el \\$1\fI\^\\$2\^\fP\\$3
  71 ..
  72 .de ZN
  73 .ie t \fB\^\\$1\^\fR\\$2
  74 .el \fI\^\\$1\^\fP\\$2
  75 ..
  76 .de hN
  77 .ie t <\fB\\$1\fR>\\$2
  78 .el <\fI\\$1\fP>\\$2
  79 ..
  80 .ny0
  81 .TH XCreateFontCursor __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
  82 .SH NAME
  83 XCreateFontCursor, XCreatePixmapCursor, XCreateGlyphCursor \- create cursors
  84 .SH SYNTAX
  85 \&#include <X11/cursorfont.h>
  86 .HP
  87 Cursor XCreateFontCursor\^(\^Display *\fIdisplay\fP\^, unsigned int
  88 \fIshape\fP\^);
  89 .HP
  90 Cursor XCreatePixmapCursor\^(\^Display *\fIdisplay\fP\^, Pixmap
  91 \fIsource\fP\^, Pixmap \fImask\fP\^, XColor *\fIforeground_color\fP\^, XColor
  92 *\fIbackground_color\fP\^, unsigned int \fIx\fP\^, unsigned int \fIy\fP\^);
  93 .HP
  94 Cursor XCreateGlyphCursor\^(\^Display *\fIdisplay\fP\^, Font
  95 \fIsource_font\fP\^, Font \fImask_font\fP\^, unsigned int \fIsource_char\fP\^,
  96 unsigned int \fImask_char\fP\^, XColor *\fIforeground_color\fP\^, XColor
  97 *\fIbackground_color\fP\^);
  98 .SH ARGUMENTS
  99 .IP \fIbackground_color\fP 1i
 100 Specifies the RGB values for the background of the source.
 101 .IP \fIdisplay\fP 1i
 102 Specifies the connection to the X server.
 103 .IP \fIforeground_color\fP 1i
 104 Specifies the RGB values for the foreground of the source.
 105 .IP \fImask\fP 1i
 106 Specifies the cursor's source bits to be displayed or
 107 .ZN None .
 108 .IP \fImask_char\fP 1i
 109 Specifies the glyph character for the mask.
 110 .IP \fImask_font\fP 1i
 111 Specifies the font for the mask glyph or
 112 .ZN None .
 113 .IP \fIshape\fP 1i
 114 Specifies the shape of the cursor.
 115 .IP \fIsource\fP 1i
 116 Specifies the shape of the source cursor.
 117 .\" *** JIM: NEED TO CHECK THIS. ***
 118 .IP \fIsource_char\fP 1i
 119 Specifies the character glyph for the source.
 120 .IP \fIsource_font\fP 1i
 121 Specifies the font for the source glyph.
 122 .ds Xy , which indicate the hotspot relative to the source's origin
 123 .IP \fIx\fP 1i
 124 .br
 125 .ns
 126 .IP \fIy\fP 1i
 127 Specify the x and y coordinates\*(Xy.
 128 .SH DESCRIPTION
 129 X provides a set of standard cursor shapes in a special font named
 130 cursor.
 131 Applications are encouraged to use this interface for their cursors
 132 because the font can be customized for the individual display type.
 133 The shape argument specifies which glyph of the standard fonts
 134 to use.
 135 .LP
 136 The hotspot comes from the information stored in the cursor font.
 137 The initial colors of a cursor are a black foreground and a white
 138 background (see
 139 .ZN XRecolorCursor ).
 140 .LP
 141 .ZN XCreateFontCursor
 142 can generate
 143 .ZN BadAlloc
 144 and
 145 .ZN BadValue
 146 errors.
 147 .LP
 148 The
 149 .ZN XCreatePixmapCursor
 150 function creates a cursor and returns the cursor ID associated with it.
 151 The foreground and background RGB values must be specified using
 152 foreground_color and background_color,
 153 even if the X server only has a
 154 .ZN StaticGray
 155 or
 156 .ZN GrayScale
 157 screen.
 158 The foreground color is used for the pixels set to 1 in the
 159 source, and the background color is used for the pixels set to 0.
 160 Both source and mask, if specified, must have depth one (or a
 161 .ZN BadMatch
 162 error results) but can have any root.
 163 The mask argument defines the shape of the cursor.
 164 The pixels set to 1 in the mask define which source pixels are displayed,
 165 and the pixels set to 0 define which pixels are ignored.
 166 If no mask is given,
 167 all pixels of the source are displayed.
 168 The mask, if present, must be the same size as the pixmap defined by the
 169 source argument, or a
 170 .ZN BadMatch
 171 error results.
 172 The hotspot must be a point within the source,
 173 or a
 174 .ZN BadMatch
 175 error results.
 176 .LP
 177 The components of the cursor can be transformed arbitrarily to meet
 178 display limitations.
 179 The pixmaps can be freed immediately if no further explicit references
 180 to them are to be made.
 181 Subsequent drawing in the source or mask pixmap has an undefined effect on the
 182 cursor.
 183 The X server might or might not make a copy of the pixmap.
 184 .LP
 185 .ZN XCreatePixmapCursor
 186 can generate
 187 .ZN BadAlloc
 188 and
 189 .ZN BadPixmap
 190 errors.
 191 .LP
 192 The
 193 .ZN XCreateGlyphCursor
 194 function is similar to
 195 .ZN XCreatePixmapCursor
 196 except that the source and mask bitmaps are obtained from the specified
 197 font glyphs.
 198 The source_char must be a defined glyph in source_font,
 199 or a
 200 .ZN BadValue
 201 error results.
 202 If mask_font is given,
 203 mask_char must be a defined glyph in mask_font,
 204 or a
 205 .ZN BadValue
 206 error results.
 207 The mask_font and character are optional.
 208 The origins of the source_char and mask_char (if defined) glyphs are
 209 positioned coincidently and define the hotspot.
 210 The source_char and mask_char need not have the same bounding box metrics,
 211 and there is no restriction on the placement of the hotspot relative to the bounding
 212 boxes.
 213 If no mask_char is given, all pixels of the source are displayed.
 214 You can free the fonts immediately by calling
 215 .ZN XFreeFont
 216 if no further explicit references to them are to be made.
 217 .LP
 218 For 2-byte matrix fonts,
 219 the 16-bit value should be formed with the byte1
 220 member in the most significant byte and the byte2 member in the
 221 least significant byte.
 222 .LP
 223 .ZN XCreateGlyphCursor
 224 can generate
 225 .ZN BadAlloc ,
 226 .ZN BadFont ,
 227 and
 228 .ZN BadValue
 229 errors.
 230 .SH DIAGNOSTICS
 231 .TP 1i
 232 .ZN BadAlloc
 233 The server failed to allocate the requested resource or server memory.
 234 .TP 1i
 235 .ZN BadFont
 236 A value for a Font or GContext argument does not name a defined Font.
 237 .TP 1i
 238 .ZN BadMatch
 239 Some argument or pair of arguments has the correct type and range but fails
 240 to match in some other way required by the request.
 241 .TP 1i
 242 .ZN BadPixmap
 243 A value for a Pixmap argument does not name a defined Pixmap.
 244 .TP 1i
 245 .ZN BadValue
 246 Some numeric value falls outside the range of values accepted by the request.
 247 Unless a specific range is specified for an argument, the full range defined
 248 by the argument's type is accepted.  Any argument defined as a set of
 249 alternatives can generate this error.
 250 .SH "SEE ALSO"
 251 XDefineCursor(__libmansuffix__),
 252 XLoadFont(__libmansuffix__),
 253 XRecolorCursor(__libmansuffix__)
 254 .br
 255 \fI\*(xL\fP