Etk
Main Page Object Hierarchy Data Structures Related Pages
Etk

Etk_Combobox


Detailed Description

The Etk_Combobox widget is made up of a button that shows a popup menu-when it is clicked, allowing the user to choose an item from a list.

combobox.png
Once the combobox is created, at least one column must be added to it with etk_combobox_column_add(). Each column can contain a specific widget type.
Once all the column are created, the combobox has to be built with etk_combobox_build(), in order to be able to add items to it. No item can be added to a combobox if it is not built, and no columns can be added anymore to the combobox once it is built.
Items can be added to the combobox with etk_combobox_item_prepend() and etk_combobox_item_append(). The parameters of those functions depend on the type of widget of the column.

Here is a simple example, where we create a combobox with three columns (one for the icon, one for the label and one with a checkbox), and then, we add two items to it:
 Etk_Combobox *combobox;

 combobox = ETK_COMBOBOX(etk_combobox_new());
 etk_combobox_column_add(combobox, ETK_COMBOBOX_IMAGE, 24, ETK_COMBOBOX_NONE, 0.0);
 etk_combobox_column_add(combobox, ETK_COMBOBOX_LABEL, 75, ETK_COMBOBOX_EXPAND, 0.0);
 etk_combobox_column_add(combobox, ETK_COMBOBOX_OTHER, 32, ETK_COMBOBOX_NONE, 1.0);
 etk_combobox_build(combobox);

 etk_combobox_item_append(combobox, image1, "item 1", checkbox1);
 etk_combobox_item_append(combobox, image2, "item 2", checkbox1);

Object Hierarchy:
  • Etk_Object
    • Etk_Widget
      • Etk_Combobox
Signals:
  • "active-item-changed": Emitted when the active item is changed (when the user selects another items)
    • Callback: void callback(Etk_Combobox *combobox, void *data)
      • combobox: the combobox whose active item has been changed
      • data: the user data set when the callback has been connected to the signal
Properties:
  • "items-height": The height of an item of the combobox (should be > 0)
    • Type: Integer
    • Access: Read/Write
    • Default Value: 24
  • "active-item": The active item of the combobox (the item displayed in the combobox button)
    • Type: Pointer (Etk_Combobox_Item *)
    • Access: Read/Write
    • Default Value: NULL


Data Structures

struct  Etk_Combobox_Item
 [Widget] A combobox's item made up of a button that shows a popup-menu when it is clicked, allowing the user to choose an item from a list More...
struct  Etk_Combobox
 [Widget] A combobox is a widget More...

Defines

#define ETK_COMBOBOX_TYPE   (etk_combobox_type_get())
#define ETK_COMBOBOX(obj)   (ETK_OBJECT_CAST((obj), ETK_COMBOBOX_TYPE, Etk_Combobox))
#define ETK_IS_COMBOBOX(obj)   (ETK_OBJECT_CHECK_TYPE((obj), ETK_COMBOBOX_TYPE))
#define ETK_COMBOBOX_ITEM_TYPE   (etk_combobox_item_type_get())
#define ETK_COMBOBOX_ITEM(obj)   (ETK_OBJECT_CAST((obj), ETK_COMBOBOX_ITEM_TYPE, Etk_Combobox_Item))
#define ETK_IS_COMBOBOX_ITEM(obj)   (ETK_OBJECT_CHECK_TYPE((obj), ETK_COMBOBOX_ITEM_TYPE))

Enumerations

enum  Etk_Combobox_Column_Type {
  ETK_COMBOBOX_LABEL,
  ETK_COMBOBOX_IMAGE,
  ETK_COMBOBOX_OTHER
}
 The different types of widgets that can be contained by a combobox's column. More...
enum  Etk_Combobox_Fill_Policy
 Indicates how a widget of a combobox-column should fill and expand. More...

Functions

Etk_Widget * etk_combobox_new (void)
 Creates a new combobox, with no column.
Etk_Widget * etk_combobox_new_default (void)
 Creates a new combobox, made up of a unique column containing a label, and already built (no need to call etk_combobox_build()).
void etk_combobox_items_height_set (Etk_Combobox *combobox, int items_height)
 Set the height of the combobox's items. The default height is 24, the minimum is 12.
int etk_combobox_items_height_get (Etk_Combobox *combobox)
 Gets the height of the combobox's items.
void etk_combobox_column_add (Etk_Combobox *combobox, Etk_Combobox_Column_Type col_type, int width, Etk_Combobox_Fill_Policy fill_policy, float align)
 Adds a column to the combobox. The combobox should not be already be built.
void etk_combobox_build (Etk_Combobox *combobox)
 Builds the combobox: you have to build a combobox after you have added all the columns to it and before you start adding items. Items can not be added if the combobox is not built.
Etk_Combobox_Item * etk_combobox_item_prepend (Etk_Combobox *combobox,...)
 Inserts a new item at the start of the combobox.
Etk_Combobox_Item * etk_combobox_item_append (Etk_Combobox *combobox,...)
 Inserts a new item at the end of the combobox.
Etk_Combobox_Item * etk_combobox_item_insert (Etk_Combobox *combobox, Etk_Combobox_Item *after,...)
 Inserts a new item after an existing item of the combobox.
Etk_Combobox_Item * etk_combobox_item_insert_valist (Etk_Combobox *combobox, Etk_Combobox_Item *after, va_list args)
 Inserts a new item after an existing item of the combobox.
void etk_combobox_item_remove (Etk_Combobox_Item *item)
 Removes an item from the combobox. The item will be freed and should not be used anymore.
void etk_combobox_clear (Etk_Combobox *combobox)
 Removes all the items of the combobox. All the items will be freed and should not be used anymore.
void etk_combobox_item_fields_set (Etk_Combobox_Item *item,...)
 Sets the values of the cells of the combobox item.
void etk_combobox_item_fields_set_valist (Etk_Combobox_Item *item, va_list args)
 Sets the values of the cells of the combobox item. The current widgets of item will be destroyed.
void etk_combobox_item_fields_get (Etk_Combobox_Item *item,...)
 Gets the values of the cells of the combobox item.
void etk_combobox_item_fields_get_valist (Etk_Combobox_Item *item, va_list args)
 Gets the values of the cells of the combobox item.
void etk_combobox_item_data_set (Etk_Combobox_Item *item, void *data)
 Sets the data associated to the combobox item.
void etk_combobox_item_data_set_full (Etk_Combobox_Item *item, void *data, void(*free_cb)(void *data))
 Sets the data associated to the combobox item.
void * etk_combobox_item_data_get (Etk_Combobox_Item *item)
 Gets the data associated to the combobox item.
void etk_combobox_active_item_set (Etk_Combobox *combobox, Etk_Combobox_Item *item)
 Sets the active item of the combobox.
Etk_Combobox_Item * etk_combobox_active_item_get (Etk_Combobox *combobox)
 Gets the active item of the combobox.
int etk_combobox_active_item_num_get (Etk_Combobox *combobox)
 Gets the index of the current active item of the combobox.
Etk_Combobox_Item * etk_combobox_first_item_get (Etk_Combobox *combobox)
 Gets the first item of a combobox.
Etk_Combobox_Item * etk_combobox_last_item_get (Etk_Combobox *combobox)
 Gets the last item of a combobox.
Etk_Combobox_Item * etk_combobox_item_prev_get (Etk_Combobox_Item *item)
 Gets the item previous to the given combobox item.
Etk_Combobox_Item * etk_combobox_item_next_get (Etk_Combobox_Item *item)
 Gets the item next to the given combobox item.
Etk_Combobox_Item * etk_combobox_nth_item_get (Etk_Combobox *combobox, int index)
 Gets the nth item of the combobox.
Etk_Combobox * etk_combobox_item_combobox_get (Etk_Combobox_Item *item)
 Gets the combobox containing the given item.


Define Documentation

#define ETK_COMBOBOX_TYPE   (etk_combobox_type_get())

Gets the type of a combobox

#define ETK_COMBOBOX ( obj   )     (ETK_OBJECT_CAST((obj), ETK_COMBOBOX_TYPE, Etk_Combobox))

Casts the object to an Etk_Combobox

#define ETK_IS_COMBOBOX ( obj   )     (ETK_OBJECT_CHECK_TYPE((obj), ETK_COMBOBOX_TYPE))

Check if the object is an Etk_Combobox

#define ETK_COMBOBOX_ITEM_TYPE   (etk_combobox_item_type_get())

Gets the type of a combobox item

#define ETK_COMBOBOX_ITEM ( obj   )     (ETK_OBJECT_CAST((obj), ETK_COMBOBOX_ITEM_TYPE, Etk_Combobox_Item))

Casts the object to an Etk_Combobox_Item

#define ETK_IS_COMBOBOX_ITEM ( obj   )     (ETK_OBJECT_CHECK_TYPE((obj), ETK_COMBOBOX_ITEM_TYPE))

Check if the object is an Etk_Combobox_Item


Enumeration Type Documentation

enum Etk_Combobox_Column_Type

The different types of widgets that can be contained by a combobox's column.

Enumerator:
ETK_COMBOBOX_LABEL  The column's widget is a label
ETK_COMBOBOX_IMAGE  The column's widget is an image
ETK_COMBOBOX_OTHER  The column's widget is any other type of widget

enum Etk_Combobox_Fill_Policy

Indicates how a widget of a combobox-column should fill and expand.


Function Documentation

Etk_Widget * etk_combobox_new ( void   ) 

Creates a new combobox, with no column.

Returns:
Returns the new combobox widget

Etk_Widget * etk_combobox_new_default ( void   ) 

Creates a new combobox, made up of a unique column containing a label, and already built (no need to call etk_combobox_build()).

Returns:
Returns the new combobox widget

void etk_combobox_items_height_set ( Etk_Combobox *  combobox,
int  items_height 
)

Set the height of the combobox's items. The default height is 24, the minimum is 12.

Parameters:
combobox a combobox
items_height the height that the combobox's items should have

int etk_combobox_items_height_get ( Etk_Combobox *  combobox  ) 

Gets the height of the combobox's items.

Parameters:
combobox a combobox
Returns:
Returns the height of the combobox's items

void etk_combobox_column_add ( Etk_Combobox *  combobox,
Etk_Combobox_Column_Type  col_type,
int  width,
Etk_Combobox_Fill_Policy  fill_policy,
float  align 
)

Adds a column to the combobox. The combobox should not be already be built.

Parameters:
combobox a combobox
col_type the type of widget that will be packed in the column
width the width of the column. If expand is ETK_TRUE, the column may be bigger if it expands
fill_policy the fill-policy of the widget of the column, it indicates how it should fill the column
align the horizontal alignment of the widget of the column, from 0.0 (left) to 1.0 (right)

void etk_combobox_build ( Etk_Combobox *  combobox  ) 

Builds the combobox: you have to build a combobox after you have added all the columns to it and before you start adding items. Items can not be added if the combobox is not built.

Parameters:
combobox the combobox to build

Etk_Combobox_Item * etk_combobox_item_prepend ( Etk_Combobox *  combobox,
  ... 
)

Inserts a new item at the start of the combobox.

Parameters:
combobox a combobox
... the different widgets to attach to the columns of the item: there must be as many arguments as the number of columns in the combobox, one for each column.
  • If the type of the corresponding column is ETK_COMBOBOX_LABEL, the argument must be a "const char *"
  • If the type of the corresponding column is ETK_COMBOBOX_IMAGE, the argument must be an "Etk_Image *"
  • If the type of the corresponding column is ETK_COMBOBOX_OTHER, the argument must be an "Etk_Widget *"
Returns:
Returns the new item
Note:
Unlike other widgets, the new item will be automatically shown, so you won't have to call etk_widget_show()

Etk_Combobox_Item * etk_combobox_item_append ( Etk_Combobox *  combobox,
  ... 
)

Inserts a new item at the end of the combobox.

Parameters:
combobox a combobox
... the different widgets to attach to the columns of the item: there must be as many arguments as the number of columns in the combobox, one for each column.
  • If the type of the corresponding column is ETK_COMBOBOX_LABEL, the argument must be a "const char *"
  • If the type of the corresponding column is ETK_COMBOBOX_IMAGE, the argument must be an "Etk_Image *"
  • If the type of the corresponding column is ETK_COMBOBOX_OTHER, the argument must be an "Etk_Widget *"
Returns:
Returns the new item
Note:
Unlike other widgets, the new item will be automatically shown, so you won't have to call etk_widget_show()

Etk_Combobox_Item * etk_combobox_item_insert ( Etk_Combobox *  combobox,
Etk_Combobox_Item *  after,
  ... 
)

Inserts a new item after an existing item of the combobox.

Parameters:
combobox a combobox
after the item after which the new item should be inserted. If after is NULL, the new item will be inserted at the start of the combobox
... the different widgets to attach to the columns of the item: there must be as many arguments as the number of columns in the combobox, one for each column.
  • If the type of the corresponding column is ETK_COMBOBOX_LABEL, the argument must be a "const char *"
  • If the type of the corresponding column is ETK_COMBOBOX_IMAGE, the argument must be an "Etk_Image *"
  • If the type of the corresponding column is ETK_COMBOBOX_OTHER, the argument must be an "Etk_Widget *"
Returns:
Returns the new item
Note:
Unlike other widgets, the new item will be automatically shown, so you won't have to call etk_widget_show()

Etk_Combobox_Item * etk_combobox_item_insert_valist ( Etk_Combobox *  combobox,
Etk_Combobox_Item *  after,
va_list  args 
)

Inserts a new item after an existing item of the combobox.

Parameters:
combobox a combobox
after the item after which the new item should be inserted. If after is NULL, the new item will be inserted at the start of the combobox
args the different widgets to attach to the columns of the item: there must be as many arguments as the number of columns in the combobox, one for each column.
  • If the type of the corresponding column is ETK_COMBOBOX_LABEL, the argument must be a "const char *"
  • If the type of the corresponding column is ETK_COMBOBOX_IMAGE, the argument must be an "Etk_Image *"
  • If the type of the corresponding column is ETK_COMBOBOX_OTHER, the argument must be an "Etk_Widget *"
Returns:
Returns the new item
Note:
Unlike other widgets, the new item and its children will be automatically shown, so you won't have to call etk_widget_show()

void etk_combobox_item_remove ( Etk_Combobox_Item *  item  ) 

Removes an item from the combobox. The item will be freed and should not be used anymore.

Parameters:
item the item to remove from its combobox
Note:
You can also call etk_object_destroy() to remove an item from a combobox, it has the same effect

void etk_combobox_clear ( Etk_Combobox *  combobox  ) 

Removes all the items of the combobox. All the items will be freed and should not be used anymore.

Parameters:
combobox a combobox

void etk_combobox_item_fields_set ( Etk_Combobox_Item *  item,
  ... 
)

Sets the values of the cells of the combobox item.

Parameters:
item a combobox item
... the different widgets to attach to the columns of the item: there must be as many arguments as the number of columns in the combobox, one for each column.
  • If the type of the corresponding column is ETK_COMBOBOX_LABEL, the argument must be a "const char *"
  • If the type of the corresponding column is ETK_COMBOBOX_IMAGE, the argument must be an "Etk_Image *"
  • If the type of the corresponding column is ETK_COMBOBOX_OTHER, the argument must be an "Etk_Widget *"
Note:
The new widgets of the item will be automatically shown

void etk_combobox_item_fields_set_valist ( Etk_Combobox_Item *  item,
va_list  args 
)

Sets the values of the cells of the combobox item. The current widgets of item will be destroyed.

Parameters:
item a combobox item
args the different widgets to attach to the columns of the item: there must be as many arguments as the number of columns in the combobox, one for each column.
  • If the type of the corresponding column is ETK_COMBOBOX_LABEL, the argument must be a "const char *"
  • If the type of the corresponding column is ETK_COMBOBOX_IMAGE, the argument must be an "Etk_Image *"
  • If the type of the corresponding column is ETK_COMBOBOX_OTHER, the argument must be an "Etk_Widget *"
Note:
The new widgets of the item will be automatically shown

void etk_combobox_item_fields_get ( Etk_Combobox_Item *  item,
  ... 
)

Gets the values of the cells of the combobox item.

Parameters:
item a combobox item
... the location where to store the different values of the cells of the item: there must be as many arguments as the number of columns in the combobox, one for each column.
  • If the type of the corresponding column is ETK_COMBOBOX_LABEL, the argument must be a "const char **"
  • If the type of the corresponding column is ETK_COMBOBOX_IMAGE, the argument must be an "Etk_Image **"
  • If the type of the corresponding column is ETK_COMBOBOX_OTHER, the argument must be an "Etk_Widget **"

void etk_combobox_item_fields_get_valist ( Etk_Combobox_Item *  item,
va_list  args 
)

Gets the values of the cells of the combobox item.

Parameters:
item a combobox item
args the location where to store the different values of the cells of the item: there must be as many arguments as the number of columns in the combobox, one for each column.
  • If the type of the corresponding column is ETK_COMBOBOX_LABEL, the argument must be a "const char **"
  • If the type of the corresponding column is ETK_COMBOBOX_IMAGE, the argument must be an "Etk_Image **"
  • If the type of the corresponding column is ETK_COMBOBOX_OTHER, the argument must be an "Etk_Widget **"

void etk_combobox_item_data_set ( Etk_Combobox_Item *  item,
void *  data 
)

Sets the data associated to the combobox item.

Parameters:
item a combobox item
data the data to associate to the combobox item

void etk_combobox_item_data_set_full ( Etk_Combobox_Item *  item,
void *  data,
void(*)(void *data)  free_cb 
)

Sets the data associated to the combobox item.

Parameters:
item a combobox item
data the data to associate to the combobox item
free_cb a function to call to free the data when the item is destroyed or when the data is changed

void * etk_combobox_item_data_get ( Etk_Combobox_Item *  item  ) 

Gets the data associated to the combobox item.

Parameters:
item a combobox item
Returns:
Returns the data associated to the combobox item

void etk_combobox_active_item_set ( Etk_Combobox *  combobox,
Etk_Combobox_Item *  item 
)

Sets the active item of the combobox.

Parameters:
combobox a combobox
item the item to set as active

Etk_Combobox_Item * etk_combobox_active_item_get ( Etk_Combobox *  combobox  ) 

Gets the active item of the combobox.

Parameters:
combobox a combobox
Returns:
Returns the active item of combobox (NULL if none)

int etk_combobox_active_item_num_get ( Etk_Combobox *  combobox  ) 

Gets the index of the current active item of the combobox.

Parameters:
combobox a combobox
Returns:
Returns the index of the current active item, or -1 if there is no active item

Etk_Combobox_Item * etk_combobox_first_item_get ( Etk_Combobox *  combobox  ) 

Gets the first item of a combobox.

Parameters:
combobox a combobox
Returns:
Returns the first item of a combobox

Etk_Combobox_Item * etk_combobox_last_item_get ( Etk_Combobox *  combobox  ) 

Gets the last item of a combobox.

Parameters:
combobox a combobox
Returns:
Returns the last item of a combobox

Etk_Combobox_Item * etk_combobox_item_prev_get ( Etk_Combobox_Item *  item  ) 

Gets the item previous to the given combobox item.

Parameters:
item a combobox item
Returns:
Returns the item previous to item, or NULL if the given item is the first one

Etk_Combobox_Item * etk_combobox_item_next_get ( Etk_Combobox_Item *  item  ) 

Gets the item next to the given combobox item.

Parameters:
item a combobox item
Returns:
Returns the item next to item, or NULL if the given item is the last one

Etk_Combobox_Item * etk_combobox_nth_item_get ( Etk_Combobox *  combobox,
int  index 
)

Gets the nth item of the combobox.

Parameters:
combobox a combobox
index the index of the item to get, starting from 0. If index is < 0 or if index is greater than the current number of items of the combobox, the function will return NULL
Returns:
Returns the nth item of the combobox, or NULL on failure

Etk_Combobox * etk_combobox_item_combobox_get ( Etk_Combobox_Item *  item  ) 

Gets the combobox containing the given item.

Parameters:
item a combobox item
Returns:
Returns the combobox containing the given item