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);
+};
+