all new stacked cycling code. so much sexy.
[mikachu/openbox.git] / otk / property.hh
1 // -*- mode: C++; indent-tabs-mode: nil; c-basic-offset: 2; -*-
2 #ifndef   __atom_hh
3 #define   __atom_hh
4
5 /*! @file property.hh
6   @brief Provides access to window properties
7 */
8
9 #include "ustring.hh"
10 #include "screeninfo.hh"
11
12 extern "C" {
13 #include <X11/Xlib.h>
14
15 #include <assert.h>
16 }
17
18 #include <vector>
19
20 namespace otk {
21
22 //! The atoms on the X server which this class will cache
23 struct Atoms {
24   // types
25   Atom cardinal; //!< The atom which represents the Cardinal data type
26   Atom window;   //!< The atom which represents window ids
27   Atom pixmap;   //!< The atom which represents pixmap ids
28   Atom atom;     //!< The atom which represents atom values
29   Atom string;   //!< The atom which represents ascii strings
30   Atom utf8;     //!< The atom which represents utf8-encoded strings
31
32   Atom openbox_pid;
33
34   // window hints
35   Atom wm_colormap_windows;
36   Atom wm_protocols;
37   Atom wm_state;
38   Atom wm_delete_window;
39   Atom wm_take_focus;
40   Atom wm_change_state;
41   Atom wm_name;
42   Atom wm_icon_name;
43   Atom wm_class;
44   Atom wm_window_role;
45   Atom motif_wm_hints;
46
47   Atom openbox_show_root_menu;
48   Atom openbox_show_workspace_menu;
49
50   // NETWM atoms
51   // root window properties
52   Atom net_supported;
53   Atom net_client_list;
54   Atom net_client_list_stacking;
55   Atom net_number_of_desktops;
56   Atom net_desktop_geometry;
57   Atom net_desktop_viewport;
58   Atom net_current_desktop;
59   Atom net_desktop_names;
60   Atom net_active_window;
61   Atom net_workarea;
62   Atom net_supporting_wm_check;
63 //  Atom net_virtual_roots;
64   // root window messages
65   Atom net_close_window;
66   Atom net_wm_moveresize;
67   // application window properties
68 //  Atom net_properties;
69   Atom net_wm_name;
70   Atom net_wm_visible_name;
71   Atom net_wm_icon_name;
72   Atom net_wm_visible_icon_name;
73   Atom net_wm_desktop;
74   Atom net_wm_window_type;
75   Atom net_wm_state;
76   Atom net_wm_strut;
77 //  Atom net_wm_icon_geometry;
78 //  Atom net_wm_icon;
79 //  Atom net_wm_pid;
80 //  Atom net_wm_handled_icons;
81   Atom net_wm_allowed_actions;
82   // application protocols
83 //  Atom   Atom net_wm_ping;
84
85   Atom net_wm_window_type_desktop;
86   Atom net_wm_window_type_dock;
87   Atom net_wm_window_type_toolbar;
88   Atom net_wm_window_type_menu;
89   Atom net_wm_window_type_utility;
90   Atom net_wm_window_type_splash;
91   Atom net_wm_window_type_dialog;
92   Atom net_wm_window_type_normal;
93
94   Atom net_wm_moveresize_size_topleft;
95   Atom net_wm_moveresize_size_topright;
96   Atom net_wm_moveresize_size_bottomleft;
97   Atom net_wm_moveresize_size_bottomright;
98   Atom net_wm_moveresize_move;
99
100   Atom net_wm_action_move;
101   Atom net_wm_action_resize;
102   Atom net_wm_action_minimize;
103   Atom net_wm_action_shade;
104   Atom net_wm_action_stick;
105   Atom net_wm_action_maximize_horz;
106   Atom net_wm_action_maximize_vert;
107   Atom net_wm_action_fullscreen;
108   Atom net_wm_action_change_desktop;
109   Atom net_wm_action_close;
110
111   Atom net_wm_state_modal;
112   Atom net_wm_state_sticky;
113   Atom net_wm_state_maximized_vert;
114   Atom net_wm_state_maximized_horz;
115   Atom net_wm_state_shaded;
116   Atom net_wm_state_skip_taskbar;
117   Atom net_wm_state_skip_pager;
118   Atom net_wm_state_hidden;
119   Atom net_wm_state_fullscreen;
120   Atom net_wm_state_above;
121   Atom net_wm_state_below;
122
123   Atom kde_net_system_tray_windows;
124   Atom kde_net_wm_system_tray_window_for;
125   Atom kde_net_wm_window_type_override;
126
127   Atom openbox_premax;
128   Atom openbox_active_window;
129 };
130
131
132 //! Provides easy access to window properties.
133 class Property {
134 public:
135   
136   //! The possible types/encodings of strings
137   enum StringType {
138     ascii, //!< Standard 8-bit ascii string
139     utf8,  //!< Utf8-encoded string
140 #ifndef DOXYGEN_IGNORE
141     NUM_STRING_TYPE
142 #endif
143   };
144
145   //! A list of ustrings
146   typedef std::vector<ustring> StringVect;
147
148   //! The value of all atoms on the X server that exist in the
149   //! Atoms struct
150   static Atoms atoms;
151
152 private:
153   //! Sets a property on a window
154   static void set(Window win, Atom atom, Atom type, unsigned char *data,
155                   int size, int nelements, bool append);
156   //! Gets a property's value from a window
157   static bool get(Window win, Atom atom, Atom type,
158                   unsigned long *nelements, unsigned char **value,
159                   int size);
160
161 public:
162   //! Initializes the Property class.
163   /*!
164     CAUTION: This function uses otk::Display, so ensure that
165     otk::Display::initialize has been called before initializing this class!
166   */
167   static void initialize();
168
169   //! Sets a single-value property on a window to a new value
170   /*!
171     @param win The window id of the window on which to set the property's value
172     @param atom The Atom value of the property to set. This can be found in the
173                 struct returned by Property::atoms.
174     @param type The Atom value of the property type. This can be found in the
175                 struct returned by Property::atoms.
176     @param value The value to set the property to
177   */
178   static void set(Window win, Atom atom, Atom type, unsigned long value);
179   //! Sets an multiple-value property on a window to a new value
180   /*!
181     @param win The window id of the window on which to set the property's value
182     @param atom The Atom value of the property to set. This can be found in the
183                 struct returned by Property::atoms.
184     @param type The Atom value of the property type. This can be found in the
185                 struct returned by Property::atoms.
186     @param value Any array of values to set the property to. The array must
187                  contain <i>elements</i> number of elements
188     @param elements The number of elements in the <i>value</i> array
189   */
190   static void set(Window win, Atom atom, Atom type,
191                   unsigned long value[], int elements);
192   //! Sets a string property on a window to a new value
193   /*!
194     @param win The window id of the window on which to set the property's value
195     @param atom The Atom value of the property to set. This can be found in the
196                 struct returned by Property::atoms.
197     @param type A member of the Property::StringType enum that specifies the
198                 type of the string the property is being set to
199     @param value The string to set the property to
200   */
201   static void set(Window win, Atom atom, StringType type,
202                   const ustring &value);
203   //! Sets a string-array property on a window to a new value
204   /*!
205     @param win The window id of the window on which to set the property's value
206     @param atom The Atom value of the property to set. This can be found in the
207                 struct returned by Property::atoms.
208     @param type A member of the Property::StringType enum that specifies the
209                 type of the string the property is being set to
210     @param strings A list of strings to set the property to
211   */
212   static void set(Window win, Atom atom, StringType type,
213                   const StringVect &strings);
214
215   //! Gets the value of a property on a window
216   /*!
217     @param win The window id of the window to get the property value from
218     @param atom The Atom value of the property to set. This can be found in the
219                 struct returned by Property::atoms.
220     @param type The Atom value of the property type. This can be found in the
221                 struct returned by Property::atoms.
222     @param nelements The maximum number of elements to retrieve from the
223                      property (assuming it has more than 1 value in it). To
224                      retrieve all possible elements, use "(unsigned) -1".<br>
225                      When the function returns, if it returns true, this will
226                      contain the actual number of elements retrieved.<br>
227     @param value If the function returns true, then this contains an array of
228                  retrieved values for the property.<br>
229                  The <i>value</i> is allocated inside the function and
230                  <b>delete[]</b> value needs to be called when you are done
231                  with it.<br>
232                  The <i>value</i> array returned is null terminated, and has
233                  <i>nelements</i> elements in it plus the terminating null.
234     @return true if retrieval of the specified property with the specified
235             type was successful; otherwise, false
236   */
237   static bool get(Window win, Atom atom, Atom type,
238                   unsigned long *nelements, unsigned long **value);
239   //! Gets a single element from the value of a property on a window
240   /*!
241     @param win The window id of the window to get the property value from
242     @param atom The Atom value of the property to set. This can be found in the
243                 struct returned by Property::atoms.
244     @param type The Atom value of the property type. This can be found in the
245                 struct returned by Property::atoms.
246     @param value If the function returns true, then this contains the first
247                  (and possibly only) element in the value of the specified
248                  property.
249     @return true if retrieval of the specified property with the specified
250             type was successful; otherwise, false
251   */
252   static bool get(Window win, Atom atom, Atom type, unsigned long *value);
253   //! Gets a single string from the value of a property on a window
254   /*!
255     @param win The window id of the window to get the property value from
256     @param atom The Atom value of the property to set. This can be found in the
257                 struct returned by Property::atoms.
258     @param type A member of the Property::StringType enum that specifies the
259                 type of the string property to retrieve
260     @param value If the function returns true, then this contains the first
261                  (and possibly only) string in the value of the specified
262                  property.
263     @return true if retrieval of the specified property with the specified
264             type was successful; otherwise, false
265   */
266   static bool get(Window win, Atom atom, StringType type, ustring *value);
267   //! Gets strings from the value of a property on a window
268   /*!
269     @param win The window id of the window to get the property value from
270     @param atom The Atom value of the property to set. This can be found in the
271                 struct returned by Property::atoms.
272     @param type A member of the Property::StringType enum that specifies the
273                 type of the string property to retrieve
274     @param nelements The maximum number of strings to retrieve from the
275                      property (assuming it has more than 1 string in it). To
276                      retrieve all possible strings, use "(unsigned) -1".<br>
277                      When the function returns, if it returns true, this will
278                      contain the actual number of strings retrieved.<br>
279     @param strings If the function returns true, then this contains all of the
280                    strings retrieved from the property's value.
281     @return true if retrieval of the specified property with the specified
282             type was successful; otherwise, false
283   */
284   static bool get(Window win, Atom atom, StringType type,
285                   unsigned long *nelements, StringVect *strings);
286
287   //! Removes a property from a window
288   /*!
289     @param win The window id of the window to remove the property from
290     @param atom The Atom value of the property to set. This can be found in the
291                 struct returned by Property::atoms.
292   */
293   static void erase(Window win, Atom atom);
294 };
295
296 }
297
298 #endif // __atom_hh