ExoIconView

## ExoIconView ExoIconView — A widget which displays a list of icons in a grid |

## Synopsis

    #include <exo/exo.h>

                ExoIconView;
    GtkWidget*  exo_icon_view_new               (void);
    GtkWidget*  exo_icon_view_new_with_model    (GtkTreeModel *model);
    GtkTreeModel* exo_icon_view_get_model       (const ExoIconView *icon_view);
    void        exo_icon_view_set_model         (ExoIconView *icon_view,
                                                 GtkTreeModel *model);
    gint        exo_icon_view_get_text_column   (const ExoIconView *icon_view);
    void        exo_icon_view_set_text_column   (ExoIconView *icon_view,
                                                 gint column);
    gint        exo_icon_view_get_markup_column (const ExoIconView *icon_view);
    void        exo_icon_view_set_markup_column (ExoIconView *icon_view,
                                                 gint column);
    gint        exo_icon_view_get_pixbuf_column (const ExoIconView *icon_view);
    void        exo_icon_view_set_pixbuf_column (ExoIconView *icon_view,
                                                 gint column);
    GtkOrientation exo_icon_view_get_orientation
                                                (const ExoIconView *icon_view);
    void        exo_icon_view_set_orientation   (ExoIconView *icon_view,
                                                 GtkOrientation orientation);
    GtkSelectionMode exo_icon_view_get_selection_mode
                                                (const ExoIconView *icon_view);
    void        exo_icon_view_set_selection_mode
                                                (ExoIconView *icon_view,
                                                 GtkSelectionMode mode);
    GtkTreePath* exo_icon_view_get_path_at_pos  (const ExoIconView *icon_view,
                                                 gint x,
                                                 gint y);
    void        (*ExoIconViewForeachFunc)       (ExoIconView *icon_view,
                                                 GtkTreePath *path,
                                                 gpointer user_data);
    void        exo_icon_view_selected_foreach  (ExoIconView *icon_view,
                                                 ExoIconViewForeachFunc func,
                                                 gpointer data);
    void        exo_icon_view_select_path       (ExoIconView *icon_view,
                                                 GtkTreePath *path);
    void        exo_icon_view_unselect_path     (ExoIconView *icon_view,
                                                 GtkTreePath *path);
    gboolean    exo_icon_view_path_is_selected  (const ExoIconView *icon_view,
                                                 GtkTreePath *path);
    GList*      exo_icon_view_get_selected_items
                                                (const ExoIconView *icon_view);
    void        exo_icon_view_select_all        (ExoIconView *icon_view);
    void        exo_icon_view_unselect_all      (ExoIconView *icon_view);
    void        exo_icon_view_item_activated    (ExoIconView *icon_view,
                                                 GtkTreePath *path);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----ExoIconView

## Implemented Interfaces

ExoIconView implements AtkImplementorIface and GtkCellLayout.

## Properties

      "column-spacing"       gint                  : Read / Write
      "columns"              gint                  : Read / Write
      "item-width"           gint                  : Read / Write
      "margin"               gint                  : Read / Write
      "markup-column"        gint                  : Read / Write
      "model"                GtkTreeModel          : Read / Write
      "orientation"          GtkOrientation        : Read / Write
      "pixbuf-column"        gint                  : Read / Write
      "reorderable"          gboolean              : Read / Write
      "row-spacing"          gint                  : Read / Write
      "selection-mode"       GtkSelectionMode      : Read / Write
      "spacing"              gint                  : Read / Write
      "text-column"          gint                  : Read / Write

## Style Properties

      "selection-box-alpha"  guchar                : Read
      "selection-box-color"  GdkColor              : Read

## Signal Prototypes

    "activate-cursor-item"
                gboolean    user_function      (ExoIconView *icon_view,
                                                gpointer user_data);
    "item-activated"
                void        user_function      (ExoIconView *icon_view,
                                                GtkTreePath *path,
                                                gpointer user_data);
    "move-cursor"
                gboolean    user_function      (ExoIconView *icon_view,
                                                GtkMovementStep step,
                                                gint count,
                                                gpointer user_data);
    "select-all"
                void        user_function      (ExoIconView *icon_view,
                                                gpointer user_data);
    "select-cursor-item"
                void        user_function      (ExoIconView *icon_view,
                                                gpointer user_data);
    "selection-changed"
                void        user_function      (ExoIconView *icon_view,
                                                gpointer user_data);
    "set-scroll-adjustments"
                void        user_function      (ExoIconView *icon_view,
                                                GtkAdjustment *hadjustment,
                                                GtkAdjustment *vadjustment,
                                                gpointer user_data);
    "toggle-cursor-item"
                void        user_function      (ExoIconView *icon_view,
                                                gpointer user_data);
    "unselect-all"
                void        user_function      (ExoIconView *icon_view,
                                                gpointer user_data);

## Description

ExoIconView provides an alternative view on a list model. It displays the model as a grid of icons with labels. Like GtkTreeView, it allows to select one or multiple items (depending on the selection mode, see `exo_icon_view_set_selection_mode()`). In addition to selection with the arrow keys, ExoIconView supports rubberband selection, which is controlled by dragging the pointer.

## Details

### ExoIconView

    typedef struct _ExoIconView ExoIconView;

The ExoIconView struct contains only private fields and should not be directly accessed.

### exo_icon_view_new ()

    GtkWidget*  exo_icon_view_new               (void);

Creates a new ExoIconView widget

Returns : | A newly created ExoIconView widget

### exo_icon_view_new_with_model ()

    GtkWidget*  exo_icon_view_new_with_model    (GtkTreeModel *model);

Creates a new ExoIconView widget with the model `model`.

`model` : | The model.
Returns : | A newly created ExoIconView widget.

### exo_icon_view_get_model ()

    GtkTreeModel* exo_icon_view_get_model       (const ExoIconView *icon_view);

Returns the model the ExoIconView is based on. Returns `NULL` if the model is unset.

`icon_view` : | a ExoIconView
Returns : | A GtkTreeModel, or `NULL` if none is currently being used.

### exo_icon_view_set_model ()

    void        exo_icon_view_set_model         (ExoIconView *icon_view,
                                                 GtkTreeModel *model);

Sets the model for a ExoIconView. If the `icon_view` already has a model set, it will remove it before setting the new model. If `model` is `NULL`, then it will unset the old model.

`icon_view` : | A ExoIconView.
`model` : | The model.

### exo_icon_view_get_text_column ()

    gint        exo_icon_view_get_text_column   (const ExoIconView *icon_view);

Returns the column with text for `icon_view`.

`icon_view` : | A ExoIconView.
Returns : | the text column, or -1 if it's unset.

### exo_icon_view_set_text_column ()

    void        exo_icon_view_set_text_column   (ExoIconView *icon_view,
                                                 gint column);

Sets the column with text for `icon_view` to be `column`. The text column must be of type G_TYPE_STRING.

`icon_view` : | A ExoIconView.
`column` : | A column in the currently used model.

### exo_icon_view_get_markup_column ()

    gint        exo_icon_view_get_markup_column (const ExoIconView *icon_view);

Returns the column with markup text for `icon_view`.

`icon_view` : | A ExoIconView.
Returns : | the markup column, or -1 if it's unset.

### exo_icon_view_set_markup_column ()

    void        exo_icon_view_set_markup_column (ExoIconView *icon_view,
                                                 gint column);

Sets the column with markup information for `icon_view` to be `column`. The markup column must be of type G_TYPE_STRING. If the markup column is set to something, it overrides the text column set by `exo_icon_view_set_text_column()`.

`icon_view` : | A ExoIconView.
`column` : | A column in the currently used model.

### exo_icon_view_get_pixbuf_column ()

    gint        exo_icon_view_get_pixbuf_column (const ExoIconView *icon_view);

Returns the column with pixbufs for `icon_view`.

`icon_view` : | A ExoIconView.
Returns : | the pixbuf column, or -1 if it's unset.

### exo_icon_view_set_pixbuf_column ()

    void        exo_icon_view_set_pixbuf_column (ExoIconView *icon_view,
                                                 gint column);

Sets the column with pixbufs for `icon_view` to be `column`. The pixbuf column must be of type GDK_TYPE_PIXBUF

`icon_view` : | A ExoIconView.
`column` : | A column in the currently used model.

### exo_icon_view_get_orientation ()

    GtkOrientation exo_icon_view_get_orientation
                                                (const ExoIconView *icon_view);

Returns the value of the ::orientation property which determines whether the labels are drawn beside the icons instead of below.

`icon_view` : | a ExoIconView
Returns : | the relative position of texts and icons

Since 0.3.1

### exo_icon_view_set_orientation ()

    void        exo_icon_view_set_orientation   (ExoIconView *icon_view,
                                                 GtkOrientation orientation);

Sets the ::orientation property which determines whether the labels are drawn beside the icons instead of below.

`icon_view` : | a ExoIconView
`orientation` : | the relative position of texts and icons

Since 0.3.1

### exo_icon_view_get_selection_mode ()

    GtkSelectionMode exo_icon_view_get_selection_mode
                                                (const ExoIconView *icon_view);

Gets the selection mode of the `icon_view`.

`icon_view` : | A ExoIconView.
Returns : | the current selection mode

### exo_icon_view_set_selection_mode ()

    void        exo_icon_view_set_selection_mode
                                                (ExoIconView *icon_view,
                                                 GtkSelectionMode mode);

Sets the selection mode of the `icon_view`.

`icon_view` : | A ExoIconView.
`mode` : | The selection mode

### exo_icon_view_get_path_at_pos ()

    GtkTreePath* exo_icon_view_get_path_at_pos  (const ExoIconView *icon_view,
                                                 gint x,
                                                 gint y);

Finds the path at the point (`x`, `y`), relative to widget coordinates. See `exo_icon_view_get_item_at_pos()`, if you are also interested in the cell at the specified position.

`icon_view` : | A ExoIconView.
`x` : | The x position to be identified
`y` : | The y position to be identified
Returns : | The GtkTreePath corresponding to the icon or `NULL` if no icon exists at that position.

### ExoIconViewForeachFunc ()

    void        (*ExoIconViewForeachFunc)       (ExoIconView *icon_view,
                                                 GtkTreePath *path,
                                                 gpointer user_data);

`icon_view` : |
`path` : |
`user_data` : |

### exo_icon_view_selected_foreach ()

    void        exo_icon_view_selected_foreach  (ExoIconView *icon_view,
                                                 ExoIconViewForeachFunc func,
                                                 gpointer data);

Calls a function for each selected icon. Note that the model or selection cannot be modified from within this function.

`icon_view` : | A ExoIconView.
`func` : | The funcion to call for each selected icon.
`data` : | User data to pass to the function.

### exo_icon_view_select_path ()

    void        exo_icon_view_select_path       (ExoIconView *icon_view,
                                                 GtkTreePath *path);

Selects the row at `path`.

`icon_view` : | A ExoIconView.
`path` : | The GtkTreePath to be selected.

### exo_icon_view_unselect_path ()

    void        exo_icon_view_unselect_path     (ExoIconView *icon_view,
                                                 GtkTreePath *path);

Unselects the row at `path`.

`icon_view` : | A ExoIconView.
`path` : | The GtkTreePath to be unselected.

### exo_icon_view_path_is_selected ()

    gboolean    exo_icon_view_path_is_selected  (const ExoIconView *icon_view,
                                                 GtkTreePath *path);

Returns `TRUE` if the icon pointed to by `path` is currently selected. If `icon` does not point to a valid location, `FALSE` is returned.

`icon_view` : | A ExoIconView.
`path` : | A GtkTreePath to check selection on.
Returns : | `TRUE` if `path` is selected.

### exo_icon_view_get_selected_items ()

    GList*      exo_icon_view_get_selected_items
                                                (const ExoIconView *icon_view);

Creates a list of paths of all selected items. Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of GtkTreeRowReferences. To do this, you can use `gtk_tree_row_reference_new()`.

To free the return value, use:

    g_list_foreach (list, gtk_tree_path_free, NULL);
    g_list_free (list);

`icon_view` : | A ExoIconView.
Returns : | A GList containing a GtkTreePath for each selected row.

### exo_icon_view_select_all ()

    void        exo_icon_view_select_all        (ExoIconView *icon_view);

Selects all the icons. `icon_view` must has its selection mode set to GTK_SELECTION_MULTIPLE.

`icon_view` : | A ExoIconView.

### exo_icon_view_unselect_all ()

    void        exo_icon_view_unselect_all      (ExoIconView *icon_view);

Unselects all the icons.

`icon_view` : | A ExoIconView.

### exo_icon_view_item_activated ()

    void        exo_icon_view_item_activated    (ExoIconView *icon_view,
                                                 GtkTreePath *path);

Activates the item determined by `path`.

`icon_view` : | a ExoIconView
`path` : | the GtkTreePath to be activated

## Properties

### The "`column-spacing`" property

      "column-spacing"       gint                  : Read / Write

Space which is inserted between grid column.

Allowed values: >= 0

Default value: 6

### The "`columns`" property

      "columns"              gint                  : Read / Write

Number of columns to display.

Allowed values: >= -1

Default value: -1

### The "`item-width`" property

      "item-width"           gint                  : Read / Write

The width used for each item.

Allowed values: >= -1

Default value: -1

### The "`margin`" property

      "margin"               gint                  : Read / Write

Space which is inserted at the edges of the icon view.

Allowed values: >= 0

Default value: 6

### The "`markup-column`" property

      "markup-column"        gint                  : Read / Write

Model column used to retrieve the text if using Pango markup.

Allowed values: >= -1

Default value: -1

### The "`model`" property

      "model"                GtkTreeModel          : Read / Write

The model for the icon view.

### The "`orientation`" property

      "orientation"          GtkOrientation        : Read / Write

How the text and icon of each item are positioned relative to each other.

Default value: GTK_ORIENTATION_VERTICAL

### The "`pixbuf-column`" property

      "pixbuf-column"        gint                  : Read / Write

Model column used to retrieve the icon pixbuf from.

Allowed values: >= -1

Default value: -1

### The "`reorderable`" property

      "reorderable"          gboolean              : Read / Write

View is reorderable.

Default value: FALSE

### The "`row-spacing`" property

      "row-spacing"          gint                  : Read / Write

Space which is inserted between grid rows.

Allowed values: >= 0

Default value: 6

### The "`selection-mode`" property

      "selection-mode"       GtkSelectionMode      : Read / Write

The selection mode.

Default value: GTK_SELECTION_SINGLE

### The "`spacing`" property

      "spacing"              gint                  : Read / Write

Space which is inserted between cells of an item.

Allowed values: >= 0

Default value: 0

### The "`text-column`" property

      "text-column"          gint                  : Read / Write

Model column used to retrieve the text from.

Allowed values: >= -1

Default value: -1

## Style Properties

### The "`selection-box-alpha`" style property

      "selection-box-alpha"  guchar                : Read

Opacity of the selection box.

Default value: 64

### The "`selection-box-color`" style property

      "selection-box-color"  GdkColor              : Read

Color of the selection box.

## Signals

### The "activate-cursor-item" signal

    gboolean    user_function                  (ExoIconView *icon_view,
                                                gpointer user_data);

`icon_view` : | a ExoIconView.
`user_data` : | user data set when the signal handler was connected.
Returns : |

### The "item-activated" signal

    void        user_function                  (ExoIconView *icon_view,
                                                GtkTreePath *path,
                                                gpointer user_data);

`icon_view` : | a ExoIconView.
`path` : |
`user_data` : | user data set when the signal handler was connected.

### The "move-cursor" signal

    gboolean    user_function                  (ExoIconView *icon_view,
                                                GtkMovementStep step,
                                                gint count,
                                                gpointer user_data);

`icon_view` : | a ExoIconView.
`step` : |
`count` : |
`user_data` : | user data set when the signal handler was connected.
Returns : |

### The "select-all" signal

    void        user_function                  (ExoIconView *icon_view,
                                                gpointer user_data);

`icon_view` : | a ExoIconView.
`user_data` : | user data set when the signal handler was connected.

### The "select-cursor-item" signal

    void        user_function                  (ExoIconView *icon_view,
                                                gpointer user_data);

`icon_view` : | a ExoIconView.
`user_data` : | user data set when the signal handler was connected.

### The "selection-changed" signal

    void        user_function                  (ExoIconView *icon_view,
                                                gpointer user_data);

`icon_view` : | a ExoIconView.
`user_data` : | user data set when the signal handler was connected.

### The "set-scroll-adjustments" signal

    void        user_function                  (ExoIconView *icon_view,
                                                GtkAdjustment *hadjustment,
                                                GtkAdjustment *vadjustment,
                                                gpointer user_data);

`icon_view` : | a ExoIconView.
`hadjustment` : |
`vadjustment` : |
`user_data` : | user data set when the signal handler was connected.

### The "toggle-cursor-item" signal

    void        user_function                  (ExoIconView *icon_view,
                                                gpointer user_data);

`icon_view` : | a ExoIconView.
`user_data` : | user data set when the signal handler was connected.

### The "unselect-all" signal

    void        user_function                  (ExoIconView *icon_view,
                                                gpointer user_data);

`icon_view` : | a ExoIconView.
`user_data` : | user data set when the signal handler was connected.