Display Queue Functions

To use the functions and types defined in this section, you should include the header file <X11/Xmu/DisplayQue.h> and link against the libXmu library. DisplayQue.h defines the following types:

typedef int (*XmuCloseDisplayQueueProc)(XmuDisplayQueue *queue,
                                        XmuDisplayQueueEntry *entry);

typedef int (*XmuFreeDisplayQueueProc)(XmuDisplayQueue *queue);

typedef struct _XmuDisplayQueueEntry {
	struct _XmuDisplayQueueEntry *prev, *next;
	Display *display;
	CloseHook closehook;
	XPointer data;
} XmuDisplayQueueEntry;

typedef struct _XmuDisplayQueue {
	int nentries;
	XmuDisplayQueueEntry *head, *tail;
	XmuCloseDisplayQueueProc closefunc;
	XmuFreeDisplayQueueProc freefunc;
	XPointer data;
} XmuDisplayQueue;

typedef int (*XmuCloseDisplayQueueProc)(XmuDisplayQueue *queue,
                                        XmuDisplayQueueEntry *entry);

typedef int (*XmuFreeDisplayQueueProc)(XmuDisplayQueue *queue);

typedef struct _XmuDisplayQueueEntry {
	struct _XmuDisplayQueueEntry *prev, *next;
	Display *display;
	CloseHook closehook;
	XPointer data;
} XmuDisplayQueueEntry;

typedef struct _XmuDisplayQueue {
	int nentries;
	XmuDisplayQueueEntry *head, *tail;
	XmuCloseDisplayQueueProc closefunc;
	XmuFreeDisplayQueueProc freefunc;
	XPointer data;
} XmuDisplayQueue;

XmuDisplayQueue *XmuDQCreate(XmuCloseDisplayQueueProc closefunc, XmuFreeDisplayQueueProc freefunc, XPointer data);

XmuDisplayQueue *XmuDQCreate(XmuCloseDisplayQueueProc closefunc, XmuFreeDisplayQueueProc freefunc, XPointer data);

closefunc	specifies the close function
freefunc	specifies the free function
data	specifies private data for the functions

This function creates and returns an empty XmuDisplayQueue (which is really just a set of displays, but is called a queue for historical reasons). The queue is initially empty, but displays can be added using XmuAddDisplay. The data value is simply stored in the queue for use by the closefunc and freefunc callbacks. Whenever a display in the queue is closed using XCloseDisplay, the closefunc (if non-NULL) is called with the queue and the display's XmuDisplayQueueEntry as follows:

	(*closefunc)(queue, entry)
      

The freefunc (if non-NULL) is called whenever the last display in the queue is closed, as follows:

	(*freefunc)(queue)
      

The application is responsible for actually freeing the queue, by calling XmuDQDestroy.

XmuDisplayQueueEntry *XmuDQAddDisplay(XmuDisplayQueue *q, Display *dpy, XPointer data);

XmuDisplayQueueEntry *XmuDQAddDisplay(XmuDisplayQueue *q, Display *dpy, XPointer data);

q	specifies the queue
dpy	specifies the display to add
data	specifies private data for the free function

This function adds the specified display to the queue. If successful, the queue entry is returned, otherwise NULL is returned. The data value is simply stored in the queue entry for use by the queue's freefunc callback. This function does not attempt to prevent duplicate entries in the queue; the caller should use XmuDQLookupDisplay to determine if a display has already been added to a queue.

XmuDisplayQueueEntry *XmuDQLookupDisplay(XmuDisplayQueue *q, Display *dpy);

XmuDisplayQueueEntry *XmuDQLookupDisplay(XmuDisplayQueue *q, Display *dpy);

q	specifies the queue
dpy	specifies the display to lookup

This function returns the queue entry for the specified display, or NULL if the display is not in the queue.

XmuDQNDisplays(q);

This macro returns the number of displays in the specified queue.

Bool XmuDQRemoveDisplay(XmuDisplayQueue *q, Display *dpy);

Bool XmuDQRemoveDisplay(XmuDisplayQueue *q, Display *dpy);

q	specifies the queue
dpy	specifies the display to remove

This function removes the specified display from the specified queue. No callbacks are performed. If the display is not found in the queue, False is returned, otherwise True is returned.

Bool XmuDQDestroy(XmuDisplayQueue *q, Bool docallbacks);

Bool XmuDQDestroy(XmuDisplayQueue *q, Bool docallbacks);

q	specifies the queue to destroy
docallbacks	specifies whether close functions should be called

This function releases all memory associated with the specified queue. If docallbacks is True, then the queue's closefunc callback (if non-NULL) is first called for each display in the queue, even though XCloseDisplay is not called on the display.