Etk
Main Page Object Hierarchy Data Structures Related Pages
Etk

Etk_Iconbox


Detailed Description

An Etk_Iconbox is a widget that can display icons aligned on a grid.

iconbox.png
The iconbox is based on a notion of "model". The icon view is describes by a model which is fully customizable: the model controls the position and the size of the cell, the icon image and the label of the iconbox's icons.
A default model is created when the iconbox is created, but you can add your own with etk_iconbox_model_new(), and enable it with etk_iconbox_current_model_set().

The model's settings can be changed with etk_iconbox_model_geometry_set(), etk_iconbox_model_icon_geometry_set() and etk_iconbox_model_label_geometry_set().

Once the model is defined, you can start adding and removing icons to the iconbox with etk_iconbox_append(), etk_iconbox_icon_del() and etk_iconbox_clear().

Object Hierarchy:
  • Etk_Object
    • Etk_Widget
      • Etk_Iconbox
Signals:
  • "icon-selected": Emitted when an icon of the iconbox has been selected. If several icons have been selected at the same time (with etk_iconbox_select_all(), or with the selection rectangle), the "icon-selected" signal will only be emitted once, on the last selected icon.
    • Callback: void callback(Etk_Iconbox *iconbox, Etk_Iconbox_Icon *icon, void *data)
      • iconbox: the iconbox connected to the callback
      • icon: the icon which has been selected
      • data: the user data set when the callback has been connected to the signal
  • "icon-unselected": Emitted when an icon of the iconbox has been unselected. If several icons have been unselected at the same time (with etk_iconbox_unselect_all(), or with the selection rectangle), the "icon-unselected" signal will only be emitted once, on the last unselected icon.
    • Callback: void callback(Etk_Iconbox *iconbox, Etk_Iconbox_Icon *icon, void *data)
      • iconbox: the iconbox connected to the callback
      • icon: the icon which has been unselected
      • data: the user data set when the callback has been connected to the signal
  • "all-selected": Emitted when all the icons of the iconbox have been selected with etk_iconbox_select_all()
    • Callback: void callback(Etk_Iconbox *iconbox, void *data)
      • iconbox: the iconbox connected to the callback
      • data: the user data set when the callback has been connected to the signal
  • "all-unselected": Emitted when all the icons of the iconbox have been unselected with etk_iconbox_select_all()
    • Callback: void callback(Etk_Iconbox *iconbox, void *data)
      • iconbox: the iconbox connected to the callback
      • data: the user data set when the callback has been connected to the signal


Data Structures

struct  Etk_Iconbox_Model
 Describes the model of an iconbox: it includes the position and the size of the cell, of the icon and of the label. An iconbox can have several models, and, at any moment, you can change the current model to change the view. More...
struct  Etk_Iconbox_Icon
 An icon of the iconbox. More...
struct  Etk_Iconbox
 [Widget] A widget that can display icons aligned on a grid More...

Defines

#define ETK_ICONBOX_TYPE   (etk_iconbox_type_get())
#define ETK_ICONBOX(obj)   (ETK_OBJECT_CAST((obj), ETK_ICONBOX_TYPE, Etk_Iconbox))
#define ETK_IS_ICONBOX(obj)   (ETK_OBJECT_CHECK_TYPE((obj), ETK_ICONBOX_TYPE))

Functions

Etk_Widget * etk_iconbox_new (void)
 Creates a new iconbox.
Etk_Iconbox_Model * etk_iconbox_model_new (Etk_Iconbox *iconbox)
 Creates a new model for the icons of the iconbox.
void etk_iconbox_model_free (Etk_Iconbox_Model *model)
 Frees the iconbox model.
void etk_iconbox_current_model_set (Etk_Iconbox *iconbox, Etk_Iconbox_Model *model)
 Sets the model used by the iconbox.
Etk_Iconbox_Model * etk_iconbox_current_model_get (Etk_Iconbox *iconbox)
 Gets the model currently used by the iconbox.
void etk_iconbox_model_geometry_set (Etk_Iconbox_Model *model, int width, int height, int xpadding, int ypadding)
 Sets the global geometry of the iconbox model.
void etk_iconbox_model_geometry_get (Etk_Iconbox_Model *model, int *width, int *height, int *xpadding, int *ypadding)
 Gets the global geometry of the iconbox model.
void etk_iconbox_model_icon_geometry_set (Etk_Iconbox_Model *model, int x, int y, int width, int height, Etk_Bool fill, Etk_Bool keep_aspect)
 Sets the icon geometry of the iconbox model.
void etk_iconbox_model_icon_geometry_get (Etk_Iconbox_Model *model, int *x, int *y, int *width, int *height, Etk_Bool *fill, Etk_Bool *keep_aspect)
 Gets the icon geometry of the iconbox model.
void etk_iconbox_model_label_geometry_set (Etk_Iconbox_Model *model, int x, int y, int width, int height, float xalign, float yalign)
 Sets the label geometry of the iconbox model.
void etk_iconbox_model_label_geometry_get (Etk_Iconbox_Model *model, int *x, int *y, int *width, int *height, float *xalign, float *yalign)
 Gets the label geometry of the iconbox model.
void etk_iconbox_freeze (Etk_Iconbox *iconbox)
 Freezes the iconbox: it will not be updated until it is thawed.
This function is useful when you want to add efficiently a lot of icons.
void etk_iconbox_thaw (Etk_Iconbox *iconbox)
 Thaws the iconbox: it will update the iconbox if it was frozen.
Etk_Iconbox_Icon * etk_iconbox_append (Etk_Iconbox *iconbox, const char *filename, const char *edje_group, const char *label)
 Appends a new icon to the iconbox.
void etk_iconbox_icon_del (Etk_Iconbox_Icon *icon)
 Removes the icon from the iconbox.
void etk_iconbox_clear (Etk_Iconbox *iconbox)
 Removes all the icons of the iconbox.
Etk_Iconbox_Icon * etk_iconbox_icon_get_at_xy (Etk_Iconbox *iconbox, int x, int y, Etk_Bool over_cell, Etk_Bool over_icon, Etk_Bool over_label)
 Gets the icon located below the position ( x, y ). The position should be relative to the canvas (TODO: relative to the icobox instead?).
void etk_iconbox_icon_file_set (Etk_Iconbox_Icon *icon, const char *filename, const char *edje_group)
 Sets the file path of the icon's image.
void etk_iconbox_icon_file_get (Etk_Iconbox_Icon *icon, const char **filename, const char **edje_group)
 Sets the file used by the icon's image.
void etk_iconbox_icon_label_set (Etk_Iconbox_Icon *icon, const char *label)
 Sets the label of the icon.
const char * etk_iconbox_icon_label_get (Etk_Iconbox_Icon *icon)
 Gets the label used for the icon image.
void etk_iconbox_icon_data_set (Etk_Iconbox_Icon *icon, void *data)
 Sets a value to the data member of an icon.
The data could be retrieved with etk_iconbox_icon_row_data_get().
void etk_iconbox_icon_data_set_full (Etk_Iconbox_Icon *icon, void *data, void(*free_cb)(void *data))
 Sets a value to the data member of an icon.
The data could be retrieved with etk_iconbox_icon_row_data_get().
void * etk_iconbox_icon_data_get (Etk_Iconbox_Icon *icon)
 Gets the value of the data member of the icon.
void etk_iconbox_select_all (Etk_Iconbox *iconbox)
 Selects all the icons of the iconbox.
void etk_iconbox_unselect_all (Etk_Iconbox *iconbox)
 Unselects all the icons of the iconbox.
void etk_iconbox_icon_select (Etk_Iconbox_Icon *icon)
 Selects the icon.
void etk_iconbox_icon_unselect (Etk_Iconbox_Icon *icon)
 Unselects the icon.
Etk_Bool etk_iconbox_is_selected (Etk_Iconbox_Icon *icon)
 Gets whether the icon is selected.
Etk_Scrolled_View * etk_iconbox_scrolled_view_get (Etk_Iconbox *iconbox)
 Gets the scrolled view of the iconbox. It can be used to change the scrollbars' policy, or to get the scroll-value.


Define Documentation

#define ETK_ICONBOX_TYPE   (etk_iconbox_type_get())

Gets the type of an iconbox

#define ETK_ICONBOX ( obj   )     (ETK_OBJECT_CAST((obj), ETK_ICONBOX_TYPE, Etk_Iconbox))

Casts the object to an Etk_Iconbox

#define ETK_IS_ICONBOX ( obj   )     (ETK_OBJECT_CHECK_TYPE((obj), ETK_ICONBOX_TYPE))

Check if the object is an Etk_Iconbobx


Function Documentation

Etk_Widget * etk_iconbox_new ( void   ) 

Creates a new iconbox.

Returns:
Returns the new iconbox widget

Etk_Iconbox_Model * etk_iconbox_model_new ( Etk_Iconbox *  iconbox  ) 

Creates a new model for the icons of the iconbox.

Parameters:
iconbox an iconbox
Returns:
Returns the new model

void etk_iconbox_model_free ( Etk_Iconbox_Model *  model  ) 

Frees the iconbox model.

Parameters:
model the iconbox model to free
Note:
You don't need to do it manually, the models are automatically freed when the iconbox is destroyed

void etk_iconbox_current_model_set ( Etk_Iconbox *  iconbox,
Etk_Iconbox_Model *  model 
)

Sets the model used by the iconbox.

Parameters:
iconbox an iconbox
model the model that the iconbox should use (if NULL, no icon will be displayed)

Etk_Iconbox_Model * etk_iconbox_current_model_get ( Etk_Iconbox *  iconbox  ) 

Gets the model currently used by the iconbox.

Parameters:
iconbox an iconbox
Returns:
Returns the model currently used by the iconbox

void etk_iconbox_model_geometry_set ( Etk_Iconbox_Model *  model,
int  width,
int  height,
int  xpadding,
int  ypadding 
)

Sets the global geometry of the iconbox model.

Parameters:
model an iconbox model
width the width of the cells of the model (min = 10)
height the height of the cells of the model (min = 10)
xpadding the horizontal padding of the cells of the model (min = 0)
ypadding the vertical padding of the cells of the model (min = 0)

void etk_iconbox_model_geometry_get ( Etk_Iconbox_Model *  model,
int *  width,
int *  height,
int *  xpadding,
int *  ypadding 
)

Gets the global geometry of the iconbox model.

Parameters:
model an iconbox model
width the location where to store the width of the cells of the model
height the location where to store the height of the cells of the model
xpadding the location where to store the horizontal padding of the cells of the model
ypadding the location where to store the vertical padding of the cells of the model

void etk_iconbox_model_icon_geometry_set ( Etk_Iconbox_Model *  model,
int  x,
int  y,
int  width,
int  height,
Etk_Bool  fill,
Etk_Bool  keep_aspect 
)

Sets the icon geometry of the iconbox model.

Parameters:
model an iconbox model
x the x position of the icon image of the model (min = 0)
y the y position of the icon image of the model (min = 0)
width the width of the icon image of the model (min = 10)
height the height of the icon image of the model (min = 10)
fill if fill == ETK_TRUE, and if the icon image is smaller than the icon geometry, the image will fill the geometry
keep_aspect if keep_aspect == ETK_TRUE, the icon image will keep its aspect ratio (no distortion)
Note:
the x/y positions are relative to the inner top left corner of the icon model:
i.e. the icon image will be in fact put at (model->xpadding + model->icon_x, model->ypadding + model->icon_y)

void etk_iconbox_model_icon_geometry_get ( Etk_Iconbox_Model *  model,
int *  x,
int *  y,
int *  width,
int *  height,
Etk_Bool *  fill,
Etk_Bool *  keep_aspect 
)

Gets the icon geometry of the iconbox model.

Parameters:
model an iconbox model
x the location where to store x position of the icon image
y the location where to store y position of the icon image
width the location where to store the width of the icon image
height the location where to store the height of the icon image
fill the location where to store the fill property of the model (see etk_iconbox_model_icon_geometry_set())
keep_aspect the location where to store the "keep aspect ratio" property of the model (see etk_iconbox_model_icon_geometry_set())
See also:
etk_iconbox_model_icon_geometry_set()

void etk_iconbox_model_label_geometry_set ( Etk_Iconbox_Model *  model,
int  x,
int  y,
int  width,
int  height,
float  xalign,
float  yalign 
)

Sets the label geometry of the iconbox model.

Parameters:
model an iconbox model
x the x position of the label of the model (min = 0)
y the y position of the label of the model (min = 0)
width the width of the label of the model (min = 10)
height the height of the label of the model (min = 5)
xalign the horizontal alignment of the label (from 0.0 to 1.0)
yalign the vertical alignment of the label
Note:
the x/y positions are relative to the inner top left corner of the icon model:
i.e. the label will be in fact put at (model->xpadding + model->label_x, model->ypadding + model->label_y)

void etk_iconbox_model_label_geometry_get ( Etk_Iconbox_Model *  model,
int *  x,
int *  y,
int *  width,
int *  height,
float *  xalign,
float *  yalign 
)

Gets the label geometry of the iconbox model.

Parameters:
model an iconbox model
x the location where to store x position of the label
y the location where to store y position of the label
width the location where to store width of the label
height the location where to store height of the label
xalign the location where to store horizontal alignment of the label
yalign the location where to store vertical alignment of the label

void etk_iconbox_freeze ( Etk_Iconbox *  iconbox  ) 

Freezes the iconbox: it will not be updated until it is thawed.
This function is useful when you want to add efficiently a lot of icons.

Parameters:
iconbox an iconbox

void etk_iconbox_thaw ( Etk_Iconbox *  iconbox  ) 

Thaws the iconbox: it will update the iconbox if it was frozen.

Parameters:
iconbox an iconbox

Etk_Iconbox_Icon * etk_iconbox_append ( Etk_Iconbox *  iconbox,
const char *  filename,
const char *  edje_group,
const char *  label 
)

Appends a new icon to the iconbox.

Parameters:
iconbox a iconbox
filename the filename of the image to use for the icon. It can be either an image or an edje file
edje_group the edje group to use for the icon. If NULL, filename will be considerated as a normal image file
label the label to associate to the icon
Returns:
Returns the new icon

void etk_iconbox_icon_del ( Etk_Iconbox_Icon *  icon  ) 

Removes the icon from the iconbox.

Parameters:
icon the icon to remove

void etk_iconbox_clear ( Etk_Iconbox *  iconbox  ) 

Removes all the icons of the iconbox.

Parameters:
iconbox an iconbox

Etk_Iconbox_Icon * etk_iconbox_icon_get_at_xy ( Etk_Iconbox *  iconbox,
int  x,
int  y,
Etk_Bool  over_cell,
Etk_Bool  over_icon,
Etk_Bool  over_label 
)

Gets the icon located below the position ( x, y ). The position should be relative to the canvas (TODO: relative to the icobox instead?).

Parameters:
iconbox an iconbox
x the x position
y the y position
over_cell if over_cell is ETK_TRUE, the function will return the icon if (x, y) is over the cell of the icon
over_icon if over_icon == ETK_TRUE, the function will return the icon if (x, y) is over the image of the icon
over_label if over_label == ETK_TRUE, the function will return the icon if (x, y) is over the label of the icon
Returns:
Returns the icon located below the position (x, y), or NULL if none

void etk_iconbox_icon_file_set ( Etk_Iconbox_Icon *  icon,
const char *  filename,
const char *  edje_group 
)

Sets the file path of the icon's image.

Parameters:
icon an icon
filename the filename of the icon's image
edje_group the edje group of the icon's image. It has to be set to NULL for a "normal" image

void etk_iconbox_icon_file_get ( Etk_Iconbox_Icon *  icon,
const char **  filename,
const char **  edje_group 
)

Sets the file used by the icon's image.

Parameters:
icon an icon
filename a location where to store the filename of the icon's image
edje_group a location where to store the edje group of the icon's image

void etk_iconbox_icon_label_set ( Etk_Iconbox_Icon *  icon,
const char *  label 
)

Sets the label of the icon.

Parameters:
icon an icon
label the label to set to the icon

const char * etk_iconbox_icon_label_get ( Etk_Iconbox_Icon *  icon  ) 

Gets the label used for the icon image.

Parameters:
icon an icon
Returns:
Returns the label of the icon

void etk_iconbox_icon_data_set ( Etk_Iconbox_Icon *  icon,
void *  data 
)

Sets a value to the data member of an icon.
The data could be retrieved with etk_iconbox_icon_row_data_get().

Parameters:
icon an icon
data the data to set

void etk_iconbox_icon_data_set_full ( Etk_Iconbox_Icon *  icon,
void *  data,
void(*)(void *data)  free_cb 
)

Sets a value to the data member of an icon.
The data could be retrieved with etk_iconbox_icon_row_data_get().

Parameters:
icon an icon
data the data to set
free_cb the function to call to free the data

void * etk_iconbox_icon_data_get ( Etk_Iconbox_Icon *  icon  ) 

Gets the value of the data member of the icon.

Parameters:
icon an icon
Returns:
Returns the value of the data member of the icon

void etk_iconbox_select_all ( Etk_Iconbox *  iconbox  ) 

Selects all the icons of the iconbox.

Parameters:
iconbox an iconbox

void etk_iconbox_unselect_all ( Etk_Iconbox *  iconbox  ) 

Unselects all the icons of the iconbox.

Parameters:
iconbox an iconbox

void etk_iconbox_icon_select ( Etk_Iconbox_Icon *  icon  ) 

Selects the icon.

Parameters:
icon the icon to select

void etk_iconbox_icon_unselect ( Etk_Iconbox_Icon *  icon  ) 

Unselects the icon.

Parameters:
icon the icon to select

Etk_Bool etk_iconbox_is_selected ( Etk_Iconbox_Icon *  icon  ) 

Gets whether the icon is selected.

Parameters:
icon an icon
Returns:
Returns ETK_TRUE if the icon is selected, ETK_FALSE otherwise

Etk_Scrolled_View * etk_iconbox_scrolled_view_get ( Etk_Iconbox *  iconbox  ) 

Gets the scrolled view of the iconbox. It can be used to change the scrollbars' policy, or to get the scroll-value.

Parameters:
iconbox an iconbox
Returns:
Returns the scrolled view of the iconbox