Search Parameter Sharing Protocol for the X Window System

Technical details

 

Current version: 1

 

All constants mentioned below are the string names of X atoms, capitalized as shown.  This avoids the need for hard-coded values, which would require a global registry.

 

Atoms and Properties

 

XsearchSelection

 

This is the name of the X Selection that is used to avoid retrieving ones own data.

 

XSearchWindows

 

This window property must be set on the root window and must be of type XA_WINDOW.  It contains the ID's of the version and data windows, in that order.

 

XsearchVersion

 

This window property is set on the version window and must be of type XA_ATOM.  It contains the maximum XSearch protocol version supported by the program that last set the contents of XsearchDataV*.

 

XsearchDataV*

 

These window properties are set on the data window and must be of type text/plain, including the charset attribute, if it is not ISO-8859-1.  This

allows the search and replace strings to be in any language.  Programs that cannot handle the character set can ignore the data.

 

 

The version number is encoded in the property name so programs that do not support the latest version can still easily retrieve data that they can interpret.

 

XsearchDataV1

 

Version 1 of the XSearch protocol contains the following data:

 

1. Search string (charset is obtained from property type)

2. 0x00

3. Replace string (charset is obtained from property type)

4. 0x00

5. 0x54 (T) if the search should wrap when it reaches the end of the text. 0x46 (F) if the search should stop when it reaches the end of the text.

6. 0x54 (T) if the search should only report "entire word" matches. 0x46 (F) if the search should report all matches.

7. 0x54 (T) if the search should only report "entire partial word" matches. 0x46 (F) if the search should report all matches.

8. 0x54 (T) if the search should ignore upper vs. lower case when reporting matches. 0x46 (F) if the search should only report matches where the case also matches.

 

 

For all four flags, the value can also be 0x58 (X) if the provider does not support the feature.  In this case, if the receiver does support the feature, the receiver should not change its current setting.

 

Providing additional search parameters

 

Most programs provide many features beyond simply searching for a literal string.  Regular expression searching is the most common (see Notes section).  In order to allow programs to share such additional information, one can append additional data to the XsearchDataV* properties after appending 0x00, followed by a unique tag to identify the data format, followed by 0x00.  To allow for new formats of this data in later releases, the data itself should have the format: first version id, data, second version id, data, etc.  This allows each program to retrieve the newest version that it can handle by skipping over the older versions.  As an example, the JX Application Framework appends the following data

 

1. 0x00

2. JX_Application_Framework

3. 0x00

4. 0x31 (1)

5. 0x54 (T) if the search string is a PCRE regular expression. 0x46 (F) if the search string is a literal string.

6. 0x54 (T) if the search string is a regular expression and newlines should not automatically terminate the match. 0x46 (F) otherwise.

7. 0x54 (T) if the replace string is a PCRE replacement expression that uses $N as a placeholder for the Nth subexpression matched by the search expression. 0x46 (F) if the replace string is a literal string.

8. 0x54 (T) if the case of the replace string should be matched to that of the text matched by the search expression. 0x46 (F) if the replace string should be used without adjusting the case.

 

For all four flags, the value can also be 0x58 (X) if the provider does not support the feature.  In this case, if the receiver does support the feature, the receiver should not change its current setting.

 

<< Previous | Next >>