BSD 4_3_Tahoe development

Work on file usr/src/new/X/doc/Xlib/ch12b.t
Work on file usr/src/new/X/doc/Xlib/ch12c.t

Synthesized-from: CSRG/cd2/4.3tahoe

diff --git a/usr/src/new/X/doc/Xlib/ch12b.t b/usr/src/new/X/doc/Xlib/ch12b.t
new file mode 100644 (file)
index 0000000..f407d81
--- /dev/null
+++ b/usr/src/new/X/doc/Xlib/ch12b.t
@@ -0,0 +1,106 @@
+.NH 2
+Associating X Resources to User Data Structures
+.IN "Hash Lookup"
+.IN "Window" "ID's"
+.IN "Resource ID's"
+.IN "XId"
+.PP
+Application programs often need to be able to easily refer to
+their own data structures when an event arrives.
+The \fIXAssocTable\fP 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).
+.PP
+An  \fIXAssocTable\fP 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.
+.IN "Definitions" "XId"
+A generic type has been defined in the X library for resource id's.
+.IN "XId"
+It is called ``XId''.
+.PP
+There  are  a  few  guidelines  that  should be observed when using an
+\fIXAssocTable\fP:
+.LP
+.IN "XId"
+First, all  \fIXId\fP's  are  relative  to  the  currently  active  display.
+Therefore,  if you are using multiple displays you need to be sure the
+correct display is active before performing an \fIXAssocTable\fP operation.
+\fIXAssocTable\fP  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.
+.LP
+Second,  because  of  the  hashing  scheme  used  by  the  association
+mechanism the following rules for determining the size of \fIXAssocTable\fPs
+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.
+.FD
+.IN "XAssocTable"
+.IN "Definitions" "XCreateAssocTable"
+.IN "XCreateAssocTable"
+XAssocTable *XCreateAssocTable(size)
+       int size;       /* Desired size (in buckets) of the table. */
+.FN
+This routine returns a pointer to a newly created \fIXAssocTable\fP.
+The "size" argument specifies the number of buckets  in  \fIXAssocTable\fP's
+hashing  system.   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
+\fIXAssocTable\fP, a NULL pointer is returned. 
+.FD
+.IN "XAssocTable"
+.IN "Definitions" "XDestroyAssocTable"
+.IN "XDestroyAssocTable"
+XDestroyAssocTable(table)
+       XAssocTable *table;     /* Table to destroy. */
+.FN
+Destroy (free the  memory  associated  with)  an  XAssocTable.
+Using an \fIXAssocTable\fP after it has been destroyed is guaranteed to have
+unpredictable and probably disastrous consequences!
+.FD
+.IN "XAssocTable"
+.IN "Definitions" "XMakeAssoc"
+.IN "XMakeAssoc"
+XMakeAssoc(table, x_id, data)
+       XAssocTable *table;     /* Table in which to make the association. */
+       XId x_id;       /* X resource id. */
+       caddr_t data;   /* Data to associate with the XId. */
+.FN
+.IN "XId"
+Insert data into an \fIXAssocTable\fP keyed  on  an  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.
+.FD
+.IN "XAssocTable"
+.IN "Definitions" "XLookUpAssoc"
+.IN "XLookupAssoc"
+caddr_t XLookUpAssoc(table, x_id)
+       XAssocTable *table;     /* Table to look in. */
+       XId x_id;       /* XId to look for. */
+.FN
+.IN "XId"
+Retrieve the data stored in an \fIXAssocTable\fP by its XId.  If  an
+appropriately  matching XId can be found in the table the routine will
+return the data associated with it. If the \fIx_id\fP can not be found in the
+table the routine will return NULL.
+.FD
+.IN "XAssocTable"
+.IN "Definitions" "XDeleteAssoc"
+.IN "XDeleteAssoc"
+XDeleteAssoc(table, x_id)
+       XAssocTable *table;     /* Table to look in. */
+       XId x_id;       /* XId to delete. */
+.FN
+.IN "XId"
+Delete an association in an \fIXAssocTable\fP keyed on its XId.
+Redundant deletes (and deletes of non-existant XId's) are meaningless
+and cause no problems.  Deleteing associations in no way impares
+the performance of an \fIXAssocTable\fP.

diff --git a/usr/src/new/X/doc/Xlib/ch12c.t b/usr/src/new/X/doc/Xlib/ch12c.t
new file mode 100644 (file)
index 0000000..8371a22
--- /dev/null
+++ b/usr/src/new/X/doc/Xlib/ch12c.t
@@ -0,0 +1,118 @@
+.NH 2
+Mouse, Button and Server Grabbing
+.PP
+Some programs need to  gain exclusive access to the mouse,
+a single mouse button under some circumstances,
+or the entire X server for the duration of some operation.
+.FD
+.IN "Definitions" "XGrabMouse"
+.IN "XGrabMouse"
+.IN "Mouse" "Grabbing"
+Status XGrabMouse (w, cursor, mask)
+       Window w;
+       Cursor cursor;
+       int mask;       /* event mask */
+.FN
+After \fIXGrabMouse\fP is called, all future mouse events will only go to
+.IN "XSelectInput"
+windows for which the client has previously called \fIXSelectInput\fP.  The
+\fIButtonPressed\fP, \fIButtonReleased\fP, \fIEnterWindow\fP,
+\fILeaveWindow\fP, \fIMouseMoved\fP,
+\fILeftDownMotion\fP, \fIMiddleDownMotion\fP,
+and \fIRightDownMotion\fP bits of the \fImask\fP
+parameter temporarily override the corresponding bits in any mask
+previously passed to \fIXSelectInput\fP; other bits in \fImask\fP are ignored.
+.PP
+.IN "XSelectInput"
+If one of the above-mentioned events occurs, and the client has not
+called \fIXSelectInput\fP on the window where the event would normally be
+sent, then the event will be sent to the window \fIw\fP, provided that the
+event is specified in 
+\fImask\fP and is not \fIEnterWindow\fP or \fILeaveWindow\fP.
+.PP
+.IN "Grabbing Error"
+An error will occur if a different client has already grabbed the mouse
+and has not ungrabbed it.  It is not an error for the same client to
+grab the mouse more than once without ungrabbing it in between.  A
+mouse-grabbing client may want to do this in order to change the cursor
+or event mask without ungrabbing the mouse.
+.PP
+Grabbing the mouse overrides any \fIXGrabButton\fP calls previously issued by
+this or any other client, until the mouse is ungrabbed.
+.PP
+Note that this procedure returns a status and is therefore synchronous,
+even though no other values are returned.
+It returns 0 if the mouse could not be grabbed, non-zero if the
+mouse was successfully grabbed.
+.FD
+.IN "Definitions" "XGrabMouse"
+.IN "XGrabMouse"
+XUngrabMouse ()
+.FN
+\fIXUngrabMouse\fP releases hold of the mouse if it was grabbed by 
+\fIXGrabMouse\fP.
+.FD
+.IN "Definitions" "XGrabButton"
+.IN "XGrabButton"
+Status XGrabButton (w, cursor, buttonMask, eventMask)
+       Window w;
+       Cursor cursor;
+       int buttonMask;
+       int eventMask;
+.FN
+After \fIXGrabButton\fP has been called, the mouse will automatically be
+grabbed whenever a particular mouse button is pressed while certain keys are
+down.
+.IN "Button Mask"
+The combination is specified in \fIbuttonMask\fP;  this mask must
+have exactly one of the \fILeftMask\fP, \fIMiddleMask\fP, and \fIRightMask\fP
+bits set,
+and may have some combination of the \fIControlMask\fP, \fIMetaMask\fP,
+\fIShiftLockMask\fP and
+\fIShiftMask\fP bits set as well.
+.PP
+If the specified button is pressed while exactly the specified keys are down,
+this and all future mouse events are grabbed until all buttons are
+.IN "XGrabMouse"
+released, with events sent to windows as described under \fIXGrabMouse\fP
+above.
+.IN "Event Mask"
+The \fIeventMask\fP determines what mouse events are reported while the
+mouse is grabbed.
+.PP
+An error will occur if another client has already grabbed the same
+button/key combination and has not ungrabbed it.
+.PP
+Note that this procedure returns a status and is therefore synchronous,
+It returns 0 if the button could not be grabbed, non-zero if the
+the button was grabbed successfully.
+.FD
+.IN "Definitions" "XUngrabButton"
+.IN "XGrabButton"
+XUngrabButton (mask)
+       int mask;       /* button mask;  see XGrabButton */
+.FN
+\fIXUngrabButton\fP notifies the server that the client is no longer
+interested in grabbing the mouse when the specified button/key
+combination occurs.
+See \fIXGrabButton\fP for the meaning of the button
+mask bits.
+This grab is overridden by a grab mouse request.
+.FD
+.IN "XGrabServer"
+.IN "Definitions" "XGrabServer"
+.IN "Grabbing" "Server"
+XGrabServer()
+
+XUngrabServer()
+.FN
+These requests can be used to control processing of output on other
+connections by the window system server.
+No processing of requests or close downs on all other connections
+will occur while the server is grabbed.
+.PP
+.IN "Menus"
+.IN "Window" "Managers"
+This may be useful for menus or window manager programs who may want to
+preserve bits on the screen while temporarily suspending processing
+on other connections.