src/urlnavigator.h

   1 /**************************************************************************
   2 *   Copyright (C) 2006 by Peter Penz                                      *
   3 *   peter.penz@gmx.at                                                     *
   4 *                                                                         *
   5 *   This program is free software; you can redistribute it and/or modify  *
   6 *   it under the terms of the GNU General Public License as published by  *
   7 *   the Free Software Foundation; either version 2 of the License, or     *
   8 *   (at your option) any later version.                                   *
   9 *                                                                         *
  10 *   This program is distributed in the hope that it will be useful,       *
  11 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  12 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  13 *   GNU General Public License for more details.                          *
  14 *                                                                         *
  15 *   You should have received a copy of the GNU General Public License     *
  16 *   along with this program; if not, write to the                         *
  17 *   Free Software Foundation, Inc.,                                       *
  18 *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA          *
  19 ***************************************************************************/
  20
  21 #ifndef UrlNAVIGATOR_H
  22 #define UrlNAVIGATOR_H
  23
  24
  25 //Added by qt3to4:
  26 #include <QLabel>
  27 #include <Q3ValueList>
  28 #include <QKeyEvent>
  29 #include <Q3PopupMenu>
  30 #include <kurl.h>
  31 #include <qstring.h>
  32 #include <kvbox.h>
  33
  34 class QComboBox;
  35 class QLabel;
  36 class QLineEdit;
  37 class Q3PopupMenu;
  38 class QCheckBox;
  39
  40 class KUrl;
  41 class KFileItem;
  42 class KUrlComboBox;
  43
  44 class BookmarkSelector;
  45 class ProtocolCombo;
  46
  47 /**
  48  * @brief Navigation bar which contains the current shown Url.
  49  *
  50  * The Url navigator offers two modes:
  51  * - Editable:     Represents the 'classic' mode, where the current Url
  52  *                 is editable inside a line editor.
  53  * - Non editable: The Url is represented by a number of buttons, where
  54  *                 clicking on a button results in activating the Url
  55  *                 the button represents. This mode also supports drag
  56  *                 and drop of items.
  57  *
  58  * The mode can be changed by a toggle button located on the left side of
  59  * the navigator.
  60  *
  61  * The Url navigator also remembers the Url history and allows to go
  62  * back and forward within this history.
  63  *
  64  * @author Peter Penz
  65 */
  66
  67 typedef Q3ValueList<KUrl> UrlStack;
  68
  69 class UrlNavigator : public KHBox
  70 {
  71     Q_OBJECT
  72
  73 public:
  74     /**
  75      * @brief Represents the history element of an Url.
  76      *
  77      * A history element contains the Url, the name of the current file
  78      * (the 'current file' is the file where the cursor is located) and
  79      * the x- and y-position of the content.
  80      */
  81     class HistoryElem {
  82     public:
  83         HistoryElem();
  84         HistoryElem(const KUrl& url);
  85         ~HistoryElem(); // non virtual
  86
  87         const KUrl& url() const { return m_url; }
  88
  89         void setCurrentFileName(const QString& name) { m_currentFileName = name; }
  90         const QString& currentFileName() const { return m_currentFileName; }
  91
  92         void setContentsX(int x) { m_contentsX = x; }
  93         int contentsX() const { return m_contentsX; }
  94
  95         void setContentsY(int y) { m_contentsY = y; }
  96         int contentsY() const { return m_contentsY; }
  97
  98     private:
  99         KUrl m_url;
 100         QString m_currentFileName;
 101         int m_contentsX;
 102         int m_contentsY;
 103     };
 104
 105     UrlNavigator(const KUrl& url, QWidget* parent);
 106     virtual ~UrlNavigator();
 107
 108     /** Returns the current active Url. */
 109     const KUrl& url() const;
 110
 111     /** Returns the portion of the current active Url up to the button at index. */
 112     KUrl url(int index) const;
 113
 114     /**
 115      * Returns the complete Url history. The index 0 indicates the oldest
 116      * history element.
 117      * @param index     Output parameter which indicates the current
 118      *                  index of the location.
 119      */
 120     const Q3ValueList<HistoryElem>& history(int& index) const;
 121
 122     /**
 123      * Goes back one step in the Url history. The signals
 124      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 125      * are submitted.
 126      */
 127     void goBack();
 128
 129     /**
 130      * Goes forward one step in the Url history. The signals
 131      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 132      * are submitted.
 133      */
 134     void goForward();
 135
 136     /**
 137      * Goes up one step of the Url path. The signals
 138      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 139      * are submitted.
 140      */
 141     void goUp();
 142
 143     /**
 144      * Goes to the home Url. The signals UrlNavigator::urlChanged
 145      * and UrlNavigator::historyChanged are submitted.
 146      */
 147     void goHome();
 148
 149     /**
 150      * @return True, if the Url is editable by the user within a line editor.
 151      *         If false is returned, each part of the Url is presented by a button
 152      *         for fast navigation.
 153      */
 154     bool isUrlEditable() const;
 155
 156     /**
 157      * Switches to the edit mode and assures that the keyboard focus
 158      * is assigned.
 159      */
 160     void editUrl(bool editOrBrowse); //TODO: switch to an enum
 161
 162     /**
 163      * Set the URL navigator to the active mode, if \a active
 164      * is true. The active mode is default. Using the URL navigator
 165      * in the inactive mode is useful when having split views,
 166      * where the inactive view is indicated by a an inactive URL
 167      * navigator visually.
 168      */
 169     void setActive(bool active);
 170
 171     /**
 172      * Returns true, if the URL navigator is in the active mode.
 173      * @see UrlNavigator::setActive()
 174      */
 175     bool isActive() const { return m_active; }
 176
 177     /**
 178      * Handles the dropping of the URLs \a urls to the given
 179      * destination \a destination and emits the signal urlsDropped.
 180      */
 181     void dropUrls(const KUrl::List& urls,
 182                   const KUrl& destination);
 183
 184 public slots:
 185     /**
 186      * Sets the current active URL.
 187      * The signals UrlNavigator::urlChanged and UrlNavigator::historyChanged
 188      * are submitted.
 189      */
 190     void setUrl(const KUrl& url);
 191
 192     /**
 193      * Activates the URL navigator (UrlNavigator::isActive() will return true)
 194      * and emits the signal 'activationChanged()'.
 195      */
 196     void requestActivation();
 197
 198     /**
 199      * Stores the coordinates of the contents into
 200      * the current history element.
 201      */
 202     void storeContentsPosition(int x, int y);
 203
 204 signals:
 205     /**
 206      * Is emitted, if the URL navigator has been activated by
 207      * a user interaction.
 208      */
 209     void activated();
 210
 211     /**
 212      * Is emitted, if the URL has been changed e. g. by
 213      * the user.
 214      * @see setUrl()
 215      */
 216     void urlChanged(const KUrl& url);
 217
 218     /**
 219      * Is emitted, if the history has been changed. Usually
 220      * the history is changed if a new URL has been selected.
 221      */
 222     void historyChanged();
 223
 224     /**
 225      * Is emitted if the URLs \a urls have been dropped
 226      * to the destination \a destination.
 227      */
 228     void urlsDropped(const KUrl::List& urls,
 229                      const KUrl& destination);
 230
 231 protected:
 232     /** If the Escape key is pressed, the navigation bar should switch
 233         to the browse mode. */
 234     virtual void keyReleaseEvent(QKeyEvent* event);
 235
 236 private slots:
 237     void slotReturnPressed(const QString& text);
 238     void slotUrlActivated(const KUrl& url);
 239     void slotRemoteHostActivated();
 240     void slotProtocolChanged(const QString& protocol);
 241     void slotRedirection(const KUrl&, const KUrl&);
 242
 243     /**
 244      * Switches the navigation bar between the editable and noneditable
 245      * state (see setUrlEditable()) and is connected to the clicked signal
 246      * of the navigation bar button.
 247      */
 248     void slotClicked();
 249
 250 private:
 251     bool m_active;
 252     int m_historyIndex;
 253     Q3ValueList<HistoryElem> m_history;
 254     QCheckBox* m_toggleButton;
 255     BookmarkSelector* m_bookmarkSelector;
 256     KUrlComboBox* m_pathBox;
 257     ProtocolCombo* m_protocols;
 258     QLabel* m_protocolSeparator;
 259     QLineEdit* m_host;
 260     Q3ValueList<QWidget*> m_navButtons;
 261     //UrlStack m_urls;
 262
 263     /**
 264      * Allows to edit the Url of the navigation bar if \a editable
 265      * is true. If \a editable is false, each part of
 266      * the Url is presented by a button for a fast navigation.
 267      */
 268     void setUrlEditable(bool editable);
 269
 270     /**
 271      * Updates the history element with the current file item
 272      * and the contents position.
 273      */
 274     void updateHistoryElem();
 275     void updateContent();
 276 };
 277
 278 #endif