diff options
Diffstat (limited to 'libX11/specs/libX11/CH05')
| -rw-r--r-- | libX11/specs/libX11/CH05 | 518 |
1 files changed, 0 insertions, 518 deletions
diff --git a/libX11/specs/libX11/CH05 b/libX11/specs/libX11/CH05 deleted file mode 100644 index 6ea218378..000000000 --- a/libX11/specs/libX11/CH05 +++ /dev/null @@ -1,518 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 5\fP\s-1 - -\s+1\fBPixmap and Cursor Functions\fP\s-1 -.sp 2 -.nr H1 5 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 5: Pixmap and Cursor Functions -.XE -Once you have connected to an X server, -you can use the Xlib functions to: -.IP \(bu 5 -Create and free pixmaps -.IP \(bu 5 -Create, recolor, and free cursors -.NH 2 -Creating and Freeing Pixmaps -.XS -\*(SN Creating and Freeing Pixmaps -.XE -.LP -Pixmaps can only be used on the screen on which they were created. -Pixmaps are off-screen resources that are used for various operations, -such as defining cursors as tiling patterns -or as the source for certain raster operations. -Most graphics requests can operate either on a window or on a pixmap. -A bitmap is a single bit-plane pixmap. -.LP -.sp -To create a pixmap of a given size, use -.PN XCreatePixmap . -.IN "XCreatePixmap" "" "@DEF@" -.sM -.FD 0 -Pixmap XCreatePixmap\^(\^\fIdisplay\fP, \fId\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdepth\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - unsigned int \fIdepth\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fId\fP 1i -Specifies which screen the pixmap is created on. -.ds Wh , which define the dimensions of the pixmap -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.IP \fIdepth\fP 1i -Specifies the depth of the pixmap. -.LP -.eM -The -.PN XCreatePixmap -function creates a pixmap of the width, height, and depth you specified -and returns a pixmap ID that identifies it. -It is valid to pass an -.PN InputOnly -window to the drawable argument. -The width and height arguments must be nonzero, -or a -.PN BadValue -error results. -The depth argument must be one of the depths supported by the screen -of the specified drawable, -or a -.PN BadValue -error results. -.LP -The server uses the specified drawable to determine on which screen -to create the pixmap. -The pixmap can be used only on this screen -and only with other drawables of the same depth (see -.PN XCopyPlane -for an exception to this rule). -The initial contents of the pixmap are undefined. -.LP -.PN XCreatePixmap -can generate -.PN BadAlloc , -.PN BadDrawable , -and -.PN BadValue -errors. -.LP -.sp -To free all storage associated with a specified pixmap, use -.PN XFreePixmap . -.IN "XFreePixmap" "" "@DEF@" -.sM -.FD 0 -XFreePixmap\^(\^\fIdisplay\fP, \fIpixmap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Pixmap \fIpixmap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIpixmap\fP 1i -Specifies the pixmap. -.LP -.eM -The -.PN XFreePixmap -function first deletes the association between the pixmap ID and the pixmap. -Then, the X server frees the pixmap storage when there are no references to it. -The pixmap should never be referenced again. -.LP -.PN XFreePixmap -can generate a -.PN BadPixmap -error. -.NH 2 -Creating, Recoloring, and Freeing Cursors -.XS -\*(SN Creating, Recoloring, and Freeing Cursors -.XE -.LP -Each window can have a different cursor defined for it. -Whenever the pointer is in a visible window, -it is set to the cursor defined for that window. -If no cursor was defined for that window, -the cursor is the one defined for the parent window. -.LP -From X's perspective, -a cursor consists of a cursor source, mask, colors, and a hotspot. -The mask pixmap determines the shape of the cursor and must be a depth -of one. -The source pixmap must have a depth of one, -and the colors determine the colors of the source. -The hotspot defines the point on the cursor that is reported -when a pointer event occurs. -There may be limitations imposed by the hardware on -cursors as to size and whether a mask is implemented. -.IN "XQueryBestCursor" -.PN XQueryBestCursor -can be used to find out what sizes are possible. -There is a standard font for creating cursors, but -Xlib provides functions that you can use to create cursors -from an arbitrary font or from bitmaps. -.LP -.sp -To create a cursor from the standard cursor font, use -.PN XCreateFontCursor . -.IN "XCreateFontCursor" "" "@DEF@" -.sM -.FD 0 -#include <X11/cursorfont.h> -.sp 6p -Cursor XCreateFontCursor\^(\^\fIdisplay\fP, \fIshape\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - unsigned int \fIshape\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIshape\fP 1i -Specifies the shape of the cursor. -.LP -.eM -X provides a set of standard cursor shapes in a special font named -cursor. -Applications are encouraged to use this interface for their cursors -because the font can be customized for the individual display type. -The shape argument specifies which glyph of the standard fonts -to use. -.LP -The hotspot comes from the information stored in the cursor font. -The initial colors of a cursor are a black foreground and a white -background (see -.PN XRecolorCursor ). -For further information about cursor shapes, -see appendix B. -.LP -.PN XCreateFontCursor -can generate -.PN BadAlloc -and -.PN BadValue -errors. -.LP -.sp -To create a cursor from font glyphs, use -.PN XCreateGlyphCursor . -.IN "XCreateGlyphCursor" "" "@DEF@" -.sM -.FD 0 -Cursor XCreateGlyphCursor\^(\^\fIdisplay\fP, \fIsource_font\fP\^, \fImask_font\fP\^, \fIsource_char\fP\^, \fImask_char\fP\^, -.br - \fIforeground_color\fP\^, \fIbackground_color\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Font \fIsource_font\fP\^, \fImask_font\fP\^; -.br - unsigned int \fIsource_char\fP\^, \fImask_char\fP\^; -.br - XColor *\fIforeground_color\fP\^; -.br - XColor *\fIbackground_color\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIsource_font\fP 1i -Specifies the font for the source glyph. -.IP \fImask_font\fP 1i -Specifies the font for the mask glyph or -.PN None . -.IP \fIsource_char\fP 1i -Specifies the character glyph for the source. -.IP \fImask_char\fP 1i -Specifies the glyph character for the mask. -.IP \fIforeground_color\fP 1i -Specifies the RGB values for the foreground of the source. -.IP \fIbackground_color\fP 1i -Specifies the RGB values for the background of the source. -.LP -.eM -The -.PN XCreateGlyphCursor -function is similar to -.PN XCreatePixmapCursor -except that the source and mask bitmaps are obtained from the specified -font glyphs. -The source_char must be a defined glyph in source_font, -or a -.PN BadValue -error results. -If mask_font is given, -mask_char must be a defined glyph in mask_font, -or a -.PN BadValue -error results. -The mask_font and character are optional. -The origins of the source_char and mask_char (if defined) glyphs are -positioned coincidently and define the hotspot. -The source_char and mask_char need not have the same bounding box metrics, -and there is no restriction on the placement of the hotspot relative to the bounding -boxes. -If no mask_char is given, all pixels of the source are displayed. -You can free the fonts immediately by calling -.PN XFreeFont -if no further explicit references to them are to be made. -.LP -For 2-byte matrix fonts, -the 16-bit value should be formed with the byte1 -member in the most significant byte and the byte2 member in the -least significant byte. -.LP -.PN XCreateGlyphCursor -can generate -.PN BadAlloc , -.PN BadFont , -and -.PN BadValue -errors. -.LP -.sp -To create a cursor from two bitmaps, -use -.PN XCreatePixmapCursor . -.IN "XCreatePixmapCursor" "" "@DEF@" -.sM -.FD 0 -Cursor XCreatePixmapCursor\^(\^\fIdisplay\fP, \fIsource\fP\^, \fImask\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^, \fIx\fP\^, \fIy\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Pixmap \fIsource\fP\^; -.br - Pixmap \fImask\fP\^; -.br - XColor *\fIforeground_color\fP\^; -.br - XColor *\fIbackground_color\fP\^; -.br - unsigned int \fIx\fP\^, \fIy\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIsource\fP 1i -Specifies the shape of the source cursor. -.\" *** JIM: NEED TO CHECK THIS. *** -.IP \fImask\fP 1i -Specifies the cursor's source bits to be displayed or -.PN None . -.IP \fIforeground_color\fP 1i -Specifies the RGB values for the foreground of the source. -.IP \fIbackground_color\fP 1i -Specifies the RGB values for the background of the source. -.ds Xy , which indicate the hotspot relative to the source's origin -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.LP -.eM -The -.PN XCreatePixmapCursor -function creates a cursor and returns the cursor ID associated with it. -The foreground and background RGB values must be specified using -foreground_color and background_color, -even if the X server only has a -.PN StaticGray -or -.PN GrayScale -screen. -The foreground color is used for the pixels set to 1 in the -source, and the background color is used for the pixels set to 0. -Both source and mask, if specified, must have depth one (or a -.PN BadMatch -error results) but can have any root. -The mask argument defines the shape of the cursor. -The pixels set to 1 in the mask define which source pixels are displayed, -and the pixels set to 0 define which pixels are ignored. -If no mask is given, -all pixels of the source are displayed. -The mask, if present, must be the same size as the pixmap defined by the -source argument, or a -.PN BadMatch -error results. -The hotspot must be a point within the source, -or a -.PN BadMatch -error results. -.LP -The components of the cursor can be transformed arbitrarily to meet -display limitations. -The pixmaps can be freed immediately if no further explicit references -to them are to be made. -Subsequent drawing in the source or mask pixmap has an undefined effect on the -cursor. -The X server might or might not make a copy of the pixmap. -.LP -.PN XCreatePixmapCursor -can generate -.PN BadAlloc -and -.PN BadPixmap -errors. -.LP -.sp -To determine useful cursor sizes, use -.PN XQueryBestCursor . -.IN "XQueryBestCursor" "" "@DEF@" -.sM -.FD 0 -Status XQueryBestCursor\^(\^\fIdisplay\fP, \fId\fP, \fIwidth\fP\^, \fIheight\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Drawable \fId\fP\^; -.br - unsigned int \fIwidth\fP\^, \fIheight\fP\^; -.br - unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Dr , which indicates the screen -.IP \fId\fP 1i -Specifies the drawable\*(Dr. -.ds Wh \ of the cursor that you want the size information for -.IP \fIwidth\fP 1i -.br -.ns -.IP \fIheight\fP 1i -Specify the width and height\*(Wh. -.IP \fIwidth_return\fP 1i -.br -.ns -.IP \fIheight_return\fP 1i -Return the best width and height that is closest to the specified width -and height. -.LP -.eM -Some displays allow larger cursors than other displays. -The -.PN XQueryBestCursor -function provides a way to find out what size cursors are actually -possible on the display. -.IN "Cursor" "limitations" -It returns the largest size that can be displayed. -Applications should be prepared to use smaller cursors on displays that -cannot support large ones. -.LP -.PN XQueryBestCursor -can generate a -.PN BadDrawable -error. -.LP -.sp -To change the color of a given cursor, use -.PN XRecolorCursor . -.IN "XRecolorCursor" "" "@DEF@" -.sM -.FD 0 -XRecolorCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Cursor \fIcursor\fP\^; -.br - XColor *\fIforeground_color\fP\^, *\fIbackground_color\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcursor\fP 1i -Specifies the cursor. -.IP \fIforeground_color\fP 1i -Specifies the RGB values for the foreground of the source. -.IP \fIbackground_color\fP 1i -Specifies the RGB values for the background of the source. -.LP -.eM -The -.PN XRecolorCursor -function changes the color of the specified cursor, and -if the cursor is being displayed on a screen, -the change is visible immediately. -The pixel members of the -.PN XColor -structures are ignored; only the RGB values are used. -.LP -.PN XRecolorCursor -can generate a -.PN BadCursor -error. -.LP -.sp -To free (destroy) a given cursor, use -.PN XFreeCursor . -.IN "XFreeCursor" "" "@DEF@" -.sM -.FD 0 -XFreeCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Cursor \fIcursor\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcursor\fP 1i -Specifies the cursor. -.LP -.eM -The -.PN XFreeCursor -function deletes the association between the cursor resource ID -and the specified cursor. -The cursor storage is freed when no other resource references it. -The specified cursor ID should not be referred to again. -.LP -.PN XFreeCursor -can generate a -.PN BadCursor -error. -.bp |