Dogcows Code - chaz/openbox/blob - otk/property.hh

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