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

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