QIconView

NAME

SYNOPSIS

Inherits QScrollView.

Public Members

Public Slots

Signals

Properties

Protected Members

Protected Slots

DESCRIPTION

A QIconView can display and manage a grid or other 2D layout of labelled icons. Each labelled icon is a QIconViewItem. Items (QIconViewItems) can be added or deleted at any time; items can be moved within the QIconView. Single or multiple items can be selected. Items can be renamed in-place. QIconView 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 QIconView is to create a QIconView object and create some QIconViewItems with the QIconView as their parent, set the icon view's geometry and show it. For example:

    QIconView *iv = new QIconView( this );


    QDir dir( path, "*.xpm" );


    for ( uint i = 0; i < dir.count(); i++ ) {


        (void) new QIconViewItem( iv, dir[i], QPixmap( path + dir[i] ) );


    }


    iv->resize( 600, 400 );


    iv->show();

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

When an item is inserted the QIconView allocates a position for it. Existing items are rearranged if autoArrange() is TRUE. The default arrangement is LeftToRight -- the QIconView 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 QIconViewItem 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 QIconView 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 QIconView 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 QIconViewItem::setKey() the new text will also serve as the key. (See QIconViewItem::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 (QIconViewItem::nextItem()) from each item in turn:

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


            do_something( item );

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

Drag and Drop

The simple approach to dragging items out of the icon view is to subclass QIconView and reimplement QIconView::dragObject().

    QDragObject *MyIconView::dragObject()


    {


        return new QTextDrag( currentItem()->text(), this );


    }

In this example we create a QTextDrag object, (derived from QDragObject), containing the item's label and return it as the drag object. We could just as easily have created a QImageDrag from the item's pixmap and returned that instead.

QIconViews and their QIconViewItems can also be the targets of drag and drops. To make the QIconView itself able to accept drops connect to the dropped() signal. When a drop occurs this signal will be emitted with a QDragEvent and a QValueList of QIconDragItems. To make a QIconViewItem into a drop target subclass QIconViewItem and reimplement QIconViewItem::acceptDrop() and QIconViewItem::dropped().

    bool MyIconViewItem::acceptDrop( const QMimeSource *mime ) const


    {


        if ( mime->provides( "text/plain" ) )


            return TRUE;


        return FALSE;


    }




    void MyIconViewItem::dropped( QDropEvent *evt, const QValueList<QIconDragItem>& )


    {


        QString label;


        if ( QTextDrag::decode( evt, label ) )


            setText( label );


    }

See iconview/simple_dd/main.h and iconview/simple_dd/main.cpp for a simple drag and drop example which demonstrates drag and drop between a QIconView and a QListBox.

If you want to use extended drag-and-drop or have drag shapes drawn you must take a more sophisticated approach.

The first part is starting drags -- you should use a QIconDrag (or a class derived from it) for the drag object. In dragObject() create the drag object, populate it with QIconDragItems and return it. Normally such a drag should offer each selected item's data. So in dragObject() you should iterate over all the items, and create a QIconDragItem for each selected item, and append these items with QIconDrag::append() to the QIconDrag object. You can use QIconDragItem::setData() to set the data of each item that should be dragged. If you want to offer the data in additional mime-types, it's best to use a class derived from QIconDrag, which implements additional encoding and decoding functions.

When a drag enters the icon view, there is little to do. Simply connect to the dropped() signal and reimplement QIconViewItem::acceptDrop() and QIconViewItem::dropped(). If you've used a QIconDrag (or a subclass of it) the second argument to the dropped signal contains a QValueList of QIconDragItems -- you can access their data by calling QIconDragItem::data() on each one.

For an example implementation of complex drag-and-drop look at the fileiconview example (qt/examples/fileiconview).

See also QIconViewItem::setDragEnabled(), QIconViewItem::setDropEnabled(), QIconViewItem::acceptDrop(), QIconViewItem::dropped(), and Advanced Widgets.

Member Type Documentation

QIconView::Arrangement

QIconView::LeftToRight - Items which don't fit into the view cause the viewport to extend vertically (you get a vertical scrollbar).

QIconView::TopToBottom - Items which don't fit into the view cause the viewport to extend horizontally (you get a horizontal scrollbar).

QIconView::ItemTextPos

QIconView::Bottom - The text is drawn below the icon.

QIconView::Right - The text is drawn to the right of the icon.

QIconView::ResizeMode

QIconView::Fixed - The icons' positions are not changed.

QIconView::Adjust - The icons' positions are adjusted to be within the new geometry, if possible.

QIconView::SelectionMode

QIconView::Single - When the user selects an item, any already-selected item becomes unselected and the user cannot unselect the selected item. This means that the user can never clear the selection. (The application programmer can, using QIconView::clearSelection().)

QIconView::Multi - When the user selects an item, e.g. by navigating to it with the keyboard arrow keys or by clicking it, the selection status of that item is toggled and the other items are left alone. Also, multiple items can be selected by dragging the mouse while the left mouse button stays pressed.

QIconView::Extended - When the user selects an item the selection is cleared and the new item selected. However, if the user presses the Ctrl key when clicking on an item, the clicked item gets toggled and all other items are left untouched. If the user presses the Shift key while clicking on an item, all items between the current item and the clicked item get selected or unselected, depending on the state of the clicked item. Also, multiple items can be selected by dragging the mouse while the left mouse button stays pressed.

QIconView::NoSelection - Items cannot be selected.

To summarise: Single is a real single-selection icon view; Multi a real multi-selection icon view; Extended is an icon view in which users can select multiple items but usually want to select either just one or a range of contiguous items; and NoSelection mode is for an icon view where the user can look but not touch.  

MEMBER FUNCTION DOCUMENTATION

QIconView::QIconView ( QWidget * parent = 0, const char * name = 0, WFlags f = 0 )

QIconView::~QIconView () [virtual]

void QIconView::adjustItems () [virtual protected slot]

void QIconView::arrangeItemsInGrid ( const QSize & grid, bool update = TRUE ) [virtual slot]

If update is TRUE (the default) the viewport is repainted.

Example: fileiconview/qfileiconview.h.  

void QIconView::arrangeItemsInGrid ( bool update = TRUE ) [virtual slot]

Arranges all the items in the grid given by gridX() and gridY().

Even if sorting() is enabled, the items are not sorted by this function. If you want to sort or rearrange the items, use iconview->sort(iconview->sortDirection()).

If update is TRUE (the default), the viewport is repainted as well.

See also QIconView::gridX, QIconView::gridY, and QIconView::sort().  

Arrangement QIconView::arrangement () const

bool QIconView::autoArrange () const

void QIconView::clear () [virtual]

void QIconView::clearSelection () [virtual]

void QIconView::clicked ( QIconViewItem * item ) [signal]

See also mouseButtonClicked(), rightButtonClicked(), and pressed().  

void QIconView::clicked ( QIconViewItem * item, const QPoint & pos ) [signal]

This signal is emitted when the user clicks any mouse button on an icon view item. item is a pointer to the item that has been clicked.

pos is the position of the mouse cursor in the global coordinate system (QMouseEvent::globalPos()). (If the click's press and release differ by a pixel or two, pos is the position at release time.)

See also mouseButtonClicked(), rightButtonClicked(), and pressed().  

void QIconView::contextMenuRequested ( QIconViewItem * item, const QPoint & pos ) [signal]

pos is the position for the context menu in the global coordinate system.  

uint QIconView::count () const

void QIconView::currentChanged ( QIconViewItem * item ) [signal]

See also currentItem().  

QIconViewItem * QIconView::currentItem () const

See also setCurrentItem(), firstItem(), and lastItem().  

void QIconView::doAutoScroll () [virtual protected slot]

void QIconView::doubleClicked ( QIconViewItem * item ) [signal]

QDragObject * QIconView::dragObject () [virtual protected]

See also QIconDrag.

Examples:  

void QIconView::drawBackground ( QPainter * p, const QRect & r ) [virtual protected]

The default implementation fills r with the viewport's backgroundBrush(). Subclasses may reimplement this to draw custom backgrounds.

See also contentsX, contentsY, and drawContents().  

void QIconView::drawRubber ( QPainter * p ) [virtual protected]

void QIconView::dropped ( QDropEvent * e, const QValueList<QIconDragItem> & lst ) [signal]

e provides all the information about the drop. If the drag object of the drop was a QIconDrag, lst contains the list of the dropped items. You can get the data using QIconDragItem::data() on each item. If the lst is empty, i.e. the drag was not a QIconDrag, you have to decode the data in e and work with that.

Note QIconViewItems may be drop targets; if a drop event occurs on an item the item handles the drop.

Examples:  

void QIconView::emitSelectionChanged ( QIconViewItem * i = 0 ) [protected]

You should never need to call this function.  

void QIconView::ensureItemVisible ( QIconViewItem * item )

See also ensureVisible().  

QIconViewItem * QIconView::findFirstVisibleItem ( const QRect & r ) const

If you want to find all items that touch r, you will need to use this function and nextItem() in a loop ending at findLastVisibleItem() and test QIconViewItem::rect() for each of these items.

See also findLastVisibleItem() and QIconViewItem::rect().  

QIconViewItem * QIconView::findItem ( const QPoint & pos ) const

QIconViewItem * QIconView::findItem ( const QString & text, ComparisonFlags compare = BeginsWith ) const

Returns a pointer to the first item whose text begins with text, or 0 if no such item could be found. Use the compare flag to control the comparison behaviour. (See Qt::StringComparisonMode.)  

QIconViewItem * QIconView::findLastVisibleItem ( const QRect & r ) const

See also findFirstVisibleItem().  

QIconViewItem * QIconView::firstItem () const

See also lastItem() and currentItem().  

int QIconView::gridX () const

int QIconView::gridY () const

int QIconView::index ( const QIconViewItem * item ) const

void QIconView::insertInGrid ( QIconViewItem * item ) [virtual protected]

void QIconView::insertItem ( QIconViewItem * item, QIconViewItem * after = 0L ) [virtual]

You should never need to call this function. Instead create QIconViewItem's and associate them with your icon view like this:

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

void QIconView::invertSelection () [virtual]

bool QIconView::isRenaming () const

void QIconView::itemRenamed ( QIconViewItem * item, const QString & name ) [signal]

See also QIconViewItem::setRenameEnabled() and QIconViewItem::rename().  

void QIconView::itemRenamed ( QIconViewItem * item ) [signal]

This signal is emitted when item has been renamed, usually by in-place renaming.

See also QIconViewItem::setRenameEnabled() and QIconViewItem::rename().  

QBrush QIconView::itemTextBackground () const

ItemTextPos QIconView::itemTextPos () const

bool QIconView::itemsMovable () const

QIconViewItem * QIconView::lastItem () const

See also firstItem() and currentItem().  

QIconViewItem * QIconView::makeRowLayout ( QIconViewItem * begin, int & y, bool & changed ) [protected]

Warning: This function may be made private in a future version of Qt. We do not recommend calling it.  

int QIconView::maxItemTextLength () const

int QIconView::maxItemWidth () const

void QIconView::mouseButtonClicked ( int button, QIconViewItem * item, const QPoint & pos ) [signal]

pos is the position of the mouse cursor in the global coordinate system (QMouseEvent::globalPos()). (If the click's press and release differ by a pixel or two, pos is the position at release time.)

See also mouseButtonPressed(), rightButtonClicked(), and clicked().  

void QIconView::mouseButtonPressed ( int button, QIconViewItem * item, const QPoint & pos ) [signal]

pos is the position of the mouse cursor in the global coordinate system (QMouseEvent::globalPos()).

See also rightButtonClicked() and pressed().  

void QIconView::moved () [signal]

Example: iconview/main.cpp.  

void QIconView::onItem ( QIconViewItem * item ) [signal]

void QIconView::onViewport () [signal]

See also onItem().  

void QIconView::pressed ( QIconViewItem * item ) [signal]

See also mouseButtonPressed(), rightButtonPressed(), and clicked().  

void QIconView::pressed ( QIconViewItem * item, const QPoint & pos ) [signal]

This signal is emitted when the user presses any mouse button. If item is non-null, the cursor is on item. If item is null, the mouse cursor isn't on any item.

pos is the position of the mouse cursor in the global coordinate system (QMouseEvent::globalPos()). (If the click's press and release differ by a pixel or two, pos is the position at release time.)

See also mouseButtonPressed(), rightButtonPressed(), and clicked().  

void QIconView::repaintItem ( QIconViewItem * item ) [virtual]

void QIconView::repaintSelectedItems ()

ResizeMode QIconView::resizeMode () const

void QIconView::returnPressed ( QIconViewItem * item ) [signal]

void QIconView::rightButtonClicked ( QIconViewItem * item, const QPoint & pos ) [signal]

pos is the position of the mouse cursor in the global coordinate system (QMouseEvent::globalPos()). (If the click's press and release differ by a pixel or two, pos is the position at release time.)

See also rightButtonPressed(), mouseButtonClicked(), and clicked().  

void QIconView::rightButtonPressed ( QIconViewItem * item, const QPoint & pos ) [signal]

pos is the position of the mouse cursor in the global coordinate system (QMouseEvent::globalPos()).  

void QIconView::selectAll ( bool select ) [virtual]

In Single and NoSelection modes, this function only changes the selection status of currentItem().  

void QIconView::selectionChanged () [signal]

void QIconView::selectionChanged ( QIconViewItem * item ) [signal]

This signal is emitted when the selection changes. item is the newly selected item. This signal is emitted only in single selection mode.  

SelectionMode QIconView::selectionMode () const

void QIconView::setArrangement ( Arrangement am ) [virtual]

void QIconView::setAutoArrange ( bool b ) [virtual]

void QIconView::setCurrentItem ( QIconViewItem * item ) [virtual]

void QIconView::setGridX ( int rx ) [virtual]

void QIconView::setGridY ( int ry ) [virtual]

void QIconView::setItemTextBackground ( const QBrush & b ) [virtual]

void QIconView::setItemTextPos ( ItemTextPos pos ) [virtual]

void QIconView::setItemsMovable ( bool b ) [virtual]

void QIconView::setMaxItemTextLength ( int w ) [virtual]

void QIconView::setMaxItemWidth ( int w ) [virtual]

void QIconView::setResizeMode ( ResizeMode am ) [virtual]

void QIconView::setSelected ( QIconViewItem * item, bool s, bool cb = FALSE ) [virtual]

If s is FALSE, item is unselected.

If s is TRUE and QIconView::selectionMode() is Single, item is selected, and the item which was selected is unselected.

If s is TRUE and QIconView::selectionMode() is Extended, item is selected. If cb is TRUE, the selection state of the icon view's other items is left unchanged. If cb is FALSE (the default) all other items are unselected.

If s is TRUE and QIconView::selectionMode() is Multi item is selected.

Note that cb is used only if QIconView::selectionMode() is Extended. cb defaults to FALSE.

All items whose selection status is changed repaint themselves.  

void QIconView::setSelectionMode ( SelectionMode m ) [virtual]

void QIconView::setShowToolTips ( bool b ) [virtual]

void QIconView::setSorting ( bool sort, bool ascending = TRUE )

Note that autoArrange() must be TRUE for sorting to take place.

If ascending is TRUE (the default), items are sorted in ascending order. If ascending is FALSE, items are sorted in descending order.

QIconViewItem::compare() is used to compare pairs of items. The sorting is based on the items' keys; these default to the items' text unless specifically set to something else.

See also QIconView::autoArrange, QIconView::autoArrange, sortDirection, sort(), and QIconViewItem::setKey().  

void QIconView::setSpacing ( int sp ) [virtual]

void QIconView::setWordWrapIconText ( bool b ) [virtual]

bool QIconView::showToolTips () const

void QIconView::slotUpdate () [virtual protected slot]

The icon view is not redrawn immediately after inserting a new item but after a very small delay using a QTimer. This means that when many items are inserted in a loop the icon view is probably redrawn only once at the end of the loop. This makes the insertions both flicker-free and faster.  

void QIconView::sort ( bool ascending = TRUE ) [virtual]

QIconViewItem::compare() is used to compare pairs of items. The sorting is based on the items' keys; these default to the items' text unless specifically set to something else.

Note that this function sets the sort order to ascending.

See also QIconViewItem::key(), QIconViewItem::setKey(), QIconViewItem::compare(), QIconView::setSorting(), and QIconView::sortDirection.  

bool QIconView::sortDirection () const

bool QIconView::sorting () const

int QIconView::spacing () const

void QIconView::startDrag () [virtual protected]

void QIconView::takeItem ( QIconViewItem * item ) [virtual]

bool QIconView::wordWrapIconText () const

Property Documentation

Arrangement arrangement

This can be LeftToRight or TopToBottom. The default is LeftToRight.

Set this property's value with setArrangement() and get this property's value with arrangement().  

bool autoArrange

The default is TRUE.

Note that if the icon view is not visible at the time of insertion, QIconView defers all position-related work until it is shown and then calls arrangeItemsInGrid().

Set this property's value with setAutoArrange() and get this property's value with autoArrange().  

uint count

Get this property's value with count().  

int gridX

If the value is -1, (the default), QIconView computes suitable column widths based on the icon view's contents.

Note that setting a grid width overrides setMaxItemWidth().

Set this property's value with setGridX() and get this property's value with gridX().  

int gridY

If the value is -1, (the default), QIconView computes suitable column heights based on the icon view's contents.

Set this property's value with setGridY() and get this property's value with gridY().  

QBrush itemTextBackground

By default this brush is set to NoBrush, meaning that only the normal icon view background is used.

Set this property's value with setItemTextBackground() and get this property's value with itemTextBackground().  

ItemTextPos itemTextPos

Valid values are Bottom or Right. The default is Bottom.

Set this property's value with setItemTextPos() and get this property's value with itemTextPos().  

bool itemsMovable

The default is TRUE.

Set this property's value with setItemsMovable() and get this property's value with itemsMovable().  

int maxItemTextLength

The default is 255 characters.

Set this property's value with setMaxItemTextLength() and get this property's value with maxItemTextLength().  

int maxItemWidth

The default is 100 pixels.

Note that if the gridX() value is set QIconView will ignore this property.

Set this property's value with setMaxItemWidth() and get this property's value with maxItemWidth().  

ResizeMode resizeMode

This can be Fixed or Adjust. The default is Fixed. See ResizeMode.

Set this property's value with setResizeMode() and get this property's value with resizeMode().  

SelectionMode selectionMode

This can be Single (the default), Extended, Multi or NoSelection.

Set this property's value with setSelectionMode() and get this property's value with selectionMode().  

bool showToolTips

The default is TRUE. Note that this has no effect if setWordWrapIconText() is TRUE, as it is by default.

Set this property's value with setShowToolTips() and get this property's value with showToolTips().  

bool sortDirection

The default is TRUE (i.e. ascending). This sort direction is only meaningful if both sorting() and autoArrange() are TRUE.

To set the sort direction, use setSorting()

Get this property's value with sortDirection().  

bool sorting

The default is FALSE, i.e. no sorting on insertion.

To set the sorting, use setSorting().

Get this property's value with sorting().  

int spacing

The default is 5 pixels.

Negative values for spacing are illegal.

Set this property's value with setSpacing() and get this property's value with spacing().  

bool wordWrapIconText

The default is TRUE.

If this property is FALSE, icon text that is too long is truncated, and an ellipsis (...) appended to indicate that truncation has occurred. The full text can still be seen by the user if they hover the mouse because the full text is shown in a tooltip; see setShowToolTips().

Set this property's value with setWordWrapIconText() and get this property's value with wordWrapIconText().

SEE ALSO

COPYRIGHT

AUTHOR

BUGS