GimpPreviewImage

struct GimpPreviewImageUpdateEvent

struct GimpPreviewImageUpdateEvent
{
  gdouble scale;                /* Scale of preview */

  /* Left/Top of requested unscaled data in image coordinates */
  gint image_x;
  gint image_y;

  /* Width/Height of requested unscaled data in image coordinates */
  gint image_width;
  gint image_height;

  /* Left/Top of preview in preview coordinates */
  gint preview_x;
  gint preview_y;

  /* Width/Height of the preview */
  gint preview_width;
  gint preview_height;
};

This event will be sent with the "update-preview" signal, that is emitted by the preview when the rendering function should render a new image for the preview.

enum GimpPreviewImageRenderStateType

typedef enum
{
  GPI_RENDER_OK,                /* No update needed */
  GPI_RENDER_UPDATE_NEEDED,     /* New image must be rendered */
  GPI_RENDER_RENDERING          /* Busy rendering new image */
}
GimpPreviewImageRenderStateType;

gimp_preview_image_new ()

GtkWidget*  gimp_preview_image_new          (GimpDrawable *drawable);

Create a new GimpPreviewImage widget. This call creates a widget with a default size, initial scale = 1.

gimp_preview_image_new_with_args ()

GtkWidget*  gimp_preview_image_new_with_args
                                            (GimpDrawable *drawable,
                                             gint preview_width,
                                             gint preview_height,
                                             gdouble initial_scale);

Create a new GimpPreviewImage widget.

gimp_preview_image_draw_scaled_drawable ()

gboolean    gimp_preview_image_draw_scaled_drawable
                                            (GimpPreviewImage *preview_image,
                                             GimpDrawable *drawable);

Draw a scaled drawable in the preview.

It is only possible to draw from within an "update-preview" signal handler when the user has not scrolled or zoomed after the invocation of this signal handler. In all other cases drawing on the preview is not allowed and all drawing requests are ignored. Rendering functions should halt immediately when this function returns FALSE, because the results of this rendering function will be ignored by the preview.

gimp_preview_image_draw_unscaled_drawable ()

gboolean    gimp_preview_image_draw_unscaled_drawable
                                            (GimpPreviewImage *preview_image,
                                             GimpDrawable *drawable);

Draw an unscaled drawable in the preview.

It is only possible to draw from within an "update-preview" signal handler when the user has not scrolled or zoomed after the invocation of this signal handler. In all other cases drawing on the preview is not allowed and all drawing requests are ignored. Rendering functions should halt immediately when this function returns FALSE, because the results of this rendering function will be ignored by the preview.

gimp_preview_image_draw_scaled_row ()

gboolean    gimp_preview_image_draw_scaled_row
                                            (GimpPreviewImage *preview_image,
                                             GimpImageType type,
                                             gint row,
                                             gint width,
                                             const guchar *data);

Draw one scaled row of data in the preview. This function handles conversion to RGB and checkerboarding of transparent areas.

It is only possible to draw from within an "update-preview" signal handler when the user has not scrolled or zoomed after the invocation of this signal handler. In all other cases drawing on the preview is not allowed and all drawing requests are ignored. Rendering functions should halt immediately when this function returns FALSE, because the results of this rendering function will be ignored by the preview.

gimp_preview_image_draw_unscaled_row ()

gboolean    gimp_preview_image_draw_unscaled_row
                                            (GimpPreviewImage *preview_image,
                                             GimpImageType type,
                                             gint row,
                                             gint width,
                                             const guchar *data);

Draw one unscaled row of data in the preview. This function handles scaling, conversion to RGB and checkerboarding of transparent areas. A nice feature is that this function will draw several lines of the preview when scale > 1.

It is only possible to draw from within an "update-preview" signal handler when the user has not scrolled or zoomed after the invocation of this signal handler. In all other cases drawing on the preview is not allowed and all drawing requests are ignored. Rendering functions should halt immediately when this function returns FALSE, because the results of this rendering function will be ignored by the preview.

gimp_preview_image_update ()

void        gimp_preview_image_update       (GimpPreviewImage *preview_image);

Plug-ins call this to do an update of the preview area. The preview will generate an "update-preview" signal. The plug-in's signal handler should then draw in on the preview with one of the drawing functions: gimp_preview_image_draw_unscaled_row(), gimp_preview_image_draw_unscaled_drawable(), gimp_preview_image_draw_scaled_row() or gimp_preview_image_draw_scaled_drawable().

gimp_preview_image_set_position ()

void        gimp_preview_image_set_position (GimpPreviewImage *preview_image,
                                             gint x_pos,
                                             gint y_pos);

Set the position of the area that is show in the preview.

gimp_preview_image_get_preview_position ()

void        gimp_preview_image_get_preview_position
                                            (GimpPreviewImage *preview_image,
                                             gint *prev_x_pos,
                                             gint *prev_y_pos,
                                             gint *prev_width,
                                             gint *prev_height);

Return the size and position of the preview in preview-coordinates.

gimp_preview_image_get_image_position ()

void        gimp_preview_image_get_image_position
                                            (GimpPreviewImage *preview_image,
                                             gint *im_x_pos,
                                             gint *im_y_pos,
                                             gint *im_width,
                                             gint *im_height);

Return the size and position of the preview in image-coordinates. The preview shows a scaled version of this area of the original or rendered image.

gimp_preview_image_set_scale ()

void        gimp_preview_image_set_scale    (GimpPreviewImage *preview_image,
                                             gdouble scale);

Set the current scale factor for the preview.

gimp_preview_image_get_scale ()

gdouble     gimp_preview_image_get_scale    (GimpPreviewImage *preview_image);

Get the current scale factor for the preview.

gimp_preview_image_set_show_original ()

void        gimp_preview_image_set_show_original
                                            (GimpPreviewImage *preview_image,
                                             gboolean show_original);

Set whether the preview_image should show a scaled version of the original image during scrolls. When show_original is FALSE only the results of the rendering function will be shown in the display. This will only give acceptable results when the rendering function is very fast.

gimp_preview_image_get_show_original ()

gboolean    gimp_preview_image_get_show_original
                                            (GimpPreviewImage *preview_image);

Query the preview_image whether it shows the original image during scrolls.

gimp_preview_image_is_drawing_allowed ()

gboolean    gimp_preview_image_is_drawing_allowed
                                            (GimpPreviewImage *preview_image);

Return if it is possible to draw on the preview image. It is only possible to draw from within an "update-preview" signal handler when the user has not scrolled or zoomed after the invocation of this signal handler. In all other cases drawing on the preview is not allowed and all drawing requests are ignored. Rendering functions should halt immediately when this function returns FALSE, because the results of this rendering function will be ignored by the preview.

gtk_adjustment_set_correct_value ()

void        gtk_adjustment_set_correct_value
                                            (GtkAdjustment *adjustment,
                                             gdouble value);

This is a replacement for gtk_adjustment_set_value() that uses correct range checks. When a GtkAdjustment is used with a GtkRange the legal range of its value is lower .. (upper - page_size). But gtk_adjustment_set_value() assumes that the legal range is lower .. upper. This function fixes that bug.

This function should be removed if the bug is fixed in Gtk.

gimp_preview_image_get_x_adjustment ()

GtkAdjustment* gimp_preview_image_get_x_adjustment
                                            (GimpPreviewImage *preview_image);

Return the adjustment that manages the x-coordinate of the preview position. The value of this adjustment is expressed in preview-coordinates.

Applications should only change the value of the adjustment, the other properties of the adjustment are managed by the widget. When you try to set the value directly (i.e. not via a GtkScale widget) you should use gtk_adjustment_set_correct_value() (don't use gtk_adjustment_set_value() because it is buggy).

gimp_preview_image_get_y_adjustment ()

GtkAdjustment* gimp_preview_image_get_y_adjustment
                                            (GimpPreviewImage *preview_image);

Return the adjustment that manages the y-coordinate of the preview position. The value of this adjustment is expressed in preview-coordinates.

Applications should only change the value of the adjustment, the other properties of the adjustment are managed by the widget. When you try to set the value directly (i.e. not via a GtkScale widget) you should use gtk_adjustment_set_correct_value() (don't use gtk_adjustment_set_value() because it is buggy).

gimp_preview_image_get_scale_adjustment ()

GtkAdjustment* gimp_preview_image_get_scale_adjustment
                                            (GimpPreviewImage *preview_image);

Return the adjustment that manages the scale of the preview position. The value of this adjustment is the ratio between the size of the scaled image and the size of the original image, e.g. a value of 0.5 means that the preview image is reduced by 50%.

Applications should only change the value of the adjustment, the other properties of the adjustment are managed by the widget. When you try to set the value directly (i.e. not via a GtkScale widget) you should use gtk_adjustment_set_correct_value() (don't use gtk_adjustment_set_value() because it is buggy).

The "update-preview" signal

void        user_function                  (GimpPreviewImage *gimppreviewimage,
                                            gpointer arg1,
                                            gpointer user_data);

This signal will be emitted when the rendering function should render a new image. The preview can be forced to emit this signal by calling gimp_preview_image_update().