src/urlnavigator.h

   1 /***************************************************************************
   2  *   Copyright (C) 2006 by Peter Penz (<peter.penz@gmx.at>)                *
   3  *   Copyright (C) 2006 by Aaron J. Seigo (<aseigo@kde.org>)               *
   4  *   Copyright (C) 2006 by Patrice Tremblay                                *
   5  *                                                                         *
   6  *   This program is free software; you can redistribute it and/or modify  *
   7  *   it under the terms of the GNU General Public License as published by  *
   8  *   the Free Software Foundation; either version 2 of the License, or     *
   9  *   (at your option) any later version.                                   *
  10  *                                                                         *
  11  *   This program is distributed in the hope that it will be useful,       *
  12  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  13  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  14  *   GNU General Public License for more details.                          *
  15  *                                                                         *
  16  *   You should have received a copy of the GNU General Public License     *
  17  *   along with this program; if not, write to the                         *
  18  *   Free Software Foundation, Inc.,                                       *
  19  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA          *
  20  ***************************************************************************/
  21
  22 #ifndef URLNAVIGATOR_H
  23 #define URLNAVIGATOR_H
  24
  25 #include <kurl.h>
  26 #include <QWidget>
  27
  28 class KBookmarkManager;
  29 class QMouseEvent;
  30
  31 /**
  32  * @brief Navigation bar which contains the current shown URL.
  33  *
  34  * The URL navigator offers two modes:
  35  * - Editable:     Represents the 'classic' mode, where the current URL
  36  *                 is editable inside a line editor.
  37  * - Non editable: The URL is represented by a number of buttons, where
  38  *                 clicking on a button results in activating the URL
  39  *                 the button represents. This mode also supports drag
  40  *                 and drop of items.
  41  *
  42  * The mode can be changed by a toggle button located on the left side of
  43  * the navigator.
  44  *
  45  * The URL navigator also remembers the URL history and allows to go
  46  * back and forward within this history.
  47  */
  48 class UrlNavigator : public QWidget
  49 {
  50     Q_OBJECT
  51
  52 public:
  53     UrlNavigator(KBookmarkManager* bookmarkManager, const KUrl& url, QWidget* parent);
  54     virtual ~UrlNavigator();
  55
  56     /** Returns the current active URL. */
  57     const KUrl& url() const;
  58
  59     /** Returns the portion of the current active URL up to the button at index. */
  60     KUrl url(int index) const;
  61
  62     /** Returns the amount of items in the history */
  63     int historySize() const;
  64
  65     /** Returns the saved position from the history */
  66     QPoint savedPosition() const;
  67
  68     /**
  69      * Goes back one step in the URL history. The signals
  70      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
  71      * are submitted.
  72      */
  73     void goBack();
  74
  75     /**
  76      * Goes forward one step in the URL history. The signals
  77      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
  78      * are submitted.
  79      */
  80     void goForward();
  81
  82     /**
  83      * Goes up one step of the URL path. The signals
  84      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
  85      * are submitted.
  86      */
  87     void goUp();
  88
  89     /**
  90      * Goes to the home URL. The signals UrlNavigator::urlChanged
  91      * and UrlNavigator::historyChanged are submitted.
  92      */
  93     void goHome();
  94
  95     /**
  96      * Sets the home URL used by goHome().
  97      */
  98     void setHomeUrl(const QString& homeUrl);
  99
 100     /**
 101      * @return True, if the URL is editable by the user within a line editor.
 102      *         If false is returned, each part of the URL is presented by a button
 103      *         for fast navigation.
 104      */
 105     bool isUrlEditable() const;
 106
 107     /**
 108      * Allows to edit the URL of the navigation bar if \a editable
 109      * is true, and sets the focus accordingly.
 110      * If \a editable is false, each part of
 111      * the URL is presented by a button for a fast navigation.
 112      */
 113     void setUrlEditable(bool editable);
 114
 115     /**
 116      * Set the URL navigator to the active mode, if \a active
 117      * is true. The active mode is default. Using the URL navigator
 118      * in the inactive mode is useful when having split views,
 119      * where the inactive view is indicated by an inactive URL
 120      * navigator visually.
 121      */
 122     void setActive(bool active);
 123
 124     /**
 125      * Returns true, if the URL navigator is in the active mode.
 126      * @see UrlNavigator::setActive()
 127      */
 128     bool isActive() const;
 129
 130     /**
 131      * Sets whether or not to show hidden files in lists
 132      */
 133     void setShowHiddenFiles( bool show );
 134
 135     /**
 136      * Returns true if the URL navigator is set to show hidden files
 137      */
 138     bool showHiddenFiles() const; // TODO rename, looks like a verb
 139
 140     /**
 141      * Handles the dropping of the URLs \a urls to the given
 142      * destination \a destination and emits the signal urlsDropped.
 143      */
 144     void dropUrls(const KUrl::List& urls,
 145                   const KUrl& destination);
 146
 147 public slots:
 148     /**
 149      * Sets the current active URL.
 150      * The signals UrlNavigator::urlChanged and UrlNavigator::historyChanged
 151      * are submitted.
 152      */
 153     void setUrl(const KUrl& url);
 154
 155     /**
 156      * Activates the URL navigator (UrlNavigator::isActive() will return true)
 157      * and emits the signal 'activationChanged()'.
 158      */
 159     void requestActivation();
 160
 161     /**
 162      * Stores the coordinates of the contents into
 163      * the current history element.
 164      */
 165     void storeContentsPosition(int x, int y);
 166
 167 signals:
 168     /**
 169      * Is emitted, if the URL navigator has been activated by
 170      * a user interaction.
 171      */
 172     void activated();
 173
 174     /**
 175      * Is emitted, if the URL has been changed e. g. by
 176      * the user.
 177      * @see setUrl()
 178      */
 179     void urlChanged(const KUrl& url);
 180
 181     /**
 182      * Is emitted, if the history has been changed. Usually
 183      * the history is changed if a new URL has been selected.
 184      */
 185     void historyChanged();
 186
 187     /**
 188      * Is emitted if the URLs \a urls have been dropped
 189      * to the destination \a destination.
 190      */
 191     void urlsDropped(const KUrl::List& urls,
 192                      const KUrl& destination);
 193
 194 protected:
 195     /**
 196      * If the Escape key is pressed, the navigation bar should switch
 197      * to the browse mode.
 198      */
 199     virtual void keyReleaseEvent(QKeyEvent* event);
 200
 201     /**
 202      * Paste the clipboard content as URL, if the middle mouse
 203      * button has been clicked.
 204      */
 205     virtual void mouseReleaseEvent(QMouseEvent* event);
 206
 207 private:
 208     Q_PRIVATE_SLOT(d, void slotReturnPressed(const QString& text))
 209     Q_PRIVATE_SLOT(d, void slotRemoteHostActivated())
 210     Q_PRIVATE_SLOT(d, void slotProtocolChanged(const QString& protocol))
 211     Q_PRIVATE_SLOT(d, void switchView())
 212     //Q_PRIVATE_SLOT(d, void slotRedirection(const KUrl&, const KUrl&))
 213
 214 private:
 215     class Private;
 216     Private* const d;
 217
 218     Q_DISABLE_COPY( UrlNavigator )
 219 };
 220
 221 #endif