summaryrefslogtreecommitdiffstats
path: root/kaddressbook/views/cardview.h
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commit460c52653ab0dcca6f19a4f492ed2c5e4e963ab0 (patch)
tree67208f7c145782a7e90b123b982ca78d88cc2c87 /kaddressbook/views/cardview.h
downloadtdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.tar.gz
tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'kaddressbook/views/cardview.h')
-rw-r--r--kaddressbook/views/cardview.h579
1 files changed, 579 insertions, 0 deletions
diff --git a/kaddressbook/views/cardview.h b/kaddressbook/views/cardview.h
new file mode 100644
index 000000000..e38a82d53
--- /dev/null
+++ b/kaddressbook/views/cardview.h
@@ -0,0 +1,579 @@
+/*
+ This file is part of KAddressBook.
+ Copyright (c) 2002 Mike Pilone <mpilone@slac.com>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program 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 General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+ As a special exception, permission is given to link this program
+ with any edition of Qt, and distribute the resulting executable,
+ without including the source code for Qt in the source distribution.
+*/
+
+#ifndef CARDVIEW_H
+#define CARDVIEW_H
+
+#include <qpair.h>
+#include <qpoint.h>
+#include <qptrlist.h>
+#include <qrect.h>
+#include <qscrollview.h>
+#include <qstring.h>
+
+class QLabel;
+class QMouseEvent;
+class QPainter;
+class QResizeEvent;
+
+class CardView;
+class CardViewItemPrivate;
+class CardViewPrivate;
+class CardViewTip;
+
+/**
+ Represents a single card (item) in the card view. A card has a caption
+ and a list of fields. A Field is a label<->value pair. The labels in a
+ card should be unique, since they will be used to index the values.
+ */
+class CardViewItem
+{
+ friend class CardView;
+
+ public:
+ /**
+ A single field in the card view. The first item is the label
+ and the second item is the value.
+ */
+ typedef QPair<QString, QString> Field;
+
+ /**
+ Constructor.
+
+ @param parent The CardView that this card should be displayed on.
+ @param caption The caption of the card. This is the text that will
+ appear at the top of the card. This is also the string that will
+ be used to sort the cards in the view.
+ */
+ CardViewItem( CardView *parent, const QString &caption = QString() );
+ virtual ~CardViewItem();
+
+ /**
+ @return The caption of the card, or QString::null if none was ever set.
+ */
+ const QString &caption() const;
+
+ /**
+ Sets the caption of the card. This is the text that will
+ appear at the top of the card. This is also the string that will
+ be used to sort the cards in the view.
+ */
+ void setCaption( const QString &caption );
+
+ /**
+ Paints the card using the given painter and color group. The
+ card will handle painting itself selected if it is selected.
+ */
+ virtual void paintCard( QPainter *p, QColorGroup &cg );
+
+ /**
+ Repaints the card. This is done by sending a repaint event to the
+ view with the clip rect defined as this card.
+ */
+ virtual void repaintCard();
+
+ /**
+ Adds a field to the card.
+
+ @param label The label of the field. The field labels must be unique
+ within a card.
+ @param value The value of the field.
+ */
+ void insertField( const QString &label, const QString &value );
+
+ /**
+ Removes the field with label <i>label</i> from the card.
+ */
+ void removeField( const QString &label );
+
+ /**
+ @return The value of the field with label <i>label</i>.
+ */
+ QString fieldValue( const QString &label ) const;
+
+ /**
+ Removes all the fields from this card.
+ */
+ void clearFields();
+
+ /**
+ @return The next card item. The order of the items will be the same
+ as the display order in the view. 0 will be returned if this is the
+ last card.
+ */
+ CardViewItem *nextItem() const;
+
+ /**
+ @return True if this card is currently selected, false otherwise.
+ */
+ bool isSelected() const;
+
+ /**
+ Called by the parent card view when the mouse has been resting for
+ a certain amount of time. If the label or value at pos is obscured
+ (trimmed) make the label display the full text.
+ */
+ void showFullString( const QPoint &pos, CardViewTip *tip );
+
+ /**
+ @return a pointer to the Field at the position itempos
+ in this item. 0 is returned if itempos is in the caption.
+ @param itempos the position in item coordinates
+ */
+ Field *fieldAt( const QPoint &itempos ) const;
+
+ CardView *cardView() const { return mView; };
+
+ /**
+ @return The height of this item as rendered, in pixels.
+
+ if @p allowCache is true, the item may use an internally
+ cached value rather than recalculating from scratch. The
+ argument is mainly to allow the cardView to change global settings (like
+ maxFieldLines) that might influence the items heights
+ */
+ int height( bool allowCache = true ) const;
+
+ protected:
+ /**
+ Sets the card as selected. This is usually only called from the
+ card view.
+ */
+ void setSelected( bool selected );
+
+ private:
+ /**
+ Sets the default values.
+ */
+ void initialize();
+
+ /**
+ Trims a string to the width <i>width</i> using the font metrics
+ to determine the width of each char. If the string is longer than
+ <i>width</i>, then the string will be trimmed and a '...' will
+ be appended.
+ */
+ QString trimString( const QString &text, int width, QFontMetrics &fm ) const;
+
+ CardViewItemPrivate *d;
+ CardView *mView;
+};
+
+/**
+ The CardView is a method of displaying data in cards. This idea is
+ similar to the idea of a rolodex or business cards. Each card has a
+ caption and a list of fields, which are label<->value pairs. The CardView
+ displays multiple cards in a grid. The Cards are sorted based on their
+ caption.
+
+ The CardView class is designed to mirror the API of the QListView or
+ QIconView. The CardView is also completely independant of KAddressBook and
+ can be used elsewhere. With the exception of a few simple config checks,
+ the CardView is also 100% independant of KDE.
+ */
+class CardView : public QScrollView
+{
+ friend class CardViewItem;
+
+ Q_OBJECT
+
+ public:
+ /**
+ Constructor.
+ */
+ CardView( QWidget *parent, const char *name );
+ virtual ~CardView();
+
+ /**
+ Inserts the item into the card view. This method does not have
+ to be called if you created the item with a proper parent. Once
+ inserted, the CardView takes ownership of the item.
+ */
+ void insertItem( CardViewItem *item );
+
+ /**
+ Takes the item from the view. The item will not be deleted and
+ ownership of the item is returned to the caller.
+ */
+ void takeItem( CardViewItem *item );
+
+ /**
+ Clears the view and deletes all card view items
+ */
+ void clear();
+
+ /**
+ @return The current item, the item that has the focus.
+ Whenever the view has focus, this item has a focus rectangle painted
+ at it's border.
+ @sa setCurrentItem()
+ */
+ CardViewItem *currentItem() const;
+
+ /**
+ Sets the CardViewItem @p item to the current item in the view.
+ */
+ void setCurrentItem( CardViewItem *item );
+
+ /**
+ @return The item found at the given point, or 0 if there is no item
+ at that point.
+ */
+ CardViewItem *itemAt( const QPoint &viewPos ) const;
+
+ /**
+ @return The bounding rect of the given item.
+ */
+ QRect itemRect( const CardViewItem *item ) const;
+
+ /**
+ Ensures that the given item is in the viewable area of the widget
+ */
+ void ensureItemVisible( const CardViewItem *item );
+
+ /**
+ Repaints the given item.
+ */
+ void repaintItem( const CardViewItem *item );
+
+ enum SelectionMode { Single, Multi, Extended, NoSelection };
+
+ /**
+ Sets the selection mode.
+
+ @see QListView
+ */
+ void setSelectionMode( SelectionMode mode );
+
+ /**
+ @return The current selection mode.
+ */
+ SelectionMode selectionMode() const;
+
+ /**
+ Selects or deselects the given item. This method honors the current
+ selection mode, so if other items are selected, they may be unselected.
+ */
+ void setSelected( CardViewItem *item, bool selected );
+
+ /**
+ Selects or deselects all items.
+ */
+ void selectAll( bool state );
+
+ /**
+ @return True if the given item is selected, false otherwise.
+ */
+ bool isSelected( CardViewItem *item ) const;
+
+ /**
+ @return The first selected item. In single select mode, this will be
+ the only selected item, in other modes this will be the first selected
+ item, but others may exist. 0 if no item is selected.
+ */
+ CardViewItem *selectedItem() const;
+
+ /**
+ @return The first item in the view. This may be 0 if no items have
+ been inserted. This method combined with CardViewItem::nextItem()
+ can be used to iterator through the list of items.
+ */
+ CardViewItem *firstItem() const;
+
+ /**
+ @return The item after the given item or 0 if the item is the last
+ item.
+ */
+ CardViewItem *itemAfter( const CardViewItem *item ) const;
+
+ /**
+ @return The number of items in the view.
+ */
+ int childCount() const;
+
+ /**
+ Attempts to find the first item matching the params.
+
+ @param text The text to match.
+ @param label The label of the field to match against.
+ @param compare The compare method to use in doing the search.
+
+ @return The first matching item, or 0 if no items match.
+ */
+ CardViewItem *findItem( const QString &text, const QString &label,
+ Qt::StringComparisonMode compare = Qt::BeginsWith ) const;
+
+ /**
+ Returns the amounts of pixels required for one column.
+ This depends on wheather drawSeparators is enabled:
+ If so, it is itemWidth + 2*itemSpacing + separatorWidth
+ If not, it is itemWidth + itemSpacing
+ @see itemWidth(), setItemWidth(), itemSpacing() and setItemSpacing()
+ */
+ uint columnWidth() const;
+
+ /**
+ Sets if the border around a card should be draw. The border is a thing
+ (1 or 2 pixel) line that bounds the card. When drawn, it shows when
+ a card is highlighted and when it isn't.
+ */
+ void setDrawCardBorder( bool enabled );
+
+ /**
+ @return True if borders are drawn, false otherwise.
+ */
+ bool drawCardBorder() const;
+
+ /**
+ Sets if the column separator should be drawn. The column separator
+ is a thin verticle line (1 or 2 pixels) that is used to separate the
+ columns in the list view. The separator is just for esthetics and it
+ does not serve a functional purpose.
+ */
+ void setDrawColSeparators( bool enabled );
+
+ /**
+ @return True if column separators are drawn, false otherwise.
+ */
+ bool drawColSeparators() const;
+
+ /**
+ Sets if the field labels should be drawn. The field labels are the
+ unique strings used to identify the fields. Sometimes drawing these
+ labels makes sense as a source of clarity for the user, othertimes they
+ waste too much space and do not assist the user.
+ */
+ void setDrawFieldLabels( bool enabled );
+
+ /**
+ @return True if the field labels are drawn, false otherwise.
+ */
+ bool drawFieldLabels() const;
+
+ /**
+ Sets if fields with no value should be drawn (of cause the label only,
+ but it allows for embedded editing sometimes...)
+ */
+ void setShowEmptyFields( bool show );
+
+ /**
+ @return Wheather empty fields should be shown
+ */
+ bool showEmptyFields() const;
+
+ /**
+ @return the advisory internal margin in items. Setting a value above 1 means
+ a space between the item contents and the focus recttangle drawn around
+ the current item. The default value is 0.
+ The value should be used by CardViewItem and derived classes.
+ Note that this should not be greater than half of the minimal item width,
+ which is 80. It is currently not checked, so setting a value greater than 40
+ will probably mean a crash in the items painting routine.
+ */
+ // Note: I looked for a value in QStyle::PixelMetric to use, but I could
+ // not see a useful one. One may turn up in a future version of Qt.
+ uint itemMargin() const;
+
+ /**
+ Sets the internal item margin. See itemMargin().
+ */
+ void setItemMargin( uint margin );
+
+ /**
+ @return the item spacing.
+ The item spacing is the space (in pixels) between each item in a
+ column, between the items and column separators if drawn, and between
+ the items and the borders of the widget. The default value is set to 10.
+ */
+ // Note: There is no useful QStyle::PixelMetric to use for this atm.
+ // An option would be using KDialog::spacingHint().
+ uint itemSpacing() const;
+
+ /**
+ Sets the item spacing.
+ @see itemSpacing()
+ */
+ void setItemSpacing( uint spacing );
+
+ /**
+ @return the width made available to the card items.
+ */
+ int itemWidth() const;
+
+ /**
+ Sets the width made available to card items.
+ */
+ void setItemWidth( int width );
+
+ /**
+ Sets the header font
+ */
+ void setHeaderFont( const QFont &fnt );
+
+ /**
+ @return the header font
+ */
+ QFont headerFont() const;
+
+ /**
+ Reimplementation from QWidget
+ */
+ void setFont( const QFont &fnt );
+
+ /**
+ Sets the column separator width
+ */
+ void setSeparatorWidth( int width );
+
+ /**
+ @return the column separator width
+ */
+ int separatorWidth() const;
+
+ /**
+ Sets the maximum number of lines to display pr field.
+ If set to 0 (the default) all lines will be displayed.
+ */
+ void setMaxFieldLines( int howmany );
+
+ /**
+ @return the maximum number of lines pr field
+ */
+ int maxFieldLines() const;
+
+ signals:
+ /**
+ Emitted whenever the selection changes. This means a user highlighted
+ a new item or unhighlighted a currently selected item.
+ */
+ void selectionChanged();
+
+ /**
+ Same as above method, only it carries the item that was selected. This
+ method will only be emitted in single select mode, since it defineds
+ which item was selected.
+ */
+ void selectionChanged( CardViewItem* );
+
+ /**
+ This method is emitted whenever an item is clicked.
+ */
+ void clicked( CardViewItem* );
+
+ /**
+ Emitted whenever the user 'executes' an item. This is dependant on
+ the KDE global config. This could be a single click or a doubleclick.
+ Also emitted when the return key is pressed on an item.
+ */
+ void executed( CardViewItem* );
+
+ /**
+ Emitted whenever the user double clicks on an item.
+ */
+ void doubleClicked( CardViewItem* );
+
+ /**
+ Emitted when the current item changes
+ */
+ void currentChanged( CardViewItem* );
+
+ /**
+ Emitted when the return key is pressed in an item.
+ */
+ void returnPressed( CardViewItem* );
+
+ /**
+ Emitted when the context menu is requested in some way.
+ */
+ void contextMenuRequested( CardViewItem*, const QPoint& );
+
+ protected:
+ /**
+ Determines which cards intersect that region and tells them to paint
+ themselves.
+ */
+ void drawContents( QPainter *p, int clipx, int clipy, int clipw, int cliph );
+
+ /**
+ Sets the layout to dirty and repaints.
+ */
+ void resizeEvent( QResizeEvent* );
+
+ /**
+ Changes the direction the canvas scolls.
+ */
+ void contentsWheelEvent( QWheelEvent* );
+
+ /**
+ Sets the layout to dirty and calls for a repaint.
+ */
+ void setLayoutDirty( bool dirty );
+
+ /**
+ Does the math based on the bounding rect of the cards to properly
+ lay the cards out on the screen. This is only done if the layout is
+ marked as dirty.
+ */
+ void calcLayout();
+
+ virtual void contentsMousePressEvent( QMouseEvent* );
+ virtual void contentsMouseMoveEvent( QMouseEvent* );
+ virtual void contentsMouseReleaseEvent( QMouseEvent* );
+ virtual void contentsMouseDoubleClickEvent( QMouseEvent* );
+
+ virtual void enterEvent( QEvent* );
+ virtual void leaveEvent( QEvent* );
+
+ virtual void focusInEvent( QFocusEvent* );
+ virtual void focusOutEvent( QFocusEvent* );
+
+ virtual void keyPressEvent( QKeyEvent* );
+
+ /**
+ Overload this method to be told when a drag should be started.
+ In most cases you will want to start a drag event with the currently
+ selected item.
+ */
+ virtual void startDrag();
+
+ private slots:
+ /**
+ Called by a timer to display a label with truncated text.
+ Pop up a label, if there is a field with obscured text or
+ label at the cursor position.
+ */
+ void tryShowFullText();
+
+ private:
+ /**
+ draws and erases the rubber bands while columns are resized.
+ @p pos is the horizontal position inside the viewport to use as
+ the anchor.
+ If pos is 0, only erase is done.
+ */
+ void drawRubberBands( int pos );
+
+ CardViewPrivate *d;
+};
+
+#endif