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 #include <QList>
  28
  29 class KBookmarkManager;
  30 class QMouseEvent;
  31
  32 /**
  33  * @brief Navigation bar which contains the current shown URL.
  34  *
  35  * The URL navigator offers two modes:
  36  * - Editable:     Represents the 'classic' mode, where the current URL
  37  *                 is editable inside a line editor.
  38  * - Non editable: The URL is represented by a number of buttons, where
  39  *                 clicking on a button results in activating the URL
  40  *                 the button represents. This mode also supports drag
  41  *                 and drop of items.
  42  *
  43  * The mode can be changed by a toggle button located on the left side of
  44  * the navigator.
  45  *
  46  * The URL navigator also remembers the URL history and allows to go
  47  * back and forward within this history.
  48  */
  49 class UrlNavigator : public QWidget
  50 {
  51     Q_OBJECT
  52
  53 public:
  54     /**
  55      * @brief Represents the history element of an URL.
  56      *
  57      * A history element contains the URL, the name of the current file
  58      * (the 'current file' is the file where the cursor is located) and
  59      * the x- and y-position of the content.
  60      */
  61     class HistoryElem {
  62     public:
  63         HistoryElem();
  64         HistoryElem(const KUrl& url);
  65         ~HistoryElem(); // non virtual
  66
  67         const KUrl& url() const { return m_url; }
  68
  69         void setCurrentFileName(const QString& name) { m_currentFileName = name; }
  70         const QString& currentFileName() const { return m_currentFileName; }
  71
  72         void setContentsX(int x) { m_contentsX = x; }
  73         int contentsX() const { return m_contentsX; }
  74
  75         void setContentsY(int y) { m_contentsY = y; }
  76         int contentsY() const { return m_contentsY; }
  77
  78     private:
  79         KUrl m_url;
  80         QString m_currentFileName;
  81         int m_contentsX;
  82         int m_contentsY;
  83     };
  84
  85     UrlNavigator(KBookmarkManager* bookmarkManager, const KUrl& url, QWidget* parent);
  86     virtual ~UrlNavigator();
  87
  88     /** Returns the current active URL. */
  89     const KUrl& url() const;
  90
  91     /** Returns the portion of the current active URL up to the button at index. */
  92     KUrl url(int index) const;
  93
  94     /** Returns the amount of items in the history */
  95     int historySize() const;
  96
  97     /**
  98      * Returns one item out of the history. The index 0 indicates the oldest
  99      * history element.
 100      * @param index     Output parameter which indicates the current
 101      *                  index of the location.
 102      */
 103     HistoryElem currentHistoryItem() const;
 104
 105     /**
 106      * Goes back one step in the URL history. The signals
 107      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 108      * are submitted.
 109      */
 110     void goBack();
 111
 112     /**
 113      * Goes forward one step in the URL history. The signals
 114      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 115      * are submitted.
 116      */
 117     void goForward();
 118
 119     /**
 120      * Goes up one step of the URL path. The signals
 121      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 122      * are submitted.
 123      */
 124     void goUp();
 125
 126     /**
 127      * Goes to the home URL. The signals UrlNavigator::urlChanged
 128      * and UrlNavigator::historyChanged are submitted.
 129      */
 130     void goHome();
 131
 132     /**
 133      * @return True, if the URL is editable by the user within a line editor.
 134      *         If false is returned, each part of the URL is presented by a button
 135      *         for fast navigation.
 136      */
 137     bool isUrlEditable() const;
 138
 139     /**
 140      * Switches to the edit mode and assures that the keyboard focus
 141      * is assigned.
 142      */
 143     void editUrl(bool editOrBrowse); //TODO: switch to an enum
 144
 145     /**
 146      * Set the URL navigator to the active mode, if \a active
 147      * is true. The active mode is default. Using the URL navigator
 148      * in the inactive mode is useful when having split views,
 149      * where the inactive view is indicated by a an inactive URL
 150      * navigator visually.
 151      */
 152     void setActive(bool active);
 153
 154     /**
 155      * Returns true, if the URL navigator is in the active mode.
 156      * @see UrlNavigator::setActive()
 157      */
 158     bool isActive() const;
 159
 160     /**
 161      * Sets whether or not to show hidden files in lists
 162      */
 163     void setShowHiddenFiles( bool show );
 164
 165     /**
 166      * Returns true if the URL navigator is set to show hidden files
 167      */
 168     bool showHiddenFiles() const; // TODO rename, looks like a verb
 169
 170     /**
 171      * Handles the dropping of the URLs \a urls to the given
 172      * destination \a destination and emits the signal urlsDropped.
 173      */
 174     void dropUrls(const KUrl::List& urls,
 175                   const KUrl& destination);
 176
 177 public slots:
 178     /**
 179      * Sets the current active URL.
 180      * The signals UrlNavigator::urlChanged and UrlNavigator::historyChanged
 181      * are submitted.
 182      */
 183     void setUrl(const KUrl& url);
 184
 185     /**
 186      * Activates the URL navigator (UrlNavigator::isActive() will return true)
 187      * and emits the signal 'activationChanged()'.
 188      */
 189     void requestActivation();
 190
 191     /**
 192      * Stores the coordinates of the contents into
 193      * the current history element.
 194      */
 195     void storeContentsPosition(int x, int y);
 196
 197 signals:
 198     /**
 199      * Is emitted, if the URL navigator has been activated by
 200      * a user interaction.
 201      */
 202     void activated();
 203
 204     /**
 205      * Is emitted, if the URL has been changed e. g. by
 206      * the user.
 207      * @see setUrl()
 208      */
 209     void urlChanged(const KUrl& url);
 210
 211     /**
 212      * Is emitted, if the history has been changed. Usually
 213      * the history is changed if a new URL has been selected.
 214      */
 215     void historyChanged();
 216
 217     /**
 218      * Is emitted if the URLs \a urls have been dropped
 219      * to the destination \a destination.
 220      */
 221     void urlsDropped(const KUrl::List& urls,
 222                      const KUrl& destination);
 223
 224 protected:
 225     /**
 226      * If the Escape key is pressed, the navigation bar should switch
 227      * to the browse mode.
 228      */
 229     virtual void keyReleaseEvent(QKeyEvent* event);
 230
 231     /**
 232      * Paste the clipboard content as URL, if the middle mouse
 233      * button has been clicked.
 234      */
 235     virtual void mouseReleaseEvent(QMouseEvent* event);
 236
 237 private:
 238     Q_PRIVATE_SLOT(d, void slotReturnPressed(const QString& text))
 239     Q_PRIVATE_SLOT(d, void slotRemoteHostActivated())
 240     Q_PRIVATE_SLOT(d, void slotProtocolChanged(const QString& protocol))
 241     Q_PRIVATE_SLOT(d, void switchView())
 242     //Q_PRIVATE_SLOT(d, void slotRedirection(const KUrl&, const KUrl&))
 243
 244 private:
 245     class Private;
 246     Private* const d;
 247
 248     Q_DISABLE_COPY( UrlNavigator )
 249 };
 250
 251 #endif