Contents

• Public Functions
• Protected Functions
• Detailed Description

Detailed Description

TheQ3IconViewItem class provides a single item in aQ3IconView.

AQ3IconViewItem contains an icon, a string and optionally a sort key, and can display itself in aQ3IconView.

The simplest way to create aQ3IconViewItem and insert it into aQ3IconView is to construct the item passing the constructor a pointer to the icon view, a string and an icon:

(void)newQ3IconViewItem(                iconView,// A pointer to a Q3IconView"This is the text of the item",                aPixmap);

By default the text of an icon view item may not be edited by the user but callingsetRenameEnabled(true) will allow the user to perform in-place editing of the item's text.

When the icon view is deleted all items in it are deleted automatically.

TheQ3IconView::firstItem() andQ3IconViewItem::nextItem() functions provide a means of iterating over all the items in aQ3IconView:

Q3IconViewItem*item;for (item= iconView->firstItem(); item; item= item->nextItem())    do_something_with(item);

The item's icon view is available fromiconView(), and its position in the icon view fromindex().

The item's selection status is available fromisSelected() and is set and controlled bysetSelected() andisSelectable().

The text and icon can be set withsetText() andsetPixmap() and retrieved withtext() andpixmap(). The item's sort key defaults totext() but may be set withsetKey() and retrieved withkey(). The comparison function,compare() useskey().

Items may be repositioned withmove() andmoveBy(). An item's geometry is available fromrect(),x(),y(),width(),height(),size(),pos(),textRect() andpixmapRect(). You can also test against the position of a point withcontains() andintersects().

To remove an item from an icon view, just delete the item. TheQ3IconViewItem destructor removes it cleanly from its icon view.

Because the icon view is designed to use drag-and-drop, the icon view item also has functions for drag-and-drop which may be reimplemented.

The class is designed to be very similar toQ3ListView andQ3ListBox in use, both via instantiation and subclassing.

Member Function Documentation

Q3IconViewItem::Q3IconViewItem(Q3IconView * parent)

Constructs aQ3IconViewItem and inserts it into icon viewparent with no text and a default icon.

Q3IconViewItem::Q3IconViewItem(Q3IconView * parent,Q3IconViewItem * after)

Constructs aQ3IconViewItem and inserts it into the icon viewparent with no text and a default icon, after the icon view itemafter.

Q3IconViewItem::Q3IconViewItem(Q3IconView * parent, constQString & text)

Constructs an icon view item and inserts it into the icon viewparent usingtext as the text and a default icon.

Q3IconViewItem::Q3IconViewItem(Q3IconView * parent,Q3IconViewItem * after, constQString & text)

Constructs an icon view item and inserts it into the icon viewparent usingtext as the text and a default icon, after the icon view itemafter.

Q3IconViewItem::Q3IconViewItem(Q3IconView * parent, constQString & text, constQPixmap & icon)

Constructs an icon view item and inserts it into the icon viewparent usingtext as the text andicon as the icon.

Q3IconViewItem::Q3IconViewItem(Q3IconView * parent,Q3IconViewItem * after, constQString & text, constQPixmap & icon)

Constructs an icon view item and inserts it into the icon viewparent usingtext as the text andicon as the icon, after the icon view itemafter.

Q3IconViewItem::Q3IconViewItem(Q3IconView * parent, constQString & text, constQPicture & picture)

Constructs an icon view item and inserts it into the icon viewparent usingtext as the text andpicture as the icon.

Q3IconViewItem::Q3IconViewItem(Q3IconView * parent,Q3IconViewItem * after, constQString & text, constQPicture & picture)

Constructs an icon view item and inserts it into the icon viewparent usingtext as the text andpicture as the icon, after the icon view itemafter.

[virtual]Q3IconViewItem::~Q3IconViewItem()

Destroys the icon view item and tells the parent icon view that the item has been destroyed.

[virtual]bool Q3IconViewItem::acceptDrop(constQMimeSource * mime) const

Returns true if you can drop things with a QMimeSource ofmime onto this item; otherwise returns false.

The default implementation always returns false. You must subclassQ3IconViewItem and reimplement acceptDrop() to accept drops.

[virtual protected]void Q3IconViewItem::calcRect(constQString & text_ = QString())

This virtual function is responsible for calculating the rectangles returned byrect(),textRect() andpixmapRect(). setRect(),setTextRect() andsetPixmapRect() are provided mainly for reimplementations of this function.

text_ is an internal parameter which defaults to an empty string.

[virtual]int Q3IconViewItem::compare(Q3IconViewItem * i) const

Compares this icon view item toi. Returns -1 if this item is less thani, 0 if they are equal, and 1 if this icon view item is greater thani.

The default implementation compares the item keys (key()) usingQString::localeAwareCompare(). A reimplementation may use different values and a different comparison function. Here is a reimplementation that uses plain Unicode comparison:

int MyIconViewItem::compare(Q3IconViewItem*i)const{return key().compare(i->key());}

See alsokey(),QString::localeAwareCompare(), andQString::compare().

bool Q3IconViewItem::contains(constQPoint & pnt) const

Returns true if the item contains the pointpnt (in contents coordinates); otherwise returns false.

bool Q3IconViewItem::dragEnabled() const

Returns true if the user is allowed to drag the icon view item; otherwise returns false.

See alsosetDragEnabled().

[virtual protected]void Q3IconViewItem::dragEntered()

This function is called when a drag enters the item's bounding rectangle.

The default implementation does nothing; subclasses may reimplement this function.

[virtual protected]void Q3IconViewItem::dragLeft()

This function is called when a drag leaves the item's bounding rectangle.

The default implementation does nothing; subclasses may reimplement this function.

bool Q3IconViewItem::dropEnabled() const

Returns true if the user is allowed to drop something onto the item; otherwise returns false.

See alsosetDropEnabled().

[virtual protected]void Q3IconViewItem::dropped(QDropEvent * e, constQ3ValueList<Q3IconDragItem> & lst)

This function is called when something is dropped on the item.e provides all the information about the drop. If the drag object of the drop was aQ3IconDrag,lst contains the list of the dropped items. You can get the data by callingQ3IconDragItem::data() on each item. If thelst is empty, i.e. the drag was not aQ3IconDrag, you must decode the data ine and work with that.

The default implementation does nothing; subclasses may reimplement this function.

int Q3IconViewItem::height() const

Returns the height of the item.

Q3IconView * Q3IconViewItem::iconView() const

Returns a pointer to this item's icon view parent.

int Q3IconViewItem::index() const

Returns the index of this item in the icon view, or -1 if an error occurred.

bool Q3IconViewItem::intersects(constQRect & r) const

Returns true if the item intersects the rectangler (in contents coordinates); otherwise returns false.

bool Q3IconViewItem::isSelectable() const

Returns true if the item is selectable; otherwise returns false.

See alsosetSelectable().

bool Q3IconViewItem::isSelected() const

Returns true if the item is selected; otherwise returns false.

See alsosetSelected().

[virtual]QString Q3IconViewItem::key() const

Returns the key of the icon view item ortext() if no key has been explicitly set.

See alsosetKey() andcompare().

[virtual]bool Q3IconViewItem::move(int x,int y)

Moves the item to position (x,y) in the icon view (these are contents coordinates). Returns true if the item is moved. Returns false if the item is already at the specified position.

[virtual]bool Q3IconViewItem::move(constQPoint & pnt)

This is an overloaded function.

Moves the item to the pointpnt.

[virtual]void Q3IconViewItem::moveBy(int dx,int dy)

Moves the itemdx pixels in the x-direction anddy pixels in the y-direction.

[virtual]void Q3IconViewItem::moveBy(constQPoint & pnt)

This is an overloaded function.

Moves the item by the x, y values in pointpnt.

Q3IconViewItem * Q3IconViewItem::nextItem() const

Returns a pointer to the next item, or 0 if this is the last item in the icon view.

To find the first item useQ3IconView::firstItem().

Example:

Q3IconViewItem*item;for (item= iconView->firstItem(); item; item= item->nextItem())    do_something_with(item);

See alsoprevItem().

[virtual protected]void Q3IconViewItem::paintFocus(QPainter * p, constQColorGroup & cg)

Paints the focus rectangle of the item using the painterp and the color groupcg.

[virtual protected]void Q3IconViewItem::paintItem(QPainter * p, constQColorGroup & cg)

Paints the item using the painterp and the color groupcg. If you want the item to be drawn with a different font or color, reimplement this function, change the values of the color group or the painter's font, and then call the Q3IconViewItem::paintItem() with the changed values.

[virtual]QPicture * Q3IconViewItem::picture() const

Returns the icon of the icon view item if it is a picture, or 0 if it is a pixmap. In the latter case usepixmap() instead. Normally you set the picture of the item withsetPicture(), but sometimes it's inconvenient to callsetPicture() for every item. So you can subclassQ3IconViewItem, reimplement this function and return a pointer to the item's picture. If you do this, youmust callcalcRect() manually each time the size of this picture changes.

See alsosetPicture().

[virtual]QPixmap * Q3IconViewItem::pixmap() const

Returns the icon of the icon view item if it is a pixmap, or 0 if it is a picture. In the latter case usepicture() instead. Normally you set the pixmap of the item withsetPixmap(), but sometimes it's inconvenient to callsetPixmap() for every item. So you can subclassQ3IconViewItem, reimplement this function and return a pointer to the item's pixmap. If you do this, youmust callcalcRect() manually each time the size of this pixmap changes.

See alsosetPixmap().

QRect Q3IconViewItem::pixmapRect(bool relative = true) const

Returns the bounding rectangle of the item's icon.

Ifrelative is true, (the default), the rectangle is relative to the origin of the item's rectangle. Ifrelative is false, the returned rectangle is relative to the origin of the icon view's contents coordinate system.

See alsosetPixmapRect().

QPoint Q3IconViewItem::pos() const

Returns the position of the item (in contents coordinates).

Q3IconViewItem * Q3IconViewItem::prevItem() const

Returns a pointer to the previous item, or 0 if this is the first item in the icon view.

See alsonextItem() andQ3IconView::firstItem().

QRect Q3IconViewItem::rect() const

Returns the bounding rectangle of the item (in contents coordinates).

[virtual protected]void Q3IconViewItem::removeRenameBox()

Removes the editbox that is used for in-place renaming.

void Q3IconViewItem::rename()

Starts in-place renaming of an icon, if allowed.

This function sets up the icon view so that the user can edit the item text, and then returns. When the user is done,setText() will be called andQ3IconView::itemRenamed() will be emitted (unless the user canceled, e.g. by pressing the Escape key).

See alsosetRenameEnabled().

bool Q3IconViewItem::renameEnabled() const

Returns true if the item can be renamed by the user with in-place renaming; otherwise returns false.

See alsosetRenameEnabled().

[virtual]void Q3IconViewItem::repaint()

Repaints the item.

[virtual]int Q3IconViewItem::rtti() const

Returns 0.

Make your derived classes return their own values for rtti(), so that you can distinguish between icon view item types. You should use values greater than 1000, preferably a large random number, to allow for extensions to this class.

[virtual]void Q3IconViewItem::setDragEnabled(bool allow)

Ifallow is true, the icon view permits the user to drag the icon view item either to another position within the icon view or to somewhere outside of it. Ifallow is false, the item cannot be dragged.

See alsodragEnabled().

[virtual]void Q3IconViewItem::setDropEnabled(bool allow)

Ifallow is true, the icon view lets the user drop something on this icon view item.

See alsodropEnabled().

[protected]void Q3IconViewItem::setItemRect(constQRect & r)

Sets the bounding rectangle of the whole item tor. This function is provided for subclasses which reimplementcalcRect(), so that they can set the calculated rectangle.Any other use is discouraged.

See alsocalcRect(),textRect(),setTextRect(),pixmapRect(), andsetPixmapRect().

[virtual]void Q3IconViewItem::setKey(constQString & k)

Setsk as the sort key of the icon view item. By defaulttext() is used for sorting.

See alsokey() andcompare().

[virtual]void Q3IconViewItem::setPicture(constQPicture & icon)

Setsicon as the item's icon in the icon view. This function might be a no-op if you reimplementpicture().

See alsopicture().

[virtual]void Q3IconViewItem::setPixmap(constQPixmap & icon)

Setsicon as the item's icon in the icon view. This function might be a no-op if you reimplementpixmap().

See alsopixmap().

[virtual]void Q3IconViewItem::setPixmap(constQPixmap & icon,bool recalc,bool redraw = true)

This is an overloaded function.

Setsicon as the item's icon in the icon view. Ifrecalc is true, the icon view's layout is recalculated. Ifredraw is true (the default), the icon view is repainted.

See alsopixmap().

[protected]void Q3IconViewItem::setPixmapRect(constQRect & r)

Sets the bounding rectangle of the item's icon tor. This function is provided for subclasses which reimplementcalcRect(), so that they can set the calculated rectangle.Any other use is discouraged.

See alsocalcRect(),pixmapRect(),setItemRect(), andsetTextRect().

[virtual]void Q3IconViewItem::setRenameEnabled(bool allow)

Ifallow is true, the user can rename the icon view item by clicking on the text (or pressing F2) while the item is selected (in-place renaming). Ifallow is false, in-place renaming is not possible.

See alsorenameEnabled().

[virtual]void Q3IconViewItem::setSelectable(bool enable)

Sets this item to be selectable ifenable is true (the default) or unselectable ifenable is false.

The user is unable to select a non-selectable item using either the keyboard or the mouse. (The application programmer can select an item in code regardless of this setting.)

See alsoisSelectable().

[virtual]void Q3IconViewItem::setSelected(bool s,bool cb)

Selects or unselects the item, depending ons; it may also unselect other items, depending onQ3IconView::selectionMode() andcb.

Ifs is false, the item is unselected.

Ifs is true andQ3IconView::selectionMode() isQ3IconView::Single, the item is selected and the item previously selected is unselected.

Ifs is true andQ3IconView::selectionMode() isQ3IconView::Extended, the item is selected. Ifcb is true, the selection state of the other items is left unchanged. Ifcb is false (the default) all other items are unselected.

Ifs is true andQ3IconView::selectionMode() isQ3IconView::Multi, the item is selected.

Note thatcb is used only ifQ3IconView::selectionMode() isQ3IconView::Extended; cb defaults to false.

All items whose selection status changes repaint themselves.

See alsoisSelected().

[virtual]void Q3IconViewItem::setSelected(bool s)

This is an overloaded function.

This variant is equivalent to calling the other variant withcb set to false.

[virtual]void Q3IconViewItem::setText(constQString & text)

Setstext as the text of the icon view item. This function might be a no-op if you reimplementtext().

See alsotext().

[virtual]void Q3IconViewItem::setText(constQString & text,bool recalc,bool redraw = true)

This is an overloaded function.

Setstext as the text of the icon view item. Ifrecalc is true, the icon view's layout is recalculated. Ifredraw is true (the default), the icon view is repainted.

See alsotext().

[protected]void Q3IconViewItem::setTextRect(constQRect & r)

Sets the bounding rectangle of the item's text tor. This function is provided for subclasses which reimplementcalcRect(), so that they can set the calculated rectangle.Any other use is discouraged.

See alsocalcRect(),textRect(),setItemRect(), andsetPixmapRect().

QSize Q3IconViewItem::size() const

Returns the size of the item.

[virtual]QString Q3IconViewItem::text() const

Returns the text of the icon view item. Normally you set the text of the item withsetText(), but sometimes it's inconvenient to callsetText() for every item; so you can subclassQ3IconViewItem, reimplement this function, and return the text of the item. If you do this, you must callcalcRect() manually each time the text (and therefore its size) changes.

See alsosetText().

QRect Q3IconViewItem::textRect(bool relative = true) const

Returns the bounding rectangle of the item's text.

Ifrelative is true, (the default), the returned rectangle is relative to the origin of the item's rectangle. Ifrelative is false, the returned rectangle is relative to the origin of the icon view's contents coordinate system.

See alsosetTextRect().

int Q3IconViewItem::width() const

Returns the width of the item.

int Q3IconViewItem::x() const

Returns the x-coordinate of the item (in contents coordinates).

int Q3IconViewItem::y() const

Returns the y-coordinate of the item (in contents coordinates).