gimpprogress

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

## Synopsis

                GimpProgressVtable;
    gboolean    gimp_progress_init              (const gchar *message);
    gboolean    gimp_progress_init_printf       (const gchar *format,
                                                 ...);
    gboolean    gimp_progress_update            (gdouble percentage);
    gboolean    gimp_progress_pulse             (void);
    gboolean    gimp_progress_set_text          (const gchar *message);
    gboolean    gimp_progress_set_text_printf   (const gchar *format,
                                                 ...);
    gpointer    gimp_progress_uninstall         (const gchar *progress_callback);
    gboolean    gimp_progress_cancel            (const gchar *progress_callback);
    gint        gimp_progress_get_window_handle (void);
    void        (*GimpProgressStartCallback)    (const gchar *message,
                                                 gboolean cancelable,
                                                 gpointer user_data);
    void        (*GimpProgressEndCallback)      (gpointer user_data);
    void        (*GimpProgressTextCallback)     (const gchar *message,
                                                 gpointer user_data);
    void        (*GimpProgressValueCallback)    (gdouble percentage,
                                                 gpointer user_data);
    const gchar* gimp_progress_install_vtable   (const GimpProgressVtable *vtable,
                                                 gpointer user_data);
    const gchar* gimp_progress_install          (GimpProgressStartCallback start_callback,
                                                 GimpProgressEndCallback end_callback,
                                                 GimpProgressTextCallback text_callback,
                                                 GimpProgressValueCallback value_callback,
                                                 gpointer user_data);

## Description

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

## Details

### GimpProgressVtable

    typedef struct {
      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);
    } GimpProgressVtable;

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

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

`format` : | a standard `printf()` format string
`...` : | arguments for `format`
Returns : | `TRUE` on success.

Since GIMP 2.4

### gimp_progress_update ()

    gboolean    gimp_progress_update            (gdouble percentage);

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

`percentage` : | Percentage of progress completed which must be between 0.0 and 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 GIMP 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 allows to change the text in the progress bar for the current plug-in. Unlike `gimp_progress_init()` it does not change the displayed value.

`message` : | Message to use in the progress dialog.
Returns : | TRUE on success.

Since GIMP 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 allows to change the text in the progress bar for the current plug-in. Unlike `gimp_progress_init()` it does not change the displayed value.

`format` : | a standard `printf()` format string
`...` : | arguments for `format`
Returns : | `TRUE` on success.

Since GIMP 2.4

### gimp_progress_uninstall ()

    gpointer    gimp_progress_uninstall         (const gchar *progress_callback);

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

`progress_callback` : | the name of the temporary procedure to uninstall
Returns : | the `user_data` that was passed to `gimp_progress_install()`.

Since GIMP 2.2

### gimp_progress_cancel ()

    gboolean    gimp_progress_cancel            (const gchar *progress_callback);

Cancels a running progress.

This function cancels the currently running progress.

`progress_callback` : | The name of the callback registered for this progress.
Returns : | TRUE on success.

Since GIMP 2.2

### 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 GIMP 2.2

### GimpProgressStartCallback ()

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

### Warning

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

`message` : |
`cancelable` : |
`user_data` : |

### GimpProgressEndCallback ()

    void        (*GimpProgressEndCallback)      (gpointer user_data);

### Warning

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

`user_data` : |

### GimpProgressTextCallback ()

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

### Warning

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

`message` : |
`user_data` : |

### GimpProgressValueCallback ()

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

### Warning

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

`percentage` : |
`user_data` : |

### gimp_progress_install_vtable ()

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

`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 GIMP 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);

### Warning

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

`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 GIMP 2.2 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().