MxImage

MxImage — A widget to display an image

Synopsis

enum                MxImageError;
#define             MX_IMAGE_ERROR
GQuark              mx_image_error_quark                (void);
                    MxImage;
                    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_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);

Object Hierarchy

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

Implemented Interfaces

MxImage implements 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

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
} MxImageError;


MX_IMAGE_ERROR

#define MX_IMAGE_ERROR (mx_image_error_quark ())


mx_image_error_quark ()

GQuark              mx_image_error_quark                (void);

Returns :


MxImage

typedef struct _MxImage MxImage;

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


MxImageClass

typedef struct {
} MxImageClass;


mx_image_new ()

ClutterActor *      mx_image_new                        (void);

Creates a new MxImage object.

Returns :

A newly created MxImage object

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

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

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

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

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

mx_image_clear ()

void                mx_image_clear                      (MxImage *image);

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

image :

A MxImage

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

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

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

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.

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

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

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

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

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

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

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

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

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

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.

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.