KItemListView(QGraphicsWidget* parent = 0);
virtual ~KItemListView();
+ /**
+ * If the scroll-orientation is vertical, the items are ordered
+ * from top to bottom (= default setting). If the scroll-orientation
+ * is horizontal, the items are ordered from left to right.
+ */
void setScrollOrientation(Qt::Orientation orientation);
Qt::Orientation scrollOrientation() const;
void setItemSize(const QSizeF& size);
QSizeF itemSize() const;
- // TODO: add note that offset is not checked against maximumOffset, only against 0.
+ /**
+ * Offset of the scrollbar that represents the scroll-orientation
+ * (see setScrollOrientation()).
+ */
void setScrollOffset(qreal offset);
qreal scrollOffset() const;
qreal maximumScrollOffset() const;
+ /**
+ * Offset related to an item, that does not fit into the available
+ * size of the listview. If the scroll-orientation is vertical
+ * the item-offset describes the offset of the horizontal axe, if
+ * the scroll-orientation is horizontal the item-offset describes
+ * the offset of the vertical axe.
+ */
void setItemOffset(qreal scrollOffset);
qreal itemOffset() const;
/**
* @return Model of the item-list. The model gets
- * initialized by KItemListController::setView() and will
+ * initialized by KItemListController::setModel() and will
* result in calling KItemListController::onModelChanged().
*/
KItemModelBase* model() const;
/** @reimp */
virtual void setGeometry(const QRectF& rect);
+ /**
+ * @return Index of the item that is below the point \a pos.
+ * The position is relative to the upper right of
+ * the visible area. Only (at least partly) visible
+ * items are considered. -1 is returned if no item is
+ * below the position.
+ */
int itemAt(const QPointF& pos) const;
bool isAboveSelectionToggle(int index, const QPointF& pos) const;
bool isAboveExpansionToggle(int index, const QPointF& pos) const;
+ /**
+ * @return Index of the first item that is at least partly visible.
+ * -1 is returned if the model contains no items.
+ */
int firstVisibleIndex() const;
+
+ /**
+ * @return Index of the last item that is at least partly visible.
+ * -1 is returned if the model contains no items.
+ */
int lastVisibleIndex() const;
/**
/**
* @param itemRanges Items that must be checked for getting the visible roles sizes.
- * @return The size of each visible role in case if KItemListView::itemSize()
- * is empty. This allows to have dynamic but equal role sizes between
- * all items. Per default an empty hash is returned.
+ * @return The size of each visible role in case if KItemListView::itemSize()
+ * is empty. This allows to have dynamic but equal role sizes between
+ * all items, like used in the classic "table-views". Per default an
+ * empty hash is returned.
*/
virtual QHash<QByteArray, QSizeF> visibleRolesSizes(const KItemRangeList& itemRanges) const;
/**
- * @return True if the view supports the expanding of items. Per default false
- * is returned. If expanding of items is supported, the methods
- * KItemModelBase::setExpanded(), KItemModelBase::isExpanded() and
- * KItemModelBase::isExpandable() must be reimplemented. The view-implementation
- * has to take care itself how to visually represent the expanded items provided
- * by the model.
+ * If set to true, items having child-items can be expanded to show the child-items as
+ * part of the view. Per default the expanding of items is is disabled. If expanding of
+ * items is enabled, the methods KItemModelBase::setExpanded(), KItemModelBase::isExpanded(),
+ * KItemModelBase::isExpandable() and KItemModelBase::expandedParentsCount()
+ * must be reimplemented. The view-implementation
+ * has to take care itself how to visually represent the expanded items provided
+ * by the model.
*/
- virtual bool supportsItemExpanding() const;
+ void setSupportsItemExpanding(bool supportsExpanding);
+ bool supportsItemExpanding() const;
/**
* @return The rectangle of the item relative to the top/left of
/**
* Turns on the header if \p show is true. Per default the
- * header is not shown.
+ * header is not shown. Usually the header is turned on when
+ * showing a classic "table-view" to describe the shown columns.
*/
void setHeaderShown(bool show);
bool isHeaderShown() const;
*/
void sortRoleChanged(const QByteArray& current, const QByteArray& previous);
+ /**
+ * Is emitted if the user has changed the visible roles by moving a header
+ * item (see KItemListView::setHeaderShown()). Note that no signal will be
+ * emitted if the roles have been changed without user interaction by
+ * KItemListView::setVisibleRoles().
+ */
+ void visibleRolesChanged(const QList<QByteArray>& current, const QList<QByteArray>& previous);
+
protected:
virtual void initializeItemListWidget(KItemListWidget* item);
virtual void onScrollOffsetChanged(qreal current, qreal previous);
virtual void onVisibleRolesChanged(const QList<QByteArray>& current, const QList<QByteArray>& previous);
virtual void onStyleOptionChanged(const KItemListStyleOption& current, const KItemListStyleOption& previous);
+ virtual void onSupportsItemExpandingChanged(bool supportsExpanding);
virtual void onTransactionBegin();
virtual void onTransactionEnd();
qreal currentWidth,
qreal previousWidth);
+ /**
+ * Is invoked if a visible role has been moved by the user. Applies
+ * the moved role to the view.
+ */
+ void slotVisibleRoleMoved(const QByteArray& role,
+ int currentIndex,
+ int previousIndex);
+
/**
* Triggers the autoscrolling if autoScroll() is enabled by checking the
* current mouse position. If the mouse position is within the autoscroll
void recycleWidget(KItemListWidget* widget);
/**
- * Changes the index of the widget to \a index. The cell-information
- * for the widget gets reset and will be updated in the next doLayout().
+ * Changes the index of the widget to \a index and assures a consistent
+ * update for m_visibleItems and m_visibleCells. The cell-information
+ * for the new index will not be updated and be initialized as empty cell.
*/
void setWidgetIndex(KItemListWidget* widget, int index);
/**
* Changes the index of the widget to \a index. In opposite to
- * setWidgetIndex() the cell-information of the widget gets updated.
+ * setWidgetIndex() the cell-information for the widget gets updated.
* This update gives doLayout() the chance to animate the moving
* of the item visually (see moveWidget()).
*/
void updateWidgetProperties(KItemListWidget* widget, int index);
/**
- * Helper method for createWidget() and setWidgetIndex() to create or update
+ * Helper method for updateWidgetPropertes() to create or update
* the itemlist group-header.
*/
void updateGroupHeaderForWidget(KItemListWidget* widget);
*/
void updateVisibleGroupHeaders();
+ /**
+ * @return Index for the item in the list returned by KItemModelBase::groups()
+ * that represents the group where the item with the index \a index
+ * belongs to. -1 is returned if no groups are available.
+ */
+ int groupIndexForItem(int index) const;
+
+ /**
+ * Updates the alternateBackground-property of the widget dependent
+ * on the state of useAlternateBackgrounds() and the grouping state.
+ */
+ void updateAlternateBackgroundForWidget(KItemListWidget* widget);
+
+ /**
+ * @return True if alternate backgrounds should be used for the items.
+ * This is the case if an empty item-size is given and if there
+ * is more than one visible role.
+ */
+ bool useAlternateBackgrounds() const;
+
/**
* @return The widths of each visible role that is shown in the KItemListHeader.
*/
* if no header is shown.
*/
QRectF headerBoundaries() const;
-
+
/**
* @return True if the number of columns or rows will be changed when applying
* the new grid- and item-size. Used to determine whether an animation
bool changesItemGridLayout(const QSizeF& newGridSize,
const QSizeF& newItemSize,
const QSizeF& newItemMargin) const;
-
+
/**
* @param changedItemCount Number of inserted or removed items.
* @return True if the inserting or removing of items should be animated.
* value != 0 will be returned.
*/
static int calculateAutoScrollingIncrement(int pos, int range, int oldInc);
-
+
/**
* Helper functions for changesItemCount().
* @return The number of items that fit into the available size by
private:
bool m_enabledSelectionToggles;
bool m_grouped;
+ bool m_supportsItemExpanding;
int m_activeTransactions; // Counter for beginTransaction()/endTransaction()
LayoutAnimationHint m_endTransactionAnimationHint;
projects / dolphin.git / blobdiff