Bonobo API Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# BonoboUIToolbarIcon

## Name

BonoboUIToolbarIcon -- a bonobo toolbar icon widget

## Synopsis

    enum        BonoboUIToolbarIconDrawMode;
    typedef     BonoboUIToolbarIcon;
    typedef     BonoboUIToolbarIconClass;
    GtkWidget*  bonobo_ui_toolbar_icon_new      (void);
    GtkWidget*  bonobo_ui_toolbar_icon_new_from_file
                                                (const gchar *filename);
    GtkWidget*  bonobo_ui_toolbar_icon_new_from_file_at_size
                                                (const gchar *filename,
                                                 gint width,
                                                 gint height);
    GtkWidget*  bonobo_ui_toolbar_icon_new_from_xpm_d
                                                (const gchar **xpm_data);
    GtkWidget*  bonobo_ui_toolbar_icon_new_from_xpm_d_at_size
                                                (const gchar **xpm_data,
                                                 gint width,
                                                 gint height);
    GtkWidget*  bonobo_ui_toolbar_icon_new_from_pixbuf
                                                (GdkPixbuf *pixbuf);
    GtkWidget*  bonobo_ui_toolbar_icon_new_from_pixbuf_at_size
                                                (GdkPixbuf *pixbuf,
                                                 gint width,
                                                 gint height);
    void        bonobo_ui_toolbar_icon_set_pixbuf_size
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 gint width,
                                                 gint height);
    void        bonobo_ui_toolbar_icon_get_pixbuf_size
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 gint *width,
                                                 gint *height);
    void        bonobo_ui_toolbar_icon_set_pixbuf
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 GdkPixbuf *pixbuf);
    GdkPixbuf*  bonobo_ui_toolbar_icon_get_pixbuf
                                                (BonoboUIToolbarIcon *gpixmap);
    void        bonobo_ui_toolbar_icon_set_pixbuf_at_state
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 GtkStateType state,
                                                 GdkPixbuf *pixbuf,
                                                 GdkBitmap *mask);
    void        bonobo_ui_toolbar_icon_set_state_pixbufs
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 GdkPixbuf *pixbufs[5],
                                                 GdkBitmap *masks[5]);
    void        bonobo_ui_toolbar_icon_set_draw_vals
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 GtkStateType state,
                                                 gfloat saturation,
                                                 gboolean pixelate);
    void        bonobo_ui_toolbar_icon_get_draw_vals
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 GtkStateType state,
                                                 gfloat *saturation,
                                                 gboolean *pixelate);
    void        bonobo_ui_toolbar_icon_set_draw_mode
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 BonoboUIToolbarIconDrawMode mode);
    BonoboUIToolbarIconDrawMode bonobo_ui_toolbar_icon_get_draw_mode
                                                (BonoboUIToolbarIcon *gpixmap);
    void        bonobo_ui_toolbar_icon_clear    (BonoboUIToolbarIcon *gpixmap);
    void        bonobo_ui_toolbar_icon_set_alpha_threshold
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 gint alpha_threshold);
    gint        bonobo_ui_toolbar_icon_get_alpha_threshold
                                                (BonoboUIToolbarIcon *gpixmap);

## Description

## Details

### enum BonoboUIToolbarIconDrawMode

    typedef enum {
            /* update struct when adding enum values */
    	BONOBO_UI_TOOLBAR_ICON_SIMPLE, /* No alpha blending */
    	BONOBO_UI_TOOLBAR_ICON_COLOR   /* */
    } BonoboUIToolbarIconDrawMode;

### BonoboUIToolbarIcon

    typedef struct {
    	GtkMisc misc;

            /* NOTE. In the old BonoboUIToolbarIcon, _lots_ of people were using BonoboUIToolbarIcon to
    	 * load images, sucking out the pixmap field, and then not using the
    	 * BonoboUIToolbarIcon as a widget at all. IF YOU DO THIS I WILL PERSONALLY
    	 * KICK YOUR ASS. Use gdk_pixbuf_new_from_file(). Thank you.
    	 * These are PRIVATE FIELDS which I will gratuitously change just to
    	 * break your broken code.
    	 *                          -  hp + jrb + quartic + Jesse Ventura + GW Bush
    	 */

    	GdkPixbuf *provided_image;

            struct {
                    GdkPixbuf *pixbuf;
                    GdkBitmap *mask;
    		gfloat saturation;
    		gboolean pixelate;
            } provided[5]; /* the five states */

    	GdkPixbuf *generated_scaled_image;
    	GdkBitmap *generated_scaled_mask;

            struct {
                    GdkPixbuf *pixbuf;
                    GdkBitmap *mask;
            } generated[5]; /* the five states */

    	gint width, height;
    	gint alpha_threshold;

    	BonoboUIToolbarIconDrawMode mode : 2;
    } BonoboUIToolbarIcon;

### BonoboUIToolbarIconClass

    typedef struct {
    	GtkMiscClass parent_class;
    } BonoboUIToolbarIconClass;

### bonobo_ui_toolbar_icon_new ()

    GtkWidget*  bonobo_ui_toolbar_icon_new      (void);

Creates a new empty `BonoboUIToolbarIcon`.

Returns : | A newly-created `BonoboUIToolbarIcon`

### bonobo_ui_toolbar_icon_new_from_file ()

    GtkWidget*  bonobo_ui_toolbar_icon_new_from_file
                                                (const gchar *filename);

Note that the new_from_file functions give you no way to detect errors; if the file isn't found/loaded, you get an empty widget. to detect errors just do:

<programlisting> gdk_pixbuf_new_from_file (filename); if (pixbuf != NULL) { gpixmap = bonobo_ui_toolbar_icon_new_from_pixbuf (pixbuf); } else { // handle your error... } </programlisting>

`filename` : | The filename of the file to be loaded.
Returns : | A newly allocated `BonoboUIToolbarIcon` with the file at `filename` loaded.

### bonobo_ui_toolbar_icon_new_from_file_at_size ()

    GtkWidget*  bonobo_ui_toolbar_icon_new_from_file_at_size
                                                (const gchar *filename,
                                                 gint width,
                                                 gint height);

Loads a new `BonoboUIToolbarIcon` from the `pixbuf`, and scales it (if necessary) to the size indicated by `height` and `width`. If either are set to -1, then the "natural" dimension of the image is used in place.

`filename` : |
`width` : | The width to scale the image to.
`height` : | The height to scale the image to.
Returns : | value: A newly allocated `BonoboUIToolbarIcon` with the image from `pixbuf` loaded.

### bonobo_ui_toolbar_icon_new_from_xpm_d ()

    GtkWidget*  bonobo_ui_toolbar_icon_new_from_xpm_d
                                                (const gchar **xpm_data);

`xpm_data` : |
Returns : |

### bonobo_ui_toolbar_icon_new_from_xpm_d_at_size ()

    GtkWidget*  bonobo_ui_toolbar_icon_new_from_xpm_d_at_size
                                                (const gchar **xpm_data,
                                                 gint width,
                                                 gint height);

`xpm_data` : |
`width` : |
`height` : |
Returns : |

### bonobo_ui_toolbar_icon_new_from_pixbuf ()

    GtkWidget*  bonobo_ui_toolbar_icon_new_from_pixbuf
                                                (GdkPixbuf *pixbuf);

`pixbuf` : |
Returns : |

### bonobo_ui_toolbar_icon_new_from_pixbuf_at_size ()

    GtkWidget*  bonobo_ui_toolbar_icon_new_from_pixbuf_at_size
                                                (GdkPixbuf *pixbuf,
                                                 gint width,
                                                 gint height);

`pixbuf` : |
`width` : |
`height` : |
Returns : |

### bonobo_ui_toolbar_icon_set_pixbuf_size ()

    void        bonobo_ui_toolbar_icon_set_pixbuf_size
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 gint width,
                                                 gint height);

Sets the current size of the image displayed. If there were custom "state" pixbufs set, as a side effect, they are discarded and must be re set at the new size.

`gpixmap` : | A `BonoboUIToolbarIcon`.
`width` : | The new width.
`height` : | The new height.

### bonobo_ui_toolbar_icon_get_pixbuf_size ()

    void        bonobo_ui_toolbar_icon_get_pixbuf_size
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 gint *width,
                                                 gint *height);

Sets `width` and `height` to be the widgets current dimensions. They will return the width or height of the image, or -1, -1 if the image's "natural" dimensions are used. Either or both dimension arguments may be NULL, as necessary.

`gpixmap` : | A `BonoboUIToolbarIcon`
`width` : | A pointer to place the width in.
`height` : | A pointer to place the height in.

### bonobo_ui_toolbar_icon_set_pixbuf ()

    void        bonobo_ui_toolbar_icon_set_pixbuf
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 GdkPixbuf *pixbuf);

Sets the image shown to be that of the pixbuf. If there is a current image used by the `gpixmap`, it is discarded along with any pixmaps at a particular state. However, the `gpixmap` will keep the same geometry as the old image, or if the width or height are set to -1, it will inherit the new image's geometry.

`gpixmap` : | A `BonoboUIToolbarIcon`.
`pixbuf` : | The new pixbuf.

### bonobo_ui_toolbar_icon_get_pixbuf ()

    GdkPixbuf*  bonobo_ui_toolbar_icon_get_pixbuf
                                                (BonoboUIToolbarIcon *gpixmap);

Gets the current image used by `gpixmap`, if you have set the pixbuf. If you've only set the value for particular states, then this won't return anything.

`gpixmap` : | A `BonoboUIToolbarIcon`.
Returns : | A pixbuf.

### bonobo_ui_toolbar_icon_set_pixbuf_at_state ()

    void        bonobo_ui_toolbar_icon_set_pixbuf_at_state
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 GtkStateType state,
                                                 GdkPixbuf *pixbuf,
                                                 GdkBitmap *mask);

Sets a custom image for the image at `state`. For example, you can set the prelighted appearance to a different image from the normal one. If necessary, the image will be scaled to the appropriate size. The mask can also be optionally NULL. The image set will be modified by the draw vals as normal.

`gpixmap` : | A `BonoboUIToolbarIcon`.
`state` : | The state being set.
`pixbuf` : | The new image for the state.
`mask` : | The mask for the new image.

### bonobo_ui_toolbar_icon_set_state_pixbufs ()

    void        bonobo_ui_toolbar_icon_set_state_pixbufs
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 GdkPixbuf *pixbufs[5],
                                                 GdkBitmap *masks[5]);

Sets a custom image for all the possible states of the image. Both `pixbufs` and `masks` are indexed by a GtkStateType. Any or all of the images can be NULL, as necessary. The image set will be modified by the draw vals as normal.

`gpixmap` : | A `BonoboUIToolbarIcon`.
`pixbufs` : | The images.
`masks` : | The masks.

### bonobo_ui_toolbar_icon_set_draw_vals ()

    void        bonobo_ui_toolbar_icon_set_draw_vals
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 GtkStateType state,
                                                 gfloat saturation,
                                                 gboolean pixelate);

Sets the modification parameters for a particular state. The saturation level determines the amount of color in the image. The default level of 1.0 leaves the color unchanged while a level of 0.0 means the image is fully saturated, and has no color. `saturation` can be set to values greater then 1.0, or less then 0.0, but this produces less meaningful results. If `pixelate` is set to TRUE, then in adition to any saturation, a light stipple is overlayed over the image.

`gpixmap` : | A `BonoboUIToolbarIcon`.
`state` : | The the state to set the modifications to
`saturation` : | The saturtion offset.
`pixelate` : | Draw the insensitive stipple.

### bonobo_ui_toolbar_icon_get_draw_vals ()

    void        bonobo_ui_toolbar_icon_get_draw_vals
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 GtkStateType state,
                                                 gfloat *saturation,
                                                 gboolean *pixelate);

Retrieve the values set by bonobo_ui_toolbar_icon_set_draw_vals(). Either return location can be NULL if you don't care about it.

`gpixmap` : | A `BonoboUIToolbarIcon`.
`state` : | The the state to set the modifications to
`saturation` : | return location for the saturation offset
`pixelate` : | return value for whether to draw the insensitive stipple

### bonobo_ui_toolbar_icon_set_draw_mode ()

    void        bonobo_ui_toolbar_icon_set_draw_mode
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 BonoboUIToolbarIconDrawMode mode);

This sets the drawing mode of the image to be `mode`. The image must have an alpha channel if `BONOBO_UI_TOOLBAR_ICON_COLOR` is to be used.

`gpixmap` : | A `BonoboUIToolbarIcon`.
`mode` : | The new drawing mode.

### bonobo_ui_toolbar_icon_get_draw_mode ()

    BonoboUIToolbarIconDrawMode bonobo_ui_toolbar_icon_get_draw_mode
                                                (BonoboUIToolbarIcon *gpixmap);

Gets the current draw mode.

`gpixmap` : | A `BonoboUIToolbarIcon`.
Returns : | The current `BonoboUIToolbarIconDrawMode` setting.

### bonobo_ui_toolbar_icon_clear ()

    void        bonobo_ui_toolbar_icon_clear    (BonoboUIToolbarIcon *gpixmap);

Removes any images from `gpixmap`. If still visible, the image will appear empty.

`gpixmap` : | A `BonoboUIToolbarIcon`.

### bonobo_ui_toolbar_icon_set_alpha_threshold ()

    void        bonobo_ui_toolbar_icon_set_alpha_threshold
                                                (BonoboUIToolbarIcon *gpixmap,
                                                 gint alpha_threshold);

Sets the alpha threshold for `gpixmap`. It is used to determine which pixels are shown when the image has an alpha channel, and is only used if no mask is set.

`gpixmap` : | A `BonoboUIToolbarIcon`.
`alpha_threshold` : | The alpha threshold

### bonobo_ui_toolbar_icon_get_alpha_threshold ()

    gint        bonobo_ui_toolbar_icon_get_alpha_threshold
                                                (BonoboUIToolbarIcon *gpixmap);

Gets the current alpha threshold.

`gpixmap` : | A `BonoboUIToolbarIcon`.
Returns : | The alpha threshold

<<< Previous Page | Home | Up | Next Page >>>
BonoboUIToolbarItem | BonoboUIToolbarButtonItem