org.gnome.gtk

## Class IconView

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.Widget
        - - org.gnome.gtk.Container
          - - org.gnome.gtk.IconView

- All Implemented Interfaces:
    CellLayout

      public class IconView
      extends Container
      implements CellLayout

  A Widget that displays the data of a `TreeModel` as a grid of icons with labels. It is thus an alternative to TreeView, and like it, IconView is the view part of GTK's model-view-controller pattern list, and thus it needs a TreeModel where the data to be displayed is actually stored.

  It is however, much simpler and less powerful than TreeView. First of all, you cannot display a hierarchical model (such as `TreeStore`) in an IconView. Only list models, such as `ListStore` can be used.

  In an IconView the rows of the underlying TreeModel are represented as items with an icon and a text label. The icon is taken from a `DataColumnPixbuf` column of the model, and the label is taken from a `DataColumnString`. As you may guess, only those two columns of the model can be displayed in an IconView.

  On the other side, configuring an IconView is easier than a TreeView. First of all, you should configure the model:

       final ListStore model;
       final DataColumnString labelColumn;
       final DataColumnPixbuf iconColumn;
       final IconView view;

       ...
       model = new ListStore(new DataColumn[] {
           labelColumn,
           ...
       }

  Of course, you don't need to populate the model before configuring the IconView. That configuration is easy, as you only need to set the data columns from which the icon and label will be taken.

       view = new IconView(model);
       view.setPixbufColumn(iconColumn);

       // you can use setMarkupColumn() as an alternative
       view.setTextColumn(labelColumn);

  Once the IconView is configured, you may want to hook up a handler for the `IconView.ItemActivated` signal, emitted when the user activates an item (for example, by double-clicking over it).

  Finally, an IconView has methods to handle the selection, so you don't need to use the TreeSelection object.

  Since:
    4.0.7
  Author:
    Vreixo Formoso, Andrew Cowie, Guillaume Mazoyer

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `IconView.ItemActivated` Emitted when an item in the IconView has been activated.
    `static interface` | `IconView.SelectionChanged` Signal emitted when the selection changes, i.e. when a new item is selected or a previously selected item was unselected.

    - ### Nested classes/interfaces inherited from class org.gnome.gtk.Widget

      `Widget.ButtonPressEvent, Widget.ButtonReleaseEvent, Widget.Destroy, Widget.Draw, Widget.EnterNotifyEvent, Widget.FocusInEvent, Widget.FocusOutEvent, Widget.Hide, Widget.KeyPressEvent, Widget.KeyReleaseEvent, Widget.LeaveNotifyEvent, Widget.MapEvent, Widget.MotionNotifyEvent, Widget.PopupMenu, Widget.QueryTooltip, Widget.ScrollEvent, Widget.SizeAllocate, Widget.UnmapEvent, Widget.VisibilityNotifyEvent`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `IconView()` Construct an IconView whose backing model will be assigned later.
    `IconView(TreeModel model)` Create a new IconView Remember you cannot use a TreeStore model with an IconView.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connect(IconView.ItemActivated handler)` Hook up a `IconView.ItemActivated` handler.
    `void` | `connect(IconView.SelectionChanged handler)` Hook up a handler for the `IconView.SelectionChanged` signal.
    `TreePath[]` | `getSelectedItems()` Get the items currently selected.
    `boolean` | `isSelected(TreePath path)` Return `true` if the currently selected icon is pointed by `path`.
    `void` | `selectAll()` Select all the icons, in order to work, you must have set the `SelectionMode` to `MULTIPLE`.
    `void` | `selectPath(TreePath path)` Select the row at `path`.
    `void` | `setColumns(int num)` The number of columns in which icons should be displayed.
    `void` | `setItemWidth(int width)` Set the maximum width that will be given to each column of icons.
    `void` | `setMarkupColumn(DataColumnString column)` Set the DataColumn, containing Pango markup, to render as the label of each item.
    `void` | `setModel(TreeModel model)` Set or change the TreeModel from which this IconView draws its data.
    `void` | `setPixbufColumn(DataColumnPixbuf column)` Set the DataColumn of the model that contains the Pixbuf to use as the icon of each item.
    `void` | `setSelectionMode(SelectionMode mode)` Set what kinds of selections are allowed.
    `void` | `setTextColumn(DataColumnString column)` Set the DataColumn in the TreeModel containing the plain text to use as label of each item.
    `void` | `unselectAll()` Unselect all the icons.
    `void` | `unselectPath(TreePath path)` Unselect the row at `path`.

    - ### Methods inherited from class org.gnome.gtk.Container

      `add, getChildren, remove, setBorderWidth`

    - ### Methods inherited from class org.gnome.gtk.Widget

      `activate, addEvents, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, destroy, getAllocatedHeight, getAllocatedWidth, getAllocation, getCanDefault, getCanFocus, getHasFocus, getName, getParent, getPreferredHeightForWidthMinimum, getPreferredHeightForWidthNatural, getPreferredHeightMinimum, getPreferredHeightNatural, getPreferredWidthForHeightMinimum, getPreferredWidthForHeightNatural, getPreferredWidthMinimum, getPreferredWidthNatural, getRequestMode, getRequisition, getSensitive, getStyleContext, getToplevel, getWindow, grabAdd, grabDefault, grabFocus, grabRemove, hide, isSensitive, overrideBackground, overrideColor, overrideFont, queueDraw, queueDrawArea, realize, setAlignHorizontal, setAlignVertical, setCanDefault, setCanFocus, setEvents, setExpandHorizontal, setExpandVertical, setName, setSensitive, setSizeRequest, setTooltipMarkup, setTooltipText, show, showAll`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### IconView

          public IconView()

      Construct an IconView whose backing model will be assigned later. You'll need to use `setModel()` to set it.
      Since:
        4.0.8

    - #### IconView

          public IconView(TreeModel model)

      Create a new IconView

      Remember you cannot use a TreeStore model with an IconView.

      Since:
        4.0.7

  - ### Method Detail

    - #### connect

          public void connect(IconView.ItemActivated handler)

      Hook up a `IconView.ItemActivated` handler.
      Since:
        4.0.7

    - #### connect

          public void connect(IconView.SelectionChanged handler)

      Hook up a handler for the `IconView.SelectionChanged` signal.
      Since:
        4.0.7

    - #### getSelectedItems

          public TreePath[] getSelectedItems()

      Get the items currently selected.

      You can use the TreeModel's `getIter()` method to convert the returned TreePaths to the more convenient TreeIter:

           IconView view;
           TreeModel model;

           for (TreePath path : view.getSelectedItems()) {
               TreeIter item = model.getIter(path);
               // do something with the item
           }

      Also remember that both TreeIter and TreePath are temporally objects no longer valid once you make any change to the model. Thus, if you plan to modify the model, you may want to convert the returned TreePaths to `TreeRowReferences`.

      Returns:
        An arrays with the selected items. If no item is selected, an empty array is returned.
      Since:
        4.0.7

    - #### isSelected

          public boolean isSelected(TreePath path)

      Return `true` if the currently selected icon is pointed by `path`.
      Since:
        4.0.15

    - #### selectAll

          public void selectAll()

      Select all the icons, in order to work, you must have set the `SelectionMode` to `MULTIPLE`.
      Since:
        4.0.15

    - #### selectPath

          public void selectPath(TreePath path)

      Select the row at `path`.
      Since:
        4.0.15

    - #### setColumns

          public void setColumns(int num)

      The number of columns in which icons should be displayed. The default is `-1` which indicates that the IconView will determine this automatically based on the size allocated to it.
      Since:
        4.0.8

    - #### setItemWidth

          public void setItemWidth(int width)

      Set the maximum width that will be given to each column of icons. The width is measured in pixels. The default value is `-1` which indicates
      Since:
        4.0.8

    - #### setMarkupColumn

          public void setMarkupColumn(DataColumnString column)

      Set the DataColumn, containing Pango markup, to render as the label of each item.
      Since:
        4.0.7

    - #### setModel

          public void setModel(TreeModel model)

      Set or change the TreeModel from which this IconView draws its data.
      Since:
        4.0.7

    - #### setPixbufColumn

          public void setPixbufColumn(DataColumnPixbuf column)

      Set the DataColumn of the model that contains the Pixbuf to use as the icon of each item.
      Since:
        4.0.7

    - #### setSelectionMode

          public void setSelectionMode(SelectionMode mode)

      Set what kinds of selections are allowed. The interesting constants you'll use most often are `NONE` and `MULTIPLE` since `SINGLE` is the default. See SelectionMode for the details of the behaviour implied by each option.
      Since:
        4.0.7

    - #### setTextColumn

          public void setTextColumn(DataColumnString column)

      Set the DataColumn in the TreeModel containing the plain text to use as label of each item. Usually you will use this method to choose the model column to map to the label. Alternatively you can use `setMarkupColumn()` to provide a text with Pango markup.
      Since:
        4.0.7

    - #### unselectAll

          public void unselectAll()

      Unselect all the icons.
      Since:
        4.0.15

    - #### unselectPath

          public void unselectPath(TreePath path)

      Unselect the row at `path`.
      Since:
        4.0.15