home *** CD-ROM | disk | FTP | other *** search
Text File | 1991-08-27 | 101.1 KB | 3,638 lines |
- \&
- .sp 1
- .ce 3
- \s+1\fBChapter 8\fP\s-1
-
- \s+1\fBGraphics Functions\fP\s-1
- .sp 2
- .nr H1 8
- .nr H2 0
- .nr H3 0
- .nr H4 0
- .nr H5 0
- .na
- .LP
- .XS
- Chapter 8: Graphics Functions
- .XE
- Once you have established a connection to a display,
- you can use the Xlib graphics functions to:
- .IP \(bu 5
- Clear and copy areas
- .IP \(bu 5
- Draw points, lines, rectangles, and arcs
- .IP \(bu 5
- Fill areas
- .IP \(bu 5
- Manipulate fonts
- .IP \(bu 5
- Draw text
- .IP \(bu 5
- Transfer images between clients and the server
- .RE
- .LP
- If the same drawable and GC is used for each call,
- Xlib batches back-to-back calls to
- .PN XDrawPoint ,
- .PN XDrawLine ,
- .PN XDrawRectangle ,
- .PN XFillArc ,
- and
- .PN XFillRectangle .
- Note that this reduces the total number of requests sent to the server.
- .NH 2
- Clearing Areas
- .XS
- \*(SN Clearing Areas
- .XE
- .LP
- Xlib provides functions that you can use to clear an area or the entire window.
- Because pixmaps do not have defined backgrounds,
- they cannot be filled by using the functions described in this section.
- Instead, to accomplish an analogous operation on a pixmap,
- you should use
- .PN XFillRectangle ,
- which sets the pixmap to a known value.
- .LP
- .sp
- To clear a rectangular area of a given window, use
- .PN XClearArea .
- .IN "Areas" "clearing"
- .IN "Clearing" "areas"
- .IN "XClearArea" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XClearArea.f,v 1.1 88/02/26 09:58:46 mento Exp $
- XClearArea\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIexposures\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Window \fIw\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- unsigned int \fIwidth\fP\^, \fIheight\fP\^;
- .br
- Bool \fIexposures\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: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
- .IP \fIw\fP 1i
- Specifies the window.
- .ds Xy , which are relative to the origin of the window \
- and specify the upper-left corner of the rectangle
- .\" $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.
- .ds Wh , which are the dimensions of the rectangle
- .\" $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: exposures.a,v 1.2 88/05/13 07:34:33 mento Exp $
- .IP \fIexposures\fP 1i
- Specifies a Boolean value that indicates if
- .PN Expose
- events are to be generated.
- .\" End marker code here
- .LP
- .\" $Header: XClearArea.d,v 1.3 88/08/18 08:25:30 mento Exp $
- The
- .PN XClearArea
- function paints a rectangular area in the specified window according to the
- specified dimensions with the window's background pixel or pixmap.
- The subwindow-mode effectively is
- .PN ClipByChildren .
- If width is zero, it
- is replaced with the current width of the window minus x.
- If height is
- zero, it is replaced with the current height of the window minus y.
- If the window has a defined background tile,
- the rectangle clipped by any children is filled with this tile.
- If the window has
- background
- .PN None ,
- the contents of the window are not changed.
- In either
- case, if exposures is
- .PN True ,
- one or more
- .PN Expose
- events are generated for regions of the rectangle that are either visible or are
- being retained in a backing store.
- If you specify a window whose class is
- .PN InputOnly ,
- a
- .PN BadMatch
- error results.
- .LP
- .PN XClearArea
- can generate
- .PN BadMatch ,
- .PN BadValue ,
- and
- .PN BadWindow
- errors.
- .LP
- .sp
- To clear the entire area in a given window, use
- .PN XClearWindow .
- .IN "Window" "clearing"
- .IN "Clearing" "windows"
- .IN "XClearWindow" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XClear.f,v 1.1 88/02/26 09:58:45 mento Exp $
- XClearWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Window \fIw\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: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
- .IP \fIw\fP 1i
- Specifies the window.
- .\" End marker code here
- .LP
- .\" $Header: XClear.d,v 1.2 88/06/11 07:49:21 mento Exp $
- The
- .PN XClearWindow
- function clears the entire area in the specified window and is
- equivalent to
- .PN XClearArea
- (display, w, 0, 0, 0, 0,
- .PN False ).
- If the window has a defined background tile, the rectangle is tiled with a
- plane-mask of all ones and
- .PN GXcopy
- function.
- If the window has
- background
- .PN None ,
- the contents of the window are not changed.
- If you specify a window whose class is
- .PN InputOnly ,
- a
- .PN BadMatch
- error results.
- .LP
- .PN XClearWindow
- can generate
- .PN BadMatch
- and
- .PN BadWindow
- errors.
- .NH 2
- Copying Areas
- .XS
- \*(SN Copying Areas
- .XE
- .LP
- Xlib provides functions that you can use to copy an area or a bit plane.
- .LP
- .sp
- To copy an area between drawables of the same
- root and depth, use
- .PN XCopyArea .
- .IN "Areas" "copying"
- .IN "Copying" "areas"
- .IN "XCopyArea" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XCopyArea.f,v 1.1 88/02/26 09:58:59 mento Exp $
- XCopyArea\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdest_x\fP\^, \fIdest_y\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fIsrc\fP\^, \fIdest\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
- .br
- unsigned int \fIwidth\fP\^, \fIheight\fP\^;
- .br
- int \fIdest_x\fP\^, \fIdest_y\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: srcdest.a,v 1.1 88/02/26 10:31:20 mento Exp $
- .IP \fIsrc\fP 1i
- .br
- .ns
- .IP \fIdest\fP 1i
- Specify the source and destination rectangles to be combined.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: srcxy.a,v 1.3 88/05/13 07:40:32 mento Exp $
- .IP \fIsrc_x\fP 1i
- .br
- .ns
- .IP \fIsrc_y\fP 1i
- Specify the x and y coordinates,
- which are relative to the origin of the source rectangle
- and specify its upper-left corner.
- .ds Wh , which are the dimensions of both the source \
- and destination rectangles
- .\" $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.
- .ds Dx , which are relative to the origin of the destination rectangle \
- and specify its upper-left corner
- .\" $Header: dstxy_gen.a,v 1.2 88/08/04 11:09:55 mento Exp $
- .IP \fIdest_x\fP 1i
- .br
- .ns
- .IP \fIdest_y\fP 1i
- Specify the x and y coordinates\*(Dx.
- .\" End marker code here
- .LP
- .\" $Header: XCopyArea.d,v 1.4 88/09/08 19:12:40 mento Exp $
- The
- .PN XCopyArea
- function combines the specified rectangle of src with the specified rectangle
- of dest.
- The drawables must have the same root and depth,
- or a
- .PN BadMatch
- error results.
- .LP
- If regions of the source rectangle are obscured and have not been
- retained in backing store
- or if regions outside the boundaries of the source drawable are specified,
- those regions are not copied.
- Instead, the
- following occurs on all corresponding destination regions that are either
- visible or are retained in backing store.
- If the destination is a window with a background other than
- .PN None ,
- corresponding regions
- of the destination are tiled with that background
- (with plane-mask of all ones and
- .PN GXcopy
- function).
- Regardless of tiling or whether the destination is a window or a pixmap,
- if graphics-exposures is
- .PN True ,
- then
- .PN GraphicsExpose
- events for all corresponding destination regions are generated.
- If graphics-exposures is
- .PN True
- but no
- .PN GraphicsExpose
- events are generated, a
- .PN NoExpose
- event is generated.
- Note that by default graphics-exposures is
- .PN True
- in new GCs.
- .LP
- This function uses these GC components: function, plane-mask,
- subwindow-mode, graphics-exposures, clip-x-origin,
- clip-y-origin, and clip-mask.
- .LP
- .PN XCopyArea
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- and
- .PN BadMatch
- errors.
- .sp
- .LP
- To copy a single bit plane of a given drawable, use
- .PN XCopyPlane .
- .IN "Plane" "copying"
- .IN "Copying" "planes"
- .IN "XCopyPlane" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XCopyPlane.f,v 1.1 88/02/26 09:59:06 mento Exp $
- XCopyPlane\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIplane\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fIsrc\fP\^, \fIdest\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
- .br
- unsigned int \fIwidth\fP\^, \fIheight\fP\^;
- .br
- int \fIdest_x\fP\^, \fIdest_y\fP\^;
- .br
- unsigned long \fIplane\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: srcdest.a,v 1.1 88/02/26 10:31:20 mento Exp $
- .IP \fIsrc\fP 1i
- .br
- .ns
- .IP \fIdest\fP 1i
- Specify the source and destination rectangles to be combined.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: srcxy.a,v 1.3 88/05/13 07:40:32 mento Exp $
- .IP \fIsrc_x\fP 1i
- .br
- .ns
- .IP \fIsrc_y\fP 1i
- Specify the x and y coordinates,
- which are relative to the origin of the source rectangle
- and specify its upper-left corner.
- .ds Wh , which are the dimensions of both the source and destination rectangles
- .\" $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.
- .ds Dx , which are relative to the origin of the destination rectangle \
- and specify its upper-left corner
- .\" $Header: dstxy_gen.a,v 1.2 88/08/04 11:09:55 mento Exp $
- .IP \fIdest_x\fP 1i
- .br
- .ns
- .IP \fIdest_y\fP 1i
- Specify the x and y coordinates\*(Dx.
- .\" $Header: plane.a,v 1.3 88/05/13 13:48:24 mento Exp $
- .IP \fIplane\fP 1i
- Specifies the bit plane.
- You must set exactly one bit to 1.
- .\" End marker code here
- .LP
- .\" $Header: XCopyPlane.d,v 1.3 88/08/18 08:34:53 mento Exp $
- The
- .PN XCopyPlane
- function uses a single bit plane of the specified source rectangle
- combined with the specified GC to modify the specified rectangle of dest.
- The drawables must have the same root but need not have the same depth.
- If the drawables do not have the same root, a
- .PN BadMatch
- error results.
- If plane does not have exactly one bit set to 1 and the values of planes
- must be less than %2 sup n%, where \fIn\fP is the depth of src, a
- .PN BadValue
- error results.
- .LP
- Effectively,
- .PN XCopyPlane
- forms a pixmap of the same depth as the rectangle of dest and with a
- size specified by the source region.
- It uses the foreground/background pixels in the GC (foreground
- everywhere the bit plane in src contains a bit set to 1,
- background everywhere the bit plane in src contains a bit set to 0)
- and the equivalent of a
- .PN CopyArea
- protocol request is performed with all the same exposure semantics.
- This can also be thought of as using the specified region of the source
- bit plane as a stipple with a fill-style of
- .PN FillOpaqueStippled
- for filling a rectangular area of the destination.
- .LP
- This function uses these GC components: function, plane-mask, foreground,
- background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin,
- and clip-mask.
- .LP
- .PN XCopyPlane
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- .PN BadMatch ,
- and
- .PN BadValue
- errors.
- .NH 2
- Drawing Points, Lines, Rectangles, and Arcs
- .XS
- \*(SN Drawing Points, Lines, Rectangles, and Arcs
- .XE
- .LP
- Xlib provides functions that you can use to draw:
- .IP \(bu 5
- A single point or multiple points
- .IP \(bu 5
- A single line or multiple lines
- .IP \(bu 5
- A single rectangle or multiple rectangles
- .IP \(bu 5
- A single arc or multiple arcs
- .LP
- Some of the functions described in the following sections
- use these structures:
- .LP
- .IN "XSegment" "" "@DEF@"
- .\" Start marker code here
- .Ds 0
- .TA .5i
- .ta .5i
- typedef struct {
- short x1, y1, x2, y2;
- } XSegment;
- .De
- .\" End marker code here
- .LP
- .IN "XPoint" "" "@DEF@"
- .\" Start marker code here
- .Ds 0
- .TA .5i
- .ta .5i
- typedef struct {
- short x, y;
- } XPoint;
- .De
- .\" End marker code here
- .LP
- .IN "XRectangle" "" "@DEF@"
- .\" Start marker code here
- .Ds 0
- .TA .5i
- .ta .5i
- typedef struct {
- short x, y;
- unsigned short width, height;
- } XRectangle;
- .De
- .\" End marker code here
- .LP
- .IN "XArc" "" "@DEF@"
- .\" Start marker code here
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- short x, y;
- unsigned short width, height;
- short angle1, angle2; /* Degrees * 64 */
- } XArc;
- .De
- .\" End marker code here
- .LP
- All x and y members are signed integers.
- The width and height members are 16-bit unsigned integers.
- You should be careful not to generate coordinates and sizes
- out of the 16-bit ranges, because the protocol only has 16-bit fields
- for these values.
- .NH 3
- Drawing Single and Multiple Points
- .XS
- \*(SN Drawing Single and Multiple Points
- .XE
- .LP
- .IN "Points" "drawing"
- .IN "Drawing" "points"
- .IN "XDrawPoints"
- .IN "XDrawPoint"
- .LP
- To draw a single point in a given drawable, use
- .PN XDrawPoint .
- .IN "XDrawPoint" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XPoint.f,v 1.1 88/02/26 10:01:54 mento Exp $
- XDrawPoint\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- 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: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: xy_point.a,v 1.1 88/02/26 10:32:57 mento Exp $
- .IP \fIx\fP 1i
- .br
- .ns
- .IP \fIy\fP 1i
- Specify the x and y coordinates where you want the point drawn.
- .\" End marker code here
- .LP
- .sp
- To draw multiple points in a given drawable, use
- .PN XDrawPoints .
- .IN "XDrawPoints" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XPoints.f,v 1.1 88/02/26 10:01:55 mento Exp $
- XDrawPoints\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- XPoint *\fIpoints\fP\^;
- .br
- int \fInpoints\fP\^;
- .br
- int \fImode\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: points.a,v 1.1 88/02/26 10:30:33 mento Exp $
- .IP \fIpoints\fP 1i
- Specifies an array of points.
- .\" $Header: npoints.a,v 1.1 88/02/26 10:29:46 mento Exp $
- .IP \fInpoints\fP 1i
- Specifies the number of points in the array.
- .\" $Header: mode.a,v 1.4 88/05/18 07:53:37 mento Exp $
- .IP \fImode\fP 1i
- Specifies the coordinate mode.
- You can pass
- .PN CoordModeOrigin
- or
- .PN CoordModePrevious .
- .\" End marker code here
- .LP
- .\" $Header: XPoint.d,v 1.4 88/06/11 07:52:15 mento Exp $
- The
- .PN XDrawPoint
- function uses the foreground pixel and function components of the
- GC to draw a single point into the specified drawable;
- .PN XDrawPoints
- draws multiple points this way.
- .PN CoordModeOrigin
- treats all coordinates as relative to the origin,
- and
- .PN CoordModePrevious
- treats all coordinates after the first as relative to the previous point.
- .PN XDrawPoints
- draws the points in the order listed in the array.
- .LP
- Both functions use these GC components: function, plane-mask,
- foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
- .LP
- .PN XDrawPoint
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- and
- .PN BadMatch
- errors.
- .PN XDrawPoints
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- .PN BadMatch ,
- and
- .PN BadValue
- errors.
- .NH 3
- Drawing Single and Multiple Lines
- .XS
- \*(SN Drawing Single and Multiple Lines
- .XE
- .LP
- .IN "Lines" "drawing"
- .IN "Drawing" "lines"
- .IN "XDrawLine"
- .IN "XDrawLines"
- .IN "Polygons" "drawing"
- .IN "Drawing" "polygons"
- .IN "XDrawSegments"
- .LP
- To draw a single line between two points in a given drawable, use
- .PN XDrawLine .
- .IN "XDrawLine" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XLine.f,v 1.1 88/02/26 09:58:43 mento Exp $
- XDrawLine\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: x1y1x2y2.a,v 1.3 88/05/13 08:17:23 mento Exp $
- .IP \fIx1\fP 1i
- .br
- .ns
- .IP \fIy1\fP 1i
- .br
- .ns
- .IP \fIx2\fP 1i
- .br
- .ns
- .IP \fIy2\fP 1i
- Specify the points (x1, y1) and (x2, y2) to be connected.
- .\" End marker code here
- .LP
- .sp
- To draw multiple lines in a given drawable, use
- .PN XDrawLines .
- .IN "XDrawLines" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XLines.f,v 1.1 88/02/26 10:01:21 mento Exp $
- XDrawLines\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- XPoint *\fIpoints\fP\^;
- .br
- int \fInpoints\fP\^;
- .br
- int \fImode\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: points.a,v 1.1 88/02/26 10:30:33 mento Exp $
- .IP \fIpoints\fP 1i
- Specifies an array of points.
- .\" $Header: npoints.a,v 1.1 88/02/26 10:29:46 mento Exp $
- .IP \fInpoints\fP 1i
- Specifies the number of points in the array.
- .\" $Header: mode.a,v 1.4 88/05/18 07:53:37 mento Exp $
- .IP \fImode\fP 1i
- Specifies the coordinate mode.
- You can pass
- .PN CoordModeOrigin
- or
- .PN CoordModePrevious .
- .\" End marker code here
- .LP
- .sp
- To draw multiple, unconnected lines in a given drawable,
- use
- .PN XDrawSegments .
- .IN "XDrawSegments" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XSegments.f,v 1.1 88/02/26 10:02:52 mento Exp $
- XDrawSegments\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIsegments\fP\^, \fInsegments\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- XSegment *\fIsegments\fP\^;
- .br
- int \fInsegments\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: segments.a,v 1.1 88/02/26 10:31:10 mento Exp $
- .IP \fIsegments\fP 1i
- Specifies an array of segments.
- .\" $Header: nsegments.a,v 1.1 88/02/26 10:29:48 mento Exp $
- .IP \fInsegments\fP 1i
- Specifies the number of segments in the array.
- .\" End marker code here
- .LP
- The
- .PN XDrawLine
- function uses the components of the specified GC to
- draw a line between the specified set of points (x1, y1) and (x2, y2).
- It does not perform joining at coincident endpoints.
- For any given line,
- .PN XDrawLine
- does not draw a pixel more than once.
- If lines intersect, the intersecting pixels are drawn multiple times.
- .LP
- The
- .PN XDrawLines
- function uses the components of the specified GC to draw
- npoints\-1 lines between each pair of points (point[i], point[i+1])
- in the array of
- .PN XPoint
- structures.
- It draws the lines in the order listed in the array.
- The lines join correctly at all intermediate points, and if the first and last
- points coincide, the first and last lines also join correctly.
- For any given line,
- .PN XDrawLines
- does not draw a pixel more than once.
- If thin (zero line-width) lines intersect,
- the intersecting pixels are drawn multiple times.
- If wide lines intersect, the intersecting pixels are drawn only once, as though
- the entire
- .PN PolyLine
- protocol request were a single, filled shape.
- .PN CoordModeOrigin
- treats all coordinates as relative to the origin,
- and
- .PN CoordModePrevious
- treats all coordinates after the first as relative to the previous point.
- .LP
- The
- .PN XDrawSegments
- function draws multiple, unconnected lines.
- For each segment,
- .PN XDrawSegments
- draws a
- line between (x1, y1) and (x2, y2).
- It draws the lines in the order listed in the array of
- .PN XSegment
- structures and does not perform joining at coincident endpoints.
- For any given line,
- .PN XDrawSegments
- does not draw a pixel more than once.
- If lines intersect, the intersecting pixels are drawn multiple times.
- .LP
- All three functions use these GC components:
- function, plane-mask, line-width,
- line-style, cap-style, fill-style, subwindow-mode,
- clip-x-origin, clip-y-origin, and clip-mask.
- The
- .PN XDrawLines
- function also uses the join-style GC component.
- All three functions also use these GC mode-dependent components:
- foreground, background, tile, stipple, tile-stipple-x-origin,
- tile-stipple-y-origin, dash-offset, and dash-list.
- .LP
- .PN XDrawLine ,
- .PN XDrawLines ,
- and
- .PN XDrawSegments
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- and
- .PN BadMatch
- errors.
- .PN XDrawLines
- also can generate
- .PN BadValue
- errors.
- .NH 3
- Drawing Single and Multiple Rectangles
- .XS
- \*(SN Drawing Single and Multiple Rectangles
- .XE
- .LP
- .IN "Rectangles" "drawing"
- .IN "Drawing" "rectangles"
- .IN "XDrawRectangle"
- .IN "XDrawRectangles"
- .LP
- To draw the outline of a single rectangle in a given drawable, use
- .PN XDrawRectangle .
- .IN "XDrawRectangle" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XRectangle.f,v 1.1 88/02/26 10:02:37 mento Exp $
- XDrawRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- unsigned int \fIwidth\fP\^, \fIheight\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .ds Xy , which specify the upper-left corner of the rectangle
- .\" $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.
- .ds Wh , which specify the dimensions of the rectangle
- .\" $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.
- .\" End marker code here
- .LP
- .sp
- To draw the outline of multiple rectangles
- in a given drawable, use
- .PN XDrawRectangles .
- .IN "XDrawRectangles" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XRectangles.f,v 1.1 88/02/26 10:02:38 mento Exp $
- XDrawRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- XRectangle \fIrectangles\fP\^[\^]\^;
- .br
- int \fInrectangles\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: rectangles.a,v 1.1 88/02/26 10:30:50 mento Exp $
- .IP \fIrectangles\fP 1i
- Specifies an array of rectangles.
- .\" $Header: nrectangles.a,v 1.1 88/02/26 10:29:47 mento Exp $
- .IP \fInrectangles\fP 1i
- Specifies the number of rectangles in the array.
- .\" End marker code here
- .LP
- .\" $Header: XRectangle.d,v 1.4 88/06/11 07:52:48 mento Exp $
- The
- .PN XDrawRectangle
- and
- .PN XDrawRectangles
- functions draw the outlines of the specified rectangle or rectangles as
- if a five-point
- .PN PolyLine
- protocol request were specified for each rectangle:
- .IP
- [x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
- .LP
- For the specified rectangle or rectangles,
- these functions do not draw a pixel more than once.
- .PN XDrawRectangles
- draws the rectangles in the order listed in the array.
- If rectangles intersect,
- the intersecting pixels are drawn multiple times.
- .LP
- Both functions use these GC components:
- function, plane-mask, line-width,
- line-style, cap-style, join-style, fill-style,
- subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
- They also use these GC mode-dependent components:
- foreground, background, tile, stipple, tile-stipple-x-origin,
- tile-stipple-y-origin, dash-offset, and dash-list.
- .LP
- .PN XDrawRectangle
- and
- .PN XDrawRectangles
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- and
- .PN BadMatch
- errors.
- .NH 3
- Drawing Single and Multiple Arcs
- .XS
- \*(SN Drawing Single and Multiple Arcs
- .XE
- .LP
- .IN "Drawing" "arcs"
- .IN "XDrawArc"
- .IN "Arcs" "drawing"
- .IN "XDrawArcs"
- .LP
- .sp
- To draw a single arc in a given drawable, use
- .PN XDrawArc .
- .IN "XDrawArc" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XArc.f,v 1.1 88/02/26 09:58:12 mento Exp $
- XDrawArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- unsigned int \fIwidth\fP\^, \fIheight\fP\^;
- .br
- int \fIangle1\fP\^, \fIangle2\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .ds Xy , which are relative to the origin of the drawable \
- and specify the upper-left corner of the bounding rectangle
- .\" $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.
- .ds Wh , which are the major and minor axes of the arc
- .\" $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: angle1.a,v 1.2 88/05/13 09:05:46 mento Exp $
- .IP \fIangle1\fP 1i
- Specifies the start of the arc relative to the three-o'clock position
- from the center, in units of degrees * 64.
- .\" $Header: angle2.a,v 1.1 88/02/26 10:04:51 mento Exp $
- .IP \fIangle2\fP 1i
- Specifies the path and extent of the arc relative to the start of the
- arc, in units of degrees * 64.
- .\" End marker code here
- .LP
- .sp
- To draw multiple arcs in a given drawable, use
- .PN XDrawArcs .
- .IN "XDrawArcs" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XArcs.f,v 1.1 88/02/26 09:58:12 mento Exp $
- XDrawArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- XArc *\fIarcs\fP\^;
- .br
- int \fInarcs\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: arcs.a,v 1.1 88/02/26 10:04:53 mento Exp $
- .IP \fIarcs\fP 1i
- Specifies an array of arcs.
- .\" $Header: narcs.a,v 1.1 88/02/26 10:29:11 mento Exp $
- .IP \fInarcs\fP 1i
- Specifies the number of arcs in the array.
- .\" End marker code here
- .LP
- .\" $Header: XArc.d,v 1.4 88/08/18 09:29:15 mento Exp $
- .EQ
- delim %%
- .EN
- .PN XDrawArc
- draws a single circular or elliptical arc, and
- .PN XDrawArcs
- draws multiple circular or elliptical arcs.
- Each arc is specified by a rectangle and two angles.
- The center of the circle or ellipse is the center of the
- rectangle, and the major and minor axes are specified by the width and height.
- Positive angles indicate counterclockwise motion,
- and negative angles indicate clockwise motion.
- If the magnitude of angle2 is greater than 360 degrees,
- .PN XDrawArc
- or
- .PN XDrawArcs
- truncates it to 360 degrees.
- .LP
- For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%,
- the origin of the major and minor axes is at
- % [ x +^ {width over 2} , ~y +^ {height over 2} ]%,
- and the infinitely thin path describing the entire circle or ellipse
- intersects the horizontal axis at % [ x, ~y +^ {height over 2} ]% and
- % [ x +^ width , ~y +^ { height over 2 }] %
- and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and
- % [ x +^ { width over 2 }, ~y +^ height ]%.
- These coordinates can be fractional
- and so are not truncated to discrete coordinates.
- The path should be defined by the ideal mathematical path.
- For a wide line with line-width lw,
- the bounding outlines for filling are given
- by the two infinitely thin paths consisting of all points whose perpendicular
- distance from the path of the circle/ellipse is equal to lw/2
- (which may be a fractional value).
- The cap-style and join-style are applied the same as for a line
- corresponding to the tangent of the circle/ellipse at the endpoint.
- .LP
- For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2 ]%,
- the angles must be specified
- in the effectively skewed coordinate system of the ellipse (for a
- circle, the angles and coordinate systems are identical). The
- relationship between these angles and angles expressed in the normal
- coordinate system of the screen (as measured with a protractor) is as
- follows:
- .LP
- .Ds
- % roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )
- * width over height right ) +^ adjust%
- .De
- .LP
- The skewed-angle and normal-angle are expressed in radians (rather
- than in degrees scaled by 64) in the range % [ 0 , ~2 pi ]% and where atan
- returns a value in the range % [ - pi over 2 , ~pi over 2 ] %
- and adjust is:
- .LP
- .Ds
- .TA 1i 2i
- .ta 1i 2i
- %0% for normal-angle in the range % [ 0 , ~pi over 2 ]%
- %pi% for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2 ]%
- %2 pi% for normal-angle in the range % [ {3 pi} over 2 , ~2 pi ]%
- .De
- .LP
- For any given arc,
- .PN XDrawArc
- and
- .PN XDrawArcs
- do not draw a pixel more than once.
- If two arcs join correctly and if the line-width is greater than zero
- and the arcs intersect,
- .PN XDrawArc
- and
- .PN XDrawArcs
- do not draw a pixel more than once.
- Otherwise,
- the intersecting pixels of intersecting arcs are drawn multiple times.
- Specifying an arc with one endpoint and a clockwise extent draws the same pixels
- as specifying the other endpoint and an equivalent counterclockwise extent,
- except as it affects joins.
- .LP
- If the last point in one arc coincides with the first point in the following
- arc, the two arcs will join correctly.
- If the first point in the first arc coincides with the last point in the last
- arc, the two arcs will join correctly.
- By specifying one axis to be zero, a horizontal or vertical line can be
- drawn.
- Angles are computed based solely on the coordinate system and ignore the
- aspect ratio.
- .LP
- Both functions use these GC components:
- function, plane-mask, line-width, line-style, cap-style, join-style,
- fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
- They also use these GC mode-dependent components:
- foreground, background, tile, stipple, tile-stipple-x-origin,
- tile-stipple-y-origin, dash-offset, and dash-list.
- .LP
- .PN XDrawArc
- and
- .PN XDrawArcs
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- and
- .PN BadMatch
- errors.
- .NH 2
- Filling Areas
- .XS
- \*(SN Filling Areas
- .XE
- .LP
- Xlib provides functions that you can use to fill:
- .IP \(bu 5
- A single rectangle or multiple rectangles
- .IP \(bu 5
- A single polygon
- .IP \(bu 5
- A single arc or multiple arcs
- .NH 3
- Filling Single and Multiple Rectangles
- .XS
- \*(SN Filling Single and Multiple Rectangles
- .XE
- .LP
- .IN "Filling" "rectangles"
- .IN "XFillRectangle"
- .IN "Rectangle" "filling"
- .IN "XFillRectangles"
- .LP
- .sp
- To fill a single rectangular area in a given drawable, use
- .PN XFillRectangle .
- .IN "XFillRectangle" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XFillRect.f,v 1.1 88/02/26 10:00:09 mento Exp $
- XFillRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- unsigned int \fIwidth\fP\^, \fIheight\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .ds Xy , which are relative to the origin of the drawable \
- and specify the upper-left corner of the rectangle
- .\" $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.
- .ds Wh , which are the dimensions of the rectangle to be filled
- .\" $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.
- .\" End marker code here
- .LP
- .sp
- To fill multiple rectangular areas in a given drawable, use
- .PN XFillRectangles .
- .IN "XFillRectangles" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XFillRects.f,v 1.1 88/02/26 10:00:10 mento Exp $
- XFillRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- XRectangle *\fIrectangles\fP\^;
- .br
- int \fInrectangles\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: rectangles.a,v 1.1 88/02/26 10:30:50 mento Exp $
- .IP \fIrectangles\fP 1i
- Specifies an array of rectangles.
- .\" $Header: nrectangles.a,v 1.1 88/02/26 10:29:47 mento Exp $
- .IP \fInrectangles\fP 1i
- Specifies the number of rectangles in the array.
- .\" End marker code here
- .LP
- .\" $Header: XFillRect.d,v 1.5 88/06/11 07:50:18 mento Exp $
- The
- .PN XFillRectangle
- and
- .PN XFillRectangles
- functions fill the specified rectangle or rectangles
- as if a four-point
- .PN FillPolygon
- protocol request were specified for each rectangle:
- .LP
- .Ds
- [x,y] [x+width,y] [x+width,y+height] [x,y+height]
- .De
- .LP
- Each function uses the x and y coordinates,
- width and height dimensions, and GC you specify.
- .LP
- .PN XFillRectangles
- fills the rectangles in the order listed in the array.
- For any given rectangle,
- .PN XFillRectangle
- and
- .PN XFillRectangles
- do not draw a pixel more than once.
- If rectangles intersect, the intersecting pixels are
- drawn multiple times.
- .LP
- Both functions use these GC components:
- function, plane-mask, fill-style, subwindow-mode,
- clip-x-origin, clip-y-origin, and clip-mask.
- They also use these GC mode-dependent components:
- foreground, background, tile, stipple, tile-stipple-x-origin,
- and tile-stipple-y-origin.
- .LP
- .PN XFillRectangle
- and
- .PN XFillRectangles
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- and
- .PN BadMatch
- errors.
- .NH 3
- Filling a Single Polygon
- .XS
- \*(SN Filling a Single Polygon
- .XE
- .LP
- .sp
- To fill a polygon area in a given drawable, use
- .PN XFillPolygon .
- .IN "Polygons" "filling"
- .IN "Filling" "polygon"
- .IN "XFillPolygon" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XFillPoly.f,v 1.1 88/02/26 10:00:08 mento Exp $
- XFillPolygon\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fIshape\fP\^, \fImode\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- XPoint *\fIpoints\fP\^;
- .br
- int \fInpoints\fP\^;
- .br
- int \fIshape\fP\^;
- .br
- int \fImode\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: points.a,v 1.1 88/02/26 10:30:33 mento Exp $
- .IP \fIpoints\fP 1i
- Specifies an array of points.
- .\" $Header: npoints.a,v 1.1 88/02/26 10:29:46 mento Exp $
- .IP \fInpoints\fP 1i
- Specifies the number of points in the array.
- .\" $Header: shape.a,v 1.4 88/04/23 09:30:27 mento Exp $
- .IP \fIshape\fP 1i
- Specifies a shape that helps the server to improve performance.
- You can pass
- .PN Complex ,
- .PN Convex ,
- or
- .PN Nonconvex .
- .\" $Header: mode.a,v 1.4 88/05/18 07:53:37 mento Exp $
- .IP \fImode\fP 1i
- Specifies the coordinate mode.
- You can pass
- .PN CoordModeOrigin
- or
- .PN CoordModePrevious .
- .\" End marker code here
- .LP
- .\" $Header: XFillPoly.d,v 1.2 88/06/11 07:50:18 mento Exp $
- .PN XFillPolygon
- fills the region closed by the specified path.
- The path is closed
- automatically if the last point in the list does not coincide with the
- first point.
- .PN XFillPolygon
- does not draw a pixel of the region more than once.
- .PN CoordModeOrigin
- treats all coordinates as relative to the origin,
- and
- .PN CoordModePrevious
- treats all coordinates after the first as relative to the previous point.
- .LP
- Depending on the specified shape, the following occurs:
- .IP \(bu 5
- If shape is
- .PN Complex ,
- the path may self-intersect.
- Note that contiguous coincident points in the path are not treated
- as self-intersection.
- .IP \(bu 5
- If shape is
- .PN Convex ,
- for every pair of points inside the polygon,
- the line segment connecting them does not intersect the path.
- If known by the client,
- specifying
- .PN Convex
- can improve performance.
- If you specify
- .PN Convex
- for a path that is not convex,
- the graphics results are undefined.
- .IP \(bu 5
- If shape is
- .PN Nonconvex ,
- the path does not self-intersect, but the shape is not
- wholly convex.
- If known by the client,
- specifying
- .PN Nonconvex
- instead of
- .PN Complex
- may improve performance.
- If you specify
- .PN Nonconvex
- for a self-intersecting path, the graphics results are undefined.
- .LP
- The fill-rule of the GC controls the filling behavior of
- self-intersecting polygons.
- .LP
- This function uses these GC components:
- function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin,
- clip-y-origin, and clip-mask.
- It also uses these GC mode-dependent components:
- foreground, background, tile, stipple, tile-stipple-x-origin,
- and tile-stipple-y-origin.
- .LP
- .PN XFillPolygon
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- .PN BadMatch ,
- and
- .PN BadValue
- errors.
- .NH 3
- Filling Single and Multiple Arcs
- .XS
- \*(SN Filling Single and Multiple Arcs
- .XE
- .LP
- .IN "XFillArc"
- .IN "Arcs" "filling"
- .IN "Filling" "arcs"
- To fill a single arc in a given drawable, use
- .PN XFillArc .
- .IN "XFillArc" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XFillArc.f,v 1.1 88/02/26 10:00:01 mento Exp $
- XFillArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- unsigned int \fIwidth\fP\^, \fIheight\fP\^;
- .br
- int \fIangle1\fP\^, \fIangle2\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .ds Xy , which are relative to the origin of the drawable \
- and specify the upper-left corner of the bounding rectangle
- .\" $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.
- .ds Wh , which are the major and minor axes of the arc
- .\" $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: angle1.a,v 1.2 88/05/13 09:05:46 mento Exp $
- .IP \fIangle1\fP 1i
- Specifies the start of the arc relative to the three-o'clock position
- from the center, in units of degrees * 64.
- .\" $Header: angle2.a,v 1.1 88/02/26 10:04:51 mento Exp $
- .IP \fIangle2\fP 1i
- Specifies the path and extent of the arc relative to the start of the
- arc, in units of degrees * 64.
- .\" End marker code here
- .LP
- .sp
- To fill multiple arcs in a given drawable, use
- .PN XFillArcs .
- .IN "XFillArcs" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XFillArcs.f,v 1.1 88/02/26 10:00:02 mento Exp $
- XFillArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- XArc *\fIarcs\fP\^;
- .br
- int \fInarcs\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: arcs.a,v 1.1 88/02/26 10:04:53 mento Exp $
- .IP \fIarcs\fP 1i
- Specifies an array of arcs.
- .\" $Header: narcs.a,v 1.1 88/02/26 10:29:11 mento Exp $
- .IP \fInarcs\fP 1i
- Specifies the number of arcs in the array.
- .\" End marker code here
- .LP
- .\" $Header: XFillArc.d,v 1.2 88/06/11 07:50:17 mento Exp $
- For each arc,
- .PN XFillArc
- or
- .PN XFillArcs
- fills the region closed by the infinitely thin path
- described by the specified arc and, depending on the
- arc-mode specified in the GC, one or two line segments.
- For
- .PN ArcChord ,
- the single line segment joining the endpoints of the arc is used.
- For
- .PN ArcPieSlice ,
- the two line segments joining the endpoints of the arc with the center
- point are used.
- .PN XFillArcs
- fills the arcs in the order listed in the array.
- For any given arc,
- .PN XFillArc
- and
- .PN XFillArcs
- do not draw a pixel more than once.
- If regions intersect,
- the intersecting pixels are drawn multiple times.
- .LP
- Both functions use these GC components:
- function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin,
- clip-y-origin, and clip-mask.
- They also use these GC mode-dependent components:
- foreground, background, tile, stipple, tile-stipple-x-origin,
- and tile-stipple-y-origin.
- .LP
- .PN XFillArc
- and
- .PN XFillArcs
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- and
- .PN BadMatch
- errors.
- .NH 2
- Font Metrics
- .XS
- \*(SN Font Metrics
- .XE
- .LP
- .IN "Font"
- A font is a graphical description of a set of characters that are used to
- increase efficiency whenever a set of small, similar sized patterns are
- repeatedly used.
- .LP
- This section discusses how to:
- .IP \(bu 5
- Load and free fonts
- .IP \(bu 5
- Obtain and free font names
- .IP \(bu 5
- Compute character string sizes
- .IP \(bu 5
- Return logical extents
- .IP \(bu 5
- Query character string sizes
- .LE
- .LP
- The X server loads fonts whenever a program requests a new font.
- The server can cache fonts for quick lookup.
- Fonts are global across all screens in a server.
- Several levels are possible when dealing with fonts.
- Most applications simply use
- .PN XLoadQueryFont
- to load a font and query the font metrics.
- .LP
- Characters in fonts are regarded as masks.
- Except for image text requests,
- the only pixels modified are those in which bits are set to 1 in the character.
- This means that it makes sense to draw text using stipples or tiles
- (for example, many menus gray-out unusable entries).
- .LP
- .\" Start marker code here
- The
- .PN XFontStruct
- structure contains all of the information for the font
- and consists of the font-specific information as well as
- a pointer to an array of
- .PN XCharStruct
- structures for the
- characters contained in the font.
- The
- .PN XFontStruct ,
- .PN XFontProp ,
- and
- .PN XCharStruct
- structures contain:
- .LP
- .IN "XCharStruct" "" "@DEF@"
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- short lbearing; /* origin to left edge of raster */
- short rbearing; /* origin to right edge of raster */
- short width; /* advance to next char's origin */
- short ascent; /* baseline to top edge of raster */
- short descent; /* baseline to bottom edge of raster */
- unsigned short attributes; /* per char flags (not predefined) */
- } XCharStruct;
- .De
- .LP
- .IN "XFontProp" "" "@DEF@"
- .Ds 0
- .TA .5i 1i 3i
- .ta .5i 1i 3i
- typedef struct {
- Atom name;
- unsigned long card32;
- } XFontProp;
- .De
- .LP
- .IN "XChar2b" "" "@DEF@"
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct { /* normal 16 bit characters are two bytes */
- unsigned char byte1;
- unsigned char byte2;
- } XChar2b;
- .De
- .LP
- .IN "XFontStruct" "" "@DEF@"
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- XExtData *ext_data; /* hook for extension to hang data */
- Font fid; /* Font id for this font */
- unsigned direction; /* hint about the direction font is painted */
- unsigned min_char_or_byte2; /* first character */
- unsigned max_char_or_byte2; /* last character */
- unsigned min_byte1; /* first row that exists */
- unsigned max_byte1; /* last row that exists */
- Bool all_chars_exist; /* flag if all characters have nonzero size */
- unsigned default_char; /* char to print for undefined character */
- int n_properties; /* how many properties there are */
- XFontProp *properties; /* pointer to array of additional properties */
- XCharStruct min_bounds; /* minimum bounds over all existing char */
- XCharStruct max_bounds; /* maximum bounds over all existing char */
- XCharStruct *per_char; /* first_char to last_char information */
- int ascent; /* logical extent above baseline for spacing */
- int descent; /* logical decent below baseline for spacing */
- } XFontStruct;
- .De
- .\" End marker code here
- .LP
- X supports single byte/character, two bytes/character matrix,
- and 16-bit character text operations.
- Note that any of these forms can be used with a font, but a
- single byte/character text request can only specify a single byte
- (that is, the first row of a 2-byte font).
- You should view 2-byte fonts as a two-dimensional matrix of defined
- characters: byte1 specifies the range of defined rows and
- byte2 defines the range of defined columns of the font.
- Single byte/character fonts have one row defined, and the byte2 range
- specified in the structure defines a range of characters.
- .LP
- The bounding box of a character is defined by the
- .PN XCharStruct
- of that character.
- When characters are absent from a font,
- the default_char is used.
- When fonts have all characters of the same size,
- only the information in the
- .PN XFontStruct
- min and max bounds are used.
- .LP
- The members of the
- .PN XFontStruct
- have the following semantics:
- .IP \(bu 5
- The direction member can be either
- .PN FontLeftToRight
- or
- .PN FontRightToLeft .
- It is just a hint as to whether most
- .PN XCharStruct
- elements
- have a positive
- .Pn ( FontLeftToRight )
- or a negative
- .Pn ( FontRightToLeft )
- character width
- metric.
- The core protocol defines no support for vertical text.
- .IP \(bu 5
- If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2
- specifies the linear character index corresponding to the first element
- of the per_char array, and max_char_or_byte2 specifies the linear character
- index of the last element.
- .IP
- If either min_byte1 or max_byte1 are nonzero, both
- min_char_or_byte2 and max_char_or_byte2 are less than 256,
- and the 2-byte character index values corresponding to the
- per_char array element N (counting from 0) are:
- .IP
- .nf
- byte1 = N/D + min_byte1
- .br
- byte2 = N\\D + min_char_or_byte2
- .IP
- .fi
- where:
- .IP
- .nf
- D = max_char_or_byte2 \- min_char_or_byte2 + 1
- / = integer division
- \\ = integer modulus
- .fi
- .IP \(bu 5
- If the per_char pointer is NULL,
- all glyphs between the first and last character indexes
- inclusive have the same information,
- as given by both min_bounds and max_bounds.
- .IP \(bu 5
- If all_chars_exist is
- .PN True ,
- all characters in the per_char array have nonzero bounding boxes.
- .IP \(bu 5
- The default_char member specifies the character that will be used when an
- undefined or nonexistent character is printed.
- The default_char is a 16-bit character (not a 2-byte character).
- For a font using 2-byte matrix format,
- the default_char has byte1 in the most-significant byte
- and byte2 in the least-significant byte.
- If the default_char itself specifies an undefined or nonexistent character,
- no printing is performed for an undefined or nonexistent character.
- .IP \(bu 5
- The min_bounds and max_bounds members contain the most extreme values of
- each individual
- .PN XCharStruct
- component over all elements of this array
- (and ignore nonexistent characters).
- The bounding box of the font (the smallest
- rectangle enclosing the shape obtained by superimposing all of the
- characters at the same origin [x,y]) has its upper-left coordinate at:
- .Ds
- [x + min_bounds.lbearing, y \- max_bounds.ascent]
- .De
- .IP
- Its width is:
- .Ds
- max_bounds.rbearing \- min_bounds.lbearing
- .De
- .IP
- Its height is:
- .Ds
- max_bounds.ascent + max_bounds.descent
- .De
- .IP \(bu 5
- The ascent member is the logical extent of the font above the baseline that is
- used for determining line spacing.
- Specific characters may extend beyond
- this.
- .IP \(bu 5
- The descent member is the logical extent of the font at or below the
- baseline that is used for determining line spacing.
- Specific characters may extend beyond this.
- .IP \(bu 5
- If the baseline is at Y-coordinate y,
- the logical extent of the font is inclusive between the Y-coordinate
- values (y \- font.ascent) and (y + font.descent \- 1).
- Typically,
- the minimum interline spacing between rows of text is given
- by ascent + descent.
- .LP
- For a character origin at [x,y],
- the bounding box of a character (that is,
- the smallest rectangle that encloses the character's shape)
- described in terms of
- .PN XCharStruct
- components is a rectangle with its upper-left corner at:
- .LP
- .Ds
- [x + lbearing, y \- ascent]
- .De
- .LP
- Its width is:
- .LP
- .Ds
- rbearing \- lbearing
- .De
- .LP
- Its height is:
- .LP
- .Ds
- ascent + descent
- .De
- .LP
- The origin for the next character is defined to be:
- .LP
- .Ds
- [x + width, y]
- .De
- .LP
- The lbearing member defines the extent of the left edge of the character ink
- from the origin.
- The rbearing member defines the extent of the right edge of the character ink
- from the origin.
- The ascent member defines the extent of the top edge of the character ink
- from the origin.
- The descent member defines the extent of the bottom edge of the character ink
- from the origin.
- The width member defines the logical width of the character.
- .LP
- Note that the baseline (the y position of the character origin)
- is logically viewed as being the scanline just below nondescending characters.
- When descent is zero,
- only pixels with Y-coordinates less than y are drawn,
- and the origin is logically viewed as being coincident with the left edge of
- a nonkerned character.
- When lbearing is zero,
- no pixels with X-coordinate less than x are drawn.
- Any of the
- .PN XCharStruct
- metric members could be negative.
- If the width is negative,
- the next character will be placed to the left of the current origin.
- .LP
- The X protocol does not define the interpretation of the attributes member
- in the
- .PN XCharStruct
- structure.
- A nonexistent character is represented with all members of its
- .PN XCharStruct
- set to zero.
- .LP
- A font is not guaranteed to have any properties.
- The interpretation of the property value (for example, long or unsigned long)
- must be derived from \fIa priori\fP knowledge of the property.
- A basic set of font properties is specified in the X Consortium standard
- \fIX Logical Font Description Conventions\fP.
- .NH 3
- Loading and Freeing Fonts
- .XS
- \*(SN Loading and Freeing Fonts
- .XE
- .LP
- Xlib provides functions that you can use to load fonts, get font information,
- unload fonts, and free font information.
- .IN "Fonts" "getting information"
- .IN "Fonts" "unloading"
- .IN "Fonts" "freeing font information"
- A few font functions use a
- .PN GContext
- resource ID or a font ID interchangeably.
- .LP
- .sp
- To load a given font, use
- .PN XLoadFont .
- .IN "XLoadFont" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XLoadFont.f,v 1.1 88/02/26 10:01:25 mento Exp $
- Font XLoadFont\^(\^\fIdisplay\fP, \fIname\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- char *\fIname\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: name.a,v 1.2 88/05/13 10:40:29 mento Exp $
- .IP \fIname\fP 1i
- Specifies the name of the font,
- which is a null-terminated string.
- .\" End marker code here
- .LP
- .\" $Header: XLoadFont.d,v 1.2 88/06/11 07:51:54 mento Exp $
- The
- .PN XLoadFont
- function loads the specified font and returns its associated font ID.
- If the font name is not in the Host Portable Character Encoding
- the result is implementation dependent.
- Use of uppercase or lowercase does not matter.
- The interpretation of characters ``?''
- and ``*'' in the name is not defined by the core protocol
- but is reserved for future definition.
- A structured format for font names is specified in the X Consortium standard
- \fIX Logical Font Description Conventions\fP.
- If
- .PN XLoadFont
- was unsuccessful at loading the specified font,
- a
- .PN BadName
- error results.
- Fonts are not associated with a particular screen
- and can be stored as a component
- of any GC.
- When the font is no longer needed, call
- .PN XUnloadFont .
- .LP
- .PN XLoadFont
- can generate
- .PN BadAlloc
- and
- .PN BadName
- errors.
- .LP
- .sp
- To return information about an available font, use
- .PN XQueryFont .
- .IN "XQueryFont" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XFontStruct *XQueryFont\^(\^\fIdisplay\fP, \fIfont_ID\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- XID \fIfont_ID\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 \fIfont_ID\fP 1i
- Specifies the font ID or the
- .PN GContext
- ID.
- .\" End marker code here
- .LP
- .\" $Header: XQueryFont.d,v 1.2 88/06/11 07:52:41 mento Exp $
- The
- .PN XQueryFont
- function returns a pointer to the
- .PN XFontStruct
- structure, which contains information associated with the font.
- You can query a font or the font stored in a GC.
- The font ID stored in the
- .PN XFontStruct
- structure will be the
- .PN GContext
- ID, and you need to be careful when using this ID in other functions
- (see
- .PN XGContextFromGC ).
- If the font does not exist,
- .PN XQueryFont
- returns NULL.
- To free this data, use
- .PN XFreeFontInfo .
- .LP
- .sp
- To perform a
- .PN XLoadFont
- and
- .PN XQueryFont
- in a single operation, use
- .PN XLoadQueryFont .
- .IN "XLoadQueryFont" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XFontStruct.f,v 1.1 88/02/26 10:00:12 mento Exp $
- XFontStruct *XLoadQueryFont\^(\^\fIdisplay\fP, \fIname\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- char *\fIname\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: name.a,v 1.2 88/05/13 10:40:29 mento Exp $
- .IP \fIname\fP 1i
- Specifies the name of the font,
- which is a null-terminated string.
- .\" End marker code here
- .LP
- .\" $Header: XFontStruct.d,v 1.3 88/06/11 07:50:37 mento Exp $
- The
- .PN XLoadQueryFont
- function provides the most common way for accessing a font.
- .PN XLoadQueryFont
- both opens (loads) the specified font and returns a pointer to the
- appropriate
- .PN XFontStruct
- structure.
- If the font name is not in the Host Portable Character Encoding
- the result is implementation dependent.
- If the font does not exist,
- .PN XLoadQueryFont
- returns NULL.
- .LP
- .PN XLoadQueryFont
- can generate a
- .PN BadAlloc
- error.
- .LP
- .sp
- To unload the font and free the storage used by the font structure
- that was allocated by
- .PN XQueryFont
- or
- .PN XLoadQueryFont ,
- use
- .PN XFreeFont .
- .IN "XFreeFont" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XFontFree.f,v 1.1 88/02/26 10:00:11 mento Exp $
- XFreeFont\^(\^\fIdisplay\fP, \fIfont_struct\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- XFontStruct *\fIfont_struct\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: ptr.a,v 1.1 88/02/26 10:30:46 mento Exp $
- .IP \fIfont_struct\fP 1i
- Specifies the storage associated with the font.
- .\" End marker code here
- .LP
- .\" $Header: XFontFree.d,v 1.3 88/05/13 10:59:37 mento Exp $
- The
- .PN XFreeFont
- function deletes the association between the font resource ID and the specified
- font and frees the
- .PN XFontStruct
- structure.
- The font itself will be freed when no other resource references it.
- The data and the font should not be referenced again.
- .LP
- .PN XFreeFont
- can generate a
- .PN BadFont
- error.
- .LP
- .sp
- To return a given font property, use
- .PN XGetFontProperty .
- .IN "XGetFontProperty" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XGetFontProp.f,v 1.1 88/02/26 10:00:27 mento Exp $
- Bool XGetFontProperty\^(\^\fIfont_struct\fP\^, \^\fIatom\fP\^, \^\fIvalue_return\fP\^)
- .br
- XFontStruct *\fIfont_struct\fP\^;
- .br
- Atom \fIatom\fP\^;
- .br
- unsigned long *\fIvalue_return\fP\^;
- .FN
- .\" $Header: ptr.a,v 1.1 88/02/26 10:30:46 mento Exp $
- .IP \fIfont_struct\fP 1i
- Specifies the storage associated with the font.
- .\" $Header: atom.a,v 1.2 88/04/06 12:06:45 mento Exp $
- .IP \fIatom\fP 1i
- Specifies the atom for the property name you want returned.
- .\" $Header: value.a,v 1.2 88/04/06 15:17:04 mento Exp $
- .IP \fIvalue_return\fP 1i
- Returns the value of the font property.
- .\" End marker code here
- .LP
- .\" $Header: XGetFontProp.d,v 1.6 88/08/18 09:39:18 mento Exp $
- Given the atom for that property,
- the
- .PN XGetFontProperty
- function returns the value of the specified font property.
- .PN XGetFontProperty
- also returns
- .PN False
- if the property was not defined or
- .PN True
- if it was defined.
- A set of predefined atoms exists for font properties,
- which can be found in
- .Pn < X11/Xatom.h >.
- This set contains the standard properties associated with
- a font.
- Although it is not guaranteed,
- it is likely that the predefined font properties will be present.
- .LP
- .sp
- To unload a font that was loaded by
- .PN XLoadFont ,
- use
- .PN XUnloadFont .
- .IN "XUnloadFont" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XCloseFont.f,v 1.1 88/02/26 09:58:49 mento Exp $
- XUnloadFont\^(\^\fIdisplay\fP, \fIfont\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Font \fIfont\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: font.a,v 1.2 88/05/09 14:28:06 mento Exp $
- .IP \fIfont\fP 1i
- Specifies the font.
- .\" End marker code here
- .LP
- .\" $Header: XCloseFont.d,v 1.2 88/06/11 07:49:24 mento Exp $
- The
- .PN XUnloadFont
- function deletes the association between the font resource ID and the specified font.
- The font itself will be freed when no other resource references it.
- The font should not be referenced again.
- .LP
- .PN XUnloadFont
- can generate a
- .PN BadFont
- error.
- .NH 3
- Obtaining and Freeing Font Names and Information
- .XS
- \*(SN Obtaining and Freeing Font Names and Information
- .XE
- .LP
- You obtain font names and information by matching a wildcard specification
- when querying a font type for a list of available sizes and so on.
- .LP
- .sp
- To return a list of the available font names, use
- .PN XListFonts .
- .IN "XListFonts" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XFontNames.f,v 1.1 88/02/26 10:00:12 mento Exp $
- char **XListFonts\^(\^\fIdisplay\fP, \fIpattern\fP\^, \fImaxnames\fP, \fIactual_count_return\fP\^)
- .br
- Display *\^\fIdisplay\fP\^;
- .br
- char *\^\fIpattern\fP\^;
- .br
- int \fImaxnames\fP\^;
- .br
- int *\^\fIactual_count_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.
- .\" $Header: pattern.a,v 1.4 88/05/13 11:08:04 mento Exp $
- .IP \fIpattern\fP 1i
- Specifies the null-terminated pattern string that can contain wildcard
- characters.
- .IP \fImaxnames\fP 1i
- Specifies the maximum number of names to be returned.
- .IP \fIactual_count_return\fP 1i
- Returns the actual number of font names.
- .\" End marker code here
- .LP
- .\" $Header: XFontNames.d,v 1.2 88/06/11 07:50:36 mento Exp $
- The
- .PN XListFonts
- function returns an array of available font names
- (as controlled by the font search path; see
- .PN XSetFontPath )
- that match the string you passed to the pattern argument.
- The pattern string can contain any characters,
- but each asterisk (*) is a wildcard for any number of characters,
- and each question mark (?) is a wildcard for a single character.
- If the pattern string is not in the Host Portable Character Encoding
- the result is implementation dependent.
- Use of uppercase or lowercase does not matter.
- Each returned string is null-terminated.
- If the data returned by the server is in the Latin Portable Character Encoding,
- then the returned strings are in the Host Portable Character Encoding.
- Otherwise, the result is implementation dependent.
- If there are no matching font names,
- .PN XListFonts
- returns NULL.
- The client should call
- .PN XFreeFontNames
- when finished with the result to free the memory.
- .LP
- .sp
- To free a font name array, use
- .PN XFreeFontNames .
- .IN "XFreeFontNames" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XFrFntNames.f,v 1.1 88/02/26 10:00:15 mento Exp $
- XFreeFontNames\^(\^\fIlist\fP\^)
- .br
- char *\fIlist\fP\^[\^]\^;
- .FN
- .\" $Header: list.a,v 1.1 88/02/26 10:28:40 mento Exp $
- .IP \fIlist\fP 1i
- Specifies the array of strings you want to free.
- .\" End marker code here
- .LP
- .\" $Header: XFrFntNames.d,v 1.2 88/04/23 09:33:05 mento Exp $
- The
- .PN XFreeFontNames
- function frees the array and strings returned by
- .PN XListFonts
- or
- .PN XListFontsWithInfo .
- .LP
- .sp
- To obtain the names and information about available fonts, use
- .PN XListFontsWithInfo .
- .IN "XListFontsWithInfo" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- char **XListFontsWithInfo\^(\^\fIdisplay\fP, \fIpattern\fP, \fImaxnames\fP, \fIcount_return\fP, \fIinfo_return\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- char *\fIpattern\fP\^;
- .br
- int \fImaxnames\fP\^;
- .br
- int *\fIcount_return\fP\^;
- .br
- XFontStruct **\fIinfo_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.
- .\" $Header: pattern.a,v 1.4 88/05/13 11:08:04 mento Exp $
- .IP \fIpattern\fP 1i
- Specifies the null-terminated pattern string that can contain wildcard
- characters.
- .IP \fImaxnames\fP 1i
- Specifies the maximum number of names to be returned.
- .IP \fIcount_return\fP 1i
- Returns the actual number of matched font names.
- .IP \fIinfo_return\fP 1i
- Returns the font information.
- .\" End marker code here
- .LP
- .\" $Header: XFNameInfo.d,v 1.3 88/06/11 07:50:14 mento Exp $
- The
- .PN XListFontsWithInfo
- function returns a list of font names that match the specified pattern and their
- associated font information.
- The list of names is limited to size specified by maxnames.
- The information returned for each font is identical to what
- .PN XLoadQueryFont
- would return except that the per-character metrics are not returned.
- The pattern string can contain any characters,
- but each asterisk (*) is a wildcard for any number of characters,
- and each question mark (?) is a wildcard for a single character.
- If the pattern string is not in the Host Portable Character Encoding
- the result is implementation dependent.
- Use of uppercase or lowercase does not matter.
- Each returned string is null-terminated.
- If the data returned by the server is in the Latin Portable Character Encoding,
- then the returned strings are in the Host Portable Character Encoding.
- Otherwise, the result is implementation dependent.
- If there are no matching font names,
- .PN XListFontsWithInfo
- returns NULL.
- .LP
- To free only the allocated name array,
- the client should call
- .PN XFreeFontNames .
- To free both the name array and the font information array,
- or to free just the font information array,
- the client should call
- .PN XFreeFontInfo .
- .LP
- .sp
- To free the the font information array, use
- .PN XFreeFontInfo .
- .IN "XFreeFontInfo" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XFreeFontInfo(\^\fInames\fP, \fIfree_info\fP, \fIactual_count\fP\^)
- .br
- char **\fInames\fP\^;
- .br
- XFontStruct *\fIfree_info\fP;
- .br
- int \fIactual_count\fP\^;
- .FN
- .IP \fInames\fP 1i
- Specifies the list of font names returned by
- .PN XListFontsWithInfo .
- .IP \fIfree_info\fP 1i
- Specifies the font information returned by
- .PN XListFontsWithInfo .
- .IP \fIactual_count\fP 1i
- Specifies the actual number of matched font names returned by
- .PN XListFontsWithInfo .
- .\" End marker code here
- .LP
- .\" $Header: XFFontInfo.d,v 1.1 88/02/26 10:41:55 mento Exp $
- The
- .PN XFreeFontInfo
- function frees the the font information array.
- To free an
- .PN XFontStruct
- structure without closing the font,
- call
- .PN XFreeFontInfo
- with the names argument specified as NULL.
- .NH 3
- Computing Character String Sizes
- .XS
- \*(SN Computing Character String Sizes
- .XE
- .LP
- Xlib provides functions that you can use to compute the width,
- the logical extents,
- and the server information about 8-bit and 2-byte text strings.
- .IN "XTextWidth"
- .IN "XTextWidth16"
- The width is computed by adding the character widths of all the characters.
- It does not matter if the font is an 8-bit or 2-byte font.
- These functions return the sum of the character metrics, in pixels.
- .LP
- .sp
- To determine the width of an 8-bit character string, use
- .PN XTextWidth .
- .IN "XTextWidth" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XTextWidth.f,v 1.1 88/02/26 10:04:00 mento Exp $
- int XTextWidth\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^)
- .br
- XFontStruct *\fIfont_struct\fP\^;
- .br
- char *\fIstring\fP\^;
- .br
- int \fIcount\fP\^;
- .FN
- .\" $Header: ptr_width.a,v 1.1 88/02/26 10:30:47 mento Exp $
- .IP \fIfont_struct\fP 1i
- Specifies the font used for the width computation.
- .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
- .IP \fIstring\fP 1i
- Specifies the character string.
- .IP \fIcount\fP 1i
- Specifies the character count in the specified string.
- .\" End marker code here
- .LP
- .sp
- To determine the width of a 2-byte character string, use
- .PN XTextWidth16 .
- .IN "XTextWidth16" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XTextWidth16.f,v 1.1 88/02/26 10:04:01 mento Exp $
- int XTextWidth16\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^)
- .br
- XFontStruct *\fIfont_struct\fP\^;
- .br
- XChar2b *\fIstring\fP\^;
- .br
- int \fIcount\fP\^;
- .FN
- .\" $Header: ptr_width.a,v 1.1 88/02/26 10:30:47 mento Exp $
- .IP \fIfont_struct\fP 1i
- Specifies the font used for the width computation.
- .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
- .IP \fIstring\fP 1i
- Specifies the character string.
- .IP \fIcount\fP 1i
- Specifies the character count in the specified string.
- .\" End marker code here
- .NH 3
- Computing Logical Extents
- .XS
- \*(SN Computing Logical Extents
- .XE
- .LP
- To compute the bounding box of an 8-bit character string in a given font, use
- .PN XTextExtents .
- .IN "XTextExtents" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XTextExtents\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \
- \fIdirection_return\fP, \fIfont_ascent_return\fP,
- .br
- \fIfont_descent_return\fP, \fIoverall_return\fP\^)
- .br
- XFontStruct *\fIfont_struct\fP\^;
- .br
- char *\fIstring\fP\^;
- .br
- int \fInchars\fP\^;
- .br
- int *\fIdirection_return\fP\^;
- .br
- int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
- .br
- XCharStruct *\fIoverall_return\fP\^;
-
- .FN
- .IP \fIfont_struct\fP 1i
- Specifies the
- .PN XFontStruct
- structure.
- .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
- .IP \fIstring\fP 1i
- Specifies the character string.
- .IP \fInchars\fP 1i
- Specifies the number of characters in the character string.
- .IP \fIdirection_return\fP 1i
- Returns the value of the direction hint
- .Pn ( FontLeftToRight
- or
- .PN FontRightToLeft ).
- .IP \fIfont_ascent_return\fP 1i
- Returns the font ascent.
- .IP \fIfont_descent_return\fP 1i
- Returns the font descent.
- .IP \fIoverall_return\fP 1i
- Returns the overall size in the specified
- .PN XCharStruct
- structure.
- .\" End marker code here
- .LP
- .sp
- To compute the bounding box of a 2-byte character string in a given font, use
- .PN XTextExtents16 .
- .IN "XTextExtents16" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XTextExtents16\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \
- \fIdirection_return\fP, \fIfont_ascent_return\fP,
- .br
- \fIfont_descent_return\fP, \fIoverall_return\fP\^)
- .br
- XFontStruct *\fIfont_struct\fP\^;
- .br
- XChar2b *\fIstring\fP\^;
- .br
- int \fInchars\fP\^;
- .br
- int *\fIdirection_return\fP\^;
- .br
- int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
- .br
- XCharStruct *\fIoverall_return\fP\^;
-
- .FN
- .IP \fIfont_struct\fP 1i
- Specifies the
- .PN XFontStruct
- structure.
- .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
- .IP \fIstring\fP 1i
- Specifies the character string.
- .IP \fInchars\fP 1i
- Specifies the number of characters in the character string.
- .IP \fIdirection_return\fP 1i
- Returns the value of the direction hint
- .Pn ( FontLeftToRight
- or
- .PN FontRightToLeft ).
- .IP \fIfont_ascent_return\fP 1i
- Returns the font ascent.
- .IP \fIfont_descent_return\fP 1i
- Returns the font descent.
- .IP \fIoverall_return\fP 1i
- Returns the overall size in the specified
- .PN XCharStruct
- structure.
- .\" End marker code here
- .LP
- .\" $Header: XTextExt.d,v 1.2 88/06/11 07:54:02 mento Exp $
- The
- .PN XTextExtents
- and
- .PN XTextExtents16
- functions
- perform the size computation locally and, thereby,
- avoid the round-trip overhead of
- .PN XQueryTextExtents
- and
- .PN XQueryTextExtents16 .
- Both functions return an
- .PN XCharStruct
- structure, whose members are set to the values as follows.
- .LP
- The ascent member is set to the maximum of the ascent metrics of all
- characters in the string.
- The descent member is set to the maximum of the descent metrics.
- The width member is set to the sum of the character-width metrics of all
- characters in the string.
- For each character in the string,
- let W be the sum of the character-width metrics of all characters preceding
- it in the string.
- Let L be the left-side-bearing metric of the character plus W.
- Let R be the right-side-bearing metric of the character plus W.
- The lbearing member is set to the minimum L of all characters in the string.
- The rbearing member is set to the maximum R.
- .LP
- For fonts defined with linear indexing rather than 2-byte matrix indexing,
- each
- .PN XChar2b
- structure is interpreted as a 16-bit number with byte1 as the
- most-significant byte.
- If the font has no defined default character,
- undefined characters in the string are taken to have all zero metrics.
- .NH 3
- Querying Character String Sizes
- .XS
- \*(SN Querying Character String Sizes
- .XE
- .LP
- To query the server for the bounding box of an 8-bit character string in a
- given font, use
- .PN XQueryTextExtents .
- .IN "XQueryTextExtents" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XQueryTextExtents\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \
- \fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP,
- .br
- \fIfont_descent_return\fP, \fIoverall_return\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- XID \fIfont_ID\fP\^;
- .br
- char *\fIstring\fP\^;
- .br
- int \fInchars\fP\^;
- .br
- int *\fIdirection_return\fP\^;
- .br
- int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
- .br
- XCharStruct *\fIoverall_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.
- .IP \fIfont_ID\fP 1i
- Specifies either the font ID or the
- .PN GContext
- ID that contains the font.
- .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
- .IP \fIstring\fP 1i
- Specifies the character string.
- .IP \fInchars\fP 1i
- Specifies the number of characters in the character string.
- .IP \fIdirection_return\fP 1i
- Returns the value of the direction hint
- .Pn ( FontLeftToRight
- or
- .PN FontRightToLeft ).
- .IP \fIfont_ascent_return\fP 1i
- Returns the font ascent.
- .IP \fIfont_descent_return\fP 1i
- Returns the font descent.
- .IP \fIoverall_return\fP 1i
- Returns the overall size in the specified
- .PN XCharStruct
- structure.
- .\" End marker code here
- .LP
- .sp
- To query the server for the bounding box of a 2-byte character string
- in a given font, use
- .PN XQueryTextExtents16 .
- .IN "XQueryTextExtents16" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XQueryTextExtents16\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \
- \fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP,
- .br
- \fIfont_descent_return\fP, \fIoverall_return\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- XID \fIfont_ID\fP\^;
- .br
- XChar2b *\fIstring\fP\^;
- .br
- int \fInchars\fP\^;
- .br
- int *\fIdirection_return\fP\^;
- .br
- int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
- .br
- XCharStruct *\fIoverall_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.
- .IP \fIfont_ID\fP 1i
- Specifies either the font ID or the
- .PN GContext
- ID that contains the font.
- .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
- .IP \fIstring\fP 1i
- Specifies the character string.
- .IP \fInchars\fP 1i
- Specifies the number of characters in the character string.
- .IP \fIdirection_return\fP 1i
- Returns the value of the direction hint
- .Pn ( FontLeftToRight
- or
- .PN FontRightToLeft ).
- .IP \fIfont_ascent_return\fP 1i
- Returns the font ascent.
- .IP \fIfont_descent_return\fP 1i
- Returns the font descent.
- .IP \fIoverall_return\fP 1i
- Returns the overall size in the specified
- .PN XCharStruct
- structure.
- .\" End marker code here
- .LP
- .\" $Header: XQryTExts.d,v 1.2 88/06/11 07:52:33 mento Exp $
- The
- .PN XQueryTextExtents
- and
- .PN XQueryTextExtents16
- functions return the bounding box of the specified 8-bit and 16-bit
- character string in the specified font or the font contained in the
- specified GC.
- These functions query the X server and, therefore, suffer the round-trip
- overhead that is avoided by
- .PN XTextExtents
- and
- .PN XTextExtents16 .
- Both functions return a
- .PN XCharStruct
- structure, whose members are set to the values as follows.
- .LP
- The ascent member is set to the maximum of the ascent metrics
- of all characters in the string.
- The descent member is set to the maximum of the descent metrics.
- The width member is set to the sum of the character-width metrics
- of all characters in the string.
- For each character in the string,
- let W be the sum of the character-width metrics of all characters preceding
- it in the string.
- Let L be the left-side-bearing metric of the character plus W.
- Let R be the right-side-bearing metric of the character plus W.
- The lbearing member is set to the minimum L of all characters in the string.
- The rbearing member is set to the maximum R.
- .LP
- For fonts defined with linear indexing rather than 2-byte matrix indexing,
- each
- .PN XChar2b
- structure is interpreted as a 16-bit number with byte1 as the
- most-significant byte.
- If the font has no defined default character,
- undefined characters in the string are taken to have all zero metrics.
- .LP
- Characters with all zero metrics are ignored.
- If the font has no defined default_char,
- the undefined characters in the string are also ignored.
- .LP
- .PN XQueryTextExtents
- and
- .PN XQueryTextExtents16
- can generate
- .PN BadFont
- and
- .PN BadGC
- errors.
- .NH 2
- Drawing Text
- .XS
- \*(SN Drawing Text
- .XE
- .LP
- This section discusses how to draw:
- .IP \(bu 5
- Complex text
- .IP \(bu 5
- Text characters
- .IP \(bu 5
- Image text characters
- .LE
- .LP
- The fundamental text functions
- .PN XDrawText
- and
- .PN XDrawText16
- use the following structures.
- .LP
- .IN "XTextItem" "" "@DEF@"
- .\" Start marker code here
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- char *chars; /* pointer to string */
- int nchars; /* number of characters */
- int delta; /* delta between strings */
- Font font; /* Font to print it in, None don't change */
- } XTextItem;
- .De
- .LP
- .IN "XTextItem16" "" "@DEF@"
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- XChar2b *chars; /* pointer to two-byte characters */
- int nchars; /* number of characters */
- int delta; /* delta between strings */
- Font font; /* font to print it in, None don't change */
- } XTextItem16;
- .De
- .\" End marker code here
- .LP
- If the font member is not
- .PN None ,
- the font is changed before printing and also is stored in the GC.
- If an error was generated during text drawing,
- the previous items may have been drawn.
- The baseline of the characters are drawn starting at the x and y
- coordinates that you pass in the text drawing functions.
- .LP
- For example, consider the background rectangle drawn by
- .PN XDrawImageString .
- If you want the upper-left corner of the background rectangle
- to be at pixel coordinate (x,y), pass the (x,y + ascent)
- as the baseline origin coordinates to the text functions.
- The ascent is the font ascent, as given in the
- .PN XFontStruct
- structure.
- If you want the lower-left corner of the background rectangle
- to be at pixel coordinate (x,y), pass the (x,y \- descent + 1)
- as the baseline origin coordinates to the text functions.
- The descent is the font descent, as given in the
- .PN XFontStruct
- structure.
- .NH 3
- Drawing Complex Text
- .XS
- \*(SN Drawing Complex Text
- .XE
- .LP
- .IN "Text" "drawing"
- .IN "Drawing" "text items"
- .LP
- To draw 8-bit characters in a given drawable, use
- .PN XDrawText .
- .IN "XDrawText" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XPolyText.f,v 1.1 88/02/26 10:01:57 mento Exp $
- XDrawText\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- XTextItem *\fIitems\fP\^;
- .br
- int \fInitems\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .ds Xy , which are relative to the origin of the specified drawable \
- and define the origin of the first character
- .\" $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.
- .\" $Header: items.a,v 1.1 88/02/26 10:28:21 mento Exp $
- .IP \fIitems\fP 1i
- Specifies an array of text items.
- .\" $Header: nitems.a,v 1.1 88/02/26 10:29:33 mento Exp $
- .IP \fInitems\fP 1i
- Specifies the number of text items in the array.
- .\" End marker code here
- .LP
- .sp
- To draw 2-byte characters in a given drawable, use
- .PN XDrawText16 .
- .IN "XDrawText16" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XPolyText16.f,v 1.1 88/02/26 10:01:59 mento Exp $
- XDrawText16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- XTextItem16 *\fIitems\fP\^;
- .br
- int \fInitems\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .ds Xy , which are relative to the origin of the specified drawable \
- and define the origin of the first character
- .\" $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.
- .\" $Header: items.a,v 1.1 88/02/26 10:28:21 mento Exp $
- .IP \fIitems\fP 1i
- Specifies an array of text items.
- .\" $Header: nitems.a,v 1.1 88/02/26 10:29:33 mento Exp $
- .IP \fInitems\fP 1i
- Specifies the number of text items in the array.
- .\" End marker code here
- .LP
- .\" $Header: XPolyText.d,v 1.2 88/06/11 07:52:25 mento Exp $
- The
- .PN XDrawText16
- function is similar to
- .PN XDrawText
- except that it uses 2-byte or 16-bit characters.
- Both functions allow complex spacing and font shifts between counted strings.
- .LP
- Each text item is processed in turn.
- A font member other than
- .PN None
- in an item causes the font to be stored in the GC
- and used for subsequent text.
- A text element delta specifies an additional change
- in the position along the x axis before the string is drawn.
- The delta is always added to the character origin
- and is not dependent on any characteristics of the font.
- Each character image, as defined by the font in the GC, is treated as an
- additional mask for a fill operation on the drawable.
- The drawable is modified only where the font character has a bit set to 1.
- If a text item generates a
- .PN BadFont
- error, the previous text items may have been drawn.
- .LP
- For fonts defined with linear indexing rather than 2-byte matrix indexing,
- each
- .PN XChar2b
- structure is interpreted as a 16-bit number with byte1 as the
- most-significant byte.
- .LP
- Both functions use these GC components:
- function, plane-mask, fill-style, font, subwindow-mode,
- clip-x-origin, clip-y-origin, and clip-mask.
- They also use these GC mode-dependent components:
- foreground, background, tile, stipple, tile-stipple-x-origin,
- and tile-stipple-y-origin.
- .LP
- .PN XDrawText
- and
- .PN XDrawText16
- can generate
- .PN BadDrawable ,
- .PN BadFont ,
- .PN BadGC ,
- and
- .PN BadMatch
- errors.
- .NH 3
- Drawing Text Characters
- .XS
- \*(SN Drawing Text Characters
- .XE
- .LP
- .IN "Strings" "drawing"
- .IN "Drawing" "strings"
- To draw 8-bit characters in a given drawable, use
- .PN XDrawString .
- .IN "XDrawString" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XText.f,v 1.1 88/02/26 10:03:22 mento Exp $
- XDrawString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- char *\fIstring\fP\^;
- .br
- int \fIlength\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .ds Xy , which are relative to the origin of the specified drawable \
- and define the origin of the first character
- .\" $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.
- .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
- .IP \fIstring\fP 1i
- Specifies the character string.
- .\" $Header: length.a,v 1.1 88/02/26 10:28:36 mento Exp $
- .IP \fIlength\fP 1i
- Specifies the number of characters in the string argument.
- .\" End marker code here
- .LP
- .sp
- To draw 2-byte characters in a given drawable, use
- .PN XDrawString16 .
- .IN "XDrawString16" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XText16.f,v 1.1 88/02/26 10:03:57 mento Exp $
- XDrawString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- XChar2b *\fIstring\fP\^;
- .br
- int \fIlength\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .ds Xy , which are relative to the origin of the specified drawable \
- and define the origin of the first character
- .\" $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.
- .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
- .IP \fIstring\fP 1i
- Specifies the character string.
- .\" $Header: length.a,v 1.1 88/02/26 10:28:36 mento Exp $
- .IP \fIlength\fP 1i
- Specifies the number of characters in the string argument.
- .\" End marker code here
- .LP
- .\" $Header: XText.d,v 1.2 88/06/11 07:54:01 mento Exp $
- Each character image, as defined by the font in the GC, is treated as an
- additional mask for a fill operation on the drawable.
- The drawable is modified only where the font character has a bit set to 1.
- For fonts defined with 2-byte matrix indexing
- and used with
- .PN XDrawString16 ,
- each byte is used as a byte2 with a byte1 of zero.
- .LP
- Both functions use these GC components:
- function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin,
- clip-y-origin, and clip-mask.
- They also use these GC mode-dependent components:
- foreground, background, tile, stipple, tile-stipple-x-origin,
- and tile-stipple-y-origin.
- .LP
- .PN XDrawString
- and
- .PN XDrawString16
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- and
- .PN BadMatch
- errors.
- .NH 3
- Drawing Image Text Characters
- .XS
- \*(SN Drawing Image Text Characters
- .XE
- .LP
- .IN "Image text" "drawing"
- .IN "Drawing" "image text"
- Some applications, in particular terminal emulators, need to
- print image text in which both the foreground and background bits of
- each character are painted.
- This prevents annoying flicker on many displays.
- .IN "XDrawImageString"
- .IN "XDrawImageString16"
- .LP
- .sp
- To draw 8-bit image text characters in a given drawable, use
- .PN XDrawImageString .
- .IN "XDrawImageString" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XImageText.f,v 1.1 88/02/26 10:01:09 mento Exp $
- XDrawImageString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- char *\fIstring\fP\^;
- .br
- int \fIlength\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .ds Xy , which are relative to the origin of the specified drawable \
- and define the origin of the first character
- .\" $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.
- .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
- .IP \fIstring\fP 1i
- Specifies the character string.
- .\" $Header: length.a,v 1.1 88/02/26 10:28:36 mento Exp $
- .IP \fIlength\fP 1i
- Specifies the number of characters in the string argument.
- .\" End marker code here
- .LP
- .sp
- To draw 2-byte image text characters in a given drawable, use
- .PN XDrawImageString16 .
- .IN "XDrawImageString16" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XImageText16.f,v 1.1 88/02/26 10:01:10 mento Exp $
- XDrawImageString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- XChar2b *\fIstring\fP\^;
- .br
- int \fIlength\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .ds Xy , which are relative to the origin of the specified drawable \
- and define the origin of the first character
- .\" $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.
- .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
- .IP \fIstring\fP 1i
- Specifies the character string.
- .\" $Header: length.a,v 1.1 88/02/26 10:28:36 mento Exp $
- .IP \fIlength\fP 1i
- Specifies the number of characters in the string argument.
- .\" End marker code here
- .LP
- .\" $Header: XImageText.d,v 1.2 88/06/11 07:51:40 mento Exp $
- The
- .PN XDrawImageString16
- function is similar to
- .PN XDrawImageString
- except that it uses 2-byte or 16-bit characters.
- Both functions also use both the foreground and background pixels
- of the GC in the destination.
- .LP
- The effect is first to fill a
- destination rectangle with the background pixel defined in the GC and then
- to paint the text with the foreground pixel.
- The upper-left corner of the filled rectangle is at:
- .LP
- .Ds
- [x, y \- font-ascent]
- .De
- .LP
- The width is:
- .LP
- .Ds
- overall-width
- .De
- .LP
- The height is:
- .LP
- .Ds
- font-ascent + font-descent
- .De
- .LP
- The overall-width, font-ascent, and font-descent
- are as would be returned by
- .PN XQueryTextExtents
- using gc and string.
- The function and fill-style defined in the GC are ignored for these functions.
- The effective function is
- .PN GXcopy ,
- and the effective fill-style is
- .PN FillSolid .
- .LP
- For fonts defined with 2-byte matrix indexing
- and used with
- .PN XDrawImageString ,
- each byte is used as a byte2 with a byte1 of zero.
- .LP
- Both functions use these GC components:
- plane-mask, foreground, background, font, subwindow-mode, clip-x-origin,
- clip-y-origin, and clip-mask.
- .LP
- .PN XDrawImageString
- and
- .PN XDrawImageString16
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- and
- .PN BadMatch
- errors.
- .LP
- .NH 2
- Transferring Images between Client and Server
- .XS
- \*(SN Transferring Images between Client and Server
- .XE
- .LP
- Xlib provides functions that you can use to transfer images between a client
- and the server.
- Because the server may require diverse data formats,
- Xlib provides an image object that fully describes the data in memory
- and that provides for basic operations on that data.
- You should reference the data
- through the image object rather than referencing the data directly.
- However, some implementations of the Xlib library may efficiently deal with
- frequently used data formats by replacing
- functions in the procedure vector with special case functions.
- Supported operations include destroying the image, getting a pixel,
- storing a pixel, extracting a subimage of an image, and adding a constant
- to an image (see section 16.5).
- .LP
- All the image manipulation functions discussed in this section make use of
- the
- .PN XImage
- data structure,
- which describes an image as it exists in the client's memory.
- .LP
- .IN "XImage" "" "@DEF@"
- .\" Start marker code here
- .Ds 0
- .TA .5i 1i 3i
- .ta .5i 1i 3i
- typedef struct _XImage {
- int width, height; /* size of image */
- int xoffset; /* number of pixels offset in X direction */
- int format; /* XYBitmap, XYPixmap, ZPixmap */
- char *data; /* pointer to image data */
- int byte_order; /* data byte order, LSBFirst, MSBFirst */
- int bitmap_unit; /* quant. of scanline 8, 16, 32 */
- int bitmap_bit_order; /* LSBFirst, MSBFirst */
- int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */
- int depth; /* depth of image */
- int bytes_per_line; /* accelerator to next scanline */
- int bits_per_pixel; /* bits per pixel (ZPixmap) */
- unsigned long red_mask; /* bits in z arrangement */
- unsigned long green_mask;
- unsigned long blue_mask;
- XPointer obdata; /* hook for the object routines to hang on */
- struct funcs { /* image manipulation routines */
- struct _XImage *(*create_image)();
- int (*destroy_image)();
- unsigned long (*get_pixel)();
- int (*put_pixel)();
- struct _XImage *(*sub_image)();
- int (*add_pixel)();
- } f;
- } XImage;
- .De
- .\" End marker code here
- .LP
- You may request that some of the members (for example,
- height, width, and xoffset) be
- changed when the image is sent to the server.
- That is, you may send a subset of the image.
- Other members (for example, byte_order, bitmap_unit, and so forth)
- are characteristics of both the image and the server.
- If these members
- differ between the image and the server,
- .PN XPutImage
- makes the appropriate
- conversions.
- .\"If the image is formatted as an XYPixmap,
- .\"(that is, the format member is set to
- .\".PN XYPixmap ),
- The first byte of the first scanline of
- plane n is located at the address (data + (n * height * bytes_per_line)).
- .LP
- .sp
- To combine an image in memory with a rectangle of a drawable on the display,
- use
- .PN XPutImage .
- .IN "XPutImage" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XPutImage.f,v 1.2 88/08/23 15:07:57 mento Exp $
- XPutImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIimage\fP\^, \fIsrc_x\fP, \fIsrc_y\fP, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- GC \fIgc\fP\^;
- .br
- XImage *\fIimage\fP\^;
- .br
- int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
- .br
- int \fIdest_x\fP\^, \fIdest_y\fP\^;
- .br
- unsigned int \fIwidth\fP\^, \fIheight\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
- .IP \fIgc\fP 1i
- Specifies the GC.
- .\" $Header: image.a,v 1.1 88/02/26 10:28:13 mento Exp $
- .IP \fIimage\fP 1i
- Specifies the image you want combined with the rectangle.
- .IP \fIsrc_x\fP 1i
- Specifies the offset in X from the left edge of the image defined
- by the
- .PN XImage
- data structure.
- .IP \fIsrc_y\fP 1i
- Specifies the offset in Y from the top edge of the image defined
- by the
- .PN XImage
- data structure.
- .ds Dx , which are relative to the origin of the drawable \
- and are the coordinates of the subimage
- .\" $Header: dstxy_gen.a,v 1.2 88/08/04 11:09:55 mento Exp $
- .IP \fIdest_x\fP 1i
- .br
- .ns
- .IP \fIdest_y\fP 1i
- Specify the x and y coordinates\*(Dx.
- .ds Wh \ of the subimage, which define the dimensions of the rectangle
- .\" $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.
- .\" End marker code here
- .LP
- .\" $Header: XPutImage.d,v 1.3 88/08/18 09:43:13 mento Exp $
- The
- .PN XPutImage
- function
- combines an image in memory with a rectangle of the specified drawable.
- If
- .PN XYBitmap
- format is used, the depth of the image must be one,
- or a
- .PN BadMatch
- error results.
- The foreground pixel in the GC defines the source for the one bits in the image,
- and the background pixel defines the source for the zero bits.
- For
- .PN XYPixmap
- and
- .PN ZPixmap ,
- the depth of the image must match the depth of the drawable,
- or a
- .PN BadMatch
- error results.
- The section of the image defined by the src_x, src_y, width, and height
- arguments is drawn on the specified part of the drawable.
- .LP
- This function uses these GC components:
- function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin,
- and clip-mask.
- It also uses these GC mode-dependent components:
- foreground and background.
- .LP
- .PN XPutImage
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- .PN BadMatch ,
- and
- .PN BadValue
- errors.
- .LP
- .sp
- To return the contents of a rectangle in a given drawable on the display,
- use
- .PN XGetImage .
- This function specifically supports rudimentary screen dumps.
- .IN "XGetImage" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XGetImage.f,v 1.1 88/02/26 10:00:47 mento Exp $
- XImage *XGetImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- unsigned int \fIwidth\fP\^, \fIheight\fP\^;
- .br
- unsigned long \fIplane_mask\fP\^;
- .br
- int \fIformat\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .ds Xy , which are relative to the origin of the drawable \
- and define the upper-left corner of the rectangle
- .\" $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.
- .ds Wh \ of the subimage, which define the dimensions of the rectangle
- .\" $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: plane_mask.a,v 1.1 88/02/26 10:30:28 mento Exp $
- .IP \fIplane_mask\fP 1i
- Specifies the plane mask.
- .\" *** JIM: NEED MORE INFO FOR THIS. ***
- .IP \fIformat\fP 1i
- Specifies the format for the image.
- You can pass
- .PN XYPixmap
- or
- .PN ZPixmap .
- .\" End marker code here
- .LP
- .\" $Header: XGetImage.d,v 1.3 88/08/18 09:45:47 mento Exp $
- The
- .PN XGetImage
- function returns a pointer to an
- .PN XImage
- structure.
- This structure provides you with the contents of the specified rectangle of
- the drawable in the format you specify.
- If the format argument is
- .PN XYPixmap ,
- the image contains only the bit planes you passed to the plane_mask argument.
- If the plane_mask argument only requests a subset of the planes of the
- display, the depth of the returned image will be the number of planes
- requested.
- If the format argument is
- .PN ZPixmap ,
- .PN XGetImage
- returns as zero the bits in all planes not
- specified in the plane_mask argument.
- The function performs no range checking on the values in plane_mask and ignores
- extraneous bits.
- .LP
- .PN XGetImage
- returns the depth of the image to the depth member of the
- .PN XImage
- structure.
- The depth of the image is as specified when the drawable was created,
- except when getting a subset of the planes in
- .PN XYPixmap
- format, when the depth is given by the number of bits set to 1 in plane_mask.
- .LP
- If the drawable is a pixmap,
- the given rectangle must be wholly contained within the pixmap,
- or a
- .PN BadMatch
- error results.
- If the drawable is a window,
- the window must be viewable,
- and it must be the case that if there were no inferiors or overlapping windows,
- the specified rectangle of the window would be fully visible on the screen
- and wholly contained within the outside edges of the window,
- or a
- .PN BadMatch
- error results.
- Note that the borders of the window can be included and read with
- this request.
- If the window has backing-store, the backing-store contents are
- returned for regions of the window that are obscured by noninferior
- windows.
- If the window does not have backing-store,
- the returned contents of such obscured regions are undefined.
- The returned contents of visible regions of inferiors
- of a different depth than the specified window's depth are also undefined.
- The pointer cursor image is not included in the returned contents.
- If a problem occurs,
- .PN XGetImage
- returns NULL.
- .LP
- .PN XGetImage
- can generate
- .PN BadDrawable ,
- .PN BadMatch ,
- and
- .PN BadValue
- errors.
- .sp
- To copy the contents of a rectangle on the display
- to a location within a preexisting image structure, use
- .PN XGetSubImage .
- .IN "XGetSubImage" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XGetSImage.f,v 1.1 88/02/26 10:00:58 mento Exp $
- XImage *XGetSubImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^, \fIdest_image\fP\^, \fIdest_x\fP\^,
- .br
- \fIdest_y\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Drawable \fId\fP\^;
- .br
- int \fIx\fP\^, \fIy\fP\^;
- .br
- unsigned int \fIwidth\fP\^, \fIheight\fP\^;
- .br
- unsigned long \fIplane_mask\fP\^;
- .br
- int \fIformat\fP\^;
- .br
- XImage *\fIdest_image\fP\^;
- .br
- int \fIdest_x\fP\^, \fIdest_y\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.a,v 1.1 88/02/26 10:04:25 mento Exp $
- .IP \fId\fP 1i
- Specifies the drawable.
- .ds Xy , which are relative to the origin of the drawable \
- and define the upper-left corner of the rectangle
- .\" $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.
- .ds Wh \ of the subimage, which define the dimensions of the rectangle
- .\" $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: plane_mask.a,v 1.1 88/02/26 10:30:28 mento Exp $
- .IP \fIplane_mask\fP 1i
- Specifies the plane mask.
- .\" *** JIM: NEED MORE INFO FOR THIS. ***
- .IP \fIformat\fP 1i
- Specifies the format for the image.
- You can pass
- .PN XYPixmap
- or
- .PN ZPixmap .
- .IP \fIdest_image\fP 1i
- Specify the destination image.
- .ds Dx , which are relative to the origin of the destination rectangle, \
- specify its upper-left corner, and determine where the subimage \
- is placed in the destination image
- .\" $Header: dstxy_gen.a,v 1.2 88/08/04 11:09:55 mento Exp $
- .IP \fIdest_x\fP 1i
- .br
- .ns
- .IP \fIdest_y\fP 1i
- Specify the x and y coordinates\*(Dx.
- .\" End marker code here
- .LP
- .\" $Header: XGetSImage.d,v 1.6 88/08/21 06:57:22 mento Exp $
- The
- .PN XGetSubImage
- function updates dest_image with the specified subimage in the same manner as
- .PN XGetImage .
- If the format argument is
- .PN XYPixmap ,
- the image contains only the bit planes you passed to the plane_mask argument.
- If the format argument is
- .PN ZPixmap ,
- .PN XGetSubImage
- returns as zero the bits in all planes not
- specified in the plane_mask argument.
- The function performs no range checking on the values in plane_mask and ignores
- extraneous bits.
- As a convenience,
- .PN XGetSubImage
- returns a pointer to the same
- .PN XImage
- structure specified by dest_image.
- .LP
- The depth of the destination
- .PN XImage
- structure must be the same as that of the drawable.
- If the specified subimage does not fit at the specified location
- on the destination image, the right and bottom edges are clipped.
- If the drawable is a pixmap,
- the given rectangle must be wholly contained within the pixmap,
- or a
- .PN BadMatch
- error results.
- If the drawable is a window,
- the window must be viewable,
- and it must be the case that if there were no inferiors or overlapping windows,
- the specified rectangle of the window would be fully visible on the screen
- and wholly contained within the outside edges of the window,
- or a
- .PN BadMatch
- error results.
- If the window has backing-store,
- then the backing-store contents are returned for regions of the window
- that are obscured by noninferior windows.
- If the window does not have backing-store,
- the returned contents of such obscured regions are undefined.
- The returned contents of visible regions of inferiors
- of a different depth than the specified window's depth are also undefined.
- If a problem occurs,
- .PN XGetSubImage
- returns NULL.
- .LP
- .PN XGetSubImage
- can generate
- .PN BadDrawable ,
- .PN BadGC ,
- .PN BadMatch ,
- and
- .PN BadValue
- errors.
- .bp
-