qiconview.3qt

Trolltech公司发布的基于C++图形开发环境

.ti -1c
.BI "void \fBitemRenamed\fR ( QIconViewItem * item ) "
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "virtual void \fBdrawRubber\fR ( QPainter * p ) "
.br
.ti -1c
.BI "virtual QDragObject* \fBdragObject\fR () "
.br
.ti -1c
.BI "virtual void \fBstartDrag\fR () "
.br
.ti -1c
.BI "virtual void \fBinsertInGrid\fR ( QIconViewItem * item ) "
.br
.ti -1c
.BI "virtual void \fBdrawBackground\fR ( QPainter * " "p" ", const QRect & r ) "
.br
.ti -1c
.BI "void \fBemitSelectionChanged\fR ( QIconViewItem * " "i" " = 0 ) "
.br
.ti -1c
.BI "void \fBemitRenamed\fR ( QIconViewItem * item ) (internal)"
.br
.ti -1c
.BI "QIconViewItem* \fBmakeRowLayout\fR ( QIconViewItem * " "begin" ", int & y ) "
.br
.in -1c
.SS "Protected Slots"
.in +1c
.ti -1c
.BI "virtual void \fBdoAutoScroll\fR () "
.br
.ti -1c
.BI "virtual void \fBadjustItems\fR () "
.br
.ti -1c
.BI "virtual void \fBslotUpdate\fR () "
.br
.in -1c
.SS "Properties"
.nf
.TS
l l l l l
- - - - -
l l l l l.
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
.TE
.fi

.SH DESCRIPTION
The QIconView class provides an area with movable labelled icons.
.PP
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.
.PP
Each item (a QIconViewItem) contains a text and a pixmap (the icon itself).
.PP
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.
.PP
When an item is inserted, QIconView allocates a spot for it. The default Arrangement is \fCLeftToRight\fR - 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().
.PP
Each (selectable) item can be selected, and the view provides various SelectionMode settings. The default is \fCSingle\fR - when one item is selected, the previously selected item is unselected.
.PP
The QIconView provides a widget which can contain lots of iconview items which can be selected, dragged and so on.
.PP
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.
.PP
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().
.PP
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().
.PP
When multiple items may be selected, the iconview provides a rubberband too.
.PP
Items can also be in-place renamed.
.PP
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.
.PP
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
.PP
.nf
.br
  QIconView *iv = the iconview
.br
  for ( QIconViewItem *i = iv->firstItem(); i; i = i->nextItem() ) {
.br
      i->doSmething();
.br
  }
.fi
.PP
To notify the application about changes in the iconview there are several signals which are emitted by the QIconView.
.PP
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:
.PP
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:
.PP
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.
.PP
If you want to have drag shapes drawn, you have to do quite a bit more and complex things:
.PP
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.
.PP
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.
.PP
For an example implementation of the complex Drag'n'Drop stuff look at the qfileiconview example (qt/examples/qfileiconview)
.PP
Finally, see also QIconViewItem::setDragEnabled(), QIconViewItem::setDropEnabled(), QIconViewItem::acceptDrop() and QIconViewItem::dropped()
.PP
.ce 1
.B "[Image Omitted]"
.PP

.ce 1
.B "[Image Omitted]"
.PP
Examples:
.(l
iconview/main.cpp
.)l
.SS "Member Type Documentation"
.SH "QIconView::Arrangement"
This enum type decides in which direction the items, which do not fit onto the screen anymore flow.
.TP
\fCLeftToRight\fR - Items, which don't fit onto the view, go further down (you get a vertical scrollbar)
.TP
\fCTopToBottom\fR - Items, which don't fit onto the view, go further right (you get a horizontal scrollbar)
.SH "QIconView::ItemTextPos"
This enum type specifies the position of the item text in relation to the icon.
.TP
\fCBottom\fR - The text is drawn at the bottom of the icon)
.TP
\fCRight\fR - The text is drawn at the right of the icon)
.SH "QIconView::ResizeMode"
This enum type decides how QIconView should treat the positions of its icons when the widget is resized. The currently defined modes are: 
.TP
\fCFixed\fR - the icons' positions are not changed.
.TP
\fCAdjust\fR - the icons' positions are adjusted to be within the new geometry, if possible.
.IP
.SH "QIconView::SelectionMode"
This enumerated type is used by QIconView to indicate how it reacts to selection by the user. It has four values: 
.TP
\fCSingle\fR - 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().
.TP
\fCMulti\fR - 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.
.TP
\fCExtended\fR - 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.
.TP
\fCNoSelection\fR - Items cannot be selected.
.IP
.PP
In other words, \fCSingle\fR is a real single-selection iconview, \fCMulti\fR a real multi-selection iconview, and \fCExtended\fR iconview where users can select multiple items but usually want to select either just one or a range of contiguous items, and \fCNoSelection\fR is for a iconview where the user can look but not touch.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QIconView::QIconView ( QWidget * parent = 0, const char * name = 0, WFlags f = 0 )"
Constructs an empty icon view.
.SH "QIconView::~QIconView () \fC[virtual]\fR"
Destructs the iconview and deletes all items.
.SH "void QIconView::adjustItems () \fC[virtual protected slot]\fR"
Adjusts the positions of the items to the geometry of the iconview.
.SH "void QIconView::arrangeItemsInGrid ( const QSize & grid, bool update = TRUE ) \fC[virtual slot]\fR"
Arranges all items in the \fIgrid;\fR 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.
.PP
if \fIupdate\fR is TRUE, the viewport is repainted.
.SH "QIconView::Arrangement QIconView::arrangement() const"
Returns the arrangement mode of the iconview.
.PP
See also QIconView::setArrangement().
.SH "bool QIconView::autoArrange () const"
Returns TRUE if all items are re-arranged in the grid if a new one is inserted, else FALSE.
.PP
See also QIconView::setAutoArrange().
.SH "void QIconView::clear () \fC[virtual]\fR"
Cleares the iconview.
.SH "void QIconView::clearSelection () \fC[virtual]\fR"
Unselects all items.
.SH "void QIconView::clicked ( QIconViewItem * item ) \fC[signal]\fR"
This signal is emitted when the user clicked (pressed + released) with any mouse button on either and item (then \fIitem\fR is the item under the mouse cursor) or somewhere else (then \fIitem\fR is 0).
.SH "void QIconView::clicked ( QIconViewItem * item, const QPoint & pos ) \fC[signal]\fR"
This signal is emitted when the user clicked (pressed + released) with any mouse button on either and item (then \fIitem\fR is the item under the mouse cursor) or somewhere else (then \fIitem\fR is 0). \fIpos\fR the position of the mouse cursor.
.SH "void QIconView::contentsDragEnterEvent ( QDragEnterEvent * e ) \fC[virtual protected]\fR"
Reimplemented for internal reasons; the API is not affected.
.SH "void QIconView::contentsDragLeaveEvent ( QDragLeaveEvent * ) \fC[virtual protected]\fR"
Reimplemented for internal reasons; the API is not affected.
.SH "void QIconView::contentsDragMoveEvent ( QDragMoveEvent * e ) \fC[virtual protected]\fR"
Reimplemented for internal reasons; the API is not affected.
.SH "void QIconView::contentsDropEvent ( QDropEvent * e ) \fC[virtual protected]\fR"
Reimplemented for internal reasons; the API is not affected.
.SH "void QIconView::contentsMouseDoubleClickEvent ( QMouseEvent * e ) \fC[virtual protected]\fR"
Reimplemented for internal reasons; the API is not affected.
.SH "void QIconView::contentsMouseMoveEvent ( QMouseEvent * e ) \fC[virtual protected]\fR"
Reimplemented for internal reasons; the API is not affected.
.SH "void QIconView::contentsMousePressEvent ( QMouseEvent * e ) \fC[virtual protected]\fR"
Reimplemented for internal reasons; the API is not affected.
.SH "void QIconView::contentsMouseReleaseEvent ( QMouseEvent * e ) \fC[virtual protected]\fR"
Reimplemented for internal reasons; the API is not affected.
.SH "uint QIconView::count () const"
Returns the number of items in the iconview.
.SH "void QIconView::currentChanged ( QIconViewItem * item ) \fC[signal]\fR"
This signal is emitted, when the different items got current. \fIitem\fR is the new current item or 0, if no item is current now.
.SH "QIconViewItem * QIconView::currentItem () const"
Returns a pointer to the current item fo the iconview, or 0, if no item is current.
.SH "void QIconView::doAutoScroll () \fC[virtual protected slot]\fR"
Does autoscrolling when selecting multiple icons with the rubber band.
.SH "void QIconView::doubleClicked ( QIconViewItem * item ) \fC[signal]\fR"
This signal is emitted, if the user double-clicked on the item \fIitem.\fR
.SH "QDragObject * QIconView::dragObject () \fC[virtual protected]\fR"
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.
.PP
See also QIconDrag.
.SH "void QIconView::drawBackground ( QPainter * p, const QRect & r ) \fC[virtual protected]\fR"
This method is called to draw the rectangle \fIr\fR of the background using the painter \fIp.\fR xOffset and yOffset are known using the methods contentsX() and contentsY().
.PP
The default implementation only fills \fIr\fR with colorGroup().base(). Subclasses may reimplement this to draw fency backgrounds.
.SH "void QIconView::drawContents ( QPainter * p, int cx, int cy, int cw, int ch ) \fC[virtual protected]\fR"
Reimplemented for internal reasons; the API is not affected.
.SH "void QIconView::drawRubber ( QPainter * p ) \fC[virtual protected]\fR"
Draws the rubber band using the painter \fIp.\fR
.SH "void QIconView::dropped ( QDropEvent * e, const QValueList<QIconDragItem> & lst ) \fC[signal]\fR"
This signal is emitted, when a drop event occurred onto the viewport (not onto an icon), which the iconview itself can't handle.
.PP
\fIe\fR gives you all information about the drop. If the drag object of the drop was a QIconDrag, \fIlst\fR contains the list of the dropped items. You can get the data using QIconDragItem::data() of each item then.
.PP
So, if \fIlst\fR is not empty, use this data for further operations, else the drag was not a QIconDrag, so you have to decode \fIe\fR yourself and work with that.
.SH "void QIconView::emitSelectionChanged ( QIconViewItem * i = 0 ) \fC[protected]\fR"
Emits signals, that indicate selection changes.
.SH "void QIconView::ensureItemVisible ( QIconViewItem * item )"
Makes sure, that \fIitem\fR is visible, and scrolls the view if required.
.SH "void QIconView::enterEvent ( QEvent * e ) \fC[virtual protected]\fR"
Reimplemented for internal reasons; the API is not affected.
.SH "bool QIconView::eventFilter ( QObject * o, QEvent * e ) \fC[virtual]\fR"
Reimplemented for internal reasons; the API is not affected.
.PP
Reimplemented from QObject.
.SH "QIconViewItem* QIconView::findFirstVisibleItem ( const QRect & r ) const"
Finds the first item which is visible in the rectangle \fIr\fR in contents coordinates. If no items are visible at all, 0 is returned.
.SH "QIconViewItem * QIconView::findItem ( const QPoint & pos ) const"
Returns a pointer to the item which contains \fIpos,\fR which is given on contents coordinates.
.SH "QIconViewItem * QIconView::findItem ( const QString & text ) const"