home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kurlbar.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  19.9 KB  |  661 lines
  1. /* This file is part of the KDE libraries
  2.     Copyright (C) 2001,2002,2003 Carsten Pfeiffer <pfeiffer@kde.org>
  3.  
  4.     library is free software; you can redistribute it and/or
  5.     modify it under the terms of the GNU Library General Public
  6.     License as published by the Free Software Foundation, version 2.
  7.  
  8.     This library is distributed in the hope that it will be useful,
  9.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  10.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11.     Library General Public License for more details.
  12.  
  13.     You should have received a copy of the GNU Library General Public License
  14.     along with this library; see the file COPYING.LIB.  If not, write to
  15.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16.     Boston, MA 02110-1301, USA.
  17. */
  18.  
  19. #ifndef KURLBAR_H
  20. #define KURLBAR_H
  21.  
  22. #include <qevent.h>
  23. #include <qframe.h>
  24. #include <qtooltip.h>
  25.  
  26. #include <kdialogbase.h>
  27. #include <kicontheme.h>
  28. #include <klistbox.h>
  29. #include <kurl.h>
  30.  
  31. class KConfig;
  32. class KURLBar;
  33.  
  34. /**
  35.  * An item to be used in KURLBar / KURLBarListBox. All the properties
  36.  * (url, icon, description, tooltip) can be changed dynamically.
  37.  *
  38.  * @author Carsten Pfeiffer <pfeiffer@kde.org>
  39.  * @see KURLBar
  40.  * @see KURLBarListBox
  41.  */
  42. class KIO_EXPORT KURLBarItem : public QListBoxPixmap
  43. {
  44. public:
  45.     /**
  46.      * Creates a KURLBarItem to be used in the @p parent KURLBar. You need
  47.      * to insert the item into the listbox manually, if you don't use
  48.      * KURLBar::insertItem().
  49.      *
  50.      * If description is empty, it will try to use the filename/directory
  51.      * of @p url, which will be shown as text of the item.
  52.      * @p url will be used as tooltip, unless you set a different tip with
  53.      * setToolTip().
  54.      * @p persistent specifies whether this item is a persistent item or a
  55.      * dynamic item, that is not saved with KURLBar::writeConfig().
  56.      * @since 3.2
  57.      */
  58.     KURLBarItem( KURLBar *parent, const KURL& url, bool persistent,
  59.                  const QString& description = QString::null,
  60.                  const QString& icon = QString::null,
  61.                  KIcon::Group group = KIcon::Panel );
  62.  
  63.     /**
  64.      * Creates a persistent KURLBarItem to be used in the @p parent KURLBar. You need
  65.      * to insert the item into the listbox manually, if you don't use
  66.      * KURLBar::insertItem().
  67.      *
  68.      * If description is empty, it will try to use the filename/directory
  69.      * of @p url, which will be shown as text of the item.
  70.      * @p url will be used as tooltip, unless you set a different tip with
  71.      * setToolTip().
  72.      * @p persistent specifies whether this item is a persistent item or a
  73.      * dynamic item, that is not saved with KURLBar::writeConfig().
  74.      */
  75.     KURLBarItem( KURLBar *parent, const KURL& url,
  76.                  const QString& description = QString::null,
  77.                  const QString& icon = QString::null,
  78.                  KIcon::Group group = KIcon::Panel );
  79.  
  80.     /**
  81.      * Destroys the item
  82.      */
  83.     ~KURLBarItem();
  84.  
  85.     /**
  86.      * Sets @p url for this item. Also updates the visible text to the
  87.      * filename/directory of the url, if no description is set.
  88.      * @see url
  89.      */
  90.     void setURL( const KURL& url );
  91.     /**
  92.      * @p sets the icon for this item. See KIconLoader for a description
  93.      * of the icon groups.
  94.      * @see icon
  95.      */
  96.     void setIcon( const QString& icon, KIcon::Group group = KIcon::Panel );
  97.     /**
  98.      * Sets the description of this item that will be shown as item-text.
  99.      * @see description
  100.      */
  101.     void setDescription( const QString& desc );
  102.     /**
  103.      * Sets a tooltip to be used for this item.
  104.      * @see toolTip
  105.      */
  106.     void setToolTip( const QString& tip );
  107.  
  108.     /**
  109.      * returns the preferred size of this item
  110.      * @since 3.1
  111.      */
  112.     QSize sizeHint() const;
  113.  
  114.     /**
  115.      * returns the width of this item.
  116.      */
  117.     virtual int width( const QListBox * ) const;
  118.     /**
  119.      * returns the height of this item.
  120.      */
  121.     virtual int height( const QListBox * ) const;
  122.  
  123.     /**
  124.      * returns the url of this item.
  125.      * @see setURL
  126.      */
  127.     const KURL& url() const                     { return m_url; }
  128.     /**
  129.      * returns the description of this item.
  130.      * @see setDescription
  131.      */
  132.     const QString& description() const          { return m_description; }
  133.     /**
  134.      * returns the icon of this item.
  135.      * @see setIcon
  136.      */
  137.     const QString& icon() const                 { return m_icon; }
  138.     /**
  139.      * returns the tooltip of this item.
  140.      * @see setToolTip
  141.      */
  142.     QString toolTip() const;
  143.     /**
  144.      * returns the icon-group of this item (determines icon-effects).
  145.      * @see setIcon
  146.      */
  147.     KIcon::Group iconGroup() const              { return m_group; }
  148.     /**
  149.      * returns the pixmap  of this item.
  150.      */
  151.     virtual const QPixmap * pixmap() const      { return &m_pixmap; }
  152.  
  153.     /**
  154.      * Makes this item a local or global one. This has only an effect
  155.      * on persistent items of course.
  156.      * @see isPersistent
  157.      * @see applicationLocal
  158.      */
  159.     void setApplicationLocal( bool local );
  160.  
  161.     /**
  162.      * returns whether this is a global item or a local one. KURLBar
  163.      * can differentiate between global and local items (only for the current
  164.      * application) for easy extensiblity.
  165.      * @see setApplicationLocal
  166.      */
  167.     bool applicationLocal() const               { return m_appLocal; }
  168.  
  169.     /**
  170.      * returns whether this item is persistent (via KURLBar::writeConfig()
  171.      * and KURLBar::readConfig()) or not.
  172.      * @since 3.2
  173.      */
  174.     bool isPersistent() const;
  175.  
  176. protected:
  177.     virtual void paint( QPainter *p );
  178.  
  179. private:
  180.     int iconSize() const;
  181.     void init( const QString& icon, KIcon::Group group,
  182.                const QString& description, bool persistent );
  183.  
  184.     KURL m_url;
  185.     QString m_description;
  186.     QString m_icon;
  187.     QString m_toolTip;
  188.     QPixmap m_pixmap;
  189.     KIcon::Group m_group;
  190.     KURLBar *m_parent;
  191.     bool m_appLocal :1;
  192.  
  193. protected:
  194.     virtual void virtual_hook( int id, void* data );
  195. private:
  196.     class KURLBarItemPrivate;
  197.     KURLBarItemPrivate *d;
  198. };
  199.  
  200.  
  201. ///////////////////////////////////////////////////////////////////
  202. ///////////////////////////////////////////////////////////////////
  203.  
  204.  
  205. class KURLBarListBox;
  206.  
  207. /**
  208.  * KURLBar is a widget that displays icons together with a description. They
  209.  * can be arranged either horizontally or vertically. Clicking on an item
  210.  * will cause the activated() signal to be emitted. The user can edit
  211.  * existing items by choosing "Edit entry" in the contextmenu. He can also
  212.  * remove or add new entries (via drag&drop or the context menu).
  213.  *
  214.  * KURLBar offers the methods readConfig() and writeConfig() to
  215.  * read and write the configuration of all the entries. It can differentiate
  216.  * between global and local entries -- global entries will be saved in the
  217.  * global configuration (kdeglobals), while local entries will be saved in
  218.  * your application's KConfig object.
  219.  *
  220.  * Due to the configurability, you usually only insert some default entries
  221.  * once and then solely use the read and writeConfig methods to preserve the
  222.  * user's configuration.
  223.  *
  224.  * The widget has a "current" item, that is visualized to differentiate it
  225.  * from others.
  226.  *
  227.  * @author Carsten Pfeiffer <pfeiffer@kde.org>
  228.  * @short A URL-bar widget, as used in the KFileDialog
  229.  */
  230. class KIO_EXPORT KURLBar : public QFrame
  231. {
  232.     Q_OBJECT
  233.  
  234. public:
  235.     /**
  236.      * Constructs a KURLBar. Set @p useGlobalItems to true if you want to
  237.      * allow global/local item separation.
  238.      */
  239.     KURLBar( bool useGlobalItems,
  240.              QWidget *parent = 0, const char *name = 0, WFlags f = 0 );
  241.     /**
  242.      * Destroys the KURLBar.
  243.      */
  244.     ~KURLBar();
  245.  
  246.     /**
  247.      * Inserts a new item into the KURLBar and returns the created
  248.      * KURLBarItem.
  249.      *
  250.      * @p url the url of the item
  251.      * @p description the description of the item (shown in the view)
  252.      * @p applicationLocal whether this should be a global or a local item
  253.      * @p icon an icon -- if empty, the default icon for the url will be used
  254.      * @p group the icon-group for using icon-effects
  255.      */
  256.     virtual KURLBarItem * insertItem( const KURL& url,
  257.                                       const QString& description,
  258.                                       bool applicationLocal = true,
  259.                                       const QString& icon = QString::null,
  260.                                       KIcon::Group group = KIcon::Panel );
  261.     /**
  262.      * Inserts a new dynamic item into the KURLBar and returns the created
  263.      * KURLBarItem.
  264.      *
  265.      * @p url the url of the item
  266.      * @p description the description of the item (shown in the view)
  267.      * @p icon an icon -- if empty, the default icon for the url will be used
  268.      * @p group the icon-group for using icon-effects
  269.      * @since 3.2
  270.      */
  271.     virtual KURLBarItem * insertDynamicItem( const KURL& url,
  272.                                              const QString& description,
  273.                                              const QString& icon = QString::null,
  274.                                              KIcon::Group group = KIcon::Panel );
  275.     /**
  276.      * The items can be arranged either vertically in one column or
  277.      * horizontally in one row.
  278.      * @see orientation
  279.      */
  280.     virtual void setOrientation( Qt::Orientation orient );
  281.     /**
  282.      * @returns the current orientation mode.
  283.      * @see setOrientation
  284.      */
  285.     Orientation orientation() const;
  286.  
  287.     /**
  288.      * Allows to set a custom KURLBarListBox.
  289.      * Note: The previous listbox will be deleted. Items of the previous
  290.      * listbox will not be moved to the new box.
  291.      * @see listBox
  292.      */
  293.     virtual void setListBox( KURLBarListBox * );
  294.     /**
  295.      * @returns the KURLBarListBox that is used.
  296.      * @see setListBox
  297.      */
  298.     KURLBarListBox *listBox() const { return m_listBox; }
  299.  
  300.     /**
  301.      * Sets the default iconsize to be used for items inserted with
  302.      * insertItem. By default KIcon::SizeMedium.
  303.      * @see iconsize
  304.      */
  305.     virtual void setIconSize( int size );
  306.     /**
  307.      * @returns the default iconsize used for items inserted with
  308.      * insertItem. By default KIcon::SizeMedium
  309.      * @see setIconSize
  310.      */
  311.     int iconSize() const { return m_iconSize; }
  312.  
  313.     /**
  314.      * Clears the view, removes all items.
  315.      */
  316.     virtual void clear();
  317.  
  318.     /**
  319.      * @returns a proper sizehint, depending on the orientation and the number
  320.      * of items available.
  321.      */
  322.     virtual QSize sizeHint() const;
  323.  
  324.     /**
  325.      * @returns a proper minimum size (reimplemented)
  326.      */
  327.     virtual QSize minimumSizeHint() const;
  328.  
  329.     /**
  330.      * Call this method to read a saved configuration from @p config,
  331.      * inside the group @p itemGroup. All items in there will be restored.
  332.      * The reading of every item is delegated to the readItem() method.
  333.      */
  334.     virtual void readConfig(  KConfig *config, const QString& itemGroup );
  335.     /**
  336.      * Call this method to save the current configuration into @p config,
  337.      * inside the group @p iconGroup. The writeItem() method is used
  338.      * to save each item.
  339.      */
  340.     virtual void writeConfig( KConfig *config, const QString& itemGroup );
  341.  
  342.     /**
  343.      * Called from readConfig() to read the i'th from @p config.
  344.      * After reading a KURLBarItem is created and initialized with the read
  345.      * values (as well as the given @p applicationLocal).
  346.      */
  347.     virtual void readItem( int i, KConfig *config, bool applicationLocal );
  348.     /**
  349.      * Called from writeConfig() to save the KURLBarItem @p item as the
  350.      * i'th entry in the config-object.
  351.      * @p global tell whether it should be saved in the global configuration
  352.      * or not (using KConfig::writeEntry( key, value, true, global ) ).
  353.      */
  354.     virtual void writeItem( KURLBarItem *item, int i, KConfig *, bool global );
  355.  
  356.     /**
  357.      * @returns the current KURLBarItem, or 0L if none.
  358.      * @see setCurrentItem
  359.      * @see currentURL
  360.      */
  361.     KURLBarItem * currentItem() const;
  362.     /**
  363.      * @returns the url of the current item or an invalid url, if there is
  364.      * no current item.
  365.      * @see currentItem
  366.      * @see setCurrentItem
  367.      */
  368.     KURL currentURL() const;
  369.  
  370.     /**
  371.      * @returns true when the urlbar was modified by the user (e.g. by
  372.      * editing/adding/removing one or more entries). Will be reset to false
  373.      * after calling writeConfig().
  374.      */
  375.     bool isModified() const             { return m_isModified; }
  376.  
  377.     /**
  378.      * @returns true when the urlbar may not be modified by the user
  379.      */
  380.     bool isImmutable() const             { return m_isImmutable; }
  381.  
  382.     /**
  383.      * @returns true if the bar is in vertical mode.
  384.      */
  385.     bool isVertical() const { return orientation() == Vertical; }
  386.  
  387. public slots:
  388.     /**
  389.      * Makes the item with the url @p url the current item. Does nothing
  390.      * if no item with that url is available.
  391.      * @see currentItem
  392.      * @see currentURL
  393.      */
  394.     virtual void setCurrentItem( const KURL& url );
  395.  
  396. signals:
  397.     /**
  398.      * This signal is emitted when the user activated an item, e.g., by
  399.      * clicking on it.
  400.      */
  401.     void activated( const KURL& url );
  402.  
  403. protected:
  404.     /**
  405.      * Pops up a KURLBarItemDialog to let the user add a new item.
  406.      * Uses editItem() to do the job.
  407.      * @returns false if the user aborted the dialog and no item is added.
  408.      */
  409.     virtual bool addNewItem();
  410.     /**
  411.      * Pops up a KURLBarItemDialog to let the user edit the properties
  412.      * of @p item. Invoked e.g. by addNewItem(), when the user drops
  413.      * a url  onto the bar or from the contextmenu.
  414.      * @returns false if the user aborted the dialog and @p item is not
  415.      * changed.
  416.      */
  417.     virtual bool editItem( KURLBarItem *item );
  418.  
  419.     virtual void resizeEvent( QResizeEvent * );
  420.  
  421.     virtual void paletteChange( const QPalette & );
  422.  
  423.     /**
  424.      * The currently active item.
  425.      */
  426.     KURLBarItem * m_activeItem;
  427.     /**
  428.      * Whether we support global entries or just local ones.
  429.      */
  430.     bool m_useGlobal  :1;
  431.  
  432.     /**
  433.      * Whether the urlbar was modified by the user (e.g. by
  434.      * editing/adding/removing an item).
  435.      */
  436.     bool m_isModified :1;
  437.  
  438.     /**
  439.      * Whether the urlbar may be modified by the user.
  440.      * If immutable is true, the urlbar can not be modified.
  441.      */
  442.     bool m_isImmutable :1;
  443.  
  444. protected slots:
  445.     /**
  446.      * Reimplemented to show a contextmenu, allowing the user to add, edit
  447.      * or remove items, or change the iconsize.
  448.      */
  449.     virtual void slotContextMenuRequested( QListBoxItem *, const QPoint& pos );
  450.     /**
  451.      * Called when an item has been selected. Emits the activated()
  452.      * signal.
  453.      */
  454.     virtual void slotSelected( QListBoxItem * );
  455.  
  456.     /**
  457.      * Called when a url was dropped onto the bar to show a
  458.      * KURLBarItemDialog.
  459.      */
  460.     virtual void slotDropped( QDropEvent * );
  461.  
  462. private slots:
  463.     void slotSelected( int button, QListBoxItem * );
  464.  
  465. private:
  466.     KURLBarListBox *m_listBox;
  467.     int m_iconSize;
  468.  
  469.  
  470. protected:
  471.     virtual void virtual_hook( int id, void* data );
  472. private:
  473.     class KURLBarPrivate;
  474.     KURLBarPrivate *d;
  475. };
  476.  
  477.  
  478. ///////////////////////////////////////////////////////////////////
  479. ///////////////////////////////////////////////////////////////////
  480.  
  481.  
  482. class QDragObject;
  483. class KURLBarToolTip;
  484.  
  485. /**
  486.  * This is the listbox used in KURLBar. It is a subclass of KListBox to support
  487.  * drag & drop and to set up the row / column mode.
  488.  *
  489.  * The widget has just one row or one column, depending on orientation().
  490.  *
  491.  * @author Carsten Pfeiffer <pfeiffer@kde.org>
  492.  */
  493. class KIO_EXPORT KURLBarListBox : public KListBox
  494. {
  495.     Q_OBJECT
  496.  
  497. public:
  498.     /**
  499.      * Constructs a KURLBarListBox.
  500.      */
  501.     KURLBarListBox( QWidget *parent = 0, const char *name = 0 );
  502.     /**
  503.      * Destroys the box.
  504.      */
  505.     ~KURLBarListBox();
  506.  
  507.     /**
  508.      * Sets the orientation of the widget. Horizontal means, all items are
  509.      * arranged in one row. Vertical means, all items are arranged in one
  510.      * column.
  511.      * @see orientation
  512.      */
  513.     virtual void setOrientation( Qt::Orientation orient );
  514.     /**
  515.      * @returns the current orientation.
  516.      * @see setOrientation
  517.      */
  518.     Qt::Orientation orientation() const { return m_orientation; }
  519.  
  520.     bool isVertical() const { return m_orientation == Qt::Vertical; }
  521.  
  522. signals:
  523.     /**
  524.      * Emitted when a drop-event happened.
  525.      */
  526.     void dropped( QDropEvent *e );
  527.  
  528. protected:
  529.     /**
  530.      * @returns a suitable QDragObject when an item is dragged.
  531.      */
  532.     virtual QDragObject * dragObject();
  533.  
  534.     virtual void contentsDragEnterEvent( QDragEnterEvent * );
  535.     virtual void contentsDropEvent( QDropEvent * );
  536.     virtual void contextMenuEvent( QContextMenuEvent * );
  537.     virtual void paintEvent( QPaintEvent* );
  538.  
  539. private:
  540.     Qt::Orientation m_orientation;
  541.     KURLBarToolTip *m_toolTip;
  542.  
  543. protected:
  544.     virtual void virtual_hook( int id, void* data );
  545. private:
  546.     class KURLBarListBoxPrivate;
  547.     KURLBarListBoxPrivate *d;
  548. };
  549.  
  550.  
  551. ///////////////////////////////////////////////////////////////////
  552. ///////////////////////////////////////////////////////////////////
  553.  
  554.  
  555. class QCheckBox;
  556. class KIconButton;
  557. class KLineEdit;
  558. class KURLRequester;
  559.  
  560. /**
  561.  * A dialog that allows editing entries of a KURLBar ( KURLBarItem).
  562.  * The dialog offers to configure a given url, description and icon.
  563.  * See the class-method getInformation() for easy usage.
  564.  *
  565.  * @author Carsten Pfeiffer <pfeiffer@kde.org>
  566.  */
  567. class KIO_EXPORT KURLBarItemDialog : public KDialogBase
  568. {
  569.     Q_OBJECT
  570.  
  571. public:
  572.     /**
  573.      * A convenience method to show the dialog and retrieve all the
  574.      * properties via the given parameters. The parameters are used to
  575.      * initialize the dialog and then return the user-configured values.
  576.      *
  577.      * See the KURLBarItem constructor for the parameter description.
  578.      */
  579.     static bool getInformation( bool allowGlobal, KURL& url,
  580.                                 QString& description, QString& icon,
  581.                                 bool& appLocal, int iconSize,
  582.                                 QWidget *parent = 0 );
  583.  
  584.     /**
  585.      * Constructs a KURLBarItemDialog.
  586.      *
  587.      * @p allowGlobal if you set this to true, the dialog will have a checkbox
  588.      *                for the user to decide if he wants the entry to be
  589.      *                available globally or just for the current application.
  590.      * @p url the url of the item
  591.      * @p description a short, translated description of the item
  592.      * @p icon an icon for the item
  593.      * @p appLocal tells whether the item should be local for this application
  594.      *             or be available globally
  595.      * @p iconSize determines the size of the icon that is shown/selectable
  596.      * @p parent the parent-widget for the dialog
  597.      *
  598.      * If you leave the icon empty, the default icon for the given url will be
  599.      * used (KMimeType::pixmapForURL()).
  600.      */
  601.     KURLBarItemDialog( bool allowGlobal, const KURL& url,
  602.                        const QString& description, QString icon,
  603.                        bool appLocal = true,
  604.                        int iconSize = KIcon::SizeMedium,
  605.                        QWidget *parent = 0, const char *name = 0 );
  606.     /**
  607.      * Destroys the dialog.
  608.      */
  609.     ~KURLBarItemDialog();
  610.  
  611.     /**
  612.      * @returns the configured url
  613.      */
  614.     KURL url() const;
  615.  
  616.     /**
  617.      * @returns the configured description
  618.      */
  619.     QString description() const;
  620.  
  621.     /**
  622.      * @returns the configured icon
  623.      */
  624.     QString icon() const;
  625.  
  626.     /**
  627.      * @returns whether the item should be local to the application or global.
  628.      * If allowGlobal was set to false in the constructor, this will always
  629.      * return true.
  630.      */
  631.     bool applicationLocal() const;
  632.  
  633. protected:
  634.     /**
  635.      * The KURLRequester used for editing the url
  636.      */
  637.     KURLRequester * m_urlEdit;
  638.     /**
  639.      * The KLineEdit used for editing the description
  640.      */
  641.     KLineEdit     * m_edit;
  642.     /**
  643.      * The KIconButton to configure the icon
  644.      */
  645.     KIconButton   * m_iconButton;
  646.     /**
  647.      * The QCheckBox to modify the local/global setting
  648.      */
  649.     QCheckBox     * m_appLocal;
  650.  
  651. public slots:
  652.     void urlChanged(const QString & );
  653.  
  654. private:
  655.     class KURLBarItemDialogPrivate;
  656.     KURLBarItemDialogPrivate *d;
  657. };
  658.  
  659.  
  660. #endif // KURLBAR_H
  661.