.\".U7
.\".UT "Version 10 Compatibilty Functions" B
\&
.sp 1
.ce 3
\s+1\fBAppendix B\fP\s-1

\s+1\fBVersion 10 Compatibility Functions\fP\s-1
.sp 2
.na
.SH
Drawing and Filling Polygons and Curves
.LP
.XS
Appendix B - Version 10 Compatibility Functions
.XE
Xlib provides functions with which you can draw or fill
arbitrary polygons or curves.  
These functions are provided mainly for compatibility with X10 
and have no server support.  
That is, they call other Xlib routines, not the server directly.  
Thus, if you just have straight lines to draw, using 
.PN XDrawLines 
.IN "XDrawLines"
or
.PN XDrawSegments 
.IN "XDrawSegments" 
is much faster.
.LP
The functions discussed here provide all the functionality of the X10
routines 
.PN XDraw , 
.IN "V10 Compatibility" "XDraw" 
.PN XDrawFilled , 
.IN "V10 Compatibility" "XDrawFilled"
.PN XDrawPatterned , 
.IN "V10 Compatibility" "XDrawPatterned" 
.PN XDrawDashed , 
.IN "V10 Compatibility" "XDrawDashed"
and
.PN XDrawTiled .  
.IN "V10 Compatibility" "XDrawTiled"
They are as compatible as possible given X11's new line drawing routines.  
One thing to note, however, is that
.PN VertexDrawLastPoint 
is no longer supported. 
Also, the error status returned is the opposite of what it was under X10 
(this is the X11 standard error status).  
.PN XAppendVertex 
and 
.PN XClearVertexFlag 
from
X10 also are not supported.
.LP
Just how the graphics context you use is set up actually
determines whether you get dashes or not, and so on.  
Lines are properly joined if they connect and include
the closing of a closed figure.  
(See XDrawLines in X 11 for further details.) 
The functions discussed here fail (return 0) only if they run out of memory
or are passed a Vertex list which has a Vertex with VertexStartClosed
set which is not followed by a Vertex with VertexEndClosed set.
.LP
.sp
To achieve the effects of the V10
.PN XDraw , 
.IN "V10 Compatibility" "XDraw" 
.PN XDrawDashed , 
.IN "V10 Compatibility" "XDrawDashed"
and 
.PN XDrawPatterned , 
.IN "V10 Compatibility" "XDrawPatterned" 
use
.PN XDraw .  
.IN "V10 Compatibility" "XDraw"  
.FD 0
#include <X11/X10.h>

Status XDraw(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^)
.br
	Display *\fIdisplay\fP\^;
.br
	Drawable \fId\fP\^;
.br
	GC \fIgc\fP\^;
.br
	Vertex *\fIvlist\fP\^;
.br
	int \fIvcount\fP\^;
.FN
.so ./Xsrc/display.a
.so ./Xsrc/d.a
.so ./Xsrc/gc.a
.IP \fIvlist\fP 1i
Specifies a pointer to the list of vertices which indicate what to draw.
.IP \fIvcount\fP 1i
Specifies how many vertices are in vlist.
.LP
.PN XDraw 
draws an arbitrary polygon or curve.  
The figure drawn is defined by the specified list of Vertexes (vlist).
The points are connected by lines as specified in the flags in the
vertex structure.
.LP
Each Vertex, as defined in
.PN <X11/Xlib.h> ,
is a structure with the following elements:
.DS 0
.TA .5i 1.5i
.ta .5i 1.5i
typedef struct _Vertex {
	short x,y;
	unsigned short flags;
} Vertex;
.DE
The x and y elements are the coordinates of the vertex 
that are relative to either the upper left inside corner of the drawable 
(if 
.PN VertexRelative 
is 0) or the previous vertex (if 
.PN VertexRelative 
is 1).
.LP
The flags, as defined in X10.h, are as follows:
.LP
.DS 0
.TA .5i 1.5i 2.5i
.ta .5i 1.5i 2.5i
VertexRelative	0x0001	else absolute
VertexDontDraw	0x0002	else draw
VertexCurved	0x0004	else straight
VertexStartClosed	0x0008	else not
VertexEndClosed	0x0010	else not
.DE
.IP \(bu 5
If 
.PN VertexRelative 
is not set,  
the coordinates are absolute (relative to the drawable).  
The first vertex must be an absolute vertex.
.IP \(bu 5
If
.PN VertexDontDraw 
is 1, 
no line or curve is drawn from the previous vertex to this one.  
This is analogous to picking up the pen and moving to another place 
before drawing another line.
.IP \(bu 5
If 
.PN VertexCurved 
is 1, 
a spline algorithm is used to draw a smooth curve from the previous vertex, 
through this one, to the next vertex.  
Otherwise, a straight line is drawn from the previous vertex to this one.  
It makes sense to set VertexCurved to 1 only if a
previous and next vertex are both defined (either explicitly in the
array, or through the definition of a closed curve--see below.)
.IP \(bu 5
It is permissible for 
.PN VertexDontDraw 
bits and 
.PN VertexCurved
bits to be both be 1. 
This is useful if you want to define the previous point for the smooth curve, 
but you do not want an actual curve drawing to start until this point.
.IP \(bu 5
If 
.PN VertexStartClosed 
is 1, 
then this point marks the beginning of a closed curve.  
This vertex must be followed later in the array by another vertex 
whose absolute coordinates are identical
and which has VertexEndClosed bit of 1.
The points in between from a cycle for the purpose of determining predecessor 
and successor vertices for the spline algorithm.
.LP
.PN XDraw 
uses the following graphics context 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.  This function also uses these graphics context
mode-dependent components: foreground, background, tile, stipple,
ts_s_origin, ts_y_origin, dash_offset, and dash_list.
.LP
.sp
To achieve the effects of the V10
.PN XDrawTiled 
.IN "V10 Compatibility" "XDrawTiled"
and 
.PN XDrawFilled , 
.IN "V10 Compatibility" "XDrawFilled"
use
.PN XDrawFilled .
.IN "V10 Compatibility" "XDrawFilled" .
.FD 0
#include <X11/X10.h>

Status XDrawFilled(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^)
.br
	Display *\fIdisplay\fP\^;
.br
	Drawable \fId\fP\^;
.br
	GC \fIgc\fP\^;
.br
	Vertex *\fIvlist\fP\^;
.br
	int \fIvcount\fP\^;
.FN
.so ./Xsrc/display.a
.so ./Xsrc/d.a
.so ./Xsrc/gc.a
.IP \fIvlist\fP 1i
Specifies a pointer to the list of vertices which indicate what to draw.
.IP \fIvcount\fP 1i
Specifies how many vertices are in vlist.
.LP
.PN XDrawFilled 
draws arbitrary polygons or curves and then fills them.
.LP
.PN XDrawFilled
uses the following graphics context 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.  This function also uses these graphics context
mode-dependent components: foreground, background, tile, stipple,
ts_s_origin, ts_y_origin, dash_offset, dash_list, fill_style and fill_rule.
.SH
Associating User Data with a Value
.LP
These functions have been replaced by the context management functions.
See Section 10.12 for further information.
It is often necessary to associate arbitrary information with resource IDs.
Xlib provides the AssocTable functions with which you can make
such an association.
.IN "Hash Lookup"
.IN "Window" "IDs"
.IN "Resource IDs"
.IN "XId"
Application programs often need to be able to easily refer to
their own data structures when an event arrives.
The 
.PN XAssocTable
system provides users of the X library with  a  method
of associating their own data structures with X resources.
(Bitmaps, Pixmaps, Fonts, Windows, and so on).
.LP
An 
.PN XAssocTable
can be used to type X resources.  
For example, the user
may wish to have three or four `types' of windows each with  different
properties. 
This can be accomplished by associating each X window ID
with a pointer to a `window property' data structure  defined  by  the
user.
A generic type has been defined in the X library for resource IDs.
.IN "XId"
It is called ``XId''.
.LP
There are a few  guidelines  that  should be observed when using an
.PN XAssocTable :
.IP \(bu 5
.IN "XId"
All  X IDs  are  relative  to  the  specified display.
Therefore,  if you are using multiple displays you need to be sure the
correct display is active before performing an 
.PN XAssocTable
operation.
.IN "V10 Compatibility" "XAssocTable"
.PN XAssocTable
imposes no restrictions on the number of X IDs per table,
the number of X IDs per display or the number of displays per table.
.IP \(bu 5
Because  of  the  hashing  scheme  used  by  the  association
mechanism the following rules for determining the size of 
.PN XAssocTables
should be followed.  
Associations will be  made  and  looked  up  more
efficiently  if  the  table  size  (number  of  buckets in the hashing
system) is a power of two and if there are not more than 8 XIds  per
bucket.
.LP
.sp
To return a pointer to a newly created assoctable, use 
.PN XCreateAssocTable .
.IN "V10 Compatibility" "XCreateAssocTable"
The definition of this function is:
.FD 0
.so ./Xsrc/XCreAscTbl.f
.FN
.so ./Xsrc/size.a
.LP
The "size" argument specifies the number of buckets in the 
hash system of
.PN XAssocTable .
For  reasons  of  efficiency  the number of buckets
should be a power of two.  Some size  suggestions  might  be:  use  32
buckets  per  100  objects;  a reasonable maximum number of object per
buckets is 8.   If  there  is  an  error  allocating  memory  for  the
.PN XAssocTable , 
a NULL pointer is returned. 
.LP
.sp
To create an entry in a specific assoctable, use 
.PN XMakeAssoc .
.IN "V10 Compatibility" "XMakeAssoc"
The definition of this function is:
.FD 0
.so ./Xsrc/XMakeAssoc.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/table.a
.so ./Xsrc/xid.a
.so ./Xsrc/data.a
.LP
.PN XMakeAssoc
inserts data into an 
.PN XAssocTable
keyed  on  an  XId.   
.IN "XId"
Data  is
inserted  into the table only once.  Redundant inserts are meaningless
and cause no problems.  The queue in each association bucket is sorted
from the lowest XId to the highest XId.
.LP
.sp
To obtain data from a specific assoctable, use 
.PN XLookUpAssoc .
.IN "V10 Compatibility" "XLookupAssoc"
The definition of this function is:
.FD 0
.so ./Xsrc/XLookUpAssoc.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/table.a
.so ./Xsrc/xid.a
.LP
.PN XLookUpAssoc
retrieves the data stored in an 
.PN XAssocTable
by its XId.  
.IN "XId"
If  an appropriately  matching XId can be found in the table the routine will
return the data associated with it. If the x_id can not be found in the
table the routine will return NULL.
.LP
.sp
To delete an entry from a specific assoctable, use 
.PN XDeleteAssoc .
.IN "V10 Compatibility" "XDeleteAssoc"
The definition of this function is:
.FD 0
.so ./Xsrc/XDeleteAssoc.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/table.a
.so ./Xsrc/xid.a
.LP
.PN XDeleteAssoc
deletes an association in an 
.PN XAssocTable
keyed on its XId.
.IN "XId"
Redundant deletes (and deletes of non-existent XIds) are meaningless
and cause no problems.  Deleting associations in no way impairs
the performance of an 
.PN XAssocTable .
.LP
.sp
To free the memory associated with a specific assoctable, use 
.PN XDestroyAssocTable .
.IN "V10 Compatibility" "XDestroyAssocTable"
The definition of this function is:
.FD 0
.so ./Xsrc/XDestAscTbl.f
.FN
.so ./Xsrc/table.a
.LP
Using an 
.PN XAssocTable
after it has been destroyed is guaranteed to have
unpredictable and probably disastrous consequences!
.bp
