Return to ch12b.t CVS log

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

Annotation of 43BSDTahoe/new/X/doc/Xlib/ch12b.t, revision 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.