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
 128
 129 //! Provides easy access to window properties.
 130 class Property {
 131 public:
 132
 133   //! The possible types/encodings of strings
 134   enum StringType {
 135     ascii, //!< Standard 8-bit ascii string
 136     utf8,  //!< Utf8-encoded string
 137 #ifndef DOXYGEN_IGNORE
 138     NUM_STRING_TYPE
 139 #endif
 140   };
 141
 142   //! A list of ustrings
 143   typedef std::vector<ustring> StringVect;
 144
 145   //! The value of all atoms on the X server that exist in the
 146   //! Atoms struct
 147   static Atoms atoms;
 148
 149 private:
 150   //! Sets a property on a window
 151   static void set(Window win, Atom atom, Atom type, unsigned char *data,
 152                   int size, int nelements, bool append);
 153   //! Gets a property's value from a window
 154   static bool get(Window win, Atom atom, Atom type,
 155                   unsigned long *nelements, unsigned char **value,
 156                   int size);
 157
 158 public:
 159   //! Initializes the Property class.
 160   /*!
 161     CAUTION: This function uses otk::Display, so ensure that
 162     otk::Display::initialize has been called before initializing this class!
 163   */
 164   static void initialize();
 165
 166   //! Sets a single-value property on a window to a new value
 167   /*!
 168     @param win The window id of the window on which to set the property's value
 169     @param atom The Atom value of the property to set. This can be found in the
 170                 struct returned by Property::atoms.
 171     @param type The Atom value of the property type. This can be found in the
 172                 struct returned by Property::atoms.
 173     @param value The value to set the property to
 174   */
 175   static void set(Window win, Atom atom, Atom type, unsigned long value);
 176   //! Sets an multiple-value property on a window to a new value
 177   /*!
 178     @param win The window id of the window on which to set the property's value
 179     @param atom The Atom value of the property to set. This can be found in the
 180                 struct returned by Property::atoms.
 181     @param type The Atom value of the property type. This can be found in the
 182                 struct returned by Property::atoms.
 183     @param value Any array of values to set the property to. The array must
 184                  contain <i>elements</i> number of elements
 185     @param elements The number of elements in the <i>value</i> array
 186   */
 187   static void set(Window win, Atom atom, Atom type,
 188                   unsigned long value[], int elements);
 189   //! Sets a string property on a window to a new value
 190   /*!
 191     @param win The window id of the window on which to set the property's value
 192     @param atom The Atom value of the property to set. This can be found in the
 193                 struct returned by Property::atoms.
 194     @param type A member of the Property::StringType enum that specifies the
 195                 type of the string the property is being set to
 196     @param value The string to set the property to
 197   */
 198   static void set(Window win, Atom atom, StringType type,
 199                   const ustring &value);
 200   //! Sets a string-array property on a window to a new value
 201   /*!
 202     @param win The window id of the window on which to set the property's value
 203     @param atom The Atom value of the property to set. This can be found in the
 204                 struct returned by Property::atoms.
 205     @param type A member of the Property::StringType enum that specifies the
 206                 type of the string the property is being set to
 207     @param strings A list of strings to set the property to
 208   */
 209   static void set(Window win, Atom atom, StringType type,
 210                   const StringVect &strings);
 211
 212   //! Gets the value of a property on a window
 213   /*!
 214     @param win The window id of the window to get the property value from
 215     @param atom The Atom value of the property to set. This can be found in the
 216                 struct returned by Property::atoms.
 217     @param type The Atom value of the property type. This can be found in the
 218                 struct returned by Property::atoms.
 219     @param nelements The maximum number of elements to retrieve from the
 220                      property (assuming it has more than 1 value in it). To
 221                      retrieve all possible elements, use "(unsigned) -1".<br>
 222                      When the function returns, if it returns true, this will
 223                      contain the actual number of elements retrieved.<br>
 224     @param value If the function returns true, then this contains an array of
 225                  retrieved values for the property.<br>
 226                  The <i>value</i> is allocated inside the function and
 227                  <b>delete[]</b> value needs to be called when you are done
 228                  with it.<br>
 229                  The <i>value</i> array returned is null terminated, and has
 230                  <i>nelements</i> elements in it plus the terminating null.
 231     @return true if retrieval of the specified property with the specified
 232             type was successful; otherwise, false
 233   */
 234   static bool get(Window win, Atom atom, Atom type,
 235                   unsigned long *nelements, unsigned long **value);
 236   //! Gets a single element from the value of a property on a window
 237   /*!
 238     @param win The window id of the window to get the property value from
 239     @param atom The Atom value of the property to set. This can be found in the
 240                 struct returned by Property::atoms.
 241     @param type The Atom value of the property type. This can be found in the
 242                 struct returned by Property::atoms.
 243     @param value If the function returns true, then this contains the first
 244                  (and possibly only) element in the value of the specified
 245                  property.
 246     @return true if retrieval of the specified property with the specified
 247             type was successful; otherwise, false
 248   */
 249   static bool get(Window win, Atom atom, Atom type, unsigned long *value);
 250   //! Gets a single string from the value of a property on a window
 251   /*!
 252     @param win The window id of the window to get the property value from
 253     @param atom The Atom value of the property to set. This can be found in the
 254                 struct returned by Property::atoms.
 255     @param type A member of the Property::StringType enum that specifies the
 256                 type of the string property to retrieve
 257     @param value If the function returns true, then this contains the first
 258                  (and possibly only) string in the value of the specified
 259                  property.
 260     @return true if retrieval of the specified property with the specified
 261             type was successful; otherwise, false
 262   */
 263   static bool get(Window win, Atom atom, StringType type, ustring *value);
 264   //! Gets strings from the value of a property on a window
 265   /*!
 266     @param win The window id of the window to get the property value from
 267     @param atom The Atom value of the property to set. This can be found in the
 268                 struct returned by Property::atoms.
 269     @param type A member of the Property::StringType enum that specifies the
 270                 type of the string property to retrieve
 271     @param nelements The maximum number of strings to retrieve from the
 272                      property (assuming it has more than 1 string in it). To
 273                      retrieve all possible strings, use "(unsigned) -1".<br>
 274                      When the function returns, if it returns true, this will
 275                      contain the actual number of strings retrieved.<br>
 276     @param strings If the function returns true, then this contains all of the
 277                    strings retrieved from the property's value.
 278     @return true if retrieval of the specified property with the specified
 279             type was successful; otherwise, false
 280   */
 281   static bool get(Window win, Atom atom, StringType type,
 282                   unsigned long *nelements, StringVect *strings);
 283
 284   //! Removes a property from a window
 285   /*!
 286     @param win The window id of the window to remove the property from
 287     @param atom The Atom value of the property to set. This can be found in the
 288                 struct returned by Property::atoms.
 289   */
 290   static void erase(Window win, Atom atom);
 291 };
 292
 293 }
 294
 295 #endif // __atom_hh