[deb_xorg-server.git] / dix / BuiltInAtoms

File: .../x11/server/dix/BuiltInAtoms

This file is of a fixed format and is used to generate both the file
include/XAtom.h and dix/initatoms.c. Neither of those files should be
edited directly. Changing the atoms in this file, or even the order in
which they occur, is equivalent to forcing a new (minor) version number
on the server. Take care.

The format of the file is that each built in atom starts in column 1
with no text, other than spaces and tabs, on that line other than a
mandatory trailing "@" at the end of the line. For each atom (Foo)
below the defines will be of the form
	#define XA_Foo <n>
and the string value of the atom will be "Foo".

The comment lines in this file are not guaranteed to be accurate. To see the
current truth, look at the Xlib documentation as well as the protocol spec.

Atoms occur in five distinct name spaces within the protocol. Any particular
atom may or may not have some client interpretation within each of the name
spaces. For each of the built in atoms, the intended semantics and the space
within which it is defined is indicated.

Those name spaces are
	Property names
	Property types
	Selections
	Font properties
	Type of a ClientMessage event	(none built into server)

For the font properties mentioned here, see the spec for more information.

				-- Selections --

PRIMARY									      @
	Selection.
SECONDARY								      @
	Selection.

			-- Property types and names --

ARC									      @
	Property type:
		x, y: INT16
		width, height: CARD16,
		angle1, angle2: INT16
ATOM									      @
	Property type:
		atom: ATOM
BITMAP									      @
	Property type:
		bitmap: PIXMAP
			This is asserted to be of depth 1.
CARDINAL								      @
	Property type:
		card: CARD32 or CARD16 or CARD8
		the datum size is dependent on the property format
COLORMAP								      @
	Property type:
		colormap: COLORMAP
CURSOR									      @
	Property type:
		cursor: CURSOR
CUT_BUFFER0								      @
CUT_BUFFER1								      @
CUT_BUFFER2								      @
CUT_BUFFER3								      @
CUT_BUFFER4								      @
CUT_BUFFER5								      @
CUT_BUFFER6								      @
CUT_BUFFER7								      @
	Property name:	(type: STRING)
		Used to implement cut buffer ring, in particular Andrew uses
		this mechanism.  Anyone else using this sort of IPC mechanism
		should use these properties.

		Data is normally fetched and stored out of CUT_BUFFER0; the
		RotateProperties request is used to rotate these buffers.
DRAWABLE								      @
	Property type:
		drawable: DRAWABLE
FONT									      @
	Property type:
		font: FONT
INTEGER									      @
	Property type:
		card: INT32 or INT16 or INT8
		the datum size is dependent on the property format
PIXMAP									      @
	Property type:
		pixmap: PIXMAP
POINT									      @
	Property type:
		x, y: INT16
RECTANGLE								      @
	Property type:
		x, y: INT16
		width, height: CARD16
RESOURCE_MANAGER							      @
	Property name: (type: STRING)
		Contents of the user's resource manager data base.
RGB_COLOR_MAP								      @
	Property type:
		colormap:	COLORMAP
		red-max:	CARD32
		red-mult:	CARD32
		green-max:	CARD32
		green-mult:	CARD32
		blue-max:	CARD32
		blue-mult:	CARD32
		base-pixel:	CARD32

	The fields `red_max', `green_max', and `blue_max' give the maximum
	red, green, and blue values, respectively.  Each color
	coefficient ranges from 0 to its max, inclusive.  For example,
	a common colormap allocation is 3/3/2:  3 planes for red, 3
	planes for green, and 2 planes for blue.  Such a colormap would
	have red_max == 7, green_max = 7, and blue_max = 3.  An alternate
	allocation that uses only 216 colors is red_max = 5, green_max =
	5, and blue_max = 5.

	The fields `red_mult', `green_mult', and `blue_mult' give the
	scale factors used to compose a full pixel value.  (See next
	paragraph.)  For a 3/3/2 allocation red_mult might be 32,
	green_mult might be 4, and blue_mult might be 1.  For a
	6-colors-each allocation, red_mult might be 36, green_mult might
	be 6, and blue_mult might be 1.

	The field `base_pixel' gives the base pixel value used to
	compose a full pixel value.  Normally base_pixel is obtained
	from a call to XAllocColorPlanes().  Given integer red, green,
	and blue coefficients in their appropriate ranges, one can
	compute a corresponding pixel value with the expression:

		r * red_mult + g * green_mult + b * blue_mult + base_pixel
	
	For gray-scale colormaps, only the colormap, red_max, red_mult,
	and base_pixel fields are defined; the other fields are
	ignored.  To compute a gray-scale pixel value, use:

		gray * red_mult + base_pixel

	This is provided to allow applications to share color maps.

RGB_BEST_MAP								      @
RGB_BLUE_MAP								      @
RGB_DEFAULT_MAP								      @
RGB_GRAY_MAP								      @
RGB_GREEN_MAP								      @
RGB_RED_MAP								      @
	Property name:	(type: RGB_COLOR_MAP)
		The needs of most applications can be met with five colormaps.
		Polite applications may need only a small RGB space, and can
		use a portion of the default color map. Applications doing
		high-quality RGB rendering will need an entire colormap,
		filled with as large an RGB space as possible, e.g. 332. For
		color separations, an application may need maximum device
		resolution for each of red, green, and blue, even if this
		requires three renderings with three colormaps.

		Each of the above five names would be used for sharing color
		maps.
STRING									      @
	Property type:
		sequence of Bytes
VISUALID								      @
	Property type:
		visual: VISUALID
WINDOW									      @
	Property type:
		window: WINDOW
WM_COMMAND								      @
	Property name: (type: STRING)
		Command line arguments used to invoke this application. The
		arguments are delimited by null characters (ASCII 0).
WM_HINTS								      @
	Property type:
		flags:		CARD32
		input:		BOOL32
		initial-state:	CARD32
		icon-pixmap:	PIXMAP
		icon-window:	WINDOW
		icon_mask:	BITMAP
		icon-x, icon-y:	INT32
		    flags contains the following bits
			0x00000001	input hint
			0x00000002	state hint
			0x00000004	icon pixmap hint
			0x00000008	icon window hint
			0x00000010	icon position hint
		     values for initial-state
			0		unspecified -> application does not
				care and WM should pick one.
			1		normal
			2		zoomed
			3		iconic
			4		inactive -> application believes
				itself to be seldomly used. WM may wish to
				place it on an inactive menu.
		This type is potentially extensible. The order is critical;
		append to the end only.
	Property name:	(type: WM_HINTS)
		Additional hints set by the client for use by the window
		manager.
WM_CLIENT_MACHINE							      @
	Property name:	(type: STRING)
		used to communicate with the window manager.  The host name
		of the machine the client is running on may be set here.
WM_ICON_NAME								      @
	Property name:	(type: STRING)
		what the application would like the label to be for
		the iconic form of the window.
WM_ICON_SIZE								      @
	Property type:
		minWidth, min-height:	CARD32
		maxWidth, max-height:	CARD32
		widthInc, height-inc:	CARD32
	Property name:	(type: ICON_SIZE)
		The window manager may set this property on the root window
		to specify the icon sizes it allows.
WM_NAME									      @
	Property name:	(type: STRING)
		used to communicate with the window manager. This is
		what the application would like the label for the window.
WM_NORMAL_HINTS								      @
	Property name:	(type: SIZE_HINTS)
		used to communicate with the window manager. This is size
		hints for a window in its "normal" state.
WM_SIZE_HINTS								      @
	Property type:
		flags:				CARD32
		x, y:				INT32
		width, height:			CARD32
		min-width, min-height:		CARD32
		max-width, max-height:		CARD32
		width-inc, height-inc:		CARD32
		min-aspect-x, min-aspect-y:	CARD32
		max-aspect-x, max-aspect-y:	CARD32
		    flags contains the following bits
			0x00000001	user specified x and y
			0x00000002	user specified width and height
			0x00000004	program specified position
			0x00000008	program specified size
			0x00000010	program specified minimum size
			0x00000020	program specified maximum size
			0x00000040	program specified resize increment
			0x00000080	program specified aspect ratio
		This type is potentially extensible. The order is critical;
		append to the end only.
WM_ZOOM_HINTS								      @
	Property name:	(type: SIZE_HINTS)
		used to communicate with the window manager. This is size
		hints for a window in its "zoomed" state.

				-- Font properties --

MIN_SPACE 								      @
	Font property: CARD32
NORM_SPACE 								      @
	Font property: CARD32
MAX_SPACE 								      @
	Font property: CARD32
END_SPACE 								      @
	Font property: CARD32
SUPERSCRIPT_X 								      @
	Font property: INT32
SUPERSCRIPT_Y 								      @
	Font property: INT32
SUBSCRIPT_X 								      @
	Font property: INT32
SUBSCRIPT_Y 								      @
	Font property: INT32
UNDERLINE_POSITION 							      @
	Font property: INT32
UNDERLINE_THICKNESS 							      @
	Font property: CARD32	
STRIKEOUT_ASCENT 							      @
	Font property: INT32
STRIKEOUT_DESCENT 							      @
	Font property: INT32
ITALIC_ANGLE 								      @
	Font property: INT32
X_HEIGHT 								      @
	Font property: INT32
QUAD_WIDTH 								      @
	Font property: INT32
WEIGHT 									      @
	Font property: CARD32
POINT_SIZE 								      @
	Font property: CARD32
RESOLUTION 								      @
	Font property: CARD32

The following optional properties on fonts have values that are atoms. The
atom print name is the useful information.

COPYRIGHT 								      @
	of the font distribution
NOTICE									      @
	trademark/copyright of the character shapes
FONT_NAME 								      @
	name of this particular instance of a font
FAMILY_NAME 								      @
	name of the 'font family' to which it belongs
FULL_NAME 								      @
	full text name of the font

The following aren't in order but putting them at the end avoids encoding
changes.

CAP_HEIGHT 								      @
	Font property: CARD32


WM_CLASS 								      @
	Property name: (type: STRING)
		Used (possibly by some window managers; definitely by 
		session managers) to look up resources in the resource 
		data base on behalf of the client who set this property.
		There are 2 elements:
			{char *resource_name; char *resource_class;}
		delimited by a null character (ascii 0)

WM_TRANSIENT_FOR							      @
	Property name: (type: WINDOW)
		Used by transient top-level windows, such as dialog 
		boxes, to point to their logical "parents".  The window 
		manager can then take down the dialog boxes when the
		"parent" gets iconified, for instance.
Commit	Line	Data
a09e091a JB	1	File: .../x11/server/dix/BuiltInAtoms
	2
	3	This file is of a fixed format and is used to generate both the file
	4	include/XAtom.h and dix/initatoms.c. Neither of those files should be
	5	edited directly. Changing the atoms in this file, or even the order in
	6	which they occur, is equivalent to forcing a new (minor) version number
	7	on the server. Take care.
	8
	9	The format of the file is that each built in atom starts in column 1
	10	with no text, other than spaces and tabs, on that line other than a
	11	mandatory trailing "@" at the end of the line. For each atom (Foo)
	12	below the defines will be of the form
	13	#define XA_Foo <n>
	14	and the string value of the atom will be "Foo".
	15
	16	The comment lines in this file are not guaranteed to be accurate. To see the
	17	current truth, look at the Xlib documentation as well as the protocol spec.
	18
	19	Atoms occur in five distinct name spaces within the protocol. Any particular
	20	atom may or may not have some client interpretation within each of the name
	21	spaces. For each of the built in atoms, the intended semantics and the space
	22	within which it is defined is indicated.
	23
	24	Those name spaces are
	25	Property names
	26	Property types
	27	Selections
	28	Font properties
	29	Type of a ClientMessage event (none built into server)
	30
	31	For the font properties mentioned here, see the spec for more information.
	32
	33	-- Selections --
	34
	35	PRIMARY @
	36	Selection.
	37	SECONDARY @
	38	Selection.
	39
	40	-- Property types and names --
	41
	42	ARC @
	43	Property type:
	44	x, y: INT16
	45	width, height: CARD16,
	46	angle1, angle2: INT16
	47	ATOM @
	48	Property type:
	49	atom: ATOM
	50	BITMAP @
	51	Property type:
	52	bitmap: PIXMAP
	53	This is asserted to be of depth 1.
	54	CARDINAL @
	55	Property type:
	56	card: CARD32 or CARD16 or CARD8
	57	the datum size is dependent on the property format
	58	COLORMAP @
	59	Property type:
	60	colormap: COLORMAP
	61	CURSOR @
	62	Property type:
	63	cursor: CURSOR
	64	CUT_BUFFER0 @
65	CUT_BUFFER1 @
66	CUT_BUFFER2 @
67	CUT_BUFFER3 @
68	CUT_BUFFER4 @
69	CUT_BUFFER5 @
70	CUT_BUFFER6 @
71	CUT_BUFFER7 @
72	Property name: (type: STRING)
73	Used to implement cut buffer ring, in particular Andrew uses
74	this mechanism. Anyone else using this sort of IPC mechanism
75	should use these properties.
76
77	Data is normally fetched and stored out of CUT_BUFFER0; the
78	RotateProperties request is used to rotate these buffers.
79	DRAWABLE @
80	Property type:
81	drawable: DRAWABLE
82	FONT @
83	Property type:
84	font: FONT
85	INTEGER @
86	Property type:
87	card: INT32 or INT16 or INT8
88	the datum size is dependent on the property format
89	PIXMAP @
90	Property type:
91	pixmap: PIXMAP
92	POINT @
93	Property type:
94	x, y: INT16
95	RECTANGLE @
96	Property type:
97	x, y: INT16
98	width, height: CARD16
99	RESOURCE_MANAGER @
100	Property name: (type: STRING)
101	Contents of the user's resource manager data base.
102	RGB_COLOR_MAP @
103	Property type:
104	colormap: COLORMAP
105	red-max: CARD32
106	red-mult: CARD32
107	green-max: CARD32
108	green-mult: CARD32
109	blue-max: CARD32
110	blue-mult: CARD32
111	base-pixel: CARD32
112
113	The fields `red_max', `green_max', and `blue_max' give the maximum
114	red, green, and blue values, respectively. Each color
115	coefficient ranges from 0 to its max, inclusive. For example,
116	a common colormap allocation is 3/3/2: 3 planes for red, 3
117	planes for green, and 2 planes for blue. Such a colormap would
118	have red_max == 7, green_max = 7, and blue_max = 3. An alternate
119	allocation that uses only 216 colors is red_max = 5, green_max =
120	5, and blue_max = 5.
121
122	The fields `red_mult', `green_mult', and `blue_mult' give the
123	scale factors used to compose a full pixel value. (See next
124	paragraph.) For a 3/3/2 allocation red_mult might be 32,
125	green_mult might be 4, and blue_mult might be 1. For a
126	6-colors-each allocation, red_mult might be 36, green_mult might
127	be 6, and blue_mult might be 1.
128
129	The field `base_pixel' gives the base pixel value used to
130	compose a full pixel value. Normally base_pixel is obtained
131	from a call to XAllocColorPlanes(). Given integer red, green,
132	and blue coefficients in their appropriate ranges, one can
133	compute a corresponding pixel value with the expression:
134
135	r * red_mult + g * green_mult + b * blue_mult + base_pixel
136
137	For gray-scale colormaps, only the colormap, red_max, red_mult,
138	and base_pixel fields are defined; the other fields are
139	ignored. To compute a gray-scale pixel value, use:
140
141	gray * red_mult + base_pixel
142
143	This is provided to allow applications to share color maps.
144
145	RGB_BEST_MAP @
146	RGB_BLUE_MAP @
147	RGB_DEFAULT_MAP @
148	RGB_GRAY_MAP @
149	RGB_GREEN_MAP @
150	RGB_RED_MAP @
151	Property name: (type: RGB_COLOR_MAP)
152	The needs of most applications can be met with five colormaps.
153	Polite applications may need only a small RGB space, and can
154	use a portion of the default color map. Applications doing
155	high-quality RGB rendering will need an entire colormap,
156	filled with as large an RGB space as possible, e.g. 332. For
157	color separations, an application may need maximum device
158	resolution for each of red, green, and blue, even if this
159	requires three renderings with three colormaps.
160
161	Each of the above five names would be used for sharing color
162	maps.
163	STRING @
164	Property type:
165	sequence of Bytes
166	VISUALID @
167	Property type:
168	visual: VISUALID
169	WINDOW @
170	Property type:
171	window: WINDOW
172	WM_COMMAND @
173	Property name: (type: STRING)
174	Command line arguments used to invoke this application. The
175	arguments are delimited by null characters (ASCII 0).
176	WM_HINTS @
177	Property type:
178	flags: CARD32
179	input: BOOL32
180	initial-state: CARD32
181	icon-pixmap: PIXMAP
182	icon-window: WINDOW
183	icon_mask: BITMAP
184	icon-x, icon-y: INT32
185	flags contains the following bits
186	0x00000001 input hint
187	0x00000002 state hint
188	0x00000004 icon pixmap hint
189	0x00000008 icon window hint
190	0x00000010 icon position hint
191	values for initial-state
192	0 unspecified -> application does not
193	care and WM should pick one.
194	1 normal
195	2 zoomed
196	3 iconic
197	4 inactive -> application believes
198	itself to be seldomly used. WM may wish to
199	place it on an inactive menu.
200	This type is potentially extensible. The order is critical;
201	append to the end only.
202	Property name: (type: WM_HINTS)
203	Additional hints set by the client for use by the window
204	manager.
205	WM_CLIENT_MACHINE @
206	Property name: (type: STRING)
207	used to communicate with the window manager. The host name
208	of the machine the client is running on may be set here.
209	WM_ICON_NAME @
210	Property name: (type: STRING)
211	what the application would like the label to be for
212	the iconic form of the window.
213	WM_ICON_SIZE @
214	Property type:
215	minWidth, min-height: CARD32
216	maxWidth, max-height: CARD32
217	widthInc, height-inc: CARD32
218	Property name: (type: ICON_SIZE)
219	The window manager may set this property on the root window
220	to specify the icon sizes it allows.
221	WM_NAME @
222	Property name: (type: STRING)
223	used to communicate with the window manager. This is
224	what the application would like the label for the window.
225	WM_NORMAL_HINTS @
226	Property name: (type: SIZE_HINTS)
227	used to communicate with the window manager. This is size
228	hints for a window in its "normal" state.
229	WM_SIZE_HINTS @
230	Property type:
231	flags: CARD32
232	x, y: INT32
233	width, height: CARD32
234	min-width, min-height: CARD32
235	max-width, max-height: CARD32
236	width-inc, height-inc: CARD32
237	min-aspect-x, min-aspect-y: CARD32
238	max-aspect-x, max-aspect-y: CARD32
239	flags contains the following bits
240	0x00000001 user specified x and y
241	0x00000002 user specified width and height
242	0x00000004 program specified position
243	0x00000008 program specified size
244	0x00000010 program specified minimum size
245	0x00000020 program specified maximum size
246	0x00000040 program specified resize increment
247	0x00000080 program specified aspect ratio
248	This type is potentially extensible. The order is critical;
249	append to the end only.
250	WM_ZOOM_HINTS @
251	Property name: (type: SIZE_HINTS)
252	used to communicate with the window manager. This is size
253	hints for a window in its "zoomed" state.
254
255	-- Font properties --
256
257	MIN_SPACE @
258	Font property: CARD32
259	NORM_SPACE @
260	Font property: CARD32
261	MAX_SPACE @
262	Font property: CARD32
263	END_SPACE @
264	Font property: CARD32
265	SUPERSCRIPT_X @
266	Font property: INT32
267	SUPERSCRIPT_Y @
268	Font property: INT32
269	SUBSCRIPT_X @
270	Font property: INT32
271	SUBSCRIPT_Y @
272	Font property: INT32
273	UNDERLINE_POSITION @
274	Font property: INT32
275	UNDERLINE_THICKNESS @
276	Font property: CARD32
277	STRIKEOUT_ASCENT @
278	Font property: INT32
279	STRIKEOUT_DESCENT @
280	Font property: INT32
281	ITALIC_ANGLE @
282	Font property: INT32
283	X_HEIGHT @
284	Font property: INT32
285	QUAD_WIDTH @
286	Font property: INT32
287	WEIGHT @
288	Font property: CARD32
289	POINT_SIZE @
290	Font property: CARD32
291	RESOLUTION @
292	Font property: CARD32
293
294	The following optional properties on fonts have values that are atoms. The
295	atom print name is the useful information.
296
297	COPYRIGHT @
298	of the font distribution
299	NOTICE @
300	trademark/copyright of the character shapes
301	FONT_NAME @
302	name of this particular instance of a font
303	FAMILY_NAME @
304	name of the 'font family' to which it belongs
305	FULL_NAME @
306	full text name of the font
307
308	The following aren't in order but putting them at the end avoids encoding
309	changes.
310
311	CAP_HEIGHT @
312	Font property: CARD32
313
314
315	WM_CLASS @
316	Property name: (type: STRING)
317	Used (possibly by some window managers; definitely by
318	session managers) to look up resources in the resource
319	data base on behalf of the client who set this property.
320	There are 2 elements:
321	{char resource_name; char resource_class;}
322	delimited by a null character (ascii 0)
323
324	WM_TRANSIENT_FOR @
325	Property name: (type: WINDOW)
326	Used by transient top-level windows, such as dialog
327	boxes, to point to their logical "parents". The window
328	manager can then take down the dialog boxes when the
329	"parent" gets iconified, for instance.