Reference Manual

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

# Inti::Gtk::Image Class Reference

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

`#include <inti/gtk/image.h>`

Inheritance diagram for Inti::Gtk::Image:

List of all members.

## Public Member Functions

Constructors

- Image ()
    Construct an empty Image.
- Image (Gdk::Pixmap *pixmap, Gdk::Bitmap *mask)
    Constructs an Image widget displaying a pixmap with a mask.
- Image (Gdk::Image *image, Gdk::Bitmap *mask)
    Construct an Image widget displaying a image with a mask.
- Image (const String &filename)
    Construct a new Image displaying the file filename.
- Image (Gdk::Pixbuf *pixbuf)
    Construct a new Image displaying pixbuf.
- Image (const char **xpm_data)
    Construct a new Image by parsing XPM data in memory.
- Image (const char *stock_id, IconSize size)
    Construct an Image displaying a stock icon.
- Image (IconSet *icon_set, IconSize size)
    Construct an Image displaying an icon set.
- Image (Gdk::PixbufAnimation &animation)
    Constrcut an Image displaying the given animation.
- virtual ~Image ()
    Destructor.

Accessors

- GtkImage * gtk_image () const
    Get a pointer to the GtkImage structure.
- GtkImageClass * gtk_image_class () const
    Get a pointer to the GtkImageClass structure.
- operator GtkImage * () const
    Conversion operator; safely converts an Image to a GtkImage pointer.
- ImageType get_storage_type () const
    Gets the type of representation being used by the Image to store image data.
- void get_pixmap (Gdk::Pixmap **pixmap, Gdk::Bitmap **mask) const
    Gets the pixmap and mask being displayed by the Image.
- void get_image (Gdk::Image **gdk_image, Gdk::Bitmap **mask) const
    Gets the Gdk::Image and mask being displayed by the Image.
- Gdk::Pixbuf * get_pixbuf () const
    Gets the Gdk::Pixbuf being displayed by the Image.
- void get_stock (char **stock_id, IconSize *size) const
    Gets the stock icon name and size being displayed by the Image.
- void get_icon_set (Pointer< IconSet > *icon_set, IconSize *size) const
    Gets the icon set and size being displayed by the Image.
- Gdk::PixbufAnimation * get_animation () const
    Gets the Gdk::PixbufAnimation being displayed by the Image.

Methods

- void set (Gdk::Pixmap *pixmap, Gdk::Bitmap *mask)
    Set the pixmap and mask to be displayed by the Image.
- void set (Gdk::Image *image, Gdk::Bitmap *mask)
    Set the image and mask to be displayed by the Image.
- void set (const String &filename)
    Set the file to be displayed by the Image.
- void set (Gdk::Pixbuf *pixbuf)
    Set the pixbuf to be displayed by the Image.
- void set (const char *stock_id, IconSize size)
    Set the stock icon name and size to be displayed by the Image.
- void set (Gtk::IconSet *icon_set, IconSize size)
    Set the icon set and icon size to be displayed by the image.
- void set (Gdk::PixbufAnimation &animation)
    Set the animation to be displayed by the image.

Property Proxies

- const PixbufPropertyProxy prop_pixbuf ()
    A Gdk::Pixbuf to display (Gdk::Pixbuf* : Read / Write).
- const PixmapPropertyProxy prop_pixmap ()
    A Gdk::Pixmap to display (Gdk::Pixmap* : Read / Write).
- const ImagePropertyProxy prop_image ()
    A Gdk::Image to display (Gdk::Image* : Read / Write).
- const MaskPropertyProxy prop_mask ()
    Mask bitmap to use with Gdk::Image or Gdk::Pixmap (Gdk::Bitmap* : Read / Write).
- const FilePropertyProxy prop_file ()
    Filename to load and display (String : Write).
- const StockPropertyProxy prop_stock ()
    Stock ID for a stock image to display (String : Read / Write).
- const IconSetPropertyProxy prop_icon_set ()
    Icon set to display (IconSet* : Read / Write).
- const IconSizePropertyProxy prop_icon_size ()
    Size to use for stock icon or icon set (int : Read / Write).
- const PixbufAnimationPropertyProxy prop_pixbuf_animation ()
    Gdk::PixbufAnimation to display (Gdk::PixbufAnimation* : Read / Write).
- const StorageTypePropertyProxy prop_storage_type ()
    The representation being used for image data (ImageType : Read).

## Protected Member Functions

Constructors

- Image (GtkImage *image, bool reference=false)
    Construct a new Image from an existing GtkImage.

## 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 = new Gdk::Pixbuf("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 <inti/main.h>
        #include <inti/gtk/image.h>
        #include <inti/gtk/eventbox.h>
        #include <inti/gtk/window.h>
        #include <inti/bind.h>

        using namespace Inti;

        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->sig_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.sig_destroy().connect(slot(&Inti::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

Inti::Gtk::Image::Image | ( | GtkImage * | image,
|  | bool | reference = false
| ) | `[explicit, protected]`

Construct a new Image from an existing GtkImage.

Parameters:

  image | A pointer to a GtkImage.
  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).

Inti::Gtk::Image::Image | ( | Gdk::Pixmap * | pixmap,
|  | Gdk::Bitmap * | mask
| ) |

Constructs an Image widget displaying a pixmap with a mask.

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.

Inti::Gtk::Image::Image | ( | Gdk::Image * | image,
|  | Gdk::Bitmap * | mask
| ) |

Construct an Image widget displaying a image with a mask.

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.

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

Inti::Gtk::Image::Image | ( | Gdk::Pixbuf * | pixbuf | ) | `[explicit]`

Construct a new Image displaying pixbuf.

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.

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

Inti::Gtk::Image::Image | ( | const char * | stock_id,
|  | IconSize | size
| ) |

Construct an Image displaying a stock icon.

Parameters:

  stock_id | A stock icon name.
  size | A stock icon size.

Sample stock icon names are STOCK_OPEN, STOCK_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().

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

Inti::Gtk::Image::Image | ( | Gdk::PixbufAnimation & | animation | ) | `[explicit]`

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

## Member Function Documentation

Gdk::PixbufAnimation* Inti::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 Inti::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 Inti::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* Inti::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 Inti::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 Inti::Gtk::Image::get_stock | ( | char ** | 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 name.
  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()). The returned string is owned by the Image and should not be freed.

ImageType Inti::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 Inti::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 Inti::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 Inti::Gtk::Image::set | ( | const char * | stock_id,
|  | IconSize | size
| ) |

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

Parameters:

  stock_id | The place to store the stock icon name.
  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()).

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

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

- gtk/image.h

Main Page - Footer