home *** CD-ROM | disk | FTP | other *** search
- \&
- .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
- .RE
- .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,
- for example, 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@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XCrePmap.f,v 1.1 88/02/26 09:59:10 mento Exp $
- 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
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: d_crepix.a,v 1.1 88/02/26 10:06:13 mento Exp $
- .IP \fId\fP 1i
- Specifies which screen the pixmap is created on.
- .ds Wh , which define the dimensions of the pixmap
- .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
- .IP \fIwidth\fP 1i
- .br
- .ns
- .IP \fIheight\fP 1i
- Specify the width and height\*(Wh.
- .\" $Header: depth1.a,v 1.3 88/05/09 09:53:55 mento Exp $
- .IP \fIdepth\fP 1i
- Specifies the depth of the pixmap.
- .\" End marker code here
- .LP
- .\" $Header: XCrePmap.d,v 1.5 88/08/18 07:41:46 mento Exp $
- 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@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XFreePixmap.f,v 1.1 88/02/26 10:00:19 mento Exp $
- XFreePixmap\^(\^\fIdisplay\fP, \fIpixmap\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Pixmap \fIpixmap\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fIpixmap\fP 1i
- Specifies the pixmap.
- .\" End marker code here
- .LP
- .\" $Header: XFreePixmap.d,v 1.2 88/05/09 09:56:57 mento Exp $
- 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@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XCursor.f,v 1.1 88/02/26 09:59:17 mento Exp $
- #include <X11/cursorfont.h>
- .sp 6p
- Cursor XCreateFontCursor\^(\^\fIdisplay\fP, \fIshape\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- unsigned int \fIshape\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fIshape\fP 1i
- Specifies the shape of the cursor.
- .\" End marker code here
- .LP
- .\" $Header: XCursor.d,v 1.2 88/06/11 07:49:47 mento Exp $
- 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@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XCreateGlCur.f,v 1.1 88/02/26 09:59:16 mento Exp $
- 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
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: sfont.a,v 1.1 88/02/26 10:31:12 mento Exp $
- .IP \fIsource_font\fP 1i
- Specifies the font for the source glyph.
- .\" $Header: mfont.a,v 1.2 88/05/13 13:01:38 mento Exp $
- .IP \fImask_font\fP 1i
- Specifies the font for the mask glyph or
- .PN None .
- .\" $Header: schar.a,v 1.1 88/02/26 10:31:06 mento Exp $
- .IP \fIsource_char\fP 1i
- Specifies the character glyph for the source.
- .\" $Header: mchar.a,v 1.1 88/02/26 10:28:52 mento Exp $
- .IP \fImask_char\fP 1i
- Specifies the glyph character for the mask.
- .\" $Header: scolor.a,v 1.2 88/05/13 12:51:29 mento Exp $
- .IP \fIforeground_color\fP 1i
- Specifies the RGB values for the foreground of the source.
- .\" $Header: bcolor.a,v 1.2 88/05/13 12:53:45 mento Exp $
- .IP \fIbackground_color\fP 1i
- Specifies the RGB values for the background of the source.
- .\" End marker code here
- .LP
- .\" $Header: XCreateGlCur.d,v 1.4 88/06/11 07:49:41 mento Exp $
- 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@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XCreCursor.f,v 1.1 88/02/26 09:59:09 mento Exp $
- 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
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: source.a,v 1.1 88/02/26 10:31:17 mento Exp $
- .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 .
- .\" $Header: scolor.a,v 1.2 88/05/13 12:51:29 mento Exp $
- .IP \fIforeground_color\fP 1i
- Specifies the RGB values for the foreground of the source.
- .\" $Header: bcolor.a,v 1.2 88/05/13 12:53:45 mento Exp $
- .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
- .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
- .IP \fIx\fP 1i
- .br
- .ns
- .IP \fIy\fP 1i
- Specify the x and y coordinates\*(Xy.
- .\" End marker code here
- .LP
- .\" $Header: XCreCursor.d,v 1.2 88/06/11 07:49:29 mento Exp $
- 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@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XQryCrsrSh.f,v 1.1 88/02/26 10:02:06 mento Exp $
- 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
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .ds Dr , which indicates the screen
- .\" $Header: d_gen.a,v 1.2 88/08/04 11:09:21 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable\*(Dr.
- .ds Wh \ of the cursor that you want the size information for
- .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
- .IP \fIwidth\fP 1i
- .br
- .ns
- .IP \fIheight\fP 1i
- Specify the width and height\*(Wh.
- .\" $Header: rwidtheight2.a,v 1.3 88/05/13 13:09:44 mento Exp $
- .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.
- .\" End marker code here
- .LP
- .\" $Header: XQryCrsrSh.d,v 1.2 88/06/11 07:52:32 mento Exp $
- 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@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XRecolorCurs.f,v 1.1 88/02/26 10:02:35 mento Exp $
- 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
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: cursor.a,v 1.1 88/02/26 10:06:06 mento Exp $
- .IP \fIcursor\fP 1i
- Specifies the cursor.
- .\" $Header: scolor.a,v 1.2 88/05/13 12:51:29 mento Exp $
- .IP \fIforeground_color\fP 1i
- Specifies the RGB values for the foreground of the source.
- .\" $Header: bcolor.a,v 1.2 88/05/13 12:53:45 mento Exp $
- .IP \fIbackground_color\fP 1i
- Specifies the RGB values for the background of the source.
- .\" End marker code here
- .LP
- .\" $Header: XRecolorCurs.d,v 1.3 88/05/19 05:25:50 mento Exp $
- 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.
- Note that 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@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XFreeCursor.f,v 1.1 88/02/26 10:00:17 mento Exp $
- XFreeCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Cursor \fIcursor\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: cursor.a,v 1.1 88/02/26 10:06:06 mento Exp $
- .IP \fIcursor\fP 1i
- Specifies the cursor.
- .\" End marker code here
- .LP
- .\" $Header: XFreeCursor.d,v 1.2 88/06/11 07:50:46 mento Exp $
- 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
-