Ewl_Image: An Image Display Widget

Detailed Description

Provides a widget for displaying evas loadable images, and edjes.

Remarks:: Inherits from Ewl_Widget.

Tutorial

The Ewl_Image widget provides methods for displaying an image in an EWL application. The image widget also supports a limited set of methods for manipulating the displayed image.

 Ewl_Widget *image;
 image = ewl_image_new();
 ewl_image_file_path_set(EWL_IMAGE(image), "/usr/share/ewl/image.png");
 ewl_widget_show(image);

After creating an image widget, the most common operation is to set the path or key on the widget. The key is only used if an edje is loaded as the image, indicating the group to load. This will cause the widget to setup its sizing information when it is realized based on the original image size. It is also possible to request the current file and key set on the image widget.

 void ewl_image_file_set(Ewl_Image *i, const char *im, const char *key);
 void ewl_image_file_path_set(Ewl_Image *i, const char *im);
 const char *ewl_image_file_path_get(Ewl_Image *i);
 void ewl_image_file_key_set(Ewl_Image *i, const char *key);
 const char *ewl_image_file_key_get(Ewl_Image *i);

Along with the image to be displayed, the basic operations of scaling and tiling can be applied to the displayed image. Scaling can be applied on either a relative or absolute scale. The functions that refer to scale are a multiplier of the images set size, so 2.0 would result in an image double the original size. The size functions force the image to be scaled to specified dimensions. Setting a tile on an image causes the image to repeat when the specified dimensions are reached, the x and y coordinates indicate the starting offset within the available area where tiling begins.

 void ewl_image_scale_set(Ewl_Image *i, double wp, double hp);
 void ewl_image_scale_get(Ewl_Image *i, double *wp, double *hp);
 void ewl_image_size_set(Ewl_Image *i, int w, int h);
 void ewl_image_size_get(Ewl_Image *i, int *w, int *h);
 void ewl_image_tile_set(Ewl_Image *i, int x, int y, int w, int h);

Two settings also impact the sizing, but are not explicit in how they determine the new size. The proportional setting causes the image to be displayed at the original aspect ratio of the specified image, regardless of scaling. The constrain setting sets a maximum size on the dimensions of an image, but will not scale the image if it's smaller than that size.

 void ewl_image_proportional_set(Ewl_Image *i, char p);
 char ewl_image_proportional_get(Ewl_Image *i);
 void ewl_image_constrain_set(Ewl_Image *i, unsigned int size);
 unsigned int ewl_image_constrain_get(Ewl_Image *i);

Since the image is inherited from the base widget class, all of the standard widget and object operations can be applied to the image widget. This includes resizing, theming, color tinting and packing in containers.


Data Structures
struct	Ewl_Image
	Inherits from Ewl_Widget and extends to provide an image widget. More...
struct	Ewl_Image_Thumbnail
	Inherits from Ewl_Image and extends to provide reference to original image. More...
Defines
#define	EWL_IMAGE(image) ((Ewl_Image *) image)
#define	EWL_IMAGE_IS(w) (ewl_widget_type_is(EWL_WIDGET(w), EWL_IMAGE_TYPE))
#define	EWL_IMAGE_THUMBNAIL(image) ((Ewl_Image_Thumbnail *) image)
#define	EWL_IMAGE_THUMBNAIL_IS(w)
#define	EWL_IMAGE_THUMBNAIL_TYPE "image_thumbnail"
#define	EWL_IMAGE_TYPE "image"
Typedefs
typedef Ewl_Image	Ewl_Image
typedef Ewl_Image_Thumbnail	Ewl_Image_Thumbnail
Functions
void	ewl_image_cb_configure (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_image_cb_destroy (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_image_cb_obscure (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_image_cb_reveal (Ewl_Widget w, void ev_data, void *user_data)
unsigned int	ewl_image_constrain_get (Ewl_Image *i)
	Get the current constrain value set on the image.
void	ewl_image_constrain_set (Ewl_Image *i, unsigned int size)
	Set a size which, if the image is bigger than, scale proportionally.
void *	ewl_image_data_get (Ewl_Image i, int w, int *h, Ewl_Image_Data_Mode mode)
	Retrieve the data of the image widget.
unsigned int	ewl_image_data_set (Ewl_Image i, void data, int w, int h, Ewl_Colorspace cs)
	Set the data of the image.
void	ewl_image_data_update_add (Ewl_Image *i, int x, int y, int w, int h)
const char *	ewl_image_file_key_get (Ewl_Image *i)
void	ewl_image_file_key_set (Ewl_Image i, const char key)
	Sets the key to use for the image.
const char *	ewl_image_file_path_get (Ewl_Image *i)
	get the filename this image uses
void	ewl_image_file_path_set (Ewl_Image i, const char im)
	Sets the path to the image file.
void	ewl_image_file_set (Ewl_Image i, const char im, const char *key)
	Change the image file displayed by an image widget.
void	ewl_image_flip (Ewl_Image *img, Ewl_Orientation orient)
	Flips the given image in the given direction.
int	ewl_image_init (Ewl_Image *i)
	Initialize an image widget to default values and callbacks.
Ewl_Widget *	ewl_image_new (void)
	Load an image widget with specified image contents.
char	ewl_image_proportional_get (Ewl_Image *i)
	Get boolean to determine how to scale.
void	ewl_image_proportional_set (Ewl_Image *i, char p)
	Set boolean to determine how to scale.
void	ewl_image_rotate (Ewl_Image *i, Ewl_Rotate rotate)
	Rotates the given image by the given rotate value.
void	ewl_image_scale_get (Ewl_Image i, double wp, double *hp)
	Retrieve the percentage an image is scaled.
void	ewl_image_scale_set (Ewl_Image *i, double wp, double hp)
	Scale image dimensions by a percentage.
void	ewl_image_size_get (Ewl_Image i, int w, int *h)
	Scale image dimensions to a specific size.
void	ewl_image_size_set (Ewl_Image *i, int w, int h)
	Scale image dimensions to a specific size.
Ewl_Widget *	ewl_image_thumbnail_get (Ewl_Image *i)
	Create a widget representing a thumbnailed version of the image.
int	ewl_image_thumbnail_init (Ewl_Image_Thumbnail *image)
	Initialize an Ewl_Image_Thumbnail to default values.
Ewl_Widget *	ewl_image_thumbnail_new (void)
	This will create and initialize a new Ewl_Image_Thumbnail widget.
void	ewl_image_thumbnail_request (Ewl_Image_Thumbnail thumb, const char path)
	This will request the generation of a thumbnail for the image given by path.
Ewl_Thumbnail_Size	ewl_image_thumbnail_size_get (Ewl_Image_Thumbnail *thumb)
	This will return the current size of thumbnails.
void	ewl_image_thumbnail_size_set (Ewl_Image_Thumbnail *thumb, Ewl_Thumbnail_Size s)
	This will set the size of the thumbnails.
void	ewl_image_tile_set (Ewl_Image *i, int x, int y, int w, int h)
	Tile the image with the given start position and given size.
Ewl_View *	ewl_image_view_get (void)
	Creates and returns a view to be used by Ewl_Image widgets.

Define Documentation

#define EWL_IMAGE ( image ) ((Ewl_Image *) image)

Typecase a pointer to an Ewl_Image widget

#define EWL_IMAGE_IS ( w ) (ewl_widget_type_is(EWL_WIDGET(w), EWL_IMAGE_TYPE))

Returns TRUE if the widget is an Ewl_Image, FALSE otherwise

#define EWL_IMAGE_THUMBNAIL ( image ) ((Ewl_Image_Thumbnail *) image)

Typecase a pointer to an Ewl_Image_Thumbnail widget

#define EWL_IMAGE_THUMBNAIL_IS ( w )

Value:

(ewl_widget_type_is(EWL_WIDGET(w), \
                        EWL_IMAGE_THUMBNAIL_TYPE))

Returns TRUE if the widget is an Ewl_Image_Thumbnail, FALSE otherwise

#define EWL_IMAGE_THUMBNAIL_TYPE "image_thumbnail"

The type name for the Ewl_Image_Thumbnail widget

#define EWL_IMAGE_TYPE "image"

The type name for the Ewl_Image widget

Typedef Documentation

typedef struct Ewl_Image Ewl_Image

The Ewl_Image widget

typedef struct Ewl_Image_Thumbnail Ewl_Image_Thumbnail

The Ewl_Image_Thumbnail widget

Function Documentation

void ewl_image_cb_configure	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_image_cb_destroy	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_image_cb_obscure	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_image_cb_reveal	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

unsigned int ewl_image_constrain_get ( Ewl_Image * i )

Get the current constrain value set on the image.

Parameters:

i,:

The Ewl_Image to get the consrain size from

Returns:: Returns the current constrain size on the image

void ewl_image_constrain_set	(	Ewl_Image *	i,
		unsigned int	size
	)

Set a size which, if the image is bigger than, scale proportionally.

Parameters:

	i,:	the image to change constrain setting
	size,:	the minimum constrain size

Returns:: Returns no value.

Sets a size to scale to proportionally if the image exceeds this size

void* ewl_image_data_get	(	Ewl_Image *	i,
		int *	w,
		int *	h,
		Ewl_Image_Data_Mode	access
	)

Retrieve the data of the image widget.

Parameters:

	i,:	The image to get the data
	w,:	pointer to store the width
	h,:	pointer to store the height
	access,:	the access mode

Returns:: Returns the image data of the image widget

This function will return the image data of the image widget. The size of the image data is stored by the pointers w and h. Since operating on the image data with out knowing its actually size is dangerous, it is not allowed to pass NULL pointer for w and h.

The access parameter defines the purpose to get the data. There are three different modes:

EWL_IMAGE_DATA_SIZE: no data is returned, use this to only retrieve the size
EWL_IMAGE_DATA_READ: the data is meant to be read only
EWL_IMAGE_DATA_WRITE: the data is meant to be read and written

If the image isn't already realized or if an error occurs, NULL will be returned.

unsigned int ewl_image_data_set	(	Ewl_Image *	i,
		void *	data,
		int	w,
		int	h,
		Ewl_Colorspace	cs
	)

Set the data of the image.

Parameters:

	i,:	The image to set the data
	w,:	the width of the data
	h,:	the height of the data
	cs,:	the colorspaced of the data

Returns:: Returns TRUE on success, else FALSE

This function will set the image data of the image widget. The colorspace of the data can either be EWL_COLORSPACE_ARGB or EWL_COLORSPACE_RGB. In the latter case the alpha channel will be ignored. The data is after that owned and freed by ewl.

void ewl_image_data_update_add	(	Ewl_Image *	i,
		int	x,
		int	y,
		int	w,
		int	h
	)

Parameters:

	i,:	the image to work with
	x,:	the x offset of the region to be updated
	y,:	the y offset of the region to be updated
	w,:	the width of the region to be updated
	h,:	the height of the region to be updated

After changing a region of an image it's neccessary to call this function, so this area will be marked to updated later. The coordinates and the size of the region is in units of the image data and not of the actual screen position.

const char* ewl_image_file_key_get ( Ewl_Image * i )

Parameters:

i,:

The image to get the key from

Returns:: Returns the key used for this image

void ewl_image_file_key_set	(	Ewl_Image *	i,
		const char *	key
	)

Sets the key to use for the image.

Parameters:

	i,:	The image to set the key into
	key,:	The key to set into the image

Returns:: Returns no value.

const char* ewl_image_file_path_get ( Ewl_Image * i )

get the filename this image uses

Parameters:

i,:

the image widget to get the file of

Returns:: Returns the currently set filename

void ewl_image_file_path_set	(	Ewl_Image *	i,
		const char *	path
	)

Sets the path to the image file.

Parameters:

	i,:	The image to set the file into
	path,:	The path to set into the image

Returns:: Returns no value.

void ewl_image_file_set	(	Ewl_Image *	i,
		const char *	im,
		const char *	key
	)

Change the image file displayed by an image widget.

Parameters:

	i,:	the image widget to change the displayed image
	im,:	the path to the new image to be displayed by i
	key,:	the key in the file for the image

Returns:: Returns no value.

Set the image displayed by i to the one found at the path im. If an edje is used, a minimum size should be specified in the edje or the code.

void ewl_image_flip	(	Ewl_Image *	img,
		Ewl_Orientation	orient
	)

Flips the given image in the given direction.

Parameters:

	img,:	The image to flip
	orient,:	The orientation to flip

Returns:: Returns no value

int ewl_image_init ( Ewl_Image * i )

Initialize an image widget to default values and callbacks.

Parameters:

i,:

the image widget to initialize

Returns:: Returns no value.

Sets the fields and callbacks of i to their default values.

Ewl_Widget* ewl_image_new ( void )

Load an image widget with specified image contents.

Returns:: Returns a pointer to a new image widget on success, NULL on failure.

The k parameter is primarily used for loading edje groups or keyed data in an image.

char ewl_image_proportional_get ( Ewl_Image * i )

Get boolean to determine how to scale.

Parameters:

i,:

the image to get the proportional setting value

Returns:: Returns TRUE if the image is forced proportional, FALSE otherwise.

void ewl_image_proportional_set	(	Ewl_Image *	i,
		char	p
	)

Set boolean to determine how to scale.

Parameters:

	i,:	the image to change proportional setting
	p,:	the boolean indicator of proportionality

Returns:: Returns no value.

Changes the flag indicating if the image is scaled proportionally.

void ewl_image_rotate	(	Ewl_Image *	i,
		Ewl_Rotate	rotate
	)

Rotates the given image by the given rotate value.

Parameters:

	i,:	The image to rotate
	rotate,:	The amount to rotate the image

Returns:: Returns no value

void ewl_image_scale_get	(	Ewl_Image *	i,
		double *	wp,
		double *	hp
	)

Retrieve the percentage an image is scaled.

Parameters:

	i,:	the image to retrieve the current scale
	wp,:	stores the percentage to scale width
	hp,:	stores the percentage to scale height

Returns:: Returns no value.

void ewl_image_scale_set	(	Ewl_Image *	i,
		double	wp,
		double	hp
	)

Scale image dimensions by a percentage.

Parameters:

	i,:	the image to scale
	wp,:	the percentage to scale width
	hp,:	the percentage to scale height

Returns:: Returns no value. Scales the given image to wp percent of preferred width by hp percent of preferred height. If i->proportional is set to TRUE, the lesser of wp and hp is applied for both directions.

void ewl_image_size_get	(	Ewl_Image *	i,
		int *	w,
		int *	h
	)

Scale image dimensions to a specific size.

Parameters:

	i,:	the image to scale
	w,:	the size to scale width
	h,:	the size to scale height

Returns:: Returns no value.

Scales the given image to w by hp. If i->proportional is set to TRUE, the image is scaled proportional to the lesser scale percentage of preferred size.

void ewl_image_size_set	(	Ewl_Image *	i,
		int	w,
		int	h
	)

Scale image dimensions to a specific size.

Parameters:

	i,:	the image to scale
	w,:	the size to scale width
	h,:	the size to scale height

Returns:: Returns no value.

Scales the given image to w by hp. If i->proportional is set to TRUE, the image is scaled proportional to the lesser scale percentage of preferred size.

Ewl_Widget* ewl_image_thumbnail_get ( Ewl_Image * i )

Create a widget representing a thumbnailed version of the image.

Parameters:

i,:

the image to thumbnail

Returns:: Returns a thumbnailed image widget on success, NULL on failure.

int ewl_image_thumbnail_init ( Ewl_Image_Thumbnail * image )

Initialize an Ewl_Image_Thumbnail to default values.

Parameters:

image,:

The Ewl_Image_Thumbnail to init

Returns:: Returns TRUE if successfully initialized, FALSE otherwise

Ewl_Widget* ewl_image_thumbnail_new ( void )

This will create and initialize a new Ewl_Image_Thumbnail widget.

Returns:: Returns a new Ewl_Image_Thumbnail widget

void ewl_image_thumbnail_request	(	Ewl_Image_Thumbnail *	thumb,
		const char *	path
	)

This will request the generation of a thumbnail for the image given by path.

Parameters:

	thumb,:	The thumbnail to request
	path,:	The path to the image

Returns:: Returns no value.

Ewl_Thumbnail_Size ewl_image_thumbnail_size_get ( Ewl_Image_Thumbnail * thumb )

This will return the current size of thumbnails.

Parameters:

thumb,:

The image thumbnail to get the size from

Returns:: Returns the size of the thumbnail.

void ewl_image_thumbnail_size_set	(	Ewl_Image_Thumbnail *	thumb,
		Ewl_Thumbnail_Size	s
	)

This will set the size of the thumbnails.

Parameters:

	thumb,:	The image thumbnail to set the size on
	s,:	The Ewl_Thumbnail_Size to set for the image

Returns:: Returns no value.

void ewl_image_tile_set	(	Ewl_Image *	i,
		int	x,
		int	y,
		int	w,
		int	h
	)

Tile the image with the given start position and given size.

Parameters:

	i,:	the image to tile
	x,:	the x position of the top right corner
	y,:	the y position of the top right corner
	w,:	the width of the tile
	h,:	the height of the tile

Returns:: Returns no value

Tiles the image across the available area, starting the image at the given position and with the given size.

Ewl_View* ewl_image_view_get ( void )

Creates and returns a view to be used by Ewl_Image widgets.

Returns:: Returns a view that can be used to display Ewl_Image widgets

Ewl_Image: An Image Display Widget

Detailed Description

Tutorial

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation