summaryrefslogtreecommitdiffstats
path: root/kdeui/kpopupmenu.h
blob: 8c593601cebaa8b133a30eabb5507a77c717bf42 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
/* This file is part of the KDE libraries
   Copyright (C) 2000 Daniel M. Duley <mosfet@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License version 2 as published by the Free Software Foundation.

   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 _KPOPUP_H
#define _KPOPUP_H "$Id$"

#define INCLUDE_MENUITEM_DEF

#include <tqpopupmenu.h>
#include <kpixmapeffect.h>
#include <kpixmap.h>
#include <kdelibs_export.h>
/**
 * @short KPopupMenu title widget.
 *
 * Title widget for use in KPopupMenu.
 *
 * You usually don't have to create this manually since
 * KPopupMenu::insertTitle will do it for you, but it is allowed if
 * you wish to customize it's look.
 *
 * @author Daniel M. Duley <mosfet@kde.org>
 */
class KDEUI_EXPORT KPopupTitle : public TQWidget
{
    Q_OBJECT

public:
    /**
     * Constructs a title widget with the user specified gradient, pixmap,
     * and colors.
     */
    KPopupTitle(TQWidget *parent=0, const char *name=0);
    /**
     * @deprecated
     * Constructs a title widget with the specified gradient and colors.
     */
    KPopupTitle(KPixmapEffect::GradientType gradient, const TQColor &color,
                const TQColor &textColor, TQWidget *parent=0,
                const char *name=0) KDE_DEPRECATED;
    /**
     * @deprecated
     * Constructs a title widget with the specified pixmap and colors.
     */
    KPopupTitle(const KPixmap &background, const TQColor &color,
                const TQColor &textColor, TQWidget *parent=0,
                const char *name=0) KDE_DEPRECATED;
    /**
     * Sets the title string and optional icon for the title widget.
     *
     * You will want to call this before inserting into a menu.
     */
    void setTitle(const TQString &text, const TQPixmap *icon=0);
    /**
     * Returns the current title.
     */
    TQString title() const { return titleStr; }
    /**
     * Returns the current icon.
     */
    TQPixmap icon() const { return miniicon; }

    TQSize tqsizeHint() const;

public slots:
    /// @since 3.1
    void setText( const TQString &text );
    /// @since 3.1
    void setIcon( const TQPixmap &pix );

protected:
    void calcSize();
    void paintEvent(TQPaintEvent *ev);

    // Remove in KDE4
    KPixmapEffect::GradientType grType;
    TQString titleStr;
    // Remove in KDE4
    KPixmap fill;
    TQPixmap miniicon;
    TQColor fgColor, bgColor, grHigh, grLow;
    bool useGradient;

protected:
    virtual void virtual_hook( int id, void* data );
private:
    class KPopupTitlePrivate;
    KPopupTitlePrivate *d;
};

/**
 * @short A menu with title items.
 *
 * KPopupMenu is a class for menus with standard title items and keyboard
 * accessibility for popups with many options and/or varying options. It acts
 * identically to TQPopupMenu, with the addition of insertTitle(),
 * changeTitle(), setKeyboardShortcutsEnabled() and
 * setKeyboardShortcutsExecute() methods.
 *
 * The titles support a text string, an icon, plus user defined gradients,
 * colors, and background pixmaps.
 *
 * The keyboard search algorithm is incremental with additional underlining
 * for user feedback.
 *
 * @author Daniel M. Duley <mosfet@kde.org>
 * @author Hamish Rodda <rodda@kde.org>
 */
class KDEUI_EXPORT KPopupMenu : public TQPopupMenu {
    Q_OBJECT
    TQ_OBJECT
public:
    /**
     * Constructs a KPopupMenu.
     */
    KPopupMenu(TQWidget *parent=0, const char *name=0);

    /**
     * Destructs the object
     */
    ~KPopupMenu();

    /**
     * Inserts a title item with no icon.
     */
    int insertTitle(const TQString &text, int id=-1, int index=-1);
    /**
     * Inserts a title item with the given icon and title.
     */
    int insertTitle(const TQPixmap &icon, const TQString &text, int id=-1,
                    int index=-1);
    /**
     * Changes the title of the item at the specified id. If a icon was
     * previously set it is cleared.
     */
    void changeTitle(int id, const TQString &text);
    /**
     * Changes the title and icon of the title item at the specified id.
     */
    void changeTitle(int id, const TQPixmap &icon, const TQString &text);
    /**
     * Returns the title of the title item at the specified id. The default
     * id of -1 is for backwards compatibility only, you should always specify
     * the id.
     */
    TQString title(int id=-1) const;
    /**
     * Returns the icon of the title item at the specified id.
     */
    TQPixmap titlePixmap(int id) const;

    /**
     * Enables keyboard navigation by searching for the entered key sequence.
     * Also underlines the currently selected item, providing feedback on the search.
     *
     * Defaults to off.
     *
     * WARNING: calls to text() of currently keyboard-selected items will
     * contain additional ampersand characters.
     *
     * WARNING: though pre-existing keyboard shortcuts will not interfere with the
     * operation of this feature, they may be confusing to the user as the existing
     * shortcuts will not work.
     * @since 3.1
     */
    void setKeyboardShortcutsEnabled(bool enable);

    /**
     * Enables execution of the menu item once it is uniquely specified.
     * Defaults to off.
     * @since 3.1
     */
    void setKeyboardShortcutsExecute(bool enable);

    /**
     * @deprecated
     * Obsolete method provided for backwards compatibility only. Use the
     * normal constructor and insertTitle instead.
     */
    KPopupMenu(const TQString &title, TQWidget *parent=0, const char *name=0) KDE_DEPRECATED;

    /**
     * @deprecated
     * Obsolete method provided for backwards compatibility only. Use
     * insertTitle and changeTitle instead.
     */
    void setTitle(const TQString &title) KDE_DEPRECATED;

    /**
     * Returns the context menu associated with this menu
     * @since 3.2
     */
    TQPopupMenu* contextMenu();

    /**
     * Returns the context menu associated with this menu
     * @since 3.2
     */
    const TQPopupMenu* contextMenu() const;

    /**
     * Hides the context menu if shown
     * @since 3.2
     */
    void hideContextMenu();

    /**
     * Returns the KPopupMenu associated with the current context menu
     * @since 3.2
     */
    static KPopupMenu* contextMenuFocus();

    /**
     * returns the ID of the menuitem associated with the current context menu
     * @since 3.2
     */
    static int contextMenuFocusItem();

    /**
     * Reimplemented for internal purposes
     * @since 3.4
     */
    virtual void activateItemAt(int index);
    /**
     * Return the state of the mouse button and keyboard modifiers
     * when the last menuitem was activated.
     * @since 3.4
     */
    TQt::ButtonState state() const;

signals:
    /**
     * connect to this signal to be notified when a context menu is about to be shown
     * @param menu The menu that the context menu is about to be shown for
     * @param menuItem The menu item that the context menu is currently on
     * @param ctxMenu The context menu itself
     * @since 3.2
     */
    void aboutToShowContextMenu(KPopupMenu* menu, int menuItem, TQPopupMenu* ctxMenu);

protected:
    virtual void closeEvent(TQCloseEvent *);
    virtual void keyPressEvent(TQKeyEvent* e);
    /// @since 3.4
    virtual void mouseReleaseEvent(TQMouseEvent* e);
    virtual void mousePressEvent(TQMouseEvent* e);
    virtual bool focusNextPrevChild( bool next );
    virtual void contextMenuEvent(TQContextMenuEvent *e);
    virtual void hideEvent(TQHideEvent*);

    virtual void virtual_hook( int id, void* data );

protected slots:
    /// @since 3.1
    TQString underlineText(const TQString& text, uint length);
    /// @since 3.1
    void resetKeyboardVars(bool noMatches = false);
    void itemHighlighted(int whichItem);
    void showCtxMenu(TQPoint pos);
    void ctxMenuHiding();
    void ctxMenuHideShowingMenu();

private:
    class KPopupMenuPrivate;
    KPopupMenuPrivate *d;
};

#endif