1 // -*- mode: C++; indent-tabs-mode: nil; c-basic-offset: 2; -*-
6 @brief Provides access to window properties
10 #include "screeninfo.hh"
21 //! The atoms on the X server which this class will cache
24 Atom cardinal; //!< The atom which represents the Cardinal data type
25 Atom window; //!< The atom which represents window ids
26 Atom pixmap; //!< The atom which represents pixmap ids
27 Atom atom; //!< The atom which represents atom values
28 Atom string; //!< The atom which represents ascii strings
29 Atom utf8; //!< The atom which represents utf8-encoded strings
34 Atom wm_colormap_windows;
37 Atom wm_delete_window;
46 Atom openbox_show_root_menu;
47 Atom openbox_show_workspace_menu;
50 // root window properties
53 Atom net_client_list_stacking;
54 Atom net_number_of_desktops;
55 Atom net_desktop_geometry;
56 Atom net_desktop_viewport;
57 Atom net_current_desktop;
58 Atom net_desktop_names;
59 Atom net_active_window;
61 Atom net_supporting_wm_check;
62 // Atom net_virtual_roots;
63 Atom net_desktop_layout;
64 Atom net_showing_desktop;
65 // root window messages
66 Atom net_close_window;
67 Atom net_wm_moveresize;
68 // application window properties
69 // Atom net_properties;
71 Atom net_wm_visible_name;
72 Atom net_wm_icon_name;
73 Atom net_wm_visible_icon_name;
75 Atom net_wm_window_type;
78 // Atom net_wm_icon_geometry;
81 // Atom net_wm_handled_icons;
82 Atom net_wm_allowed_actions;
83 // application protocols
84 // Atom Atom net_wm_ping;
86 Atom net_wm_window_type_desktop;
87 Atom net_wm_window_type_dock;
88 Atom net_wm_window_type_toolbar;
89 Atom net_wm_window_type_menu;
90 Atom net_wm_window_type_utility;
91 Atom net_wm_window_type_splash;
92 Atom net_wm_window_type_dialog;
93 Atom net_wm_window_type_normal;
95 Atom net_wm_moveresize_size_topleft;
96 Atom net_wm_moveresize_size_topright;
97 Atom net_wm_moveresize_size_bottomleft;
98 Atom net_wm_moveresize_size_bottomright;
99 Atom net_wm_moveresize_move;
101 Atom net_wm_action_move;
102 Atom net_wm_action_resize;
103 Atom net_wm_action_minimize;
104 Atom net_wm_action_shade;
105 Atom net_wm_action_stick;
106 Atom net_wm_action_maximize_horz;
107 Atom net_wm_action_maximize_vert;
108 Atom net_wm_action_fullscreen;
109 Atom net_wm_action_change_desktop;
110 Atom net_wm_action_close;
112 Atom net_wm_state_modal;
113 Atom net_wm_state_sticky;
114 Atom net_wm_state_maximized_vert;
115 Atom net_wm_state_maximized_horz;
116 Atom net_wm_state_shaded;
117 Atom net_wm_state_skip_taskbar;
118 Atom net_wm_state_skip_pager;
119 Atom net_wm_state_hidden;
120 Atom net_wm_state_fullscreen;
121 Atom net_wm_state_above;
122 Atom net_wm_state_below;
124 Atom kde_net_system_tray_windows;
125 Atom kde_net_wm_system_tray_window_for;
126 Atom kde_net_wm_window_type_override;
134 Atom openbox_active_window;
138 //! Provides easy access to window properties.
142 //! The possible types/encodings of strings
144 ascii, //!< Standard 8-bit ascii string
145 utf8, //!< Utf8-encoded string
146 #ifndef DOXYGEN_IGNORE
151 //! A list of ustrings
152 typedef std::vector<ustring> StringVect;
154 //! The value of all atoms on the X server that exist in the
159 //! Sets a property on a window
160 static void set(Window win, Atom atom, Atom type, unsigned char *data,
161 int size, int nelements, bool append);
162 //! Gets a property's value from a window
163 static bool get(Window win, Atom atom, Atom type,
164 unsigned long *nelements, unsigned char **value,
168 //! Initializes the Property class.
170 CAUTION: This function uses otk::Display, so ensure that
171 otk::Display::initialize has been called before initializing this class!
173 static void initialize();
175 //! Sets a single-value property on a window to a new value
177 @param win The window id of the window on which to set the property's value
178 @param atom The Atom value of the property to set. This can be found in the
179 struct returned by Property::atoms.
180 @param type The Atom value of the property type. This can be found in the
181 struct returned by Property::atoms.
182 @param value The value to set the property to
184 static void set(Window win, Atom atom, Atom type, unsigned long value);
185 //! Sets an multiple-value property on a window to a new value
187 @param win The window id of the window on which to set the property's value
188 @param atom The Atom value of the property to set. This can be found in the
189 struct returned by Property::atoms.
190 @param type The Atom value of the property type. This can be found in the
191 struct returned by Property::atoms.
192 @param value Any array of values to set the property to. The array must
193 contain <i>elements</i> number of elements
194 @param elements The number of elements in the <i>value</i> array
196 static void set(Window win, Atom atom, Atom type,
197 unsigned long value[], int elements);
198 //! Sets a string property on a window to a new value
200 @param win The window id of the window on which to set the property's value
201 @param atom The Atom value of the property to set. This can be found in the
202 struct returned by Property::atoms.
203 @param type A member of the Property::StringType enum that specifies the
204 type of the string the property is being set to
205 @param value The string to set the property to
207 static void set(Window win, Atom atom, StringType type,
208 const ustring &value);
209 //! Sets a string-array property on a window to a new value
211 @param win The window id of the window on which to set the property's value
212 @param atom The Atom value of the property to set. This can be found in the
213 struct returned by Property::atoms.
214 @param type A member of the Property::StringType enum that specifies the
215 type of the string the property is being set to
216 @param strings A list of strings to set the property to
218 static void set(Window win, Atom atom, StringType type,
219 const StringVect &strings);
221 //! Gets the value of a property on a window
223 @param win The window id of the window to get the property value from
224 @param atom The Atom value of the property to set. This can be found in the
225 struct returned by Property::atoms.
226 @param type The Atom value of the property type. This can be found in the
227 struct returned by Property::atoms.
228 @param nelements The maximum number of elements to retrieve from the
229 property (assuming it has more than 1 value in it). To
230 retrieve all possible elements, use "(unsigned) -1".<br>
231 When the function returns, if it returns true, this will
232 contain the actual number of elements retrieved.<br>
233 @param value If the function returns true, then this contains an array of
234 retrieved values for the property.<br>
235 The <i>value</i> is allocated inside the function and
236 <b>delete[]</b> value needs to be called when you are done
238 The <i>value</i> array returned is null terminated, and has
239 <i>nelements</i> elements in it plus the terminating null.
240 @return true if retrieval of the specified property with the specified
241 type was successful; otherwise, false
243 static bool get(Window win, Atom atom, Atom type,
244 unsigned long *nelements, unsigned long **value);
245 //! Gets a single element from the value of a property on a window
247 @param win The window id of the window to get the property value from
248 @param atom The Atom value of the property to set. This can be found in the
249 struct returned by Property::atoms.
250 @param type The Atom value of the property type. This can be found in the
251 struct returned by Property::atoms.
252 @param value If the function returns true, then this contains the first
253 (and possibly only) element in the value of the specified
255 @return true if retrieval of the specified property with the specified
256 type was successful; otherwise, false
258 static bool get(Window win, Atom atom, Atom type, unsigned long *value);
259 //! Gets a single string from the value of a property on a window
261 @param win The window id of the window to get the property value from
262 @param atom The Atom value of the property to set. This can be found in the
263 struct returned by Property::atoms.
264 @param type A member of the Property::StringType enum that specifies the
265 type of the string property to retrieve
266 @param value If the function returns true, then this contains the first
267 (and possibly only) string in the value of the specified
269 @return true if retrieval of the specified property with the specified
270 type was successful; otherwise, false
272 static bool get(Window win, Atom atom, StringType type, ustring *value);
273 //! Gets strings from the value of a property on a window
275 @param win The window id of the window to get the property value from
276 @param atom The Atom value of the property to set. This can be found in the
277 struct returned by Property::atoms.
278 @param type A member of the Property::StringType enum that specifies the
279 type of the string property to retrieve
280 @param nelements The maximum number of strings to retrieve from the
281 property (assuming it has more than 1 string in it). To
282 retrieve all possible strings, use "(unsigned) -1".<br>
283 When the function returns, if it returns true, this will
284 contain the actual number of strings retrieved.<br>
285 @param strings If the function returns true, then this contains all of the
286 strings retrieved from the property's value.
287 @return true if retrieval of the specified property with the specified
288 type was successful; otherwise, false
290 static bool get(Window win, Atom atom, StringType type,
291 unsigned long *nelements, StringVect *strings);
293 //! Removes a property from a window
295 @param win The window id of the window to remove the property from
296 @param atom The Atom value of the property to set. This can be found in the
297 struct returned by Property::atoms.
299 static void erase(Window win, Atom atom);