workspace/krunner/interfaces/quicksand/qs_matchview.h

   1 /*
   2  *   Copyright (C) 2007-2008 Ryan P. Bitanga <ryan.bitanga@gmail.com>
   3  *
   4  *   This program is free software; you can redistribute it and/or modify
   5  *   it under the terms of the GNU General Public License as published by
   6  *   the Free Software Foundation; either version 2 of the License, or
   7  *   (at your option) any later version.
   8  *
   9  *   This program is distributed in the hope that it will be useful,
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  *   GNU General Public License for more details.
  13  *
  14  *   You should have received a copy of the GNU General Public License
  15  *   along with this program; if not, write to the
  16  *   Free Software Foundation, Inc.,
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA .
  18  */
  19
  20 #ifndef QS_MATCHVIEW_H
  21 #define QS_MATCHVIEW_H
  22
  23 #include <QList>
  24 #include <QWidget>
  25
  26 class QFocusEvent;
  27 class QKeyPressEvent;
  28 class QResizeEvent;
  29
  30 namespace QuickSand {
  31
  32     class MatchItem;
  33
  34     /**
  35      * @class QsMatchView
  36      * @short A class to visualize a set of items
  37      *
  38      * QsMatchView is composed of a title label, an item count label,
  39      * a visualization box, and a popup completion box. The visualization
  40      * box has three modes: scrolling icon, selected item, and text mode.
  41      * The scrolling icon mode visualizes all items as a single horizontal
  42      * row of icons. Scrolling is controlled by either the completion box
  43      * or the view itself.
  44      */
  45     class QsMatchView : public QWidget
  46     {
  47         Q_OBJECT
  48         public:
  49             QsMatchView(QWidget *parent = 0);
  50             ~QsMatchView();
  51
  52             /**
  53              * Removes all items from the scene
  54              */
  55             void clear(bool deleteItems = false);
  56             /**
  57              * Removes items from the scene and places default find message
  58              */
  59             void reset();
  60             /**
  61              * Shows the loading animation
  62              */
  63             void showLoading();
  64             /**
  65              * Sets the list of items to be displayed on screen
  66              * @param items The list of items to display
  67              * @param popup Display the popup completion box
  68              * @param append Append items to the current list instead of replacing it
  69              */
  70             void setItems(const QList<MatchItem*> &items, bool popup = true, bool append = false);
  71
  72             /**
  73              * Sets the item count text on the upper right hand corner
  74              * Defaults to "items"
  75              */
  76              void setItemCountSuffix(const QString &suffix);
  77         public slots:
  78             /**
  79              * Sets the title text on the upper left hand corner of the widget
  80              */
  81             void setTitle(const QString &title);
  82             /**
  83              * Display the popup
  84              */
  85             void showPopup();
  86         private slots:
  87             /**
  88              * Switches between Icon Parade and Selected Item modes
  89              */
  90             void toggleView();
  91             void scrollToItem(int index);
  92             /**
  93              * Uses whole view to display selected item and hides all other matches
  94              */
  95             void showSelected();
  96             /**
  97              * Shows a scrolling list of icons for each match
  98              */
  99             void showList();
 100         signals:
 101             /**
 102              * Emitted when the user presser enter
 103              */
 104             void itemActivated(MatchItem *item);
 105             /**
 106              * Emitted when the user changes selection through either the completion
 107              * box or the scrolling icon view
 108              */
 109             void selectionChanged(MatchItem *item);
 110             /**
 111              * Emitted when the internal query string changes
 112              */
 113             void textChanged(const QString &text);
 114         private:
 115             /**
 116              * Sets the text in the bottom portion of the widget
 117              * @param text Text to display
 118              * @param color Color of the rectangle behind the text
 119              */
 120             void setDescriptionText(const QString &text, const QColor &color);
 121             /**
 122              * Convenience method. Calls setDescriptionText(text, QColor(Qt::white)
 123              */
 124             void setDescriptionText(const QString &text);
 125
 126             /**
 127              * Removes match items from scene but does not delete them
 128              */
 129             void clearItems();
 130
 131             /**
 132              * Selects item at the specified index
 133              */
 134             void selectItem(int index);
 135             /**
 136              * Highlights item and centers item when in scrolling icon mode
 137              */
 138             void focusItem(int index);
 139             void scrollLeft();
 140             void scrollRight();
 141
 142             void setItemCount(int items);
 143
 144             void resizeEvent(QResizeEvent *e);
 145             void focusInEvent(QFocusEvent *event);
 146             void focusOutEvent(QFocusEvent *event);
 147             void keyPressEvent(QKeyEvent *event);
 148
 149             class Private;
 150             Private* const d;
 151     };
 152 }
 153
 154 #endif