Return to ch12b.t CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / X / doc / Xlib

Annotation of 43BSD/contrib/X/doc/Xlib/ch12b.t, revision 1.1.1.1

1.1       root        1: .NH 2
                      2: Associating X Resources to User Data Structures
                      3: .IN "Hash Lookup"
                      4: .IN "Window" "ID's"
                      5: .IN "Resource ID's"
                      6: .IN "XId"
                      7: .PP
                      8: Application programs often need to be able to easily refer to
                      9: their own data structures when an event arrives.
                     10: The \fIXAssocTable\fP system provides users of the X library with  a  method
                     11: of associating their own data structures with X resources.
                     12: (Bitmaps, Pixmaps, Fonts, Windows, and so on).
                     13: .PP
                     14: An  \fIXAssocTable\fP can be used to type X resources.  
                     15: For example, the user
                     16: may wish to have three or four `types' of windows each with  different
                     17: properties. 
                     18: This can be accomplished by associating each X window id
                     19: with a pointer to a `window property' data structure  defined  by  the
                     20: user.
                     21: .IN "Definitions" "XId"
                     22: A generic type has been defined in the X library for resource id's.
                     23: .IN "XId"
                     24: It is called ``XId''.
                     25: .PP
                     26: There  are  a  few  guidelines  that  should be observed when using an
                     27: \fIXAssocTable\fP:
                     28: .LP
                     29: .IN "XId"
                     30: First, all  \fIXId\fP's  are  relative  to  the  currently  active  display.
                     31: Therefore,  if you are using multiple displays you need to be sure the
                     32: correct display is active before performing an \fIXAssocTable\fP operation.
                     33: \fIXAssocTable\fP  imposes no restrictions on the number of X ids per table,
                     34: the number of X ids per display or the number of displays per table.
                     35: .LP
                     36: Second,  because  of  the  hashing  scheme  used  by  the  association
                     37: mechanism the following rules for determining the size of \fIXAssocTable\fPs
                     38: should be followed.  
                     39: Associations will be  made  and  looked  up  more
                     40: efficiently  if  the  table  size  (number  of  buckets in the hashing
                     41: system) is a power of two and if there are not more than 8 Xids  per
                     42: bucket.
                     43: .FD
                     44: .IN "XAssocTable"
                     45: .IN "Definitions" "XCreateAssocTable"
                     46: .IN "XCreateAssocTable"
                     47: XAssocTable *XCreateAssocTable(size)
                     48:        int size;       /* Desired size (in buckets) of the table. */
                     49: .FN
                     50: This routine returns a pointer to a newly created \fIXAssocTable\fP.
                     51: The "size" argument specifies the number of buckets  in  \fIXAssocTable\fP's
                     52: hashing  system.   For  reasons  of  efficiency  the number of buckets
                     53: should be a power of two.  Some size  suggestions  might  be:  use  32
                     54: buckets  per  100  objects;  a reasonable maximum number of object per
                     55: buckets is 8.   If  there  is  an  error  allocating  memory  for  the
                     56: \fIXAssocTable\fP, a NULL pointer is returned. 
                     57: .FD
                     58: .IN "XAssocTable"
                     59: .IN "Definitions" "XDestroyAssocTable"
                     60: .IN "XDestroyAssocTable"
                     61: XDestroyAssocTable(table)
                     62:        XAssocTable *table;     /* Table to destroy. */
                     63: .FN
                     64: Destroy (free the  memory  associated  with)  an  XAssocTable.
                     65: Using an \fIXAssocTable\fP after it has been destroyed is guaranteed to have
                     66: unpredictable and probably disastrous consequences!
                     67: .FD
                     68: .IN "XAssocTable"
                     69: .IN "Definitions" "XMakeAssoc"
                     70: .IN "XMakeAssoc"
                     71: XMakeAssoc(table, x_id, data)
                     72:        XAssocTable *table;     /* Table in which to make the association. */
                     73:        XId x_id;       /* X resource id. */
                     74:        caddr_t data;   /* Data to associate with the XId. */
                     75: .FN
                     76: .IN "XId"
                     77: Insert data into an \fIXAssocTable\fP keyed  on  an  XId.   Data  is
                     78: inserted  into the table only once.  Redundant inserts are meaningless
                     79: and cause no problems.  The queue in each association bucket is sorted
                     80: from the lowest XId to the highest XId.
                     81: .FD
                     82: .IN "XAssocTable"
                     83: .IN "Definitions" "XLookUpAssoc"
                     84: .IN "XLookupAssoc"
                     85: caddr_t XLookUpAssoc(table, x_id)
                     86:        XAssocTable *table;     /* Table to look in. */
                     87:        XId x_id;       /* XId to look for. */
                     88: .FN
                     89: .IN "XId"
                     90: Retrieve the data stored in an \fIXAssocTable\fP by its XId.  If  an
                     91: appropriately  matching XId can be found in the table the routine will
                     92: return the data associated with it. If the \fIx_id\fP can not be found in the
                     93: table the routine will return NULL.
                     94: .FD
                     95: .IN "XAssocTable"
                     96: .IN "Definitions" "XDeleteAssoc"
                     97: .IN "XDeleteAssoc"
                     98: XDeleteAssoc(table, x_id)
                     99:        XAssocTable *table;     /* Table to look in. */
                    100:        XId x_id;       /* XId to delete. */
                    101: .FN
                    102: .IN "XId"
                    103: Delete an association in an \fIXAssocTable\fP keyed on its XId.
                    104: Redundant deletes (and deletes of non-existant XId's) are meaningless
                    105: and cause no problems.  Deleteing associations in no way impares
                    106: the performance of an \fIXAssocTable\fP.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.