Xfce Foundation Classes
Main Page  | IndexNamespace List  |  Alphabetical List  |  Class List  |  File List


Xfc::Gtk::Image Class Reference

A GtkImage C++ wrapper class. More...

#include <xfc/gtk/image.hh>

Inheritance diagram for Xfc::Gtk::Image:

Xfc::Gtk::Misc Xfc::Gtk::Widget Xfc::Gtk::Object Xfc::Atk::Implementor Xfc::G::Object Xfc::G::TypeInterface Xfc::G::TypeInstance Xfc::G::TypeInstance Xfc::Trackable Xfc::Trackable List of all members.

Public Member Functions

Accessors
Methods

Detailed Description

A GtkImage C++ wrapper class.

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.

Example: Handling button press events on an Image.

 #include <xfc/main.hh>
 #include <xfc/gtk/image.hh>
 #include <xfc/gtk/eventbox.hh>
 #include <xfc/gtk/window.hh>
 #include <xfc/bind.hh>

 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);

See also: the Image Widget HOWTO.


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.

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

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::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_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.

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.

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()).

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()).

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::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.

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.
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.

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.
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.

void Xfc::Gtk::Image::set ( Gdk::Pixbuf pixbuf  ) 

Set the pixbuf to be displayed by the Image.

Parameters:
pixbuf A Gdk::Pixbuf, or null.
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.

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 ( 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.
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.

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 ( 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::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().


The documentation for this class was generated from the following file: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3