summaryrefslogtreecommitdiffabout
path: root/kaddressbook/views/cardview.h
authorzautrix <zautrix>2004-06-26 19:01:18 (UTC)
committer zautrix <zautrix>2004-06-26 19:01:18 (UTC)
commitb9aad1f15dc600e4dbe4c62d3fcced6363188ba3 (patch) (side-by-side diff)
tree2c3d4004fb21c72cba65793859f9bcd8ffd3a49c /kaddressbook/views/cardview.h
downloadkdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.zip
kdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.tar.gz
kdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.tar.bz2
Initial revision
Diffstat (limited to 'kaddressbook/views/cardview.h') (more/less context) (ignore whitespace changes)
-rw-r--r--kaddressbook/views/cardview.h473
1 files changed, 473 insertions, 0 deletions
diff --git a/kaddressbook/views/cardview.h b/kaddressbook/views/cardview.h
new file mode 100644
index 0000000..37dddb6
--- a/dev/null
+++ b/kaddressbook/views/cardview.h
@@ -0,0 +1,473 @@
+#ifndef CARDVIEW_H
+#define CARDVIEW_H
+
+#include <qscrollview.h>
+#include <qptrlist.h>
+#include <qstring.h>
+#include <qrect.h>
+#include <qpair.h>
+#include <qpoint.h>
+
+class QLabel;
+class QPainter;
+class QResizeEvent;
+class QMouseEvent;
+class CardView;
+class CardViewPrivate;
+class CardViewItemPrivate;
+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, QString caption = QString::null);
+ 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 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);
+
+ /** 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();
+
+ /** @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() { 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);
+
+ 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();
+
+ /** 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);
+
+ /** @return The bounding rect of the given item.
+ */
+ QRect itemRect(const CardViewItem *item);
+
+ /** 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(CardViewItem *item);
+
+ /** @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.
+ */
+/*US
+ CardViewItem *findItem(const QString &text, const QString &label,
+ Qt::StringComparisonMode compare = Qt::BeginsWith);
+*/
+
+ /** 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();
+
+ /** 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.
+ * @private Note: I looked for a value in QStyle::PixelMetric to use, but I could
+ * not see a usefull one. One may turn up in a future version of Qt.
+ */
+ uint itemMargin();
+
+ /** 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.
+ * @private Note: There is no usefull QStyle::PixelMetric to use for this atm.
+ * An option would be using KDialog::spacingHint().
+ */
+ uint itemSpacing();
+
+ /** 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;
+
+ /** @reimp */
+ void setFont( const QFont &fnt );
+
+ /** Sets the column separator width */
+ void setSeparatorWidth( int width );
+
+ /** @return the column separator width */
+ int separatorWidth();
+
+ /** 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 * );
+
+ 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 *e);
+
+ /** Changes the direction the canvas scolls.
+ */
+ void contentsWheelEvent(QWheelEvent *e);
+
+ /** 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 mousePressEvent(QMouseEvent *e);
+// virtual void mouseReleaseEvent(QMouseEvent *e);
+// virtual void mouseMoveEvent(QMouseEvent *e);
+
+ virtual void contentsMousePressEvent(QMouseEvent *e);
+ virtual void contentsMouseMoveEvent(QMouseEvent *e);
+ virtual void contentsMouseReleaseEvent(QMouseEvent *e);
+ virtual void contentsMouseDoubleClickEvent(QMouseEvent *e);
+
+ 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