← Back to branch summary

~ubuntu-branches/ubuntu/utopic/kde-workspace/utopic-proposed

« back to all changes in this revision

Viewing changes to plasma/desktop/applets/kickoff/simpleapplet/menuview.h

  • Committer: Bazaar Package Importer
  • Author(s): Michał Zając
  • Date: 2011-07-09 08:31:15 UTC
  • Revision ID: james.westby@ubuntu.com-20110709083115-ohyxn6z93mily9fc
Tags: upstream-4.6.90
Import upstream version 4.6.90

Show diffs side-by-side

added added

removed removed

Lines of Context:
plasma/desktop/applets/kickoff/simpleapplet/menuview.h
 
1
/*
 
2
    Copyright 2007 Robert Knight <robertknight@gmail.com>
 
3
    Copyright 2008-2009 Sebastian Sauer <mail@dipe.org>
 
4
 
 
5
    This library is free software; you can redistribute it and/or
 
6
    modify it under the terms of the GNU Library General Public
 
7
    License as published by the Free Software Foundation; either
 
8
    version 2 of the License, or (at your option) any later version.
 
9
 
 
10
    This library 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 GNU
 
13
    Library General Public License for more details.
 
14
 
 
15
    You should have received a copy of the GNU Library General Public License
 
16
    along with this library; see the file COPYING.LIB.  If not, write to
 
17
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 
18
    Boston, MA 02110-1301, USA.
 
19
*/
 
20
 
 
21
#ifndef MENUVIEW_H
 
22
#define MENUVIEW_H
 
23
 
 
24
// Qt
 
25
#include <QtCore/QModelIndex>
 
26
 
 
27
// KDE
 
28
#include <KMenu>
 
29
 
 
30
class QAbstractItemModel;
 
31
class QStandardItem;
 
32
 
 
33
namespace Kickoff
 
34
{
 
35
 
 
36
class UrlItemLauncher;
 
37
 
 
38
/**
 
39
 * A view for a QAbstractItemModel which displays the model (set with setModel())
 
40
 * as a hierarchical menu.
 
41
 *
 
42
 * When the menu is executed and an item is triggered, the model index associated with the
 
43
 * chosen item can be found by calling indexForAction() with the triggered action.  The action
 
44
 * associated with a particular model index can be found using actionForIndex().
 
45
 *
 
46
 * MenuView creates actions for parts of the model on demand as the user explores the menu.
 
47
 * The type of action created for leaf items in the tree can be changed by re-implementing
 
48
 * createLeafAction().  When a new action is created or if the corresponding model
 
49
 * index's data changes, updateAction() is called to set the action's properties.  This
 
50
 * can be reimplemented in sub-classes to change the appearance of the actions.
 
51
 */
 
52
class MenuView : public KMenu
 
53
{
 
54
    Q_OBJECT
 
55
public:
 
56
 
 
57
    /** Constructs a new menu with the specified @p parent */
 
58
    MenuView(QWidget *parent = 0, const QString &title = QString(), const QIcon &icon = QIcon());
 
59
    /** Destructor */
 
60
    virtual ~MenuView();
 
61
 
 
62
    /// Options for a model.
 
63
    enum ModelOptions {
 
64
        None, ///< no options.
 
65
        MergeFirstLevel ///< merge the first both levels of items within the model into one hirachy in the menuview.
 
66
    };
 
67
 
 
68
    /** Adds a model to display within this menu. */
 
69
    void addModel(QAbstractItemModel *model, ModelOptions options = None, const QString & relativePath = QString());
 
70
 
 
71
    /** Adds a QStandardItem to display within this menu. This menu will take over the ownership of the item. */
 
72
    void addItem(QStandardItem *item);
 
73
 
 
74
    /** Returns the UrlItemLauncher used to handle launching of urls. */
 
75
    UrlItemLauncher *launcher() const;
 
76
 
 
77
    /** Maps an action in the menu to its corresponding index in model() */
 
78
    QModelIndex indexForAction(QAction *action) const;
 
79
 
 
80
    /**
 
81
     * Maps an index in the model to its corresponding action in the menu.
 
82
     * If @p index is invalid then menuAction() will be returned.  If @p index
 
83
     * is in a part of the tree which the user has not yet explored then 0 will
 
84
     * be returned because the menu hierarchy is constructed on-demand as the user
 
85
     * explores the menu.
 
86
     */
 
87
    QAction *actionForIndex(const QModelIndex& index) const;
 
88
 
 
89
    /**
 
90
     * Returns true if the passed \p index is a valid QModelIndex and does
 
91
     * represent a QAction. This method is equal to the actionForIndex() method
 
92
     * above except allowing to explicit ask if the QModelIndex is valid and
 
93
     * to indicate that way, that it may the case that the QModelIndex went
 
94
     * out of scope already.
 
95
     */
 
96
    bool isValidIndex(const QModelIndex& index) const;
 
97
 
 
98
    /** Sets the column from the model which is used to construct the actions in the menu. */
 
99
    void setColumn(int column);
 
100
    /** Returns the column from the model which is used to construct the actions in the menu. */
 
101
    int column() const;
 
102
 
 
103
    /** The format type enumeration. */
 
104
    enum FormatType {
 
105
        Name = 0, ///< Name only
 
106
        Description, ///< Description only
 
107
        NameDescription, ///< Name (Description)
 
108
        DescriptionName, ///< Description (Name)
 
109
        NameDashDescription ///< Name - Description
 
110
    };
 
111
    /** \return the format type. */
 
112
    FormatType formatType() const;
 
113
    /** Set the format type. */
 
114
    void setFormatType(FormatType formattype);
 
115
    /** Set visibility of model title on menu. */
 
116
    void setModelTitleVisible(QAbstractItemModel *model, bool visible);
 
117
 
 
118
protected:
 
119
 
 
120
    /**
 
121
    * Creates a new action to represent a leaf index in the tree.  A leaf index
 
122
    * is one which does not have children.  The default implementation creates a new
 
123
    * QAction with no properties set.  updateAction() is immediately called on the
 
124
    * return action to set its text and icon.
 
125
    *
 
126
    * @param index The index in the model for which an action should be created
 
127
    * @param parent The object which should be set as the parent of the new action
 
128
    */
 
129
    virtual QAction *createLeafAction(const QModelIndex& index, QObject *parent);
 
130
 
 
131
    /**
 
132
     * Sets the text, icon and other properties of @p action using the data
 
133
     * associated with @p index in the model().  This is called whenever the data for
 
134
     * a range of indexes in the tree is altered.
 
135
     *
 
136
     * The default implementation sets the action's text to the index's Qt::DisplayRole data
 
137
     * and the action's icon to the index's Qt::DecorationRole data.
 
138
     */
 
139
    virtual void updateAction(QAbstractItemModel *model, QAction *action, const QModelIndex& index);
 
140
 
 
141
    // reimplemented
 
142
    virtual bool eventFilter(QObject *watched, QEvent *event);
 
143
 
 
144
public Q_SLOTS:
 
145
    /**
 
146
     * An item in the menu got triggered.
 
147
     */
 
148
    void actionTriggered(QAction* action);
 
149
 
 
150
    void contextMenuRequested(const QPoint& pos);
 
151
 
 
152
Q_SIGNALS:
 
153
    /**
 
154
     * Compared to the aboutToShow() this signal will be emitted after the menu
 
155
     * got hidden.
 
156
     */
 
157
    void afterBeingHidden();
 
158
 
 
159
    void customContextMenuRequested(QMenu* menu, const QPoint& pos);
 
160
 
 
161
private Q_SLOTS:
 
162
    /// new items have been inserted into the model
 
163
    void rowsInserted(const QModelIndex& parent, int start, int end);
 
164
    /// existing items are about to be removed from the model
 
165
    void rowsAboutToBeRemoved(const QModelIndex& parent, int start, int end);
 
166
    /// data within an item of the model change
 
167
    void dataChanged(const QModelIndex& topLeft, const QModelIndex& bottomRight);
 
168
    /// the model did reset itself and all items are invalid
 
169
    void modelReset();
 
170
 
 
171
private:
 
172
    class Private;
 
173
    Private * const d;
 
174
};
 
175
 
 
176
}
 
177
 
 
178
#endif // MENUVIEW_H
 
179