diff options
Diffstat (limited to 'libX11/specs/libX11/CH05')
| -rw-r--r-- | libX11/specs/libX11/CH05 | 518 |
1 files changed, 518 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH05 b/libX11/specs/libX11/CH05 new file mode 100644 index 000000000..6ea218378 --- /dev/null +++ b/libX11/specs/libX11/CH05 @@ -0,0 +1,518 @@ +.\" 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 |