summaryrefslogtreecommitdiffstats
path: root/kio/kfile/kurlbar.h
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commitce4a32fe52ef09d8f5ff1dd22c001110902b60a2 (patch)
tree5ac38a06f3dde268dc7927dc155896926aaf7012 /kio/kfile/kurlbar.h
downloadtdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.tar.gz
tdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.zip
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/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'kio/kfile/kurlbar.h')
-rw-r--r--kio/kfile/kurlbar.h660
1 files changed, 660 insertions, 0 deletions
diff --git a/kio/kfile/kurlbar.h b/kio/kfile/kurlbar.h
new file mode 100644
index 000000000..6bc5de6d5
--- /dev/null
+++ b/kio/kfile/kurlbar.h
@@ -0,0 +1,660 @@
+/* This file is part of the KDE libraries
+ Copyright (C) 2001,2002,2003 Carsten Pfeiffer <pfeiffer@kde.org>
+
+ library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public
+ License as published by the Free Software Foundation, version 2.
+
+ This library 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
+ Library General Public License for more details.
+
+ You should have received a copy of the GNU Library General Public License
+ along with this library; see the file COPYING.LIB. If not, write to
+ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
+*/
+
+#ifndef KURLBAR_H
+#define KURLBAR_H
+
+#include <qevent.h>
+#include <qframe.h>
+#include <qtooltip.h>
+
+#include <kdialogbase.h>
+#include <kicontheme.h>
+#include <klistbox.h>
+#include <kurl.h>
+
+class KConfig;
+class KURLBar;
+
+/**
+ * An item to be used in KURLBar / KURLBarListBox. All the properties
+ * (url, icon, description, tooltip) can be changed dynamically.
+ *
+ * @author Carsten Pfeiffer <pfeiffer@kde.org>
+ * @see KURLBar
+ * @see KURLBarListBox
+ */
+class KIO_EXPORT KURLBarItem : public QListBoxPixmap
+{
+public:
+ /**
+ * Creates a KURLBarItem to be used in the @p parent KURLBar. You need
+ * to insert the item into the listbox manually, if you don't use
+ * KURLBar::insertItem().
+ *
+ * If description is empty, it will try to use the filename/directory
+ * of @p url, which will be shown as text of the item.
+ * @p url will be used as tooltip, unless you set a different tip with
+ * setToolTip().
+ * @p persistent specifies whether this item is a persistent item or a
+ * dynamic item, that is not saved with KURLBar::writeConfig().
+ * @since 3.2
+ */
+ KURLBarItem( KURLBar *parent, const KURL& url, bool persistent,
+ const QString& description = QString::null,
+ const QString& icon = QString::null,
+ KIcon::Group group = KIcon::Panel );
+
+ /**
+ * Creates a persistent KURLBarItem to be used in the @p parent KURLBar. You need
+ * to insert the item into the listbox manually, if you don't use
+ * KURLBar::insertItem().
+ *
+ * If description is empty, it will try to use the filename/directory
+ * of @p url, which will be shown as text of the item.
+ * @p url will be used as tooltip, unless you set a different tip with
+ * setToolTip().
+ * @p persistent specifies whether this item is a persistent item or a
+ * dynamic item, that is not saved with KURLBar::writeConfig().
+ */
+ KURLBarItem( KURLBar *parent, const KURL& url,
+ const QString& description = QString::null,
+ const QString& icon = QString::null,
+ KIcon::Group group = KIcon::Panel );
+
+ /**
+ * Destroys the item
+ */
+ ~KURLBarItem();
+
+ /**
+ * Sets @p url for this item. Also updates the visible text to the
+ * filename/directory of the url, if no description is set.
+ * @see url
+ */
+ void setURL( const KURL& url );
+ /**
+ * @p sets the icon for this item. See KIconLoader for a description
+ * of the icon groups.
+ * @see icon
+ */
+ void setIcon( const QString& icon, KIcon::Group group = KIcon::Panel );
+ /**
+ * Sets the description of this item that will be shown as item-text.
+ * @see description
+ */
+ void setDescription( const QString& desc );
+ /**
+ * Sets a tooltip to be used for this item.
+ * @see toolTip
+ */
+ void setToolTip( const QString& tip );
+
+ /**
+ * returns the preferred size of this item
+ * @since 3.1
+ */
+ QSize sizeHint() const;
+
+ /**
+ * returns the width of this item.
+ */
+ virtual int width( const QListBox * ) const;
+ /**
+ * returns the height of this item.
+ */
+ virtual int height( const QListBox * ) const;
+
+ /**
+ * returns the url of this item.
+ * @see setURL
+ */
+ const KURL& url() const { return m_url; }
+ /**
+ * returns the description of this item.
+ * @see setDescription
+ */
+ const QString& description() const { return m_description; }
+ /**
+ * returns the icon of this item.
+ * @see setIcon
+ */
+ const QString& icon() const { return m_icon; }
+ /**
+ * returns the tooltip of this item.
+ * @see setToolTip
+ */
+ QString toolTip() const;
+ /**
+ * returns the icon-group of this item (determines icon-effects).
+ * @see setIcon
+ */
+ KIcon::Group iconGroup() const { return m_group; }
+ /**
+ * returns the pixmap of this item.
+ */
+ virtual const QPixmap * pixmap() const { return &m_pixmap; }
+
+ /**
+ * Makes this item a local or global one. This has only an effect
+ * on persistent items of course.
+ * @see isPersistent
+ * @see applicationLocal
+ */
+ void setApplicationLocal( bool local );
+
+ /**
+ * returns whether this is a global item or a local one. KURLBar
+ * can differentiate between global and local items (only for the current
+ * application) for easy extensiblity.
+ * @see setApplicationLocal
+ */
+ bool applicationLocal() const { return m_appLocal; }
+
+ /**
+ * returns whether this item is persistent (via KURLBar::writeConfig()
+ * and KURLBar::readConfig()) or not.
+ * @since 3.2
+ */
+ bool isPersistent() const;
+
+protected:
+ virtual void paint( QPainter *p );
+
+private:
+ int iconSize() const;
+ void init( const QString& icon, KIcon::Group group,
+ const QString& description, bool persistent );
+
+ KURL m_url;
+ QString m_description;
+ QString m_icon;
+ QString m_toolTip;
+ QPixmap m_pixmap;
+ KIcon::Group m_group;
+ KURLBar *m_parent;
+ bool m_appLocal :1;
+
+protected:
+ virtual void virtual_hook( int id, void* data );
+private:
+ class KURLBarItemPrivate;
+ KURLBarItemPrivate *d;
+};
+
+
+///////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////
+
+
+class KURLBarListBox;
+
+/**
+ * KURLBar is a widget that displays icons together with a description. They
+ * can be arranged either horizontally or vertically. Clicking on an item
+ * will cause the activated() signal to be emitted. The user can edit
+ * existing items by choosing "Edit entry" in the contextmenu. He can also
+ * remove or add new entries (via drag&drop or the context menu).
+ *
+ * KURLBar offers the methods readConfig() and writeConfig() to
+ * read and write the configuration of all the entries. It can differentiate
+ * between global and local entries -- global entries will be saved in the
+ * global configuration (kdeglobals), while local entries will be saved in
+ * your application's KConfig object.
+ *
+ * Due to the configurability, you usually only insert some default entries
+ * once and then solely use the read and writeConfig methods to preserve the
+ * user's configuration.
+ *
+ * The widget has a "current" item, that is visualized to differentiate it
+ * from others.
+ *
+ * @author Carsten Pfeiffer <pfeiffer@kde.org>
+ * @short A URL-bar widget, as used in the KFileDialog
+ */
+class KIO_EXPORT KURLBar : public QFrame
+{
+ Q_OBJECT
+
+public:
+ /**
+ * Constructs a KURLBar. Set @p useGlobalItems to true if you want to
+ * allow global/local item separation.
+ */
+ KURLBar( bool useGlobalItems,
+ QWidget *parent = 0, const char *name = 0, WFlags f = 0 );
+ /**
+ * Destroys the KURLBar.
+ */
+ ~KURLBar();
+
+ /**
+ * Inserts a new item into the KURLBar and returns the created
+ * KURLBarItem.
+ *
+ * @p url the url of the item
+ * @p description the description of the item (shown in the view)
+ * @p applicationLocal whether this should be a global or a local item
+ * @p icon an icon -- if empty, the default icon for the url will be used
+ * @p group the icon-group for using icon-effects
+ */
+ virtual KURLBarItem * insertItem( const KURL& url,
+ const QString& description,
+ bool applicationLocal = true,
+ const QString& icon = QString::null,
+ KIcon::Group group = KIcon::Panel );
+ /**
+ * Inserts a new dynamic item into the KURLBar and returns the created
+ * KURLBarItem.
+ *
+ * @p url the url of the item
+ * @p description the description of the item (shown in the view)
+ * @p icon an icon -- if empty, the default icon for the url will be used
+ * @p group the icon-group for using icon-effects
+ * @since 3.2
+ */
+ virtual KURLBarItem * insertDynamicItem( const KURL& url,
+ const QString& description,
+ const QString& icon = QString::null,
+ KIcon::Group group = KIcon::Panel );
+ /**
+ * The items can be arranged either vertically in one column or
+ * horizontally in one row.
+ * @see orientation
+ */
+ virtual void setOrientation( Qt::Orientation orient );
+ /**
+ * @returns the current orientation mode.
+ * @see setOrientation
+ */
+ Orientation orientation() const;
+
+ /**
+ * Allows to set a custom KURLBarListBox.
+ * Note: The previous listbox will be deleted. Items of the previous
+ * listbox will not be moved to the new box.
+ * @see listBox
+ */
+ virtual void setListBox( KURLBarListBox * );
+ /**
+ * @returns the KURLBarListBox that is used.
+ * @see setListBox
+ */
+ KURLBarListBox *listBox() const { return m_listBox; }
+
+ /**
+ * Sets the default iconsize to be used for items inserted with
+ * insertItem. By default KIcon::SizeMedium.
+ * @see iconsize
+ */
+ virtual void setIconSize( int size );
+ /**
+ * @returns the default iconsize used for items inserted with
+ * insertItem. By default KIcon::SizeMedium
+ * @see setIconSize
+ */
+ int iconSize() const { return m_iconSize; }
+
+ /**
+ * Clears the view, removes all items.
+ */
+ virtual void clear();
+
+ /**
+ * @returns a proper sizehint, depending on the orientation and the number
+ * of items available.
+ */
+ virtual QSize sizeHint() const;
+
+ /**
+ * @returns a proper minimum size (reimplemented)
+ */
+ virtual QSize minimumSizeHint() const;
+
+ /**
+ * Call this method to read a saved configuration from @p config,
+ * inside the group @p itemGroup. All items in there will be restored.
+ * The reading of every item is delegated to the readItem() method.
+ */
+ virtual void readConfig( KConfig *config, const QString& itemGroup );
+ /**
+ * Call this method to save the current configuration into @p config,
+ * inside the group @p iconGroup. The writeItem() method is used
+ * to save each item.
+ */
+ virtual void writeConfig( KConfig *config, const QString& itemGroup );
+
+ /**
+ * Called from readConfig() to read the i'th from @p config.
+ * After reading a KURLBarItem is created and initialized with the read
+ * values (as well as the given @p applicationLocal).
+ */
+ virtual void readItem( int i, KConfig *config, bool applicationLocal );
+ /**
+ * Called from writeConfig() to save the KURLBarItem @p item as the
+ * i'th entry in the config-object.
+ * @p global tell whether it should be saved in the global configuration
+ * or not (using KConfig::writeEntry( key, value, true, global ) ).
+ */
+ virtual void writeItem( KURLBarItem *item, int i, KConfig *, bool global );
+
+ /**
+ * @returns the current KURLBarItem, or 0L if none.
+ * @see setCurrentItem
+ * @see currentURL
+ */
+ KURLBarItem * currentItem() const;
+ /**
+ * @returns the url of the current item or an invalid url, if there is
+ * no current item.
+ * @see currentItem
+ * @see setCurrentItem
+ */
+ KURL currentURL() const;
+
+ /**
+ * @returns true when the urlbar was modified by the user (e.g. by
+ * editing/adding/removing one or more entries). Will be reset to false
+ * after calling writeConfig().
+ */
+ bool isModified() const { return m_isModified; }
+
+ /**
+ * @returns true when the urlbar may not be modified by the user
+ */
+ bool isImmutable() const { return m_isImmutable; }
+
+ /**
+ * @returns true if the bar is in vertical mode.
+ */
+ bool isVertical() const { return orientation() == Vertical; }
+
+public slots:
+ /**
+ * Makes the item with the url @p url the current item. Does nothing
+ * if no item with that url is available.
+ * @see currentItem
+ * @see currentURL
+ */
+ virtual void setCurrentItem( const KURL& url );
+
+signals:
+ /**
+ * This signal is emitted when the user activated an item, e.g., by
+ * clicking on it.
+ */
+ void activated( const KURL& url );
+
+protected:
+ /**
+ * Pops up a KURLBarItemDialog to let the user add a new item.
+ * Uses editItem() to do the job.
+ * @returns false if the user aborted the dialog and no item is added.
+ */
+ virtual bool addNewItem();
+ /**
+ * Pops up a KURLBarItemDialog to let the user edit the properties
+ * of @p item. Invoked e.g. by addNewItem(), when the user drops
+ * a url onto the bar or from the contextmenu.
+ * @returns false if the user aborted the dialog and @p item is not
+ * changed.
+ */
+ virtual bool editItem( KURLBarItem *item );
+
+ virtual void resizeEvent( QResizeEvent * );
+
+ virtual void paletteChange( const QPalette & );
+
+ /**
+ * The currently active item.
+ */
+ KURLBarItem * m_activeItem;
+ /**
+ * Whether we support global entries or just local ones.
+ */
+ bool m_useGlobal :1;
+
+ /**
+ * Whether the urlbar was modified by the user (e.g. by
+ * editing/adding/removing an item).
+ */
+ bool m_isModified :1;
+
+ /**
+ * Whether the urlbar may be modified by the user.
+ * If immutable is true, the urlbar can not be modified.
+ */
+ bool m_isImmutable :1;
+
+protected slots:
+ /**
+ * Reimplemented to show a contextmenu, allowing the user to add, edit
+ * or remove items, or change the iconsize.
+ */
+ virtual void slotContextMenuRequested( QListBoxItem *, const QPoint& pos );
+ /**
+ * Called when an item has been selected. Emits the activated()
+ * signal.
+ */
+ virtual void slotSelected( QListBoxItem * );
+
+ /**
+ * Called when a url was dropped onto the bar to show a
+ * KURLBarItemDialog.
+ */
+ virtual void slotDropped( QDropEvent * );
+
+private slots:
+ void slotSelected( int button, QListBoxItem * );
+
+private:
+ KURLBarListBox *m_listBox;
+ int m_iconSize;
+
+
+protected:
+ virtual void virtual_hook( int id, void* data );
+private:
+ class KURLBarPrivate;
+ KURLBarPrivate *d;
+};
+
+
+///////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////
+
+
+class QDragObject;
+class KURLBarToolTip;
+
+/**
+ * This is the listbox used in KURLBar. It is a subclass of KListBox to support
+ * drag & drop and to set up the row / column mode.
+ *
+ * The widget has just one row or one column, depending on orientation().
+ *
+ * @author Carsten Pfeiffer <pfeiffer@kde.org>
+ */
+class KIO_EXPORT KURLBarListBox : public KListBox
+{
+ Q_OBJECT
+
+public:
+ /**
+ * Constructs a KURLBarListBox.
+ */
+ KURLBarListBox( QWidget *parent = 0, const char *name = 0 );
+ /**
+ * Destroys the box.
+ */
+ ~KURLBarListBox();
+
+ /**
+ * Sets the orientation of the widget. Horizontal means, all items are
+ * arranged in one row. Vertical means, all items are arranged in one
+ * column.
+ * @see orientation
+ */
+ virtual void setOrientation( Qt::Orientation orient );
+ /**
+ * @returns the current orientation.
+ * @see setOrientation
+ */
+ Qt::Orientation orientation() const { return m_orientation; }
+
+ bool isVertical() const { return m_orientation == Qt::Vertical; }
+
+signals:
+ /**
+ * Emitted when a drop-event happened.
+ */
+ void dropped( QDropEvent *e );
+
+protected:
+ /**
+ * @returns a suitable QDragObject when an item is dragged.
+ */
+ virtual QDragObject * dragObject();
+
+ virtual void contentsDragEnterEvent( QDragEnterEvent * );
+ virtual void contentsDropEvent( QDropEvent * );
+ virtual void contextMenuEvent( QContextMenuEvent * );
+ virtual void paintEvent( QPaintEvent* );
+
+private:
+ Qt::Orientation m_orientation;
+ KURLBarToolTip *m_toolTip;
+
+protected:
+ virtual void virtual_hook( int id, void* data );
+private:
+ class KURLBarListBoxPrivate;
+ KURLBarListBoxPrivate *d;
+};
+
+
+///////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////
+
+
+class QCheckBox;
+class KIconButton;
+class KLineEdit;
+class KURLRequester;
+
+/**
+ * A dialog that allows editing entries of a KURLBar ( KURLBarItem).
+ * The dialog offers to configure a given url, description and icon.
+ * See the class-method getInformation() for easy usage.
+ *
+ * @author Carsten Pfeiffer <pfeiffer@kde.org>
+ */
+class KIO_EXPORT KURLBarItemDialog : public KDialogBase
+{
+ Q_OBJECT
+
+public:
+ /**
+ * A convenience method to show the dialog and retrieve all the
+ * properties via the given parameters. The parameters are used to
+ * initialize the dialog and then return the user-configured values.
+ *
+ * See the KURLBarItem constructor for the parameter description.
+ */
+ static bool getInformation( bool allowGlobal, KURL& url,
+ QString& description, QString& icon,
+ bool& appLocal, int iconSize,
+ QWidget *parent = 0 );
+
+ /**
+ * Constructs a KURLBarItemDialog.
+ *
+ * @p allowGlobal if you set this to true, the dialog will have a checkbox
+ * for the user to decide if he wants the entry to be
+ * available globally or just for the current application.
+ * @p url the url of the item
+ * @p description a short, translated description of the item
+ * @p icon an icon for the item
+ * @p appLocal tells whether the item should be local for this application
+ * or be available globally
+ * @p iconSize determines the size of the icon that is shown/selectable
+ * @p parent the parent-widget for the dialog
+ *
+ * If you leave the icon empty, the default icon for the given url will be
+ * used (KMimeType::pixmapForURL()).
+ */
+ KURLBarItemDialog( bool allowGlobal, const KURL& url,
+ const QString& description, QString icon,
+ bool appLocal = true,
+ int iconSize = KIcon::SizeMedium,
+ QWidget *parent = 0, const char *name = 0 );
+ /**
+ * Destroys the dialog.
+ */
+ ~KURLBarItemDialog();
+
+ /**
+ * @returns the configured url
+ */
+ KURL url() const;
+
+ /**
+ * @returns the configured description
+ */
+ QString description() const;
+
+ /**
+ * @returns the configured icon
+ */
+ QString icon() const;
+
+ /**
+ * @returns whether the item should be local to the application or global.
+ * If allowGlobal was set to false in the constructor, this will always
+ * return true.
+ */
+ bool applicationLocal() const;
+
+protected:
+ /**
+ * The KURLRequester used for editing the url
+ */
+ KURLRequester * m_urlEdit;
+ /**
+ * The KLineEdit used for editing the description
+ */
+ KLineEdit * m_edit;
+ /**
+ * The KIconButton to configure the icon
+ */
+ KIconButton * m_iconButton;
+ /**
+ * The QCheckBox to modify the local/global setting
+ */
+ QCheckBox * m_appLocal;
+
+public slots:
+ void urlChanged(const QString & );
+
+private:
+ class KURLBarItemDialogPrivate;
+ KURLBarItemDialogPrivate *d;
+};
+
+
+#endif // KURLBAR_H