[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-devel
Subject: [PROPOSAL] New KListView
From: Sebastian Gottfried <sebastiangottfried () web ! de>
Date: 2006-03-15 16:33:42
Message-ID: 200603151733.42743.sebastiangottfried () web ! de
[Download RAW message or body]
Hi all,
After being a happy KDE user for a long time I thought now is the right time
to pay something back :)
In a recent thread Michaël Larouche mentioned KListView still needs to be
ported, so here comes my proposal for the new KlistView. First, I
think, it's wise to rename the class to KTreeView, because the new base class
will be QTreeView.
By using the model/view concept it should be possible to move the most
features of the old KListView into the models:
- the table headers and all the data editing features are now provided by the
model automatically. A feature I could imagine is column selecting by the
user like in firefox.
- for the column sorting the class should hold a own private
QSortFilterProxyModel (or a derived class) as a private member for reasonable
sorting, e.g. sorting number as numbers, not as strings
- drag and drop support is also complete, but a little a bit complicated. The
model can specify which items are dragable and/or dropable. The view only have
to specify if dropping and/or dragging is this view generally is allowed
- the search line widget could be easily incorporated, it must only take the
original model and expose the filtered model to KTreeView.
Questions:
What about FileManager selection mode. Is this really necessary? Or can the
defined keyboard strokes generally accessible (if the selection mode allows
it).
I have attached my first version of the class interface and I would like to
implement it after some discussion if no one objects.
Sebastian Gottfried
["ktreeview_proposal.h" (text/x-c++hdr)]
/* This file is part of the KDE libraries
Copyright (C) 2000 Reginald Stadlbauer <reggie@kde.org>
Copyright (C) 2000 Charles Samuels <charles@kde.org>
Copyright (C) 2000 Peter Putzer <putzer@kde.org>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License version 2 as published by the Free Software Foundation.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
*/
#ifndef KTREEVIEW_H
#define KTREEVIEW_H
#include <QTreeView>
#include <kdelibs_export.h>
/**
* This widget provides the KDE default tree view. Additional it could be used
* for a simple list with headers.
*
* 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
* QAbstractItemView::clicked() or QAbstractItemView::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.
*
* The widget obtains the data to display and nealy all behaviour settings from
* a model. For more information see QTreeView.
*
* It's recommended to use this widget in combination with the a KSearchLine
* widget, this enables the user to filter the view on the fly.
*
* So typically usecase could look like the following:
*
* KTreeView* view = new KTreeView(parent);
* KSearchLine* searchLine = new KSearchLine(parent);
*
* searchLine->setModel(model); // model is up to you
*
* view->setModel(searchLine->filteredModel());
*
* @see QTreeView, KSearchLine
*/
class KDEUI_EXPORT KTreeView : public QTreeView
{
/**
* Constructor.
*
* The parameter @p parent will be forwarded to QTreeView.
*/
KTreeView(QWidget* parent = 0);
/**
* Destructor.
*/
virtual ~KTreeView();
/**
* 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.
*
* @return true if point is inside execute area of an item, false in all
* other cases including the case that it is over the viewport.
*/
virtual bool isExecuteArea(const QPoint& point);
/**
* 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.
*/
bool isExecuteArea( int x );
/**
* @return true if AutoOpen is enabled (not implemented currently).
*
* @see setAutoOpen()
*/
bool autoOpen() const;
/**
* The dropVisualizerWidth defaults to 4.
*
* @see setDropVisualizerWidth()
* @return the current width of the drop-visualizer.
*/
int dropVisualizerWidth () const;
/**
* @return true if drawing of the drop-highlighter has been enabled. False by default.
*
* @see setDropHighlighter()
*/
bool dropHighlighter() const;
/**
* Let the last column fit exactly all the available width.
*
* @see fullWidth()
*/
void setFullWidth(bool fullWidth);
/**
* Returns whether the last column is set to fit the available width.
*
* @see setFullWidth()
*/
bool fullWidth() const;
/**
* Saves the list view's layout (column width, column order, sort column)
* to a KConfig group
*
* @param config the KConfig object to write to
* @param group the config group to use
*/
void saveLayout(KConfig *config, const QString &group) const;
/**
* Saves the list view's layout (column width, column order, sort column)
* to a KConfig group
*
* @param config the KConfigGroup object to write to
*/
void saveLayout(KConfigGroup & cg) const;
/**
* Reads the list view's layout from a KConfig group as stored with
* saveLayout
*
* @param config the KConfig object to read from
* @param group the config group to use
*/
void restoreLayout(KConfig *config, const QString &group);
/**
* Reads the list view's layout from a KConfig group as stored with
* saveLayout
*
* @param config the KConfigGroup object to write to
*/
void restoreLayout(KConfigGroup & cg);
/**
* Use this method to sort the tree view.
*
* @param column is the column to be sorted, or -1 to sort in order of
* insertion
* @param ascending whether to sort ascending (or descending)
*/
void setSorting(int column, bool ascending = true);
/**
* @return the currently sorted column, or -1 if none is sorted
*/
int columnSorted(void) const;
/**
* @return whether the current sort is ascending (or descending)
*/
bool ascendingSort(void) const;
/**
* Set to true if the currently sorted column should be drawn shaded. Defaults to true
*
* @param shadeSortColumn True if sort column should be shaded.
*/
void setShadeSortColumn(bool shadeSortColumn);
/**
* See if the sort column should be drawn shaded
* @return true if the sort column should be shaded
*/
bool shadeSortColumn(void) const;
Q_SIGNALS:
/**
* 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.
*
* @param index is an index to the executed listview item.
*/
void executed( const QModelIndex &index );
/**
* 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.
*
* @param index is an index to the executed listview item.
* @param pos is the position where the user has clicked
* @param c is the column into which the user clicked.
*/
void executed( const QModelIndex &index, const QPoint &pos, int c );
/**
* This signal is emitted when the shortcut key for popup-menus is pressed.
*
* Normally you should not use this, just connect a slot to signal
* contextMenu (KListView*, QListViewItem*, const QPoint&) to correctly
* handle showing context menus regardless of settings.
*
* @param list is this listview.
* @param item is the currentItem() at the time the key was pressed. May be 0L.
*/
void menuShortCutPressed (KListView* list, Q3ListViewItem* item);
/**
* This signal is emitted whenever a context-menu should be shown for item @p i.
* It automatically adjusts for all settings involved (Menu key, showMenuOnPress/Click).
*
* @param l is this listview.
* @param i is the item for which the menu should be shown. May be 0L.
* @param p is the point at which the menu should be shown.
*/
void contextMenu (KListView* l, Q3ListViewItem* i, const QPoint& p);
public Q_SLOTS:
/**
* Enable/Disable AutoOpen (not implemented currently).
*/
virtual void setAutoOpen(bool b);
/**
* Set the width of the (default) drop-visualizer.
* If you don't call this method, the width is set to 4.
*/
void setDropVisualizerWidth (int w);
/**
* Enable/Disable the drawing of a drop-highlighter
* (a rectangle around the item under the mouse cursor).
* It is disabled by default.
*/
virtual void setDropHighlighter(bool b);
protected:
/**
* Emit signal executed.
* @internal
*/
void emitExecute( Q3ListViewItem *item, const QPoint &pos, int c );
/**
* Paint the drag line. If painter is null, don't try to :)
*
* If after == 0 then the marker should be drawn at the top.
*
* @return the rectangle that you painted to.
*/
virtual QRect drawDropVisualizer (QPainter *p, const QModelIndex &parent, const QModelIndex &after);
/**
* Paint the drag rectangle. If painter is null, don't try to :)
*
*
* @return the rectangle that you painted to.
*/
virtual QRect drawItemHighlighter(QPainter *painter, const QModelIndex &item);
// Are the following three really needed ?
/**
* In FileManager selection mode: explicitly activate the mode
* in which the current item is automatically selected.
*/
void activateAutomaticSelection();
/**
* In FileManager selection mode: explicitly deactivate the mode
* in which the current item is automatically selected.
*/
void deactivateAutomaticSelection();
/**
* In FileManager selection mode: return whether it is currently in the mode
* where the current item is selected automatically.
* Returns false if items were selected explicitly, e.g. using the mouse.
*/
bool automaticSelection() const;
/**
* Reimplemented for setFullWidth()
*/
virtual void viewportResizeEvent(QResizeEvent* e);
/**
* Disable AutoSelection. This overrides the system wide setting for
* AutoSelection. Please don't call this unless you have good reasons to
* override the system wide setting for AutoSelection.
* @see resetAutoSelection()
* @since 3.2
*/
void disableAutoSelection();
/**
* Reset AutoSelection to the system wide setting.
* @see disableAutoSelection()
* @since 3.2
*/
void resetAutoSelection();
protected Q_SLOTS:
/**
* Update internal settings whenever the global ones change.
* @internal
*/
void slotSettingsChanged(int);
void slotMouseButtonClicked( int btn, Q3ListViewItem *item, const QPoint &pos, int c );
void doneEditing(Q3ListViewItem *item, int row);
/**
* Repaint the rect where I was drawing the drop line.
*/
void cleanDropVisualizer();
/**
* Repaint the rect where I was drawing the drop rectangle.
*/
void cleanItemHighlighter();
/**
* Emit the contextMenu signal. This slot is for mouse actions.
*/
void emitContextMenu (Q3ListViewItem*, const QPoint&, int);
/**
* Emit the contextMenu signal. This slot is for key presses.
*/
void emitContextMenu (KListView*, Q3ListViewItem*);
/**
* Accessory slot for AutoSelect
* @internal
*/
void slotOnItem( Q3ListViewItem *item );
/**
* Accessory slot for AutoSelect/ChangeCursorOverItem
* @internal
*/
void slotOnViewport();
/**
* Process AutoSelection.
* @internal
*/
void slotAutoSelect();
void slotDragExpand();
/**
* Reacts to header changes in full width mode
* @internal
*/
void slotHeaderChanged();
protected:
/**
* Convert the depth of an item into its indentation in pixels
*/
int depthToPixels( int depth );
protected:
virtual void virtual_hook( int id, void* data );
private:
class KListViewPrivate;
KListViewPrivate* const d;
}
#endif // KTREEVIEW_H
>> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscribe <<
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic