Xfce Foundation Classes

Xfc::Gtk::IconSet Class Reference

A GtkIconSet C++ wrapper class. More...

#include <xfc/gtk/iconfactory.hh>

Inheritance diagram for Xfc::Gtk::IconSet:

List of all members.

Public Member Functions

Constructors

IconSet ()
Constructs a new IconSet with a reference count of 1 that the caller owns.
IconSet (Gdk::Pixbuf &pixbuf)
Constructs a new IconSet with pixbuf as the default/fallback source image.
IconSet (GtkIconSet *icon_set)
Constructs a new IconSet from an existing GtkIconSet.
IconSet (GtkIconSet *icon_set, bool copy)
Constructs a new IconSet from an existing GtkIconSet.
IconSet (const IconSet &src)
Copy constructor.
~IconSet ()
Destructor.
IconSet & operator= (const IconSet &src)
Assignment operator.

Accessors

GtkIconSet * gtk_icon_set () const
Get a pointer to the GtkIconSet structure.
operator GtkIconSet * () const
Conversion operator; safely converts an IconSet to a GtkIconSet pointer.
bool get_sizes (std::vector< IconSize > &sizes) const
Obtains a list of icon sizes this icon set can render.

Methods

Pointer< Gdk::Pixbuf > render_icon (Style &style, StateType state, IconSize size, Widget *widget=0, const char *detail=0, TextDirection direction=TEXT_DIR_LTR)
Renders an icon using Gtk::Style::render_icon().
void add_source (const IconSource &source)
Add an IconSource to the icon set.

Detailed Description

A GtkIconSet C++ wrapper class.

An IconSet represents a single icon in various sizes and widget states. It can provide a Gdk::Pixbuf for a given size and state on request, and automatically caches some of the rendered Gdk::Pixbuf objects. Normally you would use Gtk::Widget::render_icon() instead of using IconSet directly. The one case where you'd use IconSet is to create application-specific icon sets to place in an IconFactory.

Note: dynamically allocated objects must either be unreferenced or assigned to a smart pointer. Stack objects are automatically unreferenced when they go out of scope.

Constructor & Destructor Documentation

Xfc::Gtk::IconSet::IconSet ( Gdk::Pixbuf & pixbuf ) [explicit]

Constructs a new IconSet with pixbuf as the default/fallback source image.

Parameters:

pixbuf A Gdk::Pixbuf.

If you don't add any additional IconSource to the icon set, all variants of the icon will be created from pixbuf, using scaling, pixelation, etc. as required to adjust the icon size or make the icon look insensitive/prelighted. The IconSet is created with a reference count of 1 that the caller owns.

Xfc::Gtk::IconSet::IconSet ( GtkIconSet * icon_set ) [explicit]

Constructs a new IconSet from an existing GtkIconSet.

Parameters:

icon_set A GtkIconSet.

This constructor creates a temporary wrapper for a GtkIconSet. It neither copies the GtkIconSet or takes over its ownership. The IconSet is created with a reference count of 1 that the caller owns.

Xfc::Gtk::IconSet::IconSet ( GtkIconSet * icon_set,

bool copy

)

Constructs a new IconSet from an existing GtkIconSet.

Parameters:

icon_set A GtkIconSet.

copy true if a copy of GtkIconSet should be made.

This constructor either takes over the ownership of the GtkIconSet, or makes a copy of the GtkIconSet. The IconSet is created with a reference count of 1 that the caller owns. This constructor is primarily intended for use by the G::Boxed::wrap() method.

Member Function Documentation

void Xfc::Gtk::IconSet::add_source ( const IconSource & source )

Add an IconSource to the icon set.

Parameters:

source An IconSource.

Icon sets have a list of IconSource, which they use as base icons for rendering icons in different states and sizes.
Icons are scaled, made to look insensitive, etc. in render_icon(), but IconSet needs base images to work with. The base images and when to use them are described by a IconSource. This method copies source, so you can reuse the same source immediately without affecting the icon set. An example of when you'd use this method: a web browser's "Back to Previous Page" icon might point in a different direction in Hebrew and in English; it might look different when insensitive; and it might change size depending on toolbar mode (small/large icons). So a single icon set would contain all those variants of the icon, and you might add a separate source for each one.
You should nearly always add a "default" icon source with all fields wildcarded, which will be used as a fallback if no more specific source matches. IconSet always prefers more specific icon sources to more generic icon sources. The order in which you add the sources to the icon set does not matter. When you construct an IconSet with a pixbuf, the icon set creates a default icon source based on the pixbuf.

bool Xfc::Gtk::IconSet::get_sizes ( std::vector< IconSize > & sizes ) const

Obtains a list of icon sizes this icon set can render.

Parameters:

sizes A reference to a vector of IconSize to hold the sizes.

Returns:
true if sizes contains any sizes; false if empty.

Pointer<Gdk::Pixbuf> Xfc::Gtk::IconSet::render_icon ( Style & style,

StateType state,

IconSize size,

Widget * widget = 0,

const char * detail = 0,

TextDirection direction = TEXT_DIR_LTR

)

Renders an icon using Gtk::Style::render_icon().

Parameters:

style A Style associated with widget.

state The widget state.

size The icon size.

widget The widget that will display the icon, or null.

detail The detail to pass to the theme engine, or null.

direction The text direction.

Returns:
A Gdk::Pixbuf to be displayed.
In most cases, Gtk::Widget::render_icon() is better, since it automatically provides most of the arguments from the current widget settings. This method never returns null; if the icon can't be rendered (perhaps because an image file fails to load), a default "missing image" icon will be returned instead. A smart pointer to a Gdk::Pixbuf is returned because the returned pixbuf must be unreferenced. This will happen automatically when the smart pointer goes out of scope.

The documentation for this class was generated from the following file:

iconset.hh

Xfce Foundation Classes

XFC 4.3