gimpprogress: GIMP Library Reference Manual

## gimpprogress gimpprogress — Functions for embedding the progress bar into a plug-in's GUI. |

## Functions

gboolean | gimp_progress_init ()
gboolean | gimp_progress_init_printf ()
gboolean | gimp_progress_update ()
gboolean | gimp_progress_pulse ()
gboolean | gimp_progress_set_text ()
gboolean | gimp_progress_set_text_printf ()
gboolean | gimp_progress_end ()
gint | gimp_progress_get_window_handle ()
void | (*GimpProgressStartCallback) ()
void | (*GimpProgressEndCallback) ()
void | (*GimpProgressTextCallback) ()
void | (*GimpProgressValueCallback) ()
const gchar * | gimp_progress_install_vtable ()
const gchar * | gimp_progress_install ()
gpointer | gimp_progress_uninstall ()
gboolean | gimp_progress_cancel ()

## Types and Values

struct | GimpProgressVtable

## Description

Functions for embedding the progress bar into a plug-in's GUI.

## Functions

### gimp_progress_init ()

    gboolean
    gimp_progress_init (const gchar *message);

Initializes the progress bar for the current plug-in.

Initializes the progress bar for the current plug-in. It is only valid to call this procedure from a plug-in.

#### Parameters

message | Message to use in the progress dialog. |

#### Returns

TRUE on success.

### gimp_progress_init_printf ()

    gboolean
    gimp_progress_init_printf (const gchar *format,
                               ...);

Initializes the progress bar for the current plug-in.

Initializes the progress bar for the current plug-in. It is only valid to call this procedure from a plug-in.

#### Parameters

format | a standard `printf()` format string |
... | arguments for `format` |

#### Returns

`TRUE` on success.

Since: 2.4

### gimp_progress_update ()

    gboolean
    gimp_progress_update (gdouble percentage);

Updates the progress bar for the current plug-in.

#### Parameters

percentage | Percentage of progress completed (in the range from 0.0 to 1.0). |

#### Returns

TRUE on success.

### gimp_progress_pulse ()

    gboolean
    gimp_progress_pulse (void);

Pulses the progress bar for the current plug-in.

Updates the progress bar for the current plug-in. It is only valid to call this procedure from a plug-in. Use this function instead of `gimp_progress_update()` if you cannot tell how much progress has been made. This usually causes the the progress bar to enter \"activity mode\", where a block bounces back and forth.

#### Returns

TRUE on success.

Since: 2.4

### gimp_progress_set_text ()

    gboolean
    gimp_progress_set_text (const gchar *message);

Changes the text in the progress bar for the current plug-in.

This function changes the text in the progress bar for the current plug-in. Unlike `gimp_progress_init()` it does not change the displayed value.

#### Parameters

message | Message to use in the progress dialog. |

#### Returns

TRUE on success.

Since: 2.4

### gimp_progress_set_text_printf ()

    gboolean
    gimp_progress_set_text_printf (const gchar *format,
                                   ...);

Changes the text in the progress bar for the current plug-in.

This function changes the text in the progress bar for the current plug-in. Unlike `gimp_progress_init()` it does not change the displayed value.

#### Parameters

format | a standard `printf()` format string |
... | arguments for `format` |

#### Returns

`TRUE` on success.

Since: 2.4

### gimp_progress_end ()

    gboolean
    gimp_progress_end (void);

Ends the progress bar for the current plug-in.

Ends the progress display for the current plug-in. Most plug-ins don't need to call this, they just exit when the work is done. It is only valid to call this procedure from a plug-in.

#### Returns

TRUE on success.

Since: 2.4

### gimp_progress_get_window_handle ()

    gint
    gimp_progress_get_window_handle (void);

Returns the native window ID of the toplevel window this plug-in's progress is displayed in.

This function returns the native window ID of the toplevel window this plug-in\'s progress is displayed in.

#### Returns

The progress bar's toplevel window.

Since: 2.2

### GimpProgressStartCallback ()

    void
    (*GimpProgressStartCallback) (const gchar *message,
                                  gboolean cancelable,
                                  gpointer user_data);

`GimpProgressStartCallback` is deprecated and should not be used in newly-written code.

### GimpProgressEndCallback ()

    void
    (*GimpProgressEndCallback) (gpointer user_data);

`GimpProgressEndCallback` is deprecated and should not be used in newly-written code.

### GimpProgressTextCallback ()

    void
    (*GimpProgressTextCallback) (const gchar *message,
                                 gpointer user_data);

`GimpProgressTextCallback` is deprecated and should not be used in newly-written code.

### GimpProgressValueCallback ()

    void
    (*GimpProgressValueCallback) (gdouble percentage,
                                  gpointer user_data);

`GimpProgressValueCallback` is deprecated and should not be used in newly-written code.

### gimp_progress_install_vtable ()

    const gchar *
    gimp_progress_install_vtable (const GimpProgressVtable *vtable,
                                  gpointer user_data);

#### Parameters

vtable | a pointer to a `GimpProgressVtable` . |
user_data | a pointer that is passed as user_data to all vtable functions. |

#### Returns

the name of the temporary procedure that's been installed

Since: 2.4

### gimp_progress_install ()

    const gchar *
    gimp_progress_install (GimpProgressStartCallback start_callback,
                           GimpProgressEndCallback end_callback,
                           GimpProgressTextCallback text_callback,
                           GimpProgressValueCallback value_callback,
                           gpointer user_data);

`gimp_progress_install` is deprecated and should not be used in newly-written code.

Note that since GIMP 2.4, `value_callback` can be called with negative values. This is triggered by calls to `gimp_progress_pulse()`. The callback should then implement a progress indicating business, e.g. by calling `gtk_progress_bar_pulse()`.

#### Parameters

start_callback | the function to call when progress starts |
end_callback | the function to call when progress finishes |
text_callback | the function to call to change the text |
value_callback | the function to call to change the value |
user_data | a pointer that is returned when uninstalling the progress |

#### Returns

the name of the temporary procedure that's been installed

Since: 2.2

### gimp_progress_uninstall ()

    gpointer
    gimp_progress_uninstall (const gchar *progress_callback);

Uninstalls a temporary progress procedure that was installed using `gimp_progress_install()`.

#### Parameters

progress_callback | the name of the temporary procedure to uninstall |

#### Returns

the `user_data` that was passed to `gimp_progress_install()`.

Since: 2.2

### gimp_progress_cancel ()

    gboolean
    gimp_progress_cancel (const gchar *progress_callback);

Cancels a running progress.

This function cancels the currently running progress.

#### Parameters

progress_callback | The name of the callback registered for this progress. |

#### Returns

TRUE on success.

Since: 2.2

## Types and Values

### struct GimpProgressVtable

    struct GimpProgressVtable {
      void    (* start)        (const gchar *message,
                                gboolean     cancelable,
                                gpointer     user_data);
      void    (* end)          (gpointer     user_data);
      void    (* set_text)     (const gchar *message,
                                gpointer     user_data);
      void    (* set_value)    (gdouble      percentage,
                                gpointer     user_data);
      void    (* pulse)        (gpointer     user_data);

      guint32 (* get_window)   (gpointer     user_data);

      /* Padding for future expansion. Must be initialized with NULL! */
      void (* _gimp_reserved1) (void);
      void (* _gimp_reserved2) (void);
      void (* _gimp_reserved3) (void);
      void (* _gimp_reserved4) (void);
      void (* _gimp_reserved5) (void);
      void (* _gimp_reserved6) (void);
      void (* _gimp_reserved7) (void);
      void (* _gimp_reserved8) (void);
    };