libs/gtkmm2/gtk/gtkmm/icontheme.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_ICONTHEME_H
   4 #define _GTKMM_ICONTHEME_H
   5
   6 #include <glibmm.h>
   7
   8 /* Copyright (C) 2003 The gtkmm Development Team
   9  *
  10  * This library is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Library General Public
  12  * License as published by the Free Software Foundation; either
  13  * version 2 of the License, or (at your option) any later version.
  14  *
  15  * This library is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Library General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Library General Public
  21  * License along with this library; if not, write to the Free
  22  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  23  */
  24
  25 #include <gdkmm/pixbuf.h>
  26 #include <gdkmm/screen.h>
  27
  28 #include <gtkmm/iconinfo.h>
  29
  30
  31 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  32 typedef struct _GtkIconTheme GtkIconTheme;
  33 typedef struct _GtkIconThemeClass GtkIconThemeClass;
  34 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  35
  36
  37 namespace Gtk
  38 { class IconTheme_Class; } // namespace Gtk
  39 namespace Gtk
  40 {
  41
  42 /** @addtogroup gtkmmEnums Enums and Flags */
  43
  44 /**
  45  * @ingroup gtkmmEnums
  46  * @par Bitwise operators:
  47  * <tt>%IconLookupFlags operator|(IconLookupFlags, IconLookupFlags)</tt><br>
  48  * <tt>%IconLookupFlags operator&(IconLookupFlags, IconLookupFlags)</tt><br>
  49  * <tt>%IconLookupFlags operator^(IconLookupFlags, IconLookupFlags)</tt><br>
  50  * <tt>%IconLookupFlags operator~(IconLookupFlags)</tt><br>
  51  * <tt>%IconLookupFlags& operator|=(IconLookupFlags&, IconLookupFlags)</tt><br>
  52  * <tt>%IconLookupFlags& operator&=(IconLookupFlags&, IconLookupFlags)</tt><br>
  53  * <tt>%IconLookupFlags& operator^=(IconLookupFlags&, IconLookupFlags)</tt><br>
  54  */
  55 enum IconLookupFlags
  56 {
  57   ICON_LOOKUP_NO_SVG = 1 << 0,
  58   ICON_LOOKUP_FORCE_SVG = 1 << 1,
  59   ICON_LOOKUP_USE_BUILTIN = 1 << 2
  60 };
  61
  62 /** @ingroup gtkmmEnums */
  63 inline IconLookupFlags operator|(IconLookupFlags lhs, IconLookupFlags rhs)
  64   { return static_cast<IconLookupFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
  65
  66 /** @ingroup gtkmmEnums */
  67 inline IconLookupFlags operator&(IconLookupFlags lhs, IconLookupFlags rhs)
  68   { return static_cast<IconLookupFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
  69
  70 /** @ingroup gtkmmEnums */
  71 inline IconLookupFlags operator^(IconLookupFlags lhs, IconLookupFlags rhs)
  72   { return static_cast<IconLookupFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
  73
  74 /** @ingroup gtkmmEnums */
  75 inline IconLookupFlags operator~(IconLookupFlags flags)
  76   { return static_cast<IconLookupFlags>(~static_cast<unsigned>(flags)); }
  77
  78 /** @ingroup gtkmmEnums */
  79 inline IconLookupFlags& operator|=(IconLookupFlags& lhs, IconLookupFlags rhs)
  80   { return (lhs = static_cast<IconLookupFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
  81
  82 /** @ingroup gtkmmEnums */
  83 inline IconLookupFlags& operator&=(IconLookupFlags& lhs, IconLookupFlags rhs)
  84   { return (lhs = static_cast<IconLookupFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
  85
  86 /** @ingroup gtkmmEnums */
  87 inline IconLookupFlags& operator^=(IconLookupFlags& lhs, IconLookupFlags rhs)
  88   { return (lhs = static_cast<IconLookupFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
  89
  90
  91 /** Exception class for Gdk::IconTheme errors.
  92  */
  93 class IconThemeError : public Glib::Error
  94 {
  95 public:
  96   enum Code
  97   {
  98     ICON_THEME_NOT_FOUND,
  99     ICON_THEME_FAILED
 100   };
 101
 102   IconThemeError(Code error_code, const Glib::ustring& error_message);
 103   explicit IconThemeError(GError* gobject);
 104   Code code() const;
 105
 106 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 107 private:
 108   static void throw_func(GError* gobject);
 109   friend void wrap_init(); // uses throw_func()
 110 #endif
 111 };
 112
 113 } // namespace Gtk
 114
 115 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 116 namespace Glib
 117 {
 118
 119 template <>
 120 class Value<Gtk::IconThemeError::Code> : public Glib::Value_Enum<Gtk::IconThemeError::Code>
 121 {
 122 public:
 123   static GType value_type() G_GNUC_CONST;
 124 };
 125
 126 } // namespace Glib
 127 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 128
 129
 130 namespace Gtk
 131 {
 132
 133
 134 class IconTheme : public Glib::Object
 135 {
 136
 137 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 138
 139 public:
 140   typedef IconTheme CppObjectType;
 141   typedef IconTheme_Class CppClassType;
 142   typedef GtkIconTheme BaseObjectType;
 143   typedef GtkIconThemeClass BaseClassType;
 144
 145 private:  friend class IconTheme_Class;
 146   static CppClassType icontheme_class_;
 147
 148 private:
 149   // noncopyable
 150   IconTheme(const IconTheme&);
 151   IconTheme& operator=(const IconTheme&);
 152
 153 protected:
 154   explicit IconTheme(const Glib::ConstructParams& construct_params);
 155   explicit IconTheme(GtkIconTheme* castitem);
 156
 157 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 158
 159 public:
 160   virtual ~IconTheme();
 161
 162 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 163   static GType get_type()      G_GNUC_CONST;
 164   static GType get_base_type() G_GNUC_CONST;
 165 #endif
 166
 167   ///Provides access to the underlying C GObject.
 168   GtkIconTheme*       gobj()       { return reinterpret_cast<GtkIconTheme*>(gobject_); }
 169
 170   ///Provides access to the underlying C GObject.
 171   const GtkIconTheme* gobj() const { return reinterpret_cast<GtkIconTheme*>(gobject_); }
 172
 173   ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
 174   GtkIconTheme* gobj_copy();
 175
 176 private:
 177
 178
 179 protected:
 180   IconTheme();
 181 public:
 182
 183   static Glib::RefPtr<IconTheme> create();
 184
 185
 186   /** Gets the icon theme for the default screen. See
 187    * get_for_screen().
 188    * @return A unique Gtk::IconTheme associated with
 189    * the default screen. This icon theme is associated with
 190    * the screen and can be used as long as the screen
 191    * is open.
 192    *
 193    * Since: 2.4.
 194    */
 195   static Glib::RefPtr<IconTheme> get_default();
 196
 197   /** Gets the icon theme object associated with @a screen ; if this
 198    * function has not previously been called for the given
 199    * screen, a new icon theme object will be created and
 200    * associated with the screen. Icon theme objects are
 201    * fairly expensive to create, so using this function
 202    * is usually a better choice than calling than new()
 203    * and setting the screen yourself; by using this function
 204    * a single icon theme object will be shared between users.
 205    * @param screen A Gdk::Screen.
 206    * @return A unique Gtk::IconTheme associated with
 207    * the given screen. This icon theme is associated with
 208    * the screen and can be used as long as the screen
 209    * is open.
 210    *
 211    * Since: 2.4.
 212    */
 213   static Glib::RefPtr<IconTheme> get_for_screen(const Glib::RefPtr<Gdk::Screen>& screen);
 214
 215   /** Sets the screen for an icon theme; the screen is used
 216    * to track the user's currently configured icon theme,
 217    * which might be different for different screens.
 218    *
 219    * Since: 2.4
 220    * @param screen A Gdk::Screen.
 221    */
 222   void set_screen(const Glib::RefPtr<Gdk::Screen>& screen);
 223   void set_search_path(const Glib::ArrayHandle<Glib::ustring>& path);
 224   Glib::ArrayHandle<Glib::ustring> get_search_path() const;
 225
 226   /** Appends a directory to the search path.
 227    * See set_search_path().
 228    *
 229    * Since: 2.4
 230    * @param path Directory name to append to the icon path.
 231    */
 232   void append_search_path(const Glib::ustring& path);
 233
 234   /** Prepends a directory to the search path.
 235    * See set_search_path().
 236    *
 237    * Since: 2.4
 238    * @param path Directory name to prepend to the icon path.
 239    */
 240   void prepend_search_path(const Glib::ustring& path);
 241
 242   /** Sets the name of the icon theme that the Gtk::IconTheme object uses
 243    * overriding system configuration. This function cannot be called
 244    * on the icon theme objects returned from get_default()
 245    * and get_default().
 246    *
 247    * Since: 2.4
 248    * @param theme_name Name of icon theme to use instead of configured theme.
 249    */
 250   void set_custom_theme(const Glib::ustring& theme_name);
 251
 252   /** Checks whether an icon theme includes an icon
 253    * for a particular name.
 254    * @param icon_name The name of an icon.
 255    * @return <tt>true</tt> if @a icon_theme  includes an
 256    * icon for @a icon_name .
 257    *
 258    * Since: 2.4.
 259    */
 260   bool has_icon(const Glib::ustring& icon_name) const;
 261
 262   Glib::ArrayHandle<int> get_icon_sizes(const Glib::ustring& icon_name) const;
 263
 264
 265 //TODO: Update the docs for this, to suggest use of IconInfo::operator bool() instead of saying that it returns null.
 266
 267   /** Looks up a named icon and returns a structure containing
 268    * information such as the filename of the icon. The icon
 269    * can then be rendered into a pixbuf using
 270    * gtk_icon_info_load_icon(). (load_icon()
 271    * combines these two steps if all you need is the pixbuf.)
 272    * @param icon_name The name of the icon to lookup.
 273    * @param size Desired icon size.
 274    * @param flags Flags modifying the behavior of the icon lookup.
 275    * @return A Gtk::IconInfo structure containing information
 276    * about the icon, or <tt>0</tt> if the icon wasn't found. Free with
 277    * gtk_icon_info_free()
 278    *
 279    * Since: 2.4.
 280    */
 281   IconInfo lookup_icon(const Glib::ustring& icon_name, int size, IconLookupFlags flags) const;
 282
 283
 284   /** Looks up an icon in an icon theme, scales it to the given size
 285    * and renders it into a pixbuf. This is a convenience function;
 286    * if more details about the icon are needed, use
 287    * lookup_icon() followed by gtk_icon_info_load_icon().
 288    * @param icon_name The name of the icon to lookup.
 289    * @param size The desired icon size. The resulting icon may not be exactly this size; see gtk_icon_info_load_icon().
 290    * @param flags Flags modifying the behavior of the icon lookup.
 291    * @return The rendered icon; this may be a newly created icon
 292    * or a new reference to an internal icon, so you must not modify
 293    * the icon. Use Glib::object_unref() to release your reference to the
 294    * icon. <tt>0</tt> if the icon isn't found.
 295    *
 296    * Since: 2.4.
 297    */
 298   Glib::RefPtr<Gdk::Pixbuf> load_icon(const Glib::ustring& icon_name, int size, IconLookupFlags flags) const;
 299
 300
 301   /** Lists the icons in the current icon theme. Only a subset
 302    * of the icons can be listed by providing a context string.
 303    * The set of values for the context string is system dependent,
 304    * but will typically include such values as 'apps' and
 305    * 'mimetypes'.
 306    * @param context A string identifying a particular type of icon,
 307    * or <tt>0</tt> to list all icons.
 308    * @return A G::List list holding the names of all the
 309    * icons in the theme. You must first free each element
 310    * in the list with Glib::free(), then free the list itself
 311    * with Glib::list_free().
 312    *
 313    * Since: 2.4.
 314    */
 315   Glib::ListHandle<Glib::ustring> list_icons(const Glib::ustring& context) const;
 316
 317   /** Gets the name of an icon that is representative of the
 318    * current theme (for instance, to use when presenting
 319    * a list of themes to the user.)
 320    * @return The name of an example icon or <tt>0</tt>.
 321    * Free with Glib::free().
 322    *
 323    * Since: 2.4.
 324    */
 325   Glib::ustring get_example_icon_name() const;
 326
 327   /** Checks to see if the icon theme has changed; if it has, any
 328    * currently cached information is discarded and will be reloaded
 329    * next time @a icon_theme  is accessed.
 330    * @return <tt>true</tt> if the icon theme has changed and needed
 331    * to be reloaded.
 332    *
 333    * Since: 2.4.
 334    */
 335   bool rescan_if_needed();
 336
 337   /** Registers a built-in icon for icon theme lookups. The idea
 338    * of built-in icons is to allow an application or library
 339    * that uses themed icons to function requiring files to
 340    * be present in the file system. For instance, the default
 341    * images for all of GTK+'s stock icons are registered
 342    * as built-icons.
 343    *
 344    * In general, if you use add_builtin_icon()
 345    * you should also install the icon in the icon theme, so
 346    * that the icon is generally available.
 347    *
 348    * This function will generally be used with pixbufs loaded
 349    * via gdk_pixbuf_new_from_inline().
 350    *
 351    * Since: 2.4
 352    * @param icon_name The name of the icon to register.
 353    * @param size The size at which to register the icon (different
 354    * images can be registered for the same icon name
 355    * at different sizes.).
 356    * @param pixbuf Gdk::Pixbuf that contains the image to use
 357    * for @a icon_name .
 358    */
 359   static void add_builtin_icon(const Glib::ustring& icon_name, int size, const Glib::RefPtr<Gdk::Pixbuf>& pixbuf);
 360
 361
 362   Glib::SignalProxy0< void > signal_changed();
 363
 364
 365 public:
 366
 367 public:
 368   //C++ methods used to invoke GTK+ virtual functions:
 369
 370 protected:
 371   //GTK+ Virtual Functions (override these to change behaviour):
 372
 373   //Default Signal Handlers::
 374   virtual void on_changed();
 375
 376
 377 };
 378
 379 } // namespace Gtk
 380
 381
 382 namespace Glib
 383 {
 384   /** @relates Gtk::IconTheme
 385    * @param object The C instance
 386    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 387    * @result A C++ instance that wraps this C instance.
 388    */
 389   Glib::RefPtr<Gtk::IconTheme> wrap(GtkIconTheme* object, bool take_copy = false);
 390 }
 391
 392
 393 #endif /* _GTKMM_ICONTHEME_H */
 394