GimpViewable

GimpViewable

Synopsis

#define             GIMP_VIEWABLE_MAX_BUTTON_SIZE
#define             GIMP_VIEWABLE_MAX_MENU_SIZE
#define             GIMP_VIEWABLE_MAX_PREVIEW_SIZE
#define             GIMP_VIEWABLE_MAX_POPUP_SIZE
#define             GIMP_VIEWABLE_PRIORITY_IDLE
                    GimpViewable;
void                gimp_viewable_invalidate_preview    (GimpViewable *viewable);
void                gimp_viewable_size_changed          (GimpViewable *viewable);
void                gimp_viewable_calc_preview_size     (gint aspect_width,
                                                         gint aspect_height,
                                                         gint width,
                                                         gint height,
                                                         gboolean dot_for_dot,
                                                         gdouble xresolution,
                                                         gdouble yresolution,
                                                         gint *return_width,
                                                         gint *return_height,
                                                         gboolean *scaling_up);
gboolean            gimp_viewable_get_size              (GimpViewable *viewable,
                                                         gint *width,
                                                         gint *height);
void                gimp_viewable_get_preview_size      (GimpViewable *viewable,
                                                         gint size,
                                                         gboolean popup,
                                                         gboolean dot_for_dot,
                                                         gint *width,
                                                         gint *height);
gboolean            gimp_viewable_get_popup_size        (GimpViewable *viewable,
                                                         gint width,
                                                         gint height,
                                                         gboolean dot_for_dot,
                                                         gint *popup_width,
                                                         gint *popup_height);
TempBuf *           gimp_viewable_get_preview           (GimpViewable *viewable,
                                                         GimpContext *context,
                                                         gint width,
                                                         gint height);
TempBuf *           gimp_viewable_get_new_preview       (GimpViewable *viewable,
                                                         GimpContext *context,
                                                         gint width,
                                                         gint height);
TempBuf *           gimp_viewable_get_dummy_preview     (GimpViewable *viewable,
                                                         gint width,
                                                         gint height,
                                                         gint bpp);
GdkPixbuf *         gimp_viewable_get_pixbuf            (GimpViewable *viewable,
                                                         GimpContext *context,
                                                         gint width,
                                                         gint height);
GdkPixbuf *         gimp_viewable_get_new_pixbuf        (GimpViewable *viewable,
                                                         GimpContext *context,
                                                         gint width,
                                                         gint height);
GdkPixbuf *         gimp_viewable_get_dummy_pixbuf      (GimpViewable *viewable,
                                                         gint width,
                                                         gint height,
                                                         gint bpp);
gchar *             gimp_viewable_get_description       (GimpViewable *viewable,
                                                         gchar **tooltip);
const gchar *       gimp_viewable_get_stock_id          (GimpViewable *viewable);
void                gimp_viewable_set_stock_id          (GimpViewable *viewable,
                                                         const gchar *stock_id);
void                gimp_viewable_preview_freeze        (GimpViewable *viewable);
void                gimp_viewable_preview_thaw          (GimpViewable *viewable);
gboolean            gimp_viewable_preview_is_frozen     (GimpViewable *viewable);
GimpViewable *      gimp_viewable_get_parent            (GimpViewable *viewable);
void                gimp_viewable_set_parent            (GimpViewable *viewable,
                                                         GimpViewable *parent);
GimpContainer *     gimp_viewable_get_children          (GimpViewable *viewable);
gboolean            gimp_viewable_get_expanded          (GimpViewable *viewable);
void                gimp_viewable_set_expanded          (GimpViewable *viewable,
                                                         gboolean expanded);
gboolean            gimp_viewable_is_ancestor           (GimpViewable *ancestor,
                                                         GimpViewable *descendant);

Object Hierarchy

  GObject
   +----GimpObject
         +----GimpViewable
               +----GimpContext
               +----GimpImageMapConfig
               +----GimpData
               +----GimpBuffer
               +----GimpItem
               +----GimpUndo
               +----GimpControllerInfo
               +----GimpFont
               +----GimpImage
               +----GimpImagefile
               +----GimpPaintInfo
               +----GimpTemplate
               +----GimpToolInfo

Implemented Interfaces

GimpViewable implements GimpConfigInterface.

Properties

  "frozen"                   gboolean              : Read
  "stock-id"                 gchar*                : Read / Write / Construct

Signals

  "invalidate-preview"                             : Run First
  "size-changed"                                   : Run First

Description

Details

GIMP_VIEWABLE_MAX_BUTTON_SIZE

#define GIMP_VIEWABLE_MAX_BUTTON_SIZE    64


GIMP_VIEWABLE_MAX_MENU_SIZE

#define GIMP_VIEWABLE_MAX_MENU_SIZE      48


GIMP_VIEWABLE_MAX_PREVIEW_SIZE

#define GIMP_VIEWABLE_MAX_PREVIEW_SIZE 2048


GIMP_VIEWABLE_MAX_POPUP_SIZE

#define GIMP_VIEWABLE_MAX_POPUP_SIZE    256


GIMP_VIEWABLE_PRIORITY_IDLE

#define GIMP_VIEWABLE_PRIORITY_IDLE    G_PRIORITY_LOW


GimpViewable

typedef struct _GimpViewable GimpViewable;


gimp_viewable_invalidate_preview ()

void                gimp_viewable_invalidate_preview    (GimpViewable *viewable);

Causes any cached preview to be marked as invalid, so that a new preview will be generated at the next attempt to display one.

viewable :

a viewable object

gimp_viewable_size_changed ()

void                gimp_viewable_size_changed          (GimpViewable *viewable);

This function sends a signal that is handled at a lower level in the object hierarchy, and provides a mechanism by which objects derived from GimpViewable can respond to size changes.

viewable :

a viewable object

gimp_viewable_calc_preview_size ()

void                gimp_viewable_calc_preview_size     (gint aspect_width,
                                                         gint aspect_height,
                                                         gint width,
                                                         gint height,
                                                         gboolean dot_for_dot,
                                                         gdouble xresolution,
                                                         gdouble yresolution,
                                                         gint *return_width,
                                                         gint *return_height,
                                                         gboolean *scaling_up);

A utility function, for calculating the dimensions of a preview based on the information specified in the arguments. The arguments aspect_width and aspect_height are the dimensions of the unscaled preview. The arguments width and height represent the maximum width and height that the scaled preview must fit into. The preview is scaled to be as large as possible without exceeding these constraints.

If dot_for_dot is TRUE, and xresolution and yresolution are different, then these results are corrected for the difference in resolution on the two axes, so that the requested aspect ratio applies to the appearance of the display rather than to pixel counts.

aspect_width :

unscaled width of the preview for an item.

aspect_height :

unscaled height of the preview for an item.

width :

maximum available width for scaled preview.

height :

maximum available height for scaled preview.

dot_for_dot :

if TRUE, ignore any differences in axis resolution.

xresolution :

resolution in the horizontal direction.

yresolution :

resolution in the vertical direction.

return_width :

place to return the calculated preview width.

return_height :

place to return the calculated preview height.

scaling_up :

returns TRUE here if the calculated preview size is larger than the viewable itself.

gimp_viewable_get_size ()

gboolean            gimp_viewable_get_size              (GimpViewable *viewable,
                                                         gint *width,
                                                         gint *height);


gimp_viewable_get_preview_size ()

void                gimp_viewable_get_preview_size      (GimpViewable *viewable,
                                                         gint size,
                                                         gboolean popup,
                                                         gboolean dot_for_dot,
                                                         gint *width,
                                                         gint *height);

Retrieve the size of a viewable's preview. By default, this simply returns the value of the size argument for both the width and height, but this can be overridden in objects derived from GimpViewable. If either the width or height exceeds GIMP_VIEWABLE_MAX_PREVIEW_SIZE, they are silently truncated.

viewable :

the object for which to calculate the preview size.

size :

requested size for preview.

popup :

TRUE if the preview is intended for a popup window.

dot_for_dot :

If TRUE, ignore any differences in X and Y resolution.

width :

return location for the the calculated width.

height :

return location for the calculated height.

gimp_viewable_get_popup_size ()

gboolean            gimp_viewable_get_popup_size        (GimpViewable *viewable,
                                                         gint width,
                                                         gint height,
                                                         gboolean dot_for_dot,
                                                         gint *popup_width,
                                                         gint *popup_height);

Calculate the size of a viewable's preview, for use in making a popup. The arguments width and height specify the size of the preview from which the popup will be shown.

viewable :

the object for which to calculate the popup size.

width :

the width of the preview from which the popup will be shown.

height :

the height of the preview from which the popup will be shown.

dot_for_dot :

If TRUE, ignore any differences in X and Y resolution.

popup_width :

return location for the calculated popup width.

popup_height :

return location for the calculated popup height.

Returns :

Whether the viewable wants a popup to be shown. Usually TRUE if the passed preview size is smaller than the viewable size, and FALSE if the viewable completely fits into the original preview.

gimp_viewable_get_preview ()

TempBuf *           gimp_viewable_get_preview           (GimpViewable *viewable,
                                                         GimpContext *context,
                                                         gint width,
                                                         gint height);

Gets a preview for a viewable object, by running through a variety of methods until it finds one that works. First, if an implementation exists of a "get_preview" method, it is tried, and the result is returned if it is not NULL. Second, the function checks to see whether there is a cached preview with the correct dimensions; if so, it is returned. If neither of these works, then the function looks for an implementation of the "get_new_preview" method, and executes it, caching the result. If everything fails, NULL is returned.

viewable :

The viewable object to get a preview for.

context :

The context to render the preview for.

width :

desired width for the preview

height :

desired height for the preview

Returns :

A TempBuf containg the preview image, or NULL if none can be found or created.

gimp_viewable_get_new_preview ()

TempBuf *           gimp_viewable_get_new_preview       (GimpViewable *viewable,
                                                         GimpContext *context,
                                                         gint width,
                                                         gint height);

Gets a new preview for a viewable object. Similar to gimp_viewable_get_preview(), except that it tries things in a different order, first looking for a "get_new_preview" method, and then if that fails for a "get_preview" method. This function does not look for a cached preview.

viewable :

The viewable object to get a preview for.

width :

desired width for the preview

height :

desired height for the preview

Returns :

A TempBuf containg the preview image, or NULL if none can be found or created.

gimp_viewable_get_dummy_preview ()

TempBuf *           gimp_viewable_get_dummy_preview     (GimpViewable *viewable,
                                                         gint width,
                                                         gint height,
                                                         gint bpp);

Creates a dummy preview the fits into the specified dimensions, containing a default "question" symbol. This function is used to generate a preview in situations where layer previews have been disabled in the current Gimp configuration.

viewable :

viewable object for which to get a dummy preview.

width :

width of the preview.

height :

height of the preview.

bpp :

bytes per pixel for the preview, must be 3 or 4.

Returns :

a TempBuf containing the preview image.

gimp_viewable_get_pixbuf ()

GdkPixbuf *         gimp_viewable_get_pixbuf            (GimpViewable *viewable,
                                                         GimpContext *context,
                                                         gint width,
                                                         gint height);

Gets a preview for a viewable object, by running through a variety of methods until it finds one that works. First, if an implementation exists of a "get_pixbuf" method, it is tried, and the result is returned if it is not NULL. Second, the function checks to see whether there is a cached preview with the correct dimensions; if so, it is returned. If neither of these works, then the function looks for an implementation of the "get_new_pixbuf" method, and executes it, caching the result. If everything fails, NULL is returned.

viewable :

The viewable object to get a pixbuf preview for.

context :

The context to render the preview for.

width :

desired width for the preview

height :

desired height for the preview

Returns :

A GdkPixbuf containing the preview pixbuf, or NULL if none can be found or created.

gimp_viewable_get_new_pixbuf ()

GdkPixbuf *         gimp_viewable_get_new_pixbuf        (GimpViewable *viewable,
                                                         GimpContext *context,
                                                         gint width,
                                                         gint height);

Gets a new preview for a viewable object. Similar to gimp_viewable_get_pixbuf(), except that it tries things in a different order, first looking for a "get_new_pixbuf" method, and then if that fails for a "get_pixbuf" method. This function does not look for a cached pixbuf.

viewable :

The viewable object to get a new pixbuf preview for.

context :

The context to render the preview for.

width :

desired width for the pixbuf

height :

desired height for the pixbuf

Returns :

A GdkPixbuf containing the preview, or NULL if none can be created.

gimp_viewable_get_dummy_pixbuf ()

GdkPixbuf *         gimp_viewable_get_dummy_pixbuf      (GimpViewable *viewable,
                                                         gint width,
                                                         gint height,
                                                         gint bpp);

Creates a pixbuf containing a default "question" symbol, sized to fit into the specified dimensions. The depth of the pixbuf must be 3 or 4 because GdkPixbuf does not support grayscale. This function is used to generate a preview in situations where previewing has been disabled in the current Gimp configuration. [Note: this function is currently unused except internally to GimpViewable -- consider making it static?]

viewable :

the viewable object for which to create a dummy representation.

width :

maximum permitted width for the pixbuf.

height :

maximum permitted height for the pixbuf.

bpp :

bytes per pixel for the pixbuf, must equal 3 or 4.

Returns :

the created GdkPixbuf.

gimp_viewable_get_description ()

gchar *             gimp_viewable_get_description       (GimpViewable *viewable,
                                                         gchar **tooltip);

Retrieves a string containing a description of the viewable object, By default, it simply returns the name of the object, but this can be overridden by object types that inherit from GimpViewable.

viewable :

viewable object for which to retrieve a description.

tooltip :

return loaction for an optional tooltip string.

Returns :

a copy of the description string. This should be freed when it is no longer needed.

gimp_viewable_get_stock_id ()

const gchar *       gimp_viewable_get_stock_id          (GimpViewable *viewable);

Gets the current value of the object's stock ID, for use in constructing an iconic representation of the object.

viewable :

viewable object for which to retrieve a stock ID.

Returns :

a pointer to the string containing the stock ID. The contents must not be altered or freed.

gimp_viewable_set_stock_id ()

void                gimp_viewable_set_stock_id          (GimpViewable *viewable,
                                                         const gchar *stock_id);

Seta the object's stock ID, for use in constructing iconic smbols of the object. The contents of stock_id are copied, so you can free it when you are done with it.

viewable :

viewable object to assign the specified stock ID.

stock_id :

string containing a stock identifier.

gimp_viewable_preview_freeze ()

void                gimp_viewable_preview_freeze        (GimpViewable *viewable);


gimp_viewable_preview_thaw ()

void                gimp_viewable_preview_thaw          (GimpViewable *viewable);


gimp_viewable_preview_is_frozen ()

gboolean            gimp_viewable_preview_is_frozen     (GimpViewable *viewable);


gimp_viewable_get_parent ()

GimpViewable *      gimp_viewable_get_parent            (GimpViewable *viewable);


gimp_viewable_set_parent ()

void                gimp_viewable_set_parent            (GimpViewable *viewable,
                                                         GimpViewable *parent);


gimp_viewable_get_children ()

GimpContainer *     gimp_viewable_get_children          (GimpViewable *viewable);


gimp_viewable_get_expanded ()

gboolean            gimp_viewable_get_expanded          (GimpViewable *viewable);


gimp_viewable_set_expanded ()

void                gimp_viewable_set_expanded          (GimpViewable *viewable,
                                                         gboolean expanded);


gimp_viewable_is_ancestor ()

gboolean            gimp_viewable_is_ancestor           (GimpViewable *ancestor,
                                                         GimpViewable *descendant);

Property Details

The "frozen" property

  "frozen"                   gboolean              : Read

Default value: FALSE


The "stock-id" property

  "stock-id"                 gchar*                : Read / Write / Construct

Default value: NULL

Signal Details

The "invalidate-preview" signal

void                user_function                      (GimpViewable *gimpviewable,
                                                        gpointer      user_data)         : Run First

gimpviewable :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "size-changed" signal

void                user_function                      (GimpViewable *gimpviewable,
                                                        gpointer      user_data)         : Run First

gimpviewable :

the object which received the signal.

user_data :

user data set when the signal handler was connected.