KListView Class Reference

This Widget extends the functionality of QListView to honor the system wide settings for Single Click/Double Click mode, AutoSelection and ChangeCursorOverLink (TM). More...

#include <klistview.h>

Inheritance diagram for KListView:

[legend]Collaboration diagram for KListView:

[legend]List of all members.


Public Types
enum	SelectionModeExt { Single = QListView::Single, Multi = QListView::Multi, Extended = QListView::Extended, NoSelection = QListView::NoSelection, FileManager }
Public Slots
virtual void	rename (QListViewItem *item, int c)
void	setRenameable (int column, bool yesno=true)
virtual void	setItemsMovable (bool b)
virtual void	setItemsRenameable (bool b)
virtual void	setDragEnabled (bool b)
virtual void	setAutoOpen (bool b)
virtual void	setDropVisualizer (bool b)
void	setDropVisualizerWidth (int w)
virtual void	setTooltipColumn (int column)
virtual void	setDropHighlighter (bool b)
virtual void	setCreateChildren (bool b) KDE_DEPRECATED
void	setSelectionModeExt (SelectionModeExt mode)
void	setTabOrderedRenaming (bool b)
bool	tabOrderedRenaming () const
Signals
void	executed (QListViewItem *item)
void	executed (QListViewItem *item, const QPoint &pos, int c)
void	dropped (QDropEvent e, QListViewItem after)
void	dropped (KListView list, QDropEvent e, QListViewItem *after)
void	dropped (KListView list, QDropEvent e, QListViewItem parent, QListViewItem after)
void	dropped (QDropEvent e, QListViewItem parent, QListViewItem *after)
void	moved ()
void	aboutToMove ()
void	moved (QListViewItem item, QListViewItem afterFirst, QListViewItem *afterNow)
void	moved (QPtrList< QListViewItem > &items, QPtrList< QListViewItem > &afterFirst, QPtrList< QListViewItem > &afterNow)
void	itemRenamed (QListViewItem *item, const QString &str, int col)
void	itemRenamed (QListViewItem *item)
void	menuShortCutPressed (KListView list, QListViewItem item)
void	contextMenu (KListView l, QListViewItem i, const QPoint &p)
void	itemAdded (QListViewItem *item)
void	itemRemoved (QListViewItem *item)
Public Member Functions
	KListView (QWidget parent=0, const char name=0)
virtual	~KListView ()
virtual void	setAcceptDrops (bool)
virtual bool	isExecuteArea (const QPoint &point)
bool	isExecuteArea (int x)
QPtrList< QListViewItem >	selectedItems () const
QPtrList< QListViewItem >	selectedItems (bool includeHiddenItems) const
void	moveItem (QListViewItem item, QListViewItem parent, QListViewItem *after)
QListViewItem *	lastItem () const
QListViewItem *	lastChild () const
KLineEdit *	renameLineEdit () const
bool	itemsMovable () const
bool	itemsRenameable () const
bool	dragEnabled () const
bool	autoOpen () const
bool	isRenameable (int column) const
bool	dropVisualizer () const
int	tooltipColumn () const
bool	createChildren () const KDE_DEPRECATED
bool	dropHighlighter () const
int	dropVisualizerWidth () const
SelectionModeExt	selectionModeExt () const
int	itemIndex (const QListViewItem *item) const
QListViewItem *	itemAtIndex (int index)
void	setFullWidth () KDE_DEPRECATED
void	setFullWidth (bool fullWidth)
bool	fullWidth () const
virtual int	addColumn (const QString &label, int width=-1)
virtual int	addColumn (const QIconSet &iconset, const QString &label, int width=-1)
virtual void	removeColumn (int index)
void	setAlternateBackground (const QColor &c)
const QColor &	alternateBackground () const
void	saveLayout (KConfig *config, const QString &group) const
void	restoreLayout (KConfig *config, const QString &group)
virtual void	setSorting (int column, bool ascending=true)
int	columnSorted (void) const
bool	ascendingSort (void) const
virtual void	takeItem (QListViewItem *i)
void	setShadeSortColumn (bool shadeSortColumn)
bool	shadeSortColumn (void) const
Protected Slots
void	slotSettingsChanged (int)
void	slotMouseButtonClicked (int btn, QListViewItem *item, const QPoint &pos, int c)
void	doneEditing (QListViewItem *item, int row)
void	cleanDropVisualizer ()
void	cleanItemHighlighter ()
void	emitContextMenu (QListViewItem *, const QPoint &, int)
void	emitContextMenu (KListView , QListViewItem )
void	slotOnItem (QListViewItem *item)
void	slotOnViewport ()
void	slotAutoSelect ()
void	slotDragExpand ()
void	slotHeaderChanged ()
Protected Member Functions
bool	below (const QRect &rect, const QPoint &p)
bool	below (QListViewItem *i, const QPoint &p)
virtual bool	event (QEvent *)
void	emitExecute (QListViewItem *item, const QPoint &pos, int c)
virtual void	focusInEvent (QFocusEvent *fe)
virtual void	focusOutEvent (QFocusEvent *fe)
virtual void	leaveEvent (QEvent *e)
virtual QString	tooltip (QListViewItem *item, int column) const
virtual bool	showTooltip (QListViewItem *item, const QPoint &pos, int column) const
virtual void	contentsDragMoveEvent (QDragMoveEvent *event)
virtual void	contentsMousePressEvent (QMouseEvent *e)
virtual void	contentsMouseMoveEvent (QMouseEvent *e)
virtual void	contentsMouseDoubleClickEvent (QMouseEvent *e)
virtual void	contentsDragLeaveEvent (QDragLeaveEvent *event)
virtual void	contentsMouseReleaseEvent (QMouseEvent *)
virtual void	contentsDropEvent (QDropEvent *)
virtual void	contentsDragEnterEvent (QDragEnterEvent *)
virtual QDragObject *	dragObject ()
virtual bool	acceptDrag (QDropEvent *event) const
virtual QRect	drawDropVisualizer (QPainter p, QListViewItem parent, QListViewItem *after)
virtual QRect	drawItemHighlighter (QPainter painter, QListViewItem item)
virtual void	startDrag ()
virtual void	keyPressEvent (QKeyEvent *)
virtual void	viewportPaintEvent (QPaintEvent *)
void	activateAutomaticSelection ()
void	deactivateAutomaticSelection ()
bool	automaticSelection () const
virtual void	viewportResizeEvent (QResizeEvent *e)
void	disableAutoSelection ()
void	resetAutoSelection ()
void	doubleClicked (QListViewItem *item, const QPoint &pos, int c)
virtual void	movableDropEvent (QListViewItem parent, QListViewItem afterme)
virtual void	findDrop (const QPoint &pos, QListViewItem &parent, QListViewItem &after)
void	fileManagerKeyPressEvent (QKeyEvent *)
int	depthToPixels (int depth)
virtual void	virtual_hook (int id, void *data)
Properties
bool	fullWidth
bool	itemsMovable
bool	itemsRenameable
bool	dragEnabled
bool	autoOpen
bool	dropVisualizer
int	tooltipColumn
int	dropVisualizerWidth
QColor	alternateBackground
bool	shadeSortColumn
Friends
class	KListViewItem

Detailed Description

This Widget extends the functionality of QListView to honor the system wide settings for Single Click/Double Click mode, AutoSelection and ChangeCursorOverLink (TM).

There is a new signal executed(). It gets connected to either QListView::clicked() or QListView::doubleClicked() depending on the KDE wide Single Click/Double Click settings. It is strongly recommended that you use this signal instead of the above mentioned. This way you don�t need to care about the current settings. If you want to get informed when the user selects something connect to the QListView::selectionChanged() signal.

Drag-and-Drop is supported with the signal dropped(), just setAcceptDrops(true) and connect it to a suitable slot. To see where you are dropping, setDropVisualizer(true). And also you'll need acceptDrag(QDropEvent*)

KListView is drag-enabled, too: to benefit from that you've got derive from it. Reimplement dragObject() and (possibly) startDrag(), and setDragEnabled(true).

Definition at line 53 of file klistview.h.

Member Enumeration Documentation

enum KListView::SelectionModeExt

Possible selection modes.
The first four correspond directly to QListView::SelectionMode, while the FileManager selection mode is defined as follows:

home: move to the first

end: move to the last

PgUp/PgDn: move one page up/down

up/down: move one item up/down

insert: toggle selection of current and move to the next

space: toggle selection of the current

CTRL+up: move to the previous item and toggle selection of this one

CTRL+down: toggle selection of the current item and move to the next

CTRL+end: toggle selection from (including) the current item to (including) the last item

CTRL+home: toggle selection from (including) the current item to the (including) the first item

CTRL+PgDn: toggle selection from (including) the current item to (excluding) the item one page down

CTRL+PgUp: toggle selection from (excluding) the current item to (including) the item one page up

The combinations work the same with SHIFT instead of CTRL, except that if you start selecting something using SHIFT everything selected before will be deselected first.
Additionally the current item is always selected automatically when navigating using the keyboard, except other items were selected explicitly.
This way e.g. SHIFT+up/PgUp then SHIFT+down/PgDn leaves no item selected
Definition at line 104 of file klistview.h.

Constructor & Destructor Documentation

KListView::KListView ( QWidget * parent = 0,

const char * name = 0

)

Constructor.
The parameters parent and name are handled by QListView, as usual.
Definition at line 410 of file klistview.cpp.
References KGlobalSettings::alternateBackgroundColor(), cleanDropVisualizer(), cleanItemHighlighter(), emitContextMenu(), menuShortCutPressed(), QListView::onItem(), QListView::onViewport(), slotAutoSelect(), slotOnItem(), slotOnViewport(), and slotSettingsChanged().

KListView::~KListView ( ) [virtual]

Destructor.

Definition at line 455 of file klistview.cpp.

Member Function Documentation

void KListView::setAcceptDrops ( bool ) [virtual]

Reimplemented for internal reasons.
Further reimplementations should call this function or else some features may not work correctly.
The API is unaffected.
Definition at line 1893 of file klistview.cpp.

bool KListView::isExecuteArea ( const QPoint & point ) [virtual]

This function determines whether the given coordinates are within the execute area.
The execute area is the part of a QListViewItem where mouse clicks or double clicks respectively generate a executed() signal. Depending on QListView::allColumnsShowFocus() this is either the whole item or only the first column.
Returns:
true if point is inside execute area of an item, false in all other cases including the case that it is over the viewport.

Definition at line 460 of file klistview.cpp.
References QListView::itemAt().
Referenced by contentsDragMoveEvent(), contentsMouseMoveEvent(), emitExecute(), isExecuteArea(), and slotOnItem().

bool KListView::isExecuteArea ( int x )

Same thing, but from an x coordinate only.
This only checks if x is in the first column (if all columns don't show focus), without testing if the y coordinate is over an item or not.
Definition at line 470 of file klistview.cpp.
References isExecuteArea().

QPtrList< QListViewItem > KListView::selectedItems ( ) const

Returns:
a list containing the currently selected items.

Deprecated:

Definition at line 1205 of file klistview.cpp.
Referenced by fileManagerKeyPressEvent().

QPtrList< QListViewItem > KListView::selectedItems ( bool includeHiddenItems ) const

Returns:
a list containing the currently selected items.

Parameters:

includeHiddenItems Set to true to return all items regardless of visibility. Set to false to only return items that are isVisible().

Returns:
a list of all selected listview items

Since:
3.4

Definition at line 1210 of file klistview.cpp.
References QPtrList::append(), QListViewItemIterator::current(), QListView::selectedItem(), and QListView::selectionMode().

void KListView::moveItem ( QListViewItem * item,

QListViewItem * parent,

QListViewItem * after

)

Arbitrarily move item to parent, positioned immediately after item after.
If after is 0, item is made the first child of parent.
(Un-deprecated in kde-3.4)
Definition at line 1247 of file klistview.cpp.
References QListView::insertItem(), QListViewItem::insertItem(), QListViewItem::moveItem(), QListViewItem::parent(), takeItem(), and QListViewItem::takeItem().
Referenced by movableDropEvent().

QListViewItem * KListView::lastItem ( ) const

Returns:
the last item (not child!) of this listview.

See also:
lastChild()

Reimplemented from QListView.
Definition at line 1119 of file klistview.cpp.
References lastChild().
Referenced by findDrop().

QListViewItem * KListView::lastChild ( ) const

Returns:
the last child of this listview.

See also:
lastItem()

Definition at line 1109 of file klistview.cpp.
References QListView::firstChild(), and QListViewItem::nextSibling().
Referenced by lastItem().

KLineEdit * KListView::renameLineEdit ( ) const

Returns:
the lineedit used for inline renaming. Use that to setup a KCompletion or QValidator for the lineedit

Since:
3.2

Definition at line 1129 of file klistview.cpp.

bool KListView::itemsMovable ( ) const

Returns:
if it is legal to move items in the list view. True by default.

See also:
setDragEnabled()
setItemsMovable()

Referenced by acceptDrag(), and contentsDropEvent().

bool KListView::itemsRenameable ( ) const

Returns:
whether inplace-renaming has been enabled. False by default.

See also:
setItemsRenameable()

bool KListView::dragEnabled ( ) const

Returns:
whether dragging is enabled. False by default.

See also:
setDragEnabled()

Referenced by contentsMouseMoveEvent().

bool KListView::autoOpen ( ) const

Returns:
true if AutoOpen is enabled (not implemented currently).

See also:
setAutoOpen()

bool KListView::isRenameable ( int column ) const

Returns:
true if column is renamable.

See also:
setRenameable()

Definition at line 1370 of file klistview.cpp.
References QRect::contains().

bool KListView::dropVisualizer ( ) const

Returns:
true if drawing of the drop-visualizer has been enabled. True by default.

See also:
setDropVisualizer()

Referenced by contentsDragMoveEvent().

int KListView::tooltipColumn ( ) const

Returns:
the column for which tooltips are displayed (or -1 if none set).

See also:
setTooltipColumn()

Referenced by showTooltip().

bool KListView::createChildren ( ) const

For future expansions.
Do not use.

Deprecated:

Definition at line 1400 of file klistview.cpp.

bool KListView::dropHighlighter ( ) const

Returns:
true if drawing of the drop-highlighter has been enabled. False by default.

See also:
setDropHighlighter()

Definition at line 1421 of file klistview.cpp.
Referenced by contentsDragMoveEvent().

int KListView::dropVisualizerWidth ( ) const

The dropVisualizerWidth defaults to 4.

See also:
setDropVisualizerWidth()

Returns:
the current width of the drop-visualizer.

KListView::SelectionModeExt KListView::selectionModeExt ( ) const

Returns:
the "extended" selection mode of this listview.

See also:
SelectionModeExt
setSelectionModeExt

Definition at line 1836 of file klistview.cpp.
Referenced by contentsMousePressEvent().

int KListView::itemIndex ( const QListViewItem * item ) const

Returns the index of item within the item tree or -1 if item doesn't exist in this list view.
This function takes all items into account not only the visible ones.
Definition at line 1841 of file klistview.cpp.
References QListViewItemIterator::current(), and QListView::firstChild().
Referenced by slotAutoSelect().

QListViewItem * KListView::itemAtIndex ( int index )

Returns the item of index within the item tree or 0 if index doesn't exist in this list view.
This function takes all items into account not only the visible ones.
Definition at line 1860 of file klistview.cpp.
References QListView::firstChild().

void KListView::setFullWidth ( )

Deprecated:

See also:
setFullWidth()

Definition at line 1932 of file klistview.cpp.

void KListView::setFullWidth ( bool fullWidth )

Let the last column fit exactly all the available width.

See also:
fullWidth()

Definition at line 1937 of file klistview.cpp.
References QListView::columns(), and QListView::header().

bool KListView::fullWidth ( ) const

Returns whether the last column is set to fit the available width.

See also:
setFullWidth()

int KListView::addColumn ( const QString & label,

int width = -1

) [virtual]

Reimplemented for full width support.

See also:
removeColumn()

Reimplemented from QListView.
Definition at line 1948 of file klistview.cpp.
References QListView::addColumn(), QListView::columns(), and QListView::header().
Referenced by KJanusWidget::KJanusWidget().

int KListView::addColumn ( const QIconSet & iconset,

const QString & label,

int width = -1

) [virtual]

Reimplemented for full width support.

Reimplemented from QListView.
Definition at line 1958 of file klistview.cpp.
References QListView::addColumn(), QListView::columns(), and QListView::header().

void KListView::removeColumn ( int index ) [virtual]

Reimplemented for full width support.

See also:
addColumn()

Reimplemented from QListView.
Definition at line 1968 of file klistview.cpp.
References QListView::columns(), QListView::header(), and QListView::removeColumn().

void KListView::setAlternateBackground ( const QColor & c )

sets the alternate background background color.
This only has an effect if the items are KListViewItems

Parameters:

c the color to use for every other item. Set to an invalid color to disable alternate colors.

See also:
alternateBackground()

Definition at line 1984 of file klistview.cpp.

const QColor& KListView::alternateBackground ( ) const

Returns:
the alternate background color

See also:
setAlternateBackground()

void KListView::saveLayout ( KConfig * config,

const QString & group

) const

Saves the list view's layout (column widtsh, column order, sort column) to a KConfig group.

Parameters:

config the KConfig object to write to

group the config group to use

Definition at line 2001 of file klistview.cpp.
References QListView::columns(), QListView::columnWidth(), QListView::header(), QHeader::mapToIndex(), and QString::number().

void KListView::restoreLayout ( KConfig * config,

const QString & group

)

Reads the list view's layout from a KConfig group as stored with saveLayout.

Parameters:

config the KConfig object to read from

group the config group to use

Definition at line 2019 of file klistview.cpp.
References QListView::columns(), QListView::header(), QListView::setColumnWidth(), and setSorting().

void KListView::setSorting ( int column,

bool ascending = true

) [virtual]

Reimplemented to remember the current sort column and order.

Parameters:

column is the column to be sorted, or -1 to sort in order of insertion

ascending whether to sort ascending (or descending)

Reimplemented from QListView.
Definition at line 2054 of file klistview.cpp.
References QListView::ensureItemVisible(), QListView::firstChild(), QListViewItem::isSelected(), QListViewItem::isVisible(), QListViewItem::itemBelow(), KListViewItem::m_known, QListView::selectedItem(), QListView::selectionMode(), and QListView::setSorting().
Referenced by KJanusWidget::KJanusWidget(), and restoreLayout().

int KListView::columnSorted ( void ) const

Returns:
the currently sorted column, or -1 if none is sorted

Definition at line 2087 of file klistview.cpp.
Referenced by KListViewItem::backgroundColor().

bool KListView::ascendingSort ( void ) const

Returns:
whether the current sort is ascending (or descending)

Definition at line 2092 of file klistview.cpp.

void KListView::takeItem ( QListViewItem * i ) [virtual]

Reimplemented for internal reasons.

Reimplemented from QListView.
Definition at line 2097 of file klistview.cpp.
References QListView::takeItem().
Referenced by moveItem().

void KListView::setShadeSortColumn ( bool shadeSortColumn )

Set to true if the currently sorted column should be drawn shaded.
Defaults to true
Parameters:

shadeSortColumn True if sort column should be shaded.

Since:
3.4

Definition at line 1990 of file klistview.cpp.

bool KListView::shadeSortColumn ( void ) const

See if the sort column should be drawn shaded.

Returns:
true if the sort column should be shaded

Since:
3.4

void KListView::executed ( QListViewItem * item ) [signal]

This signal is emitted whenever the user executes an listview item.
That means depending on the KDE wide Single Click/Double Click setting the user clicked or double clicked on that item.
Parameters:

item is the pointer to the executed listview item.

Note that you may not delete any QListViewItem objects in slots connected to this signal.
Referenced by emitExecute().

void KListView::executed ( QListViewItem * item,

const QPoint & pos,

int c

) [signal]

This signal is emitted whenever the user executes an listview item.
That means depending on the KDE wide Single Click/Double Click setting the user clicked or double clicked on that item.
Parameters:

item is the pointer to the executed listview item.

pos is the position where the user has clicked

c is the column into which the user clicked.

Note that you may not delete any QListViewItem objects in slots connected to this signal.

void KListView::dropped ( QDropEvent * e,

QListViewItem * after

) [signal]

This signal gets emitted whenever something acceptable is dropped onto the listview.

Parameters:

e is the drop event itself (it has already been accepted)

after is the item after which the drop occurred (or 0L, if the drop was above all items)

See also:
acceptDrop()

Reimplemented in KFileTreeView.
Referenced by contentsDropEvent().

void KListView::dropped ( KListView * list,

QDropEvent * e,

QListViewItem * after

) [signal]

This signal gets emitted whenever something acceptable is dropped onto the listview.
This is an overloaded version of the above (provided to simplify processing drops outside of the class).

Parameters:

list is the listview

e is the drop event itself (it has already been accepted)

after is the item after which the drop occurred (or 0L, if the drop was above all items

void KListView::dropped ( KListView * list,

QDropEvent * e,

QListViewItem * parent,

QListViewItem * after

) [signal]

This signal gets emitted whenever something acceptable is dropped onto the listview.
This function also provides a parent, in the event that your listview is a tree
Parameters:

list is the listview

e is the drop event itself (it has already been accepted)

parent the item that is to be the parent of the new item

after is the item after which the drop occurred (or 0L, if the drop was above all items

void KListView::dropped ( QDropEvent * e,

QListViewItem * parent,

QListViewItem * after

) [signal]

This signal gets emitted whenever something acceptable is dropped onto the listview.
This function also provides a parent, in the event that your listview is a tree
Parameters:

e is the drop event itself (it has already been accepted)

parent the item that is to be the parent of the new item

after is the item after which the drop occurred (or 0L, if the drop was above all items

Reimplemented in KFileTreeView.

void KListView::moved ( ) [signal]

This signal is emitted when ever the user moves an item in the list via DnD.
If more than one item is moved at the same time, this signal is only emitted once.
Referenced by movableDropEvent(), and startDrag().

void KListView::aboutToMove ( ) [signal]

Connect to this signal if you want to do some preprocessing before a move is made, for example, to disable sorting.
This is sent only once per each groups of moves. That is, for each drop that is a move this will be emitted once, before KListView calls
See also:
moveItem()

Referenced by movableDropEvent().

void KListView::moved ( QListViewItem * item,

QListViewItem * afterFirst,

QListViewItem * afterNow

kdeui Library API Documentation

KListView Class Reference

Public Types

Public Slots

Signals

Public Member Functions

Protected Slots

Protected Member Functions

Properties

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation