|
|
The QIconView class provides an area with movable labelled icons. More...
#include <qiconview.h>
Inherits QScrollView.
| Type | Name | READ | WRITE | Options |
|---|---|---|---|---|
| bool | sorting | sorting | ||
| bool | sortDirection | sortDirection | ||
| SelectionMode | selectionMode | selectionMode | setSelectionMode | |
| int | gridX | gridX | setGridX | |
| int | gridY | gridY | setGridY | |
| int | spacing | spacing | setSpacing | |
| ItemTextPos | itemTextPos | itemTextPos | setItemTextPos | |
| QBrush | itemTextBackground | itemTextBackground | setItemTextBackground | |
| Arrangement | arrangement | arrangement | setArrangement | |
| ResizeMode | resizeMode | resizeMode | setResizeMode | |
| int | maxItemWidth | maxItemWidth | setMaxItemWidth | |
| int | maxItemTextLength | maxItemTextLength | setMaxItemTextLength | |
| bool | autoArrange | autoArrange | setAutoArrange | |
| bool | itemsMovable | itemsMovable | setItemsMovable | |
| bool | wordWrapIconText | wordWrapIconText | setWordWrapIconText | |
| bool | showToolTips | showToolTips | setShowToolTips | |
| uint | count | count |
It can display and control a grid or other 2-d layout of items, and provides the ability to add or remove new items at any time, lets the user select one or may items, rearrange the items, provides drag and drop of items, and so on.
Each item (a QIconViewItem) contains a text and a pixmap (the icon itself).
The simplest usage of QIconView is to create the object, create some QIconViewItems with the view as parent, set the view's geometry, and show it.
When an item is inserted, QIconView allocates a spot for it. The
default Arrangement is LeftToRight - QIconView fills up the
leftmost column first, then goes rightwards. You can change that
using setArrangement(), or insert items in a specified position by
calling the appropriate constructors or QIconViewItem::insertItem(),
or sort while the view is on-screen using setSorting() and/or
sort().
Each (selectable) item
can be selected, and the view provides various SelectionMode
settings. The default is Single - when one item is selected, the
previously selected item is unselected.
The QIconView provides a widget which can contain lots of iconview items which can be selected, dragged and so on.
Items can be inserted in a grid and can flow from top to bottom (TopToBottom) or from left to right (LeftToRight). The text can be either displayed at the bottom of the icons or the the right of the icons. Items can also be inserted in a sorted order. There are also methods to re-arrange and re-sort the items after they have been inserted.
There is a variety of selection modes, described in the QIconView::SelectionMode documentation. The default is single-selection, and you can change it using setSelectionMode().
Since QIconView offers multiple selection it has to display keyboard focus and selection state separately. Therefore there are functions both 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 iconview provides a rubberband too.
Items can also be in-place renamed.
The normal way to insert some items is to create QIconViewItems and pass the iconview as parent. By using insertItem(), items can be inserted manually too. The QIconView offers basic methods similar to the QListView and QListBox, like QIconView::takeItem(), QIconView::clearSelection(), QIconView::setSelected(), QIconView::setCurrentItem(), QIconView::currentItem() and much more.
As the internal structure to store the iconview items is linear (a double linked list), no iterator class is needed to iterate over all items. This can be easily done with a code like
QIconView *iv = the iconview
for ( QIconViewItem *i = iv->firstItem(); i; i = i->nextItem() ) {
i->doSmething();
}
To notify the application about changes in the iconview there are several signals which are emitted by the QIconView.
The QIconView is designed for Drag'n'Drop, as the icons are also moved inside the iconview itself using DnD. So the QIconView provides some methods for extended DnD too. To use DnD correctly in the iconview, please read following instructions:
There are two different ways to do that, depending what you want. The first case is the simple one, in which case just the dragobject you created is dragged around. If you want, that drag shapes (the rectangles of the dragged items with exact positions) are drawn, you have to choose the more complicated way. Here first the simple case is described:
In the simple case you only need for starting a drag to reimplement QIconView::dragObject(). There you create a QDragObject with the data you want to drag and return it. And for entering drags you don't need to do anything special then. Just connect to dropped() signal to get notified about drops onto the viewport and reimplement QIconViewItem::acceptDrop() and QIconViewItem::dropped() to be able to react on drops onto an iconview item.
If you want to have drag shapes drawn, you have to do quite a bit more and complex things:
The first part is starting drags: If you want to use extended DnD in the QIconView, you should use QIconDrag (or a derived class from that) as dragobject and in dragObject() create such an object and return it. Before returning it, fill it there with QIconDragItems. Normally such a drag should offer data of each selected item. So in dragObject() you should iterate over all items, create for each selected item a QIconDragItem and append this with QIconDrag::append() to the QIconDrag object. With QIconDragItem::setData() you can set the data of each item which should be dragged. If you want to offer the data in additional mime-types, it's the best to use a class derived from QIconDrag which implements additional encoding and decoding functions.
Now, when a drag enters the iconview, there is not much todo. Just connect to the dropped() signal and reimplement QIconViewItem::dropped() and QIconViewItem::acceptDrop(). The only special thing in this case is the second argument in the dropped() signal and in QIconViewItem::dropped(). Fur further details about that look at the documentation of these signal/method.
For an example implementation of the complex Drag'n'Drop stuff look at the qfileiconview example (qt/examples/qfileiconview)
Finally, see also QIconViewItem::setDragEnabled(), QIconViewItem::setDropEnabled(), QIconViewItem::acceptDrop() and QIconViewItem::dropped()
Examples: iconview/main.cpp
LeftToRight - Items, which don't fit onto the view, go further down (you get a vertical scrollbar)
TopToBottom - Items, which don't fit onto the view, go further right (you get a horizontal scrollbar)
Bottom - The text is drawn at the bottom of the icon)
Right - The text is drawn at the right of the icon)
Fixed - the icons' positions are not changed.
Adjust - the icons' positions are adjusted to be within the
new geometry, if possible.
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, even
though the selection may be cleared by the application programmer
using QIconView::clearSelection().
Multi - When the user selects an item in the most ordinary
way, the selection status of that item is toggled and the other
items are left alone.
Extended - When the user selects an item in the most
ordinary way, 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. And
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 stayes pressed.
NoSelection - Items cannot be selected.
In other words, Single is a real single-selection iconview, Multi a real multi-selection iconview, and Extended iconview
where users can select multiple items but usually want to select
either just one or a range of contiguous items, and NoSelection
is for a iconview where the user can look but not touch.
Constructs an empty icon view.
[virtual]Destructs the iconview and deletes all items.
[virtual protected slot]Adjusts the positions of the items to the geometry of the iconview.
[virtual slot]Arranges all items in the grid. For the grid the specified values, given by QIconView::setGridX() and QIconView::setGridY() are used. Even if QIconView::sorting() is enabled, the items are not resorted in this method. If you want to sort and re-arrange all items, use iconview->sort( iconview->sortDirection() );
If update is TRUE, the viewport is repainted.
See also QIconView::setGridX(), QIconView::setGridY() and QIconView::sort().
[virtual slot]Arranges all items in the grid; If the grid is invalid (see QSize::isValid(), an invalid size is created when using the default constructor of QSize()) the best fitting grid is calculated first and used then.
if update is TRUE, the viewport is repainted.
Returns the arrangement mode of the iconview.
See also QIconView::setArrangement().
Returns TRUE if all items are re-arranged in the grid if a new one is inserted, else FALSE.
See also QIconView::setAutoArrange().
[virtual]Cleares the iconview.
[virtual]Unselects all items.
[signal]This signal is emitted when the user clicked (pressed + released) with any mouse button on either and item (then item is the item under the mouse cursor) or somewhere else (then item is 0).
[signal]This signal is emitted when the user clicked (pressed + released) with any mouse button on either and item (then item is the item under the mouse cursor) or somewhere else (then item is 0). pos the position of the mouse cursor.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Returns the number of items in the iconview.
[signal]This signal is emitted, when the different items got current. item is the new current item or 0, if no item is current now.
Returns a pointer to the current item fo the iconview, or 0, if no item is current.
[virtual protected slot]Does autoscrolling when selecting multiple icons with the rubber band.
[signal]This signal is emitted, if the user double-clicked on the item item.
[virtual protected]Returns the QDragObject which should be used for DnD. This method is called by the iconview when starting a drag to get the dragobject which should be used for the drag. Subclasses may reimplement this.
See also QIconDrag.
[virtual protected]This method is called to draw the rectangle r of the background using the painter p. xOffset and yOffset are known using the methods contentsX() and contentsY().
The default implementation only fills r with colorGroup().base(). Subclasses may reimplement this to draw fency backgrounds.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
[virtual protected]Draws the rubber band using the painter p.
[signal]This signal is emitted, when a drop event occurred onto the viewport (not onto an icon), which the iconview itself can't handle.
e gives you all 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() of each item then.
So, if lst is not empty, use this data for further operations, else the drag was not a QIconDrag, so you have to decode e yourself and work with that.
[protected]Emits signals, that indicate selection changes.
Makes sure, that item is visible, and scrolls the view if required.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
[virtual]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QObject.
Finds the first item which is visible in the rectangle r in contents coordinates. If no items are visible at all, 0 is returned.
Returns a pointer to the item which contains pos, which is given on contents coordinates.
Returns a pointer to the first item which could be found that contains text, or 0 if no such item could be found.
Finds the last item which is visible in the rectangle r in contents coordinates. If no items are visible at all, 0 is returned.
Returns a pointer to the first item fo the iconview, or 0, if there are no items in the iconview.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Returns the horizontal grid.
See also QIconView::setGridX().
Returns the vertica grid.
See also QIconView::setGridY().
Returns the index of item or -1 if item doesn't exist in this icon view.
[virtual protected]Inserts an item in the grid of the iconview. You should never need to call this manually.
[virtual]Inserts the iconview item item after after. If after is 0, item is appended.
You should never need to call this method yourself, you should rather do
(void) new QIconViewItem( iconview, "This is the text of the item", pixmap );
This does everything required for inserting an item.
[virtual]Inverts the selection. Works only in Multi and Extended selection mode.
[signal]If the item has been renamed (e.g. by in-place renaming), this signal is emitted.
[signal]If the item has been renamed (e.g. by in-place renaming), this signal is emitted. name is the new text (name) of the item.
Returns the brush which is used to draw the background of an item text
See also setItemTextBackground().
Returns the position, at which the text of the items are drawn.
See also QIconView::setItemTextPos().
Returns TRUE, if the user is allowed to move items around in the iconview, else FALSE;
See also QIconView::setItemsMovable().
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Returns a pointer to the last item fo the iconview, or 0, if there are no items in the iconview.
[protected]Lays out a row of icons (in Arrangement == TopToBottom this is a column). Starts laying out with the item begin. y is the starting coordinate. Returns the last item of the row and sets the new starting coordinate to y.
This function may be made private in a future version of Qt. We recommend not calling it.
Returns the maximum length (in characters), which the text of an icon may have.
See also QIconView::setMaxItemTextLength().
Returns the maximum width (in pixels), which an item may have.
See also QIconView::setMaxItemWidth().
[virtual]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QWidget.
[signal]This signal is emitted when the user clicked (pressed + released) with any mouse button on either and item (then item is the item under the mouse cursor) or somewhere else (then item is 0). button is the number of the mouse button which the user clicked, and pos the position of the mouse cursor.
[signal]This signal is emitted when the user pressed with any mouse button on either and item (then item is the item under the mouse cursor) or somewhere else (then item is 0). button is the number of the mouse button which the user pressed, and pos the position of the mouse cursor.
[signal]This signal is emitted after successfully dropping an (or some) item(s) of the iconview somewhere and if they should be removed now.
[signal]This signal is emitted, when the user moves the mouse cursor onto an item. It´s only emitted once per item.
[signal]This signal is emitted, when the user moves the mouse cursor, which was on an item away from the item onto the viewport.
[signal]This signal is emitted when the user pressed with any mouse button on either and item (then item is the item under the mouse cursor) or somewhere else (then item is 0).
[signal]This signal is emitted when the user pressed with any mouse button on either and item (then item is the item under the mouse cursor) or somewhere else (then item is 0). pos the position of the mouse cursor.
[virtual]Repaints the item.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Returns the resize mode of the iconview.
See also QIconView::setResizeMode().
[signal]This signal is emitted, if the user pressed the return or enter button. item is the item which was current while return or enter was pressed.
[signal]This signal is emitted when the user clicked (pressed + released) with the right mouse button on either and item (then item is the item under the mouse cursor) or somewhere else (then item is 0). pos the position of the mouse cursor.
[signal]This signal is emitted when the user pressed with the right mouse button on either and item (then item is the item under the mouse cursor) or somewhere else (then item is 0). pos the position of the mouse cursor.
[virtual]If select is TRUE, all items get selected, else all get unselected. This works only in the selection modes Multi and Extended. In Single and NoSelection mode the selection of the current item is just set to select.
[signal]This signal is emitted when the selection has been changed. It's emitted in each selection mode.
[signal]This signal is emitted when the selection has been changed. item is the new selected item. This signal is only emitted in single selection mode.
Returns the selection mode of the iconview. The initial mode is
Single.
See also setSelectionMode().
Sets the arrangement mode of the iconview to am, which must be
one of LeftToRight and TopToBottom.
See also Arrangement.
[virtual]If b is TRUE, all items are re-arranged in the grid if a new one is inserted. Else, the best fitting place for the new item is searched and the other ones are not touched.
This setting only applies if the iconview is visible. If you insert items and the iconview is not visible, the icons are reordered when it gets visible.
[virtual slot]Reimplemented for internal reasons; the API is not affected.
[virtual]Makes item the new current item of the iconview.
[virtual]Reimplemented for internal reasons; the API is not affected.
[virtual]Sets the horizontal grid to rx. If rx is -1, there is no horizontal grid used for arranging items.
[virtual]Sets the vertical grid to ry. If ry is -1, there is no vertical grid used for arranging items.
[virtual]Sets the brush, which should be used when drawing the background of an item text. By default, this brush is set to NoBrush, which means no extra brush is used for drawing the item text background (just the normal iconview background).
Sets the position, where the text of the items is drawn. This can be Bottom or Right.
[virtual]If b is TRUE, the user is allowed to move items around in the iconview. if b is FALSE, the user is not allowed to do that.
[virtual]Sets the maximum length (in characters), which an item text may have.
[virtual]Sets the maximum width, which an item may have. If a gridX() is set, this value is ignored, and the gridX() value is used.
[virtual]Reimplemented for internal reasons; the API is not affected.
Sets the resize mode of the iconview to rm, which must be one of
Fixed and Adjust.
See also ResizeMode.
[virtual]Selects or unselects item depending on s, and may also unselect other items, depending on QIconView::selectionMode() and cb.
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 other items of the iconview
are not touched. 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 change repaint themselves.
Sets the selection mode of the iconview to m, which may be one of
Single (the default), Extended, Multi or NoSelection.
See also selectionMode().
Examples: iconview/main.cpp
[virtual]If wordWrapIconText() is FALSE, it happens that an item text is truncated because it's too large for one line. If you specify TRUE for b here and the user moves the mouse onto the item a tooltip with the whole item text is shown. If you pass FALSE here this feature is switched off.
See also setWordWrapIconText().
If sort is TRUE, new items are inserted sorted. The sort direction is specified using ascending.
Inserting items sorted only works when re-arranging items is set to TRUE as well (using QIconView::setAutoArrange()).
See also QIconView::setAutoArrange() and QIconView::autoArrange().
[virtual]Sets the space between iconview items to sp.
[virtual]If the width of an item text is larger than the maximal item width, there are two possibilities how the QIconView can deal with this. Either it does a word wrap of the item text, so that it uses multiple lines. Or it truncates the item text so that it shrinks to the maximal item width and appends three dots "..." to the displayed text to indicate that not the full text is displayed.
If you set b to TRUE, a word wrap is done, else the text is displayed truncated.
NOTE: Both possibilities just change the way how the text is displayed, they do NOT modify the item text itslef.
See also setShowToolTips().
[virtual]Reimplemented for internal reasons; the API is not affected.
Returns TRUE if a tooltip is shown for truncated item texts and FALSE otherwise.
See also setShowToolTips() and setWordWrapIconText().
[virtual]Reimplemented for internal reasons; the API is not affected.
Examples: iconview/main.cpp
Reimplemented from QWidget.
[virtual]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QWidget.
[virtual protected slot]Because of efficiency, the iconview is not redrawn immediately after inserting a new item, but with a very small delay using a QTimer. The result of this is, that if lots of items are inserted in a short time (e.g. in a loop), the iconview is not redrawn after each inserted item, but after inserting all of them, which makes the operation much faster and flicker-free.
[virtual]Sorts the items of the listview and re-arranges them afterwards. If ascending is TRUE, the items are sorted in increasing order, else in decreasing order. For sorting QIconViewItem::compare() is used. The default sort direction is set to the sort direction you set here.
See also QIconViewItem::key(), QIconViewItem::setKey(), QIconViewItem::compare(), QIconView::setSorting() and QIconView::sortDirection().
Returns TRUE if the sort direction for inserting new items is ascending, FALSE means descending. This sort direction has only a meaning if re-sorting and re-arranging of new inserted items is enabled.
See also QIconView::setSorting() and QIconView::setAutoArrange().
Returns TRUE if new items are inserted sorted, else FALSE.
See also QIconView::setSorting().
Returns the spacing between iconview items.
[virtual protected]Starts a drag.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QWidget.
[virtual]Takes the iconview item item out of the iconview and causes an update
of the screen display. The item is not deleted. You should normally not
need to call this function, as QIconViewItem::~QIconViewItem() calls it.
The normal way to delete an item is delete.
Returns TRUE, if an item text which needs too much space (to the width) is displayed word wrapped, or FALSE if it gets displayed truncated.
See also setWordWrapIconText() and setShowToolTips().
[protected]For internal use only.
[virtual slot]For internal use only.
Search the documentation, FAQ, qt-interest archive and more (uses
www.trolltech.com):
This file is part of the Qt toolkit, copyright © 1995-2000 Trolltech, all rights reserved.
| Copyright © 2000 Trolltech | Trademarks | Qt version 2.2.1
|