Search Parameter Sharing Protocol for the X Window System

Procedures

 

Initialization

 

When a program starts, it must initialize itself so that it can use the XSearch protocol.  Define D1 to be the display that is already open.

 

1. Call XOpenDisplay(DisplayString(D1)) to create a new connection (D2) to the same X server.

2. Create two X windows via D2 with the "override redirect" property so they will be invisible to the user.  These will be the version and data windows if nobody else has already initialized XSearch.  Creating the windows via a separate Display allows the program to be lazy about releasing the rest of its resources when terminating.

3. Call XSetCloseDownMode(D2, RetainPermanent) to guarantee that the version and data windows will persist even after the program exits.

4. Call XCloseDisplay(D2).

5. Call XGrabServer(D1) to avoid race conditions.

6. If the XSearchWindows property does not exist on the root window:

   1. Store the version and data window ID's in the XSearchWindows property on the root window.

   2. Set the search parameters, as explained below.

7. If the XSearchWindows property exists on the root window:

   1. Call XKillClient() on the version window created in Step 2.  It is not sufficient to merely destroy the windows because then the X server will still eventually run out of client slots.

   2. Retrieve the version and data window ID's stored in the XSearchWindows property.

   3. Retrieve the search parameters, as explained below.

8. Call XSelectInput() on the version window with PropertyChangeMask.

9. Call XUngrabServer(D1).

 

Setting the search parameters

 

The search parameters must be updated when:

 

• The user changes the search or replace string via a menu item (e.g. "Copy selection to search string").

• The user is done typing in the search or replace string input fields.  The user indicates this by changing focus to a different input field, closing the dialog, or performing a search.

• The user changes one of the other search parameters.

 

To update the search parameters:

 

1. Call XGrabServer()to avoid race conditions.

2. Request ownership of the X Selection named XsearchSelection.  If this fails, call XUngrabServer() and give up.

3. Update the window properties XsearchDataV1 to XsearchDataVN on the data window, where N is the maximum version that the program can write.

4. Update the window property XsearchVersion on the version window to contain the value of N from Step 3.

5. Call XUngrabServer().

 

Retrieving the search parameters

 

The search parameters must be retrieved when the program receives a PropertyNotify event from the version window for the XsearchVersion property and the program does not currently own XsearchSelection.

 

1. Retrieve the XsearchVersion property from the version window.

2. Retrieve the XsearchDataVN property from the data window, where N is the minimum of the value from the XsearchVersion property and the highest version that the program supports.

 

Unfortunately, one cannot optimize this by waiting to retrieve the data until the search dialog is activated or a search is performed.  One must enable or

disable menu items such as "Search forward" based on whether or not the current search string is empty.  Waiting for the user to open the menu or press a shortcut key is pointless because the menu items may be on the toolbar, in which case they have to be enabled or disabled as soon as a change occurs.

 

<< Previous | Next >>