Initial revision

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