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 / kcompletionbox.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  7.0 KB  |  247 lines
  1. /* This file is part of the KDE libraries
  2.  
  3.    Copyright (c) 2000 Carsten Pfeiffer <pfeiffer@kde.org>
  4.                  2000 Stefan Schimanski <1Stein@gmx.de>
  5.                  2000,2001,2002,2003,2004 Dawit Alemayehu <adawit@kde.org>
  6.  
  7.    This library is free software; you can redistribute it and/or
  8.    modify it under the terms of the GNU Library General Public
  9.    License (LGPL) as published by the Free Software Foundation; either
  10.    version 2 of the License, or (at your option) any later version.
  11.  
  12.    This library is distributed in the hope that it will be useful,
  13.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15.    Library General Public License for more details.
  16.  
  17.    You should have received a copy of the GNU Library General Public License
  18.    along with this library; see the file COPYING.LIB.  If not, write to
  19.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  20.    Boston, MA 02110-1301, USA.
  21. */
  22.  
  23. #ifndef KCOMPLETIONBOX_H
  24. #define KCOMPLETIONBOX_H
  25.  
  26. class QEvent;
  27. #include <qstringlist.h>
  28. #include <klistbox.h>
  29.  
  30. /**
  31.  * @short A helper widget for "completion-widgets" (KLineEdit, KComboBox))
  32.  *
  33.  * A little utility class for "completion-widgets", like KLineEdit or
  34.  * KComboBox. KCompletionBox is a listbox, displayed as a rectangle without
  35.  * any window decoration, usually directly under the lineedit or combobox.
  36.  * It is filled with all possible matches for a completion, so the user
  37.  * can select the one he wants.
  38.  *
  39.  * It is used when KGlobalSettings::Completion == CompletionPopup or CompletionPopupAuto.
  40.  *
  41.  * @author Carsten Pfeiffer <pfeiffer@kde.org>
  42.  */
  43. class KDEUI_EXPORT KCompletionBox : public KListBox
  44. {
  45.     Q_OBJECT
  46.     Q_PROPERTY( bool isTabHandling READ isTabHandling WRITE setTabHandling )
  47.     Q_PROPERTY(QString cancelledText READ cancelledText WRITE setCancelledText)
  48.     Q_PROPERTY( bool activateOnSelect READ activateOnSelect WRITE setActivateOnSelect )
  49.  
  50. public:
  51.     /**
  52.      * Constructs a KCompletionBox.
  53.      *
  54.      * The parent widget is used to give the focus back when pressing the
  55.      * up-button on the very first item.
  56.      */
  57.     KCompletionBox( QWidget *parent, const char *name = 0 );
  58.  
  59.     /**
  60.      * Destroys the box
  61.      */
  62.     ~KCompletionBox();
  63.  
  64.     virtual QSize sizeHint() const;
  65.  
  66.     /**
  67.      * @returns true if selecting an item results in the emition of the selected signal.
  68.      *
  69.      * @since 3.4.1
  70.      */
  71.     bool activateOnSelect() const;
  72.  
  73. public slots:
  74.     /**
  75.      * Returns a list of all items currently in the box.
  76.      */
  77.     QStringList items() const;
  78.  
  79.     /**
  80.      * Inserts @p items into the box. Does not clear the items before.
  81.      * @p index determines at which position @p items will be inserted.
  82.      * (defaults to appending them at the end)
  83.      */
  84.     void insertItems( const QStringList& items, int index = -1 );
  85.  
  86.     /**
  87.      * Clears the box and inserts @p items.
  88.      */
  89.     void setItems( const QStringList& items );
  90.  
  91.     /**
  92.      * Adjusts the size of the box to fit the width of the parent given in the
  93.      * constructor and pops it up at the most appropriate place, relative to
  94.      * the parent.
  95.      *
  96.      * Depending on the screensize and the position of the parent, this may
  97.      * be a different place, however the default is to pop it up and the
  98.      * lower left corner of the parent.
  99.      *
  100.      * Make sure to hide() the box when appropriate.
  101.      */
  102.     virtual void popup();
  103.  
  104.     /**
  105.      * Makes this widget (when visible) capture Tab-key events to traverse the
  106.      * items in the dropdown list.
  107.      *
  108.      * Default off, as it conflicts with the usual behavior of Tab to traverse
  109.      * widgets. It is useful for cases like Konqueror's Location Bar, though.
  110.      *
  111.      * @see isTabHandling
  112.      */
  113.     void setTabHandling( bool enable );
  114.  
  115.     /**
  116.      * @returns true if this widget is handling Tab-key events to traverse the
  117.      * items in the dropdown list, otherwise false.
  118.      *
  119.      * Default is false.
  120.      *
  121.      * @see setTabHandling
  122.      */
  123.     bool isTabHandling() const;
  124.  
  125.     /**
  126.      * Sets the text to be emitted if the user chooses not to
  127.      * pick from the available matches.
  128.      *
  129.      * If the canceled text is not set through this function, the
  130.      * userCancelled signal will not be emitted.
  131.      *
  132.      * @see userCancelled( const QString& )
  133.      * @param txt  the text to be emitted if the user cancels this box
  134.      */
  135.     void setCancelledText( const QString& txt);
  136.  
  137.     /**
  138.      * @returns the text set via setCancelledText() or QString::null.
  139.      */
  140.     QString cancelledText() const;
  141.  
  142.     /**
  143.      * Set whether or not the selected signal should be emitted when an
  144.      * item is selected. By default the selected signal is emitted.
  145.      *
  146.      * @param state false if the signal should not be emitted.
  147.      * @since 3.4.1
  148.      */
  149.     void setActivateOnSelect(bool state);
  150.  
  151.  
  152.     /**
  153.      * Moves the selection one line down or select the first item if nothing is selected yet.
  154.      */
  155.     void down();
  156.  
  157.     /**
  158.      * Moves the selection one line up or select the first item if nothing is selected yet.
  159.      */
  160.     void up();
  161.  
  162.     /**
  163.      * Moves the selection one page down.
  164.      */
  165.     void pageDown();
  166.  
  167.     /**
  168.      * Moves the selection one page up.
  169.      */
  170.     void pageUp();
  171.  
  172.     /**
  173.      * Moves the selection up to the first item.
  174.      */
  175.     void home();
  176.  
  177.     /**
  178.      * Moves the selection down to the last item.
  179.      */
  180.     void end();
  181.  
  182.     /**
  183.      * Re-implemented for internal reasons.  API is unaffected.
  184.      */
  185.     virtual void show();
  186.  
  187.     /**
  188.      * Re-implemented for internal reasons.  API is unaffected.
  189.      */
  190.     virtual void hide();
  191.  
  192. signals:
  193.     /**
  194.      * Emitted when an item was selected, contains the text of
  195.      * the selected item.
  196.      */
  197.     void activated( const QString& );
  198.  
  199.     /**
  200.      * Emitted whenever the user chooses to ignore the available
  201.      * selections and close the this box.
  202.      */
  203.     void userCancelled( const QString& );
  204.  
  205. protected:
  206.     /**
  207.      * This calculates the size of the dropdown and the relative position of the top
  208.      * left corner with respect to the parent widget. This matches the geometry and position
  209.      * normally used by K/QComboBox when used with one.
  210.      */
  211.     QRect calculateGeometry() const;
  212.  
  213.     /**
  214.      * This properly sizes and positions the listbox.
  215.      */
  216.     void sizeAndPosition();
  217.  
  218.     /**
  219.      * Reimplemented from KListBox to get events from the viewport (to hide
  220.      * this widget on mouse-click, Escape-presses, etc.
  221.      */
  222.     virtual bool eventFilter( QObject *, QEvent * );
  223.  
  224. protected slots:
  225.     /**
  226.      * Called when an item was activated. Emits
  227.      * activated() with the item.
  228.      */
  229.     virtual void slotActivated( QListBoxItem * );
  230.  
  231. private slots:
  232.     void slotSetCurrentItem( QListBoxItem *i ) { setCurrentItem( i ); } // grrr
  233.     void slotCurrentChanged();
  234.     void canceled();
  235.     void slotItemClicked( QListBoxItem * );
  236.  
  237. protected:
  238.     virtual void virtual_hook( int id, void* data );
  239.  
  240. private:
  241.     class KCompletionBoxPrivate;
  242.     KCompletionBoxPrivate* const d;
  243. };
  244.  
  245.  
  246. #endif // KCOMPLETIONBOX_H
  247.