libkdepim/multiplyingline.h

   1 /*
   2     Copyright (C) 2010 Casey Link <unnamedrambler@gmail.com>
   3     Copyright (C) 2009-2010 Klaralvdalens Datakonsult AB, a KDAB Group company <info@kdab.net>
   4
   5     Refactored from earlier code by:
   6     Copyright (c) 2010 Volker Krause <vkrause@kde.org>
   7     Copyright (c) 2004 Cornelius Schumacher <schumacher@kde.org>
   8
   9     This library is free software; you can redistribute it and/or modify it
  10     under the terms of the GNU Library General Public License as published by
  11     the Free Software Foundation; either version 2 of the License, or (at your
  12     option) any later version.
  13
  14     This library is distributed in the hope that it will be useful, but WITHOUT
  15     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  16     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  17     License for more details.
  18
  19     You should have received a copy of the GNU Library General Public License
  20     along with this library; see the file COPYING.LIB.  If not, write to the
  21     Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  22     02110-1301, USA.
  23 */
  24
  25 #ifndef MULTIPLYINGLINE_H
  26 #define MULTIPLYINGLINE_H
  27
  28 #include "kdepim_export.h"
  29
  30 #include <KGlobalSettings>
  31
  32 #include <QtGui/QWidget>
  33 #include <QSharedPointer>
  34
  35 namespace KPIM {
  36
  37 /**
  38   @short ABC representing line data
  39   @author Casey Link
  40 */
  41 class KDEPIM_EXPORT MultiplyingLineData
  42 {
  43   public:
  44     typedef QSharedPointer<MultiplyingLineData> Ptr;
  45     virtual ~MultiplyingLineData(){}
  46
  47     /**
  48       Clear data, reset to defaults
  49     */
  50     virtual void clear() = 0;
  51     /**
  52       Is the data empty?
  53     */
  54     virtual bool isEmpty() const = 0;
  55 };
  56
  57 /**
  58  @short Abstract Base Class representing a line in the Multiplying line widget.
  59  This class (and its subclasses) represent the lines in the MultiplyingLineEditor. Users of the
  60  MultiplyingLineEditor widget should subclass this class, and add their own input widgets as members,
  61  then implement the pure virtual methods and connect all the appropriate slots.
  62  @author Casey Link
  63 */
  64 class KDEPIM_EXPORT MultiplyingLine : public QWidget
  65 {
  66
  67     Q_OBJECT
  68   public:
  69     explicit MultiplyingLine( QWidget *parent );
  70     virtual ~MultiplyingLine() {}
  71
  72     /**
  73       This line is being activated. Focus should be set
  74       on the first or most important widget in the line.
  75       */
  76     virtual void activate() = 0;
  77     /**
  78      Check if whatever receives focus in activate()
  79      currently has focus.
  80      @return true if this line is active
  81      */
  82     virtual bool isActive() const = 0;
  83
  84     /**
  85       Determine if this line was modified.
  86       @return true if the user has made any modifications to this
  87       MultiplyingLine.
  88     */
  89     virtual bool isModified() const = 0;
  90
  91     /**
  92       Resets the modified flag to false.
  93     */
  94     virtual void clearModified() = 0;
  95
  96     /**
  97       Retrieve the data.
  98       @return the data associated with this line.
  99     */
 100     virtual MultiplyingLineData::Ptr data() const = 0;
 101     /**
 102       Set the data of this line. The containing widgets should be
 103       populated accordingly.
 104       @param data the data to populate this line wit
 105     */
 106     virtual void setData( const MultiplyingLineData::Ptr &data ) = 0;
 107
 108     /**
 109       Whether this line is empty or not. Usually there is a primary widget
 110       that can be tested (such as a line edit).
 111       @return true if this line is empty, false otherwise.
 112     */
 113     virtual bool isEmpty() const = 0;
 114
 115     /**
 116       Set the width of the left most column to be the argument width.
 117       This method allows other widgets to align their label/combobox column with ours
 118       by communicating how many pixels that first column is for them.
 119       @param w the width to set the left most column to.
 120       @return the width that is actually being used.
 121     */
 122     virtual int setColumnWidth( int w ) = 0;
 123
 124     /**
 125       Used to set setup the correct chain of widgets to focus on
 126       when the user presses tab.
 127       @param previous the previous widget (probably from the preceeding line)
 128
 129       Example with a 3 widget line:
 130
 131       void YourLine::fixTabOrder( QWidget *previous ) {
 132         setTabOrder( previous, mLeftMost );
 133         setTabOrder( mLeftMost, mMiddle);
 134         setTabOrder( mMiddle, mRightMost);
 135       }
 136       */
 137     virtual void fixTabOrder( QWidget *previous ) = 0;
 138
 139     /**
 140       @return The final widget in this line on which if the user presses
 141       tab focus should be given to the next line. This will commonly
 142       be used as the parameter of fixTabOrder( QWidget *previous ).
 143       @see fixTabOrder( QWidget *previous )
 144       */
 145     virtual QWidget *tabOut() const = 0;
 146
 147     /**
 148       Clear the contents of this line. Reset to default state
 149      */
 150     virtual void clear() = 0;
 151
 152     /**
 153       Sets the type of completion to be used for KLineEdits in this line
 154       @param mode the completion mode
 155       */
 156     virtual void setCompletionMode( KGlobalSettings::Completion mode ) = 0;
 157
 158     /**
 159       If the view is resized while the completion popup is open, things might start
 160       to overlap. This method should hide() then show() the completionBox for any
 161       currently visible completion boxes.
 162       (somewhat hacky) Example:
 163       void YourLine::moveCompletionPopup() {
 164         if( mLineEdit->completionBox( false ) ) { // check if box is not null without creating it
 165           if( mLineEdit->completionBox()->isVisible() ) { // check if it is currently being shown
 166             mLineEdit->completionBox()->hide(); // trigger the moving
 167             mLineEdit->completionBox()->show();
 168           }
 169         }
 170       */
 171     virtual void moveCompletionPopup() = 0;
 172
 173     /**
 174      * Re implement this method if you need to do something
 175      * before a line is deleted.
 176      *
 177      * Default implementation does nothing.
 178      */
 179     virtual void aboutToBeDeleted();
 180
 181   signals:
 182     /**
 183       Emitted when the return/enter key is pressed
 184     */
 185     void returnPressed( KPIM::MultiplyingLine * );
 186     /**
 187       Emitted when the down key is pressed
 188     */
 189     void downPressed( KPIM::MultiplyingLine * );
 190     /**
 191       Emitted when the up key is pressed
 192     */
 193     void upPressed( KPIM::MultiplyingLine * );
 194     /**
 195       Emitted when the right key is pressed
 196     */
 197     void rightPressed();
 198     /**
 199       Should be emitted when the line should be deleted
 200       */
 201     void deleteLine( KPIM::MultiplyingLine * );
 202     /**
 203       Emitted when the completion mode changes
 204     */
 205     void completionModeChanged( KGlobalSettings::Completion );
 206   public slots:
 207     void slotPropagateDeletion();
 208
 209   protected slots:
 210     void slotReturnPressed();
 211     void slotFocusUp();
 212     void slotFocusDown();
 213
 214
 215   protected:
 216     /**
 217       Handles key press events on this line.
 218       Default behavior handles Up and Down presses.
 219     */
 220     virtual void keyPressEvent( QKeyEvent * );
 221 };
 222
 223 }
 224
 225 #endif // MULTIPLYINGLINE_H