GIMP Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# gimpexport

## Name

gimpexport -- Export an image before it is saved.

## Synopsis

    enum        GimpExportCapabilities;
    enum        GimpExportReturnType;
    GimpExportReturnType gimp_export_image      (gint32 *image_ID,
                                                 gint32 *drawable_ID,
                                                 gchar *format_name,
                                                 GimpExportCapabilities capabilities);

## Description

This function should be called by all save_plugins unless they are able to save all image formats the GIMP knows about. It takes care of asking the user if she wishes to export the image to a format the save_plugin can handle. It then performs the necessary conversions (e.g. Flatten) on a copy of the image so that the image can be saved without changing the original image. The capabilities of the save_plugin are specified by combining GimpExportCapabilities using a bitwise OR. Make sure you have initialized GTK+ before you call this function as it will most probably have to open a dialog.

## Details

### enum GimpExportCapabilities

    typedef enum {
      CAN_HANDLE_RGB                 = 1 << 0,
      CAN_HANDLE_GRAY                = 1 << 1,
      CAN_HANDLE_INDEXED             = 1 << 2,
      CAN_HANDLE_ALPHA               = 1 << 3,
      CAN_HANDLE_LAYERS              = 1 << 4,
      CAN_HANDLE_LAYERS_AS_ANIMATION = 1 << 5,
      NEEDS_ALPHA                    = 1 << 6
    } GimpExportCapabilities;

`CAN_HANDLE_RGB` | Use if the plug_in can save RGB images.
`CAN_HANDLE_GRAY` | Use if the plug_in can save GRAY images.
`CAN_HANDLE_INDEXED` | Use if the plug_in can save INDEXED images.
`CAN_HANDLE_ALPHA` | Use if the plugin can save an alpha channel with all image_types.
`CAN_HANDLE_LAYERS` | Use if the plugin can save multiple layers.
`CAN_HANDLE_LAYERS_AS_ANIMATION` | Use if the plugin can save multiple layers but treats them as frames in an animation.
`NEEDS_ALPHA` | Use if the plugin needs an alpha channels and can't save flat images.

### enum GimpExportReturnType

    typedef enum
    {
      EXPORT_CANCEL,
      EXPORT_IGNORE,
      EXPORT_EXPORT
    } GimpExportReturnType;

`EXPORT_CANCEL` | The user chose Cancel in the export dialog. The plugin should terminate itself.
`EXPORT_IGNORE` | The user chose Ignore in the export dialog. No conversion is performed and the plugin should try to save as usual.
`EXPORT_EXPORT` | The user chose Export in the export dialog. A copy of the image is created and then converted to fit the needs of the plugin. The plugin has to take care of deleting the copy when it has finished saving it.

### gimp_export_image ()

    GimpExportReturnType gimp_export_image      (gint32 *image_ID,
                                                 gint32 *drawable_ID,
                                                 gchar *format_name,
                                                 GimpExportCapabilities capabilities);

Takes an image and a drawable to be saved together with a description of the capabilities of the image_format. If the type of image doesn't match the capabilities of the format a dialog is opened that informs the user that the image has to be exported and offers to do the necessary conversions.

If the user chooses to export the image, a copy is created. This copy is then converted, the image_ID and drawable_ID are changed to point to the new image and the procedure returns EXPORT_EXPORT. The save_plugin has to take care of deleting the created image using gimp_image_delete() when it has saved it.

If the user chooses to Ignore the export problem, the image_ID and drawable_ID is not altered, EXPORT_IGNORE is returned and the save_plugin should try to save the original image. If the user chooses Cancel, EXPORT_CANCEL is returned and the save_plugin should quit itself with status STATUS_CANCEL.

`image_ID` : | Pointer to the image_ID.
`drawable_ID` : | Pointer to the drawable_ID.
`format_name` : | The (short) name of the image_format (e.g. JPEG or GIF).
`capabilities` : | What can the image_format do?
Returns : | An enum of GimpExportReturnType describing the user_action.

<<< Previous Page | Home | Up | Next Page >>>
gimpdialog | gimphelpui