MxImage

MxImage — A widget to display an image

Functions

Properties

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

Signals

void image-load-error Run Last
void image-loaded Run Last

Types and Values

enum MxImageError
struct MxImage
struct MxImageClass

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── ClutterActor
            ╰── MxWidget
                ╰── MxImage

Implemented Interfaces

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

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.

Functions

MX_IMAGE_ERROR

#define MX_IMAGE_ERROR (mx_image_error_quark ())

mx_image_error_quark ()

GQuark
mx_image_error_quark (void);

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.

Parameters

image

An MxImage

 

data

Image data.

[array]

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.

Parameters

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.

Parameters

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.

Parameters

image

An MxImage

 

buffer

A buffer pointing to encoded image data.

[array length=buffer_size][transfer full]

buffer_size

The size of buffer , in bytes

 

buffer_free_func

A function to free buffer , or NULL.

[allow-none]

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.

Parameters

image

An MxImage

 

buffer

A buffer pointing to encoded image data.

[array length=buffer_size][transfer full]

buffer_size

The size of buffer , in bytes

 

buffer_free_func

A function to free buffer , or NULL.

[allow-none]

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.

Parameters

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

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

image

A MxImage

 

texture

A CoglHandle to a texture

 

Returns

TRUE on success, FALSE on failure

Since 1.2

Types and Values

enum MxImageError

Members

MX_IMAGE_ERROR_BAD_FORMAT

   

MX_IMAGE_ERROR_NO_ASYNC

   

MX_IMAGE_ERROR_INTERNAL

   

MX_IMAGE_ERROR_INVALID_PARAMETER

   

struct MxImage

struct MxImage;

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


struct MxImageClass

struct MxImageClass {
};

Property Details

The “allow-upscale” property

  “allow-upscale”            gboolean

Allow images to be up-scaled.

Flags: Read / Write

Default value: FALSE


The “image-rotation” property

  “image-rotation”           gfloat

Image rotation in degrees.

Flags: Read / Write

Allowed values: [0,2.14748e+09]

Default value: 0


The “load-async” property

  “load-async”               gboolean

Whether to load images asynchronously.

Flags: Read / Write

Default value: FALSE


The “scale-height-threshold” property

  “scale-height-threshold”   guint

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

Flags: Read / Write

Default value: 0


The “scale-mode” property

  “scale-mode”               MxImageScaleMode

The scaling mode for the images.

Flags: Read / Write

Default value: MX_IMAGE_SCALE_NONE


The “scale-width-threshold” property

  “scale-width-threshold”    guint

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

Flags: Read / Write

Default value: 0


The “transition-duration” property

  “transition-duration”      guint

Transition duration in ms.

Flags: Read / Write

Default value: 250

Signal Details

The “image-load-error” signal

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

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

Parameters

image

the MxImage that emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 1.2


The “image-loaded” signal

void
user_function (MxImage *image,
               gpointer user_data)

Emitted when an asynchronous image load has completed successfully

Parameters

image

the MxImage that emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 1.2