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

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

Generated by GTK-Doc V1.17