Xfce Foundation Classes

The Image widget displays an image. Various kinds of objects can be displayed as an image; most typically, you would load a Gdk::Pixbuf from a file, and then display that. There's a convenience constructor to do this, used as follows:

    Gtk::Image *image = new Gtk::Image("myfile.png");

If the file isn't loaded successfully, the image will contain a "broken image" icon similar to that used in many web browsers. If you want to handle errors in loading the file yourself, for example by displaying an error message, then load the image as a Gdk::Pixbuf, then create the Image with the pixbuf, like this:

    G::Error error;
    Pointer<Gdk::Pixbuf> pixbuf = Gdk::Pixbuf::create("myfile.png", &error);
    if (error.get())
    {
        display_some_message();
    }
    else
    {
        Gtk::Image *image = new Gtk::Image(pixbuf);
    }

A Gdk::Pixbuf smart pointer is used because the new pixbuf must be unreferecned. You don't need to hold on to a reference, the Image will do that.

The image file may contain an animation, if so the Image will display an animation (Gdk::PixbufAnimation) instead of a static image. Image is a subclass of Misc, which implies that you can align it (center, left, right) and add padding to it, using Misc methods. Image is a "no window" widget (has no Gdk::Window of its own), so by default does not receive events. If you want to receive events on the image, such as button clicks, place the image inside an EventBox, then connect to the event signals on the event box.

    #include <xfc/main.h>
    #include <xfc/gtk/image.h>
    #include <xfc/gtk/eventbox.h>
    #include <xfc/gtk/window.h>
    #include <xfc/bind.h>
   
    using namespace Xfc;
   
    class Window : public Gtk::Window
    {
    protected:
        bool on_image_button_press(GdkEventButton *event, Gtk::Image *image);
    public:
        Window();
    };
   
    Window::Window()
    {
        set_title("Basic Window");
   
        // Create the event box and image.
        Gtk::EventBox *event_box = new Gtk::EventBox;
        Gtk::Image *image = new Gtk::Image("myfile.png");
   
        // If you have more than one image you could bind the new image to the slot, like this.
        event_box->signal_button_press_event().connect(bind(slot(this, &Window::on_image_button_press), image));
   
        // Add the image to the event box and then the event box to the window.
        event_box->add(*image);
        add(*event_box);
   
        event_box->show_all();
        show();
    }
   
    bool
    Window::on_image_button_press(GdkEventButton *event, Gtk::Image *image)
    {
        g_print ("Event box clicked at coordinates %.0f,%.0f\n", event->x, event->y);
   
        // The event was handled so return true to stop any further signal emission.
        return true;
    }
   
    int main (int argc, char *argv[])
    {
        using namespace Main;
   
        init(&argc, &argv);
   
        Window window;
        window.signal_destroy().connect(slot(&Xfc::Main::quit));
   
        run();
        return 0;
    }

When handling events on the event box, keep in mind that coordinates in the image may be different from event box coordinates due to the alignment and padding settings on the image (see Misc). The simplest way to solve this is to set the alignment to 0.0 (left/top), and set the padding to zero. Then the origin of the image will be the same as the origin of the event box.

Sometimes an application will want to avoid depending on external data files, such as image files. GTK+ comes with a program to avoid this, called gdk-pixbuf-csource. This program allows you to convert an image into a C variable declaration, which can then be passed to the Gdk::Pixbuf constructor:

    Pixbuf(int stream_length, const unsigned char *stream, bool copy_pixels, G::Error *error = 0);

Constructor & Destructor Documentation

Xfc::Gtk::Image::Image	(	GtkImage *	image,
		bool	owns_reference = `false`
	)	`[explicit, protected]`

Construct a new Image from an existing GtkImage.

Parameters:

	image	A pointer to a GtkImage.
	owns_reference	Set false if the initial reference count is floating, set true if it's not.

The image can be a newly created GtkImage or an existing GtkImage (see G::Object::Object).

Xfc::Gtk::Image::Image	(	Gdk::Pixmap &	pixmap,
		Gdk::Bitmap &	mask
	)

Constructs an Image widget displaying a pixmap with a mask.

Parameters:

	pixmap	A Gdk::Pixmap.
	mask	A Gdk::Bitmap.

The Image does not assume a reference to the pixmap or mask; you still need to unref them if you own references. Image will add its own reference rather than adopting yours.

Xfc::Gtk::Image::Image	(	Gdk::Image &	image,
		Gdk::Bitmap &	mask
	)

Construct an Image widget displaying a image with a mask.

Parameters:

	image	A Gdk::Image.
	mask	A Gdk::Bitmap.

An Image is a client-side image buffer in the pixel format of the current display. The Image does not assume a reference to the image or mask; you still need to unref them if you own references. Image will add its own reference rather than adopting yours.

Xfc::Gtk::Image::Image ( const String & filename ) [explicit]

Construct a new Image displaying the file filename.

Parameters:

filename

A filename.

If the file isn't found or can't be loaded, the resulting Image will display a "broken image" icon. If the file contains an animation, the image will contain an animation. If you need to detect failures to load the file, use Gdk::Pixbuf to load the file yourself, then create the Image from the pixbuf. (Or for animations, use Gdk::PixbufAnimation. The storage type (get_storage_type()) of the Image is not defined, it will be whatever is appropriate for displaying the file.

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

Construct a new Image displaying pixbuf.

Parameters:

pixbuf

A Gdk::Pixbuf.

The Image does not assume a reference to the pixbuf; you still need to unref it if you own references. Image will add its own reference rather than adopting yours. Note that this method just creates an Image from the pixbuf. The Image created will not react to state changes. Should you want that, you should use an IconSet.

Xfc::Gtk::Image::Image ( const char ** xpm_data ) [explicit]

Construct a new Image by parsing XPM data in memory.

Parameters:

xpm_data

A pointer to inline XPM data.

The xpm_data is commonly the result of including an XPM file into a program's C source. This method creates a new GdkPixbuf by parsing XPM data in memory and then constructs the Image from the pixbuf.

Xfc::Gtk::Image::Image	(	const StockId &	stock_id,
		IconSize	size
	)

Construct an Image displaying a stock icon.

Parameters:

	stock_id	A stock icon ID.
	size	A stock icon size.

Sample stock icon names are Gtk:StockId::OPEN, Gtk:StockId::EXIT. Sample stock sizes are ICON_SIZE_MENU, ICON_SIZE_SMALL_TOOLBAR. If the stock icon name isn't known, a "broken image" icon will be displayed instead. You can register your own stock icon names, see Gtk::IconFactory::add_default() and Gtk::IconFactory::add().

Xfc::Gtk::Image::Image	(	IconSet &	icon_set,
		IconSize	size
	)

Construct an Image displaying an icon set.

Parameters:

	icon_set	An IconSet.
	size	A stock icon size.

Sample stock sizes are ICON_SIZE_MENU, ICON_SIZE_SMALL_TOOLBAR. Instead of using this method, usually it's better to create an IconFactory, put your icon sets in the icon factory, add the icon factory to the list of default factories with Gtk::IconFactory::add_default(), and then contruct the Image from the stock ID and icon size. This will allow themes to override the icon you ship with your application. The Image does not assume a reference to the icon set; you still need to unref it if you own references. Image will add its own reference rather than adopting yours.

Xfc::Gtk::Image::Image ( Gdk::PixbufAnimation & animation ) [explicit]

Construct an Image displaying the given animation.

Parameters:

animation

An animation.

The Image does not assume a reference to the animation; you still need to unref it if you own references. Image will add its own reference rather than adopting yours.

Xfc::Gtk::Image::Image	(	const String &	icon_name,
		IconSize	size
	)

Construct an Image displaying an icon from the current icon theme.

Parameters:

	icon_name	An icon name.
	size	A stock icon size.

If the icon name isn't known, a "broken image" icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately.

Member Function Documentation

Gdk::PixbufAnimation* Xfc::Gtk::Image::get_animation

(

)

const

Gets the Gdk::PixbufAnimation being displayed by the Image.

Returns:: The displayed animation, or null if the image is empty.

The storage type of the image must be IMAGE_EMPTY or IMAGE_ANIMATION (see get_storage_type()). The caller of this method does not own a reference to the returned animation.

void Xfc::Gtk::Image::get_icon_name	(	String &	icon_name,
		IconSize *	size
	)	const

Gets the icon name and size being displayed by the GtkImage.

Parameters:

	icon_name	A String to hold the icon name.
	size	A place to store the icon size.

The storage type of the image must be Gtk::IMAGE_EMPTY or Gtk::IMAGE_ICON_NAME (see get_storage_type()).

void Xfc::Gtk::Image::get_icon_set	(	Pointer< IconSet > *	icon_set,
		IconSize *	size
	)	const

Gets the icon set and size being displayed by the Image.

Parameters:

	icon_set	An IconSet smart pointer to store a pointer to the IconSet.
	size	The location to store a stock icon size.

The storage type of the image must be IMAGE_EMPTY or IMAGE_ICON_SET (see get_storage_type()).

void Xfc::Gtk::Image::get_image	(	Gdk::Image **	gdk_image,
		Gdk::Bitmap **	mask
	)	const

Gets the Gdk::Image and mask being displayed by the Image.

Parameters:

	gdk_image	The return location for the Gdk::Image.
	mask	The return location for the Gdk::Bitmap.

The storage type of the image must be IMAGE_EMPTY or IMAGE_IMAGE (see get_storage_type()). The caller of this method does not own a reference to the returned image and mask.

Gdk::Pixbuf* Xfc::Gtk::Image::get_pixbuf

(

)

const

Gets the Gdk::Pixbuf being displayed by the Image.

Returns:: The displayed pixbuf, or null if the image is empty.

The storage type of the image must be IMAGE_EMPTY or IMAGE_PIXBUF (see get_storage_type()). The caller of this function does not own a reference to the returned pixbuf.

int Xfc::Gtk::Image::get_pixel_size

(

)

const

Gets the pixel size used for named icons.

Returns:: The pixel size used for named icons.

void Xfc::Gtk::Image::get_pixmap	(	Gdk::Pixmap **	pixmap,
		Gdk::Bitmap **	mask
	)	const

Gets the pixmap and mask being displayed by the Image.

Parameters:

	pixmap	The location to store the pixmap, or null.
	mask	The location to store the mask, or null.

The storage type of the image must be IMAGE_EMPTY or IMAGE_PIXMAP (see get_storage_type()). The caller of this function does not own a reference to the returned pixmap and mask.

void Xfc::Gtk::Image::get_stock	(	StockId *	stock_id,
		IconSize *	size
	)	const

Gets the stock icon name and size being displayed by the Image.

Parameters:

	stock_id	The place to store the stock icon ID.
	size	The place to store the stock icon size.

The storage type of the image must be IMAGE_EMPTY or IMAGE_STOCK (see get_storage_type()). In the version of this function that sets a char* string, the string is owned by the Image and should not be freed.

ImageType Xfc::Gtk::Image::get_storage_type

(

)

const

Gets the type of representation being used by the Image to store image data.

Returns:: The image representation being used.

If the GtkImage has no image data, the return value will be IMAGE_EMPTY.

void Xfc::Gtk::Image::reset

(

)

Clears the image and resets its size to zero width and height.

After calling this this method the actual image size will be the xpad and ypad values set by calling Gtk::Misc::set_padding().

void Xfc::Gtk::Image::set	(	const String &	icon_name,
		IconSize	size
	)

Set the icon to be displayed by the image from an icon name in the current icon theme.

Parameters:

	icon_name	An icon name.
	size	A stock icon size.

If the icon name isn't known, a "broken image" icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately.

void Xfc::Gtk::Image::set

(

Gdk::PixbufAnimation &

animation

)

Set the animation to be displayed by the image.

Parameters:

animation

An animation.

The Image does not assume a reference to the animation; you still need to unref it if you own references. Image will add its own reference rather than adopting yours.

void Xfc::Gtk::Image::set	(	Gtk::IconSet *	icon_set,
		IconSize	size
	)

Set the icon set and icon size to be displayed by the image.

Parameters:

	icon_set	An IconSet.
	size	A stock icon size.

void Xfc::Gtk::Image::set	(	const StockId &	stock_id,
		IconSize	size
	)

Set the stock icon name and size to be displayed by the Image.

Parameters:

	stock_id	The stock icon ID.
	size	The stock icon size.

The storage type of the image must be IMAGE_EMPTY or IMAGE_STOCK (see get_storage_type()).

void Xfc::Gtk::Image::set

(

Gdk::Pixbuf *

pixbuf

)

Set the pixbuf to be displayed by the Image.

Parameters:

pixbuf

A Gdk::Pixbuf, or null.

void Xfc::Gtk::Image::set

(

const String &

filename

)

Set the file to be displayed by the Image.

Parameters:

filename

The name of the file to display.

void Xfc::Gtk::Image::set	(	Gdk::Image *	image,
		Gdk::Bitmap *	mask
	)

Set the image and mask to be displayed by the Image.

Parameters:

	image	A Gdk::Image, or null.
	mask	A Gdk::Bitmap, or null.

void Xfc::Gtk::Image::set	(	Gdk::Pixmap *	pixmap,
		Gdk::Bitmap *	mask
	)

Set the pixmap and mask to be displayed by the Image.

Parameters:

	pixmap	A Gdk::Pixmap, or null.
	mask	A Gdk::Bitmap, or null.

The Image does not assume a reference to the pixmap or mask; you still need to unref them if you own references. Image will add its own reference rather than adopting yours.

Xfc::Gtk::Image Class Reference

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation