Q3IconView Class Reference
[Qt3Support module]

Detailed Description

The Q3IconView class provides an area with movable labelled icons.

A Q3IconView can display and manage a grid or other 2D layout of labelled icons. Each labelled icon is a Q3IconViewItem. Items (Q3IconViewItems) can be added or deleted at any time; items can be moved within the Q3IconView. Single or multiple items can be selected. Items can be renamed in-place. Q3IconView also supports drag and drop.

Each item contains a label string, a pixmap or picture (the icon itself) and optionally a sort key. The sort key is used for sorting the items and defaults to the label string. The label string can be displayed below or to the right of the icon (see ItemTextPos).

The simplest way to create a Q3IconView is to create a Q3IconView object and create some Q3IconViewItems with the Q3IconView as their parent, set the icon view's geometry and show it. For example:

 Q3IconView *iv = new Q3IconView(this);
 QDir dir(path, "*.xpm");
 for (uint i = 0; i < dir.count(); i++) {
     (void) new Q3IconViewItem(iv, dir[i], QPixmap(path + dir[i]));
 }
 iv->resize(600, 400);
 iv->show();

The Q3IconViewItem call passes a pointer to the Q3IconView we wish to populate, along with the label text and a QPixmap.

When an item is inserted the Q3IconView allocates a position for it. Existing items are rearranged if autoArrange() is true. The default arrangement is LeftToRight -- the Q3IconView fills up the left-most column from top to bottom, then moves one column right and fills that from top to bottom and so on. The arrangement can be modified with any of the following approaches:

• Call setArrangement(), e.g. with TopToBottom which will fill the top-most row from left to right, then moves one row down and fills that row from left to right and so on.
• Construct each Q3IconViewItem using a constructor which allows you to specify which item the new one is to follow.
• Call setSorting() or sort() to sort the items.

The spacing between items is set with setSpacing(). Items can be laid out using a fixed grid using setGridX() and setGridY(); by default the Q3IconView calculates a grid dynamically. The position of items' label text is set with setItemTextPos(). The text's background can be set with setItemTextBackground(). The maximum width of an item and of its text are set with setMaxItemWidth() and setMaxItemTextLength(). The label text will be word-wrapped if it is too long; this is controlled by setWordWrapIconText(). If the label text is truncated, the user can still see the entire text in a tool tip if they hover the mouse over the item. This is controlled with setShowToolTips().

Items which are selectable may be selected depending on the SelectionMode; the default is Single. Because Q3IconView offers multiple selection it must display keyboard focus and selection state separately. Therefore there are functions to set the selection state of an item (setSelected()) and to select which item displays keyboard focus (setCurrentItem()). When multiple items may be selected the icon view provides a rubberband, too.

When in-place renaming is enabled (it is disabled by default), the user may change the item's label. They do this by selecting the item (single clicking it or navigating to it with the arrow keys), then single clicking it (or pressing F2), and entering their text. If no key has been set with Q3IconViewItem::setKey() the new text will also serve as the key. (See Q3IconViewItem::setRenameEnabled().)

You can control whether users can move items themselves with setItemsMovable().

Because the internal structure used to store the icon view items is linear, no iterator class is needed to iterate over all the items. Instead we iterate by getting the first item from the icon view and then each subsequent (Q3IconViewItem::nextItem()) from each item in turn:

 for (Q3IconViewItem *item = iv->firstItem(); item; item = item->nextItem())
     do_something(item);

Q3IconView also provides currentItem(). You can search for an item using findItem() (searching by position or for label text) and with findFirstVisibleItem() and findLastVisibleItem(). The number of items is returned by count(). An item can be removed from an icon view using takeItem(); to delete an item use delete. All the items can be deleted with clear().

The Q3IconView emits a wide range of useful signals, including selectionChanged(), currentChanged(), clicked(), moved() and itemRenamed().

 Q3DragObject *MyIconView::dragObject()
 {
     return new Q3TextDrag(currentItem()->text(), this);
 }

 bool MyIconViewItem::acceptDrop(const QMimeSource *mime) const
 {
     if (mime->provides("text/plain"))
         return true;
     return false;
 }

 void MyIconViewItem::dropped(QDropEvent *evt, const Q3ValueList<Q3IconDragItem>&)
 {
     QString label;
     if (Q3TextDrag::decode(evt, label))
         setText(label);
 }

 (void) new Q3IconViewItem(myIconview, "The text of the item", aPixmap);