MxImage

## MxImage MxImage — A widget to display an image |

## Synopsis

    enum                MxImageError;
    #define             MX_IMAGE_ERROR
    GQuark              mx_image_error_quark                (void);
    struct              MxImage;
    struct              MxImageClass;
    ClutterActor *      mx_image_new                        (void);
    gboolean            mx_image_set_from_data              (MxImage *image,
                                                             const guchar *data,
                                                             CoglPixelFormat pixel_format,
                                                             gint width,
                                                             gint height,
                                                             gint rowstride,
                                                             GError **error);
    gboolean            mx_image_set_from_file              (MxImage *image,
                                                             const gchar *filename,
                                                             GError **error);
    gboolean            mx_image_set_from_file_at_size      (MxImage *image,
                                                             const gchar *filename,
                                                             gint width,
                                                             gint height,
                                                             GError **error);
    gboolean            mx_image_set_from_buffer            (MxImage *image,
                                                             guchar *buffer,
                                                             gsize buffer_size,
                                                             GDestroyNotify buffer_free_func,
                                                             GError **error);
    gboolean            mx_image_set_from_buffer_at_size    (MxImage *image,
                                                             guchar *buffer,
                                                             gsize buffer_size,
                                                             GDestroyNotify buffer_free_func,
                                                             gint width,
                                                             gint height,
                                                             GError **error);
    void                mx_image_clear                      (MxImage *image);
    void                mx_image_set_scale_mode             (MxImage *image,
                                                             MxImageScaleMode mode);
    MxImageScaleMode    mx_image_get_scale_mode             (MxImage *image);
    void                mx_image_animate_scale_mode         (MxImage *image,
                                                             gulong mode,
                                                             guint duration,
                                                             MxImageScaleMode scale_mode);
    void                mx_image_set_image_rotation         (MxImage *image,
                                                             gfloat rotation);
    gfloat              mx_image_get_image_rotation         (MxImage *image);
    void                mx_image_set_load_async             (MxImage *image,
                                                             gboolean load_async);
    gboolean            mx_image_get_load_async             (MxImage *image);
    void                mx_image_set_allow_upscale          (MxImage *image,
                                                             gboolean allow);
    gboolean            mx_image_get_allow_upscale          (MxImage *image);
    void                mx_image_set_scale_width_threshold  (MxImage *image,
                                                             guint pixels);
    guint               mx_image_get_scale_width_threshold  (MxImage *image);
    void                mx_image_set_scale_height_threshold (MxImage *image,
                                                             guint pixels);
    guint               mx_image_get_scale_height_threshold (MxImage *image);
    void                mx_image_set_transition_duration    (MxImage *image,
                                                             guint duration);
    guint               mx_image_get_transition_duration    (MxImage *image);
    gboolean            mx_image_set_from_cogl_texture      (MxImage *image,
                                                             CoglHandle texture);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----MxWidget
                         +----MxImage

## Implemented Interfaces

MxImage implements ClutterContainer, ClutterScriptable, ClutterAnimatable, AtkImplementorIface and MxStylable.

## Properties

      "allow-upscale"            gboolean              : Read / Write
      "image-rotation"           gfloat                : Read / Write
      "load-async"               gboolean              : Read / Write
      "scale-height-threshold"   guint                 : Read / Write
      "scale-mode"               MxImageScaleMode      : Read / Write
      "scale-width-threshold"    guint                 : Read / Write
      "transition-duration"      guint                 : Read / Write

## Signals

      "image-load-error"                               : Run Last
      "image-loaded"                                   : Run Last

## Description

The MxImage widget can load and display images. The image may be centered or scaled to fit within the allocation. A transition effect occurs when a new image is loaded.

## Details

### enum MxImageError

    typedef enum {
      MX_IMAGE_ERROR_BAD_FORMAT,
      MX_IMAGE_ERROR_NO_ASYNC,
      MX_IMAGE_ERROR_INTERNAL,
      MX_IMAGE_ERROR_INVALID_PARAMETER
    } MxImageError;

### MX_IMAGE_ERROR

    #define MX_IMAGE_ERROR (mx_image_error_quark ())

### mx_image_error_quark ()

    GQuark              mx_image_error_quark                (void);

### struct MxImage

    struct MxImage;

The contents of this structure are private and should only be accessed through the public API.

### struct MxImageClass

    struct MxImageClass {
    };

### mx_image_new ()

    ClutterActor *      mx_image_new                        (void);

Creates a new MxImage object.

Returns : | A newly created MxImage object

Since 1.2

### mx_image_set_from_data ()

    gboolean            mx_image_set_from_data              (MxImage *image,
                                                             const guchar *data,
                                                             CoglPixelFormat pixel_format,
                                                             gint width,
                                                             gint height,
                                                             gint rowstride,
                                                             GError **error);

Set the image data from a buffer. In case of failure, FALSE is returned and `error` is set.

`image` : | An MxImage
`data` : | Image data
`pixel_format` : | The CoglPixelFormat of the buffer
`width` : | Width in pixels of image data.
`height` : | Height in pixels of image data
`rowstride` : | Distance in bytes between row starts.
`error` : | Return location for a GError, or NULL
Returns : | TRUE if the image was successfully updated

Since 1.2

### mx_image_set_from_file ()

    gboolean            mx_image_set_from_file              (MxImage *image,
                                                             const gchar *filename,
                                                             GError **error);

Set the image data from an image file. In case of failure, FALSE is returned and `error` is set.

`image` : | An MxImage
`filename` : | Filename to read the file from
`error` : | Return location for a GError, or NULL
Returns : | TRUE if the image was successfully updated

Since 1.2

### mx_image_set_from_file_at_size ()

    gboolean            mx_image_set_from_file_at_size      (MxImage *image,
                                                             const gchar *filename,
                                                             gint width,
                                                             gint height,
                                                             GError **error);

Set the image data from an image file, and scale the image during loading. In case of failure, FALSE is returned and `error` is set. The aspect ratio will always be maintained.

`image` : | An MxImage
`filename` : | Filename to read the file from
`width` : | Width to scale the image to, or -1
`height` : | Height to scale the image to, or -1
`error` : | Return location for a GError, or NULL
Returns : | TRUE if the image was successfully updated

Since 1.2

### mx_image_set_from_buffer ()

    gboolean            mx_image_set_from_buffer            (MxImage *image,
                                                             guchar *buffer,
                                                             gsize buffer_size,
                                                             GDestroyNotify buffer_free_func,
                                                             GError **error);

Set the image data from unencoded image data, stored in memory. In case of failure, FALSE is returned and `error` is set. It is expected that `buffer` will remain accessible for the duration of the load. Once it is finished with, `buffer_free_func` will be called.

`image` : | An MxImage
`buffer` : | A buffer pointing to encoded image data
`buffer_size` : | The size of `buffer`, in bytes
`buffer_free_func` : | A function to free `buffer`, or `NULL`
`error` : | Return location for a GError, or NULL
Returns : | TRUE if the image was successfully updated

Since 1.2

### mx_image_set_from_buffer_at_size ()

    gboolean            mx_image_set_from_buffer_at_size    (MxImage *image,
                                                             guchar *buffer,
                                                             gsize buffer_size,
                                                             GDestroyNotify buffer_free_func,
                                                             gint width,
                                                             gint height,
                                                             GError **error);

Set the image data from unencoded image data, stored in memory, and scales it while loading. In case of failure, FALSE is returned and `error` is set. It is expected that `buffer` will remain accessible for the duration of the load. Once it is finished with, `buffer_free_func` will be called. The aspect ratio will always be maintained.

`image` : | An MxImage
`buffer` : | A buffer pointing to encoded image data
`buffer_size` : | The size of `buffer`, in bytes
`buffer_free_func` : | A function to free `buffer`, or `NULL`
`width` : | Width to scale the image to, or -1
`height` : | Height to scale the image to, or -1
`error` : | Return location for a GError, or NULL
Returns : | TRUE if the image was successfully updated

Since 1.2

### mx_image_clear ()

    void                mx_image_clear                      (MxImage *image);

Clear the current image and set a blank, transparent image.

`image` : | A MxImage
Returns : | static void

Since 1.2

### mx_image_set_scale_mode ()

    void                mx_image_set_scale_mode             (MxImage *image,
                                                             MxImageScaleMode mode);

Set the scale mode on `MxImage`

`image` : | An MxImage
`mode` : | The MxImageScaleMode to set

Since 1.2

### mx_image_get_scale_mode ()

    MxImageScaleMode    mx_image_get_scale_mode             (MxImage *image);

Get the current scale mode of `MxImage`.

`image` : | An MxImage
Returns : | The current MxImageScaleMode

Since 1.2

### mx_image_animate_scale_mode ()

    void                mx_image_animate_scale_mode         (MxImage *image,
                                                             gulong mode,
                                                             guint duration,
                                                             MxImageScaleMode scale_mode);

Sets the value of "scale-mode" to `scale_mode` and animates the scale factor of the image between the previous value and the new value.

`image` : | An MxImage
`mode` : | a ClutterAnimationMode
`duration` : | duration of the animation in milliseconds
`scale_mode` : | The MxImageScaleMode to set

Since 1.2

### mx_image_set_image_rotation ()

    void                mx_image_set_image_rotation         (MxImage *image,
                                                             gfloat rotation);

Set the MxImage:image-rotation property.

`image` : | A MxImage
`rotation` : | Rotation angle in degrees

Since 1.2

### mx_image_get_image_rotation ()

    gfloat              mx_image_get_image_rotation         (MxImage *image);

Get the value of the MxImage:image-rotation property.

`image` : | A MxImage
Returns : | The value of the image-rotation property.

Since 1.2

### mx_image_set_load_async ()

    void                mx_image_set_load_async             (MxImage *image,
                                                             gboolean load_async);

Sets whether to load images asynchronously. Asynchronous image loading requires thread support (see `g_thread_init()`).

When using asynchronous image loading, all image-loading functions will return immediately as successful. The "image-loaded" and "image-load-error" signals are used to signal success or failure of asynchronous image loading.

`image` : | A MxImage
`load_async` : | `TRUE` to load images asynchronously

Since 1.2

### mx_image_get_load_async ()

    gboolean            mx_image_get_load_async             (MxImage *image);

Determines whether asynchronous image loading is in use.

`image` : | A MxImage
Returns : | `TRUE` if images are set to load asynchronously, `FALSE` otherwise

Since 1.2

### mx_image_set_allow_upscale ()

    void                mx_image_set_allow_upscale          (MxImage *image,
                                                             gboolean allow);

Sets whether up-scaling of images is allowed. If set to `TRUE` and a size larger than the image is requested, the image will be up-scaled in software.

The advantage of this is that software up-scaling is potentially higher quality, but it comes at the expense of video memory.

`image` : | A MxImage
`allow` : | `TRUE` to allow upscaling, `FALSE` otherwise

Since 1.2

### mx_image_get_allow_upscale ()

    gboolean            mx_image_get_allow_upscale          (MxImage *image);

Determines whether image up-scaling is allowed.

`image` : | A MxImage
Returns : | `TRUE` if upscaling is allowed, `FALSE` otherwise

Since 1.2

### mx_image_set_scale_width_threshold ()

    void                mx_image_set_scale_width_threshold  (MxImage *image,
                                                             guint pixels);

Sets the threshold used to determine whether to scale the width of the image. If a specific width is requested, the image width is allowed to differ by this amount before scaling is employed.

This can be useful to avoid excessive CPU usage when the image differs only slightly to the desired size.

`image` : | A MxImage
`pixels` : | Number of pixels

Since 1.2

### mx_image_get_scale_width_threshold ()

    guint               mx_image_get_scale_width_threshold  (MxImage *image);

Retrieves the width scaling threshold.

`image` : | A MxImage
Returns : | The width scaling threshold, in pixels

Since 1.2

### mx_image_set_scale_height_threshold ()

    void                mx_image_set_scale_height_threshold (MxImage *image,
                                                             guint pixels);

Sets the threshold used to determine whether to scale the height of the image. If a specific height is requested, the image height is allowed to differ by this amount before scaling is employed.

This can be useful to avoid excessive CPU usage when the image differs only slightly to the desired size.

`image` : | A MxImage
`pixels` : | Number of pixels

Since 1.2

### mx_image_get_scale_height_threshold ()

    guint               mx_image_get_scale_height_threshold (MxImage *image);

Retrieves the height scaling threshold.

`image` : | A MxImage
Returns : | The height scaling threshold, in pixels

Since 1.2

### mx_image_set_transition_duration ()

    void                mx_image_set_transition_duration    (MxImage *image,
                                                             guint duration);

Set the MxImage:transition-duration property.

`image` : | A MxImage
`duration` : | Transition duration in milliseconds

Since 1.2

### mx_image_get_transition_duration ()

    guint               mx_image_get_transition_duration    (MxImage *image);

Get the value of the MxImage:transition-duration property.

`image` : | A MxImage
Returns : | The value of the transition-duration property.

Since 1.2

### mx_image_set_from_cogl_texture ()

    gboolean            mx_image_set_from_cogl_texture      (MxImage *image,
                                                             CoglHandle texture);

Sets the contents of the image from the given Cogl texture.

`image` : | A MxImage
`texture` : | A CoglHandle to a texture
Returns : | `TRUE` on success, `FALSE` on failure

Since 1.2

## Property Details

### The `"allow-upscale"` property

      "allow-upscale"            gboolean              : Read / Write

Allow images to be up-scaled.

Default value: FALSE

### The `"image-rotation"` property

      "image-rotation"           gfloat                : Read / Write

Image rotation in degrees.

Allowed values: [0,2.14748e+09]

Default value: 0

### The `"load-async"` property

      "load-async"               gboolean              : Read / Write

Whether to load images asynchronously.

Default value: FALSE

### The `"scale-height-threshold"` property

      "scale-height-threshold"   guint                 : Read / Write

Amount of pixels difference allowed between requested height and image height.

Default value: 0

### The `"scale-mode"` property

      "scale-mode"               MxImageScaleMode      : Read / Write

The scaling mode for the images.

Default value: MX_IMAGE_SCALE_NONE

### The `"scale-width-threshold"` property

      "scale-width-threshold"    guint                 : Read / Write

Amount of pixels difference allowed between requested width and image width.

Default value: 0

### The `"transition-duration"` property

      "transition-duration"      guint                 : Read / Write

Transition duration in ms.

Default value: 250

## Signal Details

### The `"image-load-error"` signal

    void                user_function                      (MxImage *image,
                                                            GError  *arg1,
                                                            gpointer user_data)      : Run Last

Emitted when an asynchronous image load has encountered an error and cannot load the requested image.

`image` : | the MxImage that emitted the signal
`user_data` : | user data set when the signal handler was connected.

Since 1.2

### The `"image-loaded"` signal

    void                user_function                      (MxImage *image,
                                                            gpointer user_data)      : Run Last

Emitted when an asynchronous image load has completed successfully

`image` : | the MxImage that emitted the signal
`user_data` : | user data set when the signal handler was connected.

Since 1.2