summaryrefslogtreecommitdiffstats
path: root/kdeui/kpassivepopup.h
blob: 326c995cba0bbcc5bee857b3c671ad11cb07441c (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
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
// -*- c++ -*-

/*
 *   Copyright            : (C) 2001-2002 by Richard Moore
 *   Copyright            : (C) 2004-2005 by Sascha Cunz
 *   License              : This file is released under the terms of the LGPL, version 2.
 *   Email                : rich@kde.org
 *   Email                : sascha.cunz@tiscali.de
 */

#ifndef KPASSIVEPOPUP_H
#define KPASSIVEPOPUP_H

#include <tqframe.h>

#include <kdelibs_export.h>

class TQBoxLayout;
class TQTimer;
class TQLabel;
class TQVBox;

/**
 * @short A dialog-like popup that displays messages without interupting the user.
 *
 * The simplest uses of KPassivePopup are by using the various message() static
 * methods. The position the popup appears at depends on the type of the parent window:
 *
 * @li Normal Windows: The popup is placed adjacent to the icon of the window.
 * @li System Tray Windows: The popup is placed adjact to the system tray window itself.
 * @li Skip Taskbar Windows: The popup is placed adjact to the window
 *     itself if it is visible, and at the edge of the desktop otherwise.
 *
 * You also have the option of calling show with a TQPoint as a parameter that
 * removes the automatic placing of KPassivePopup and shows it in the point you want.
 *
 * The most basic use of KPassivePopup displays a popup containing a piece of text:
 * \code
 *    KPassivePopup::message( "This is the message", this );
 * \endcode
 * We can create popups with titles and icons too, as this example shows:
 * \code
 *    TQPixmap px;
 *    px.load( "hi32-app-logtracker.png" );
 *    KPassivePopup::message( "Some title", "This is the main text", px, this );
 * \endcode
 * For more control over the popup, you can use the setView(TQWidget *) method
 * to create a custom popup.
 * \code
 *    KPassivePopup *pop = new KPassivePopup( parent );
 *
 *    TQVBox *vb = new TQVBox( pop );
 *    (void) new TQLabel( vb, "<b>Isn't this great?</b>" );
 *
 *    TQHBox *box = new TQHBox( vb );
 *    (void) new TQPushButton( box, "Yes" );
 *    (void) new TQPushButton( box, "No" );
 *
 *    pop->setView( vb );
 *    pop->show();
 * \endcode
 *
 * @version $Id$
 * @since 3.1
 * @author Richard Moore, rich@kde.org
 * @author Sascha Cunz, sascha.cunz@tiscali.de
 */
class KDEUI_EXPORT KPassivePopup : public QFrame
{
    Q_OBJECT
    Q_PROPERTY (bool autoDelete READ autoDelete WRITE setAutoDelete )
    Q_PROPERTY (int timeout READ timeout WRITE setTimeout )

public:
    /**
     * Styles that a KPassivePopup can have.
     * @since 3.5
     */
    enum PopupStyle
    {
        Boxed,             ///< Information will appear in a framed box (default)
        Balloon,           ///< Information will appear in a comic-alike balloon
	CustomStyle=128    ///< Ids greater than this are reserved for use by subclasses
    };

    /**
     * Creates a popup for the specified widget.
     */
    KPassivePopup( TQWidget *parent=0, const char *name=0, WFlags f=0 );

    /**
     * Creates a popup for the specified window.
     */
    KPassivePopup( WId parent, const char *name=0, WFlags f=0 );

    /**
     * Creates a popup for the specified widget.
     * @since 3.5
     */
    KPassivePopup( int popupStyle, TQWidget *parent=0, const char *name=0, WFlags f=0 );

    /**
     * Creates a popup for the specified window.
     * @since 3.5
     */
    KPassivePopup( int popupStyle, WId parent, const char *name=0, WFlags f=0 );

    /**
     * Cleans up.
     */
    virtual ~KPassivePopup();

    /**
     * Sets the main view to be the specified widget (which must be a child of the popup).
     */
    void setView( TQWidget *child );

    /**
     * Creates a standard view then calls setView(TQWidget*) .
     */
    void setView( const TQString &caption, const TQString &text = TQString::null );

    /**
     * Creates a standard view then calls setView(TQWidget*) .
     */
    virtual void setView( const TQString &caption, const TQString &text, const TQPixmap &icon );

    /**
     * Returns a widget that is used as standard view if one of the 
     * setView() methods taking the TQString arguments is used.
     * You can use the returned widget to customize the passivepopup while 
     * keeping the look similar to the "standard" passivepopups.
     *
     * After customizing the widget, pass it to setView( TQWidget* )
     *
     * @param caption The window caption (title) on the popup
     * @param text The text for the popup
     * @param icon The icon to use for the popup
     * @param parent The parent widget used for the returned TQVBox. If left 0L,
     * then "this", i.e. the passive popup object will be used.
     *
     * @return a TQVBox containing the given arguments, looking like the
     * standard passivepopups.
     * @see setView( TQWidget * )
     * @see setView( const TQString&, const TQString& )
     * @see setView( const TQString&, const TQString&, const TQPixmap& )
     */
    TQVBox * standardView( const TQString& caption, const TQString& text,
                          const TQPixmap& icon, TQWidget *parent = 0L );

    /**
     * Returns the main view.
     */
    TQWidget *view() const { return msgView; }

    /**
     * Returns the delay before the popup is removed automatically.
     */
    int timeout() const { return hideDelay; }

    /**
     * Enables / disables auto-deletion of this widget when the timeout
     * occurs.
     * The default is false. If you use the class-methods message(),
     * auto-delection is turned on by default.
     */
    virtual void setAutoDelete( bool autoDelete );

    /**
     * @returns true if the widget auto-deletes itself when the timeout occurs.
     * @see setAutoDelete
     */
    bool autoDelete() const { return m_autoDelete; }

    /**
     * Sets the anchor of this balloon. The balloon tries automatically to adjust
     * itself somehow around the point.
     * @since 3.5
     */
    void setAnchor( const TQPoint& anchor );

    // TODO KDE4: give all the statics method a const TQPoint p = TQPoint() that in 
    // case the point is not null calls the show(cosnt TQPoint &p) method instead
    // the show() one.
    /**
     * Convenience method that displays popup with the specified  message  beside the
     * icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static KPassivePopup *message( const TQString &text, TQWidget *parent, const char *name=0 );

    /**
     * Convenience method that displays popup with the specified caption and message
     * beside the icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static KPassivePopup *message( const TQString &caption, const TQString &text,
				   TQWidget *parent, const char *name=0 );

    /**
     * Convenience method that displays popup with the specified icon, caption and
     * message beside the icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static KPassivePopup *message( const TQString &caption, const TQString &text,
				   const TQPixmap &icon,
				   TQWidget *parent, const char *name=0, int timeout = -1 );

    /**
     * Convenience method that displays popup with the specified icon, caption and
     * message beside the icon of the specified window.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static KPassivePopup *message( const TQString &caption, const TQString &text,
				   const TQPixmap &icon,
				   WId parent, const char *name=0, int timeout = -1 );

    /**
     * Convenience method that displays popup with the specified popup-style and message beside the
     * icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static KPassivePopup *message( int popupStyle, const TQString &text, TQWidget *parent,
				   const char *name=0 );

    /**
     * Convenience method that displays popup with the specified popup-style, caption and message
     * beside the icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static KPassivePopup *message( int popupStyle, const TQString &caption, const TQString &text,
				   TQWidget *parent, const char *name=0 );

    /**
     * Convenience method that displays popup with the specified popup-style, icon, caption and
     * message beside the icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static KPassivePopup *message( int popupStyle, const TQString &caption, const TQString &text,
				   const TQPixmap &icon,
				   TQWidget *parent, const char *name=0, int timeout = -1 );

    /**
     * Convenience method that displays popup with the specified popup-style, icon, caption and
     * message beside the icon of the specified window.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static KPassivePopup *message( int popupStyle, const TQString &caption, const TQString &text,
				   const TQPixmap &icon,
				   WId parent, const char *name=0, int timeout = -1 );


public slots:
    /**
     * Sets the delay for the popup is removed automatically. Setting the delay to 0
     * disables the timeout, if you're doing this, you may want to connect the
     * clicked() signal to the hide() slot.
     * Setting the delay to -1 makes it use the default value.
     *
     * @see timeout
     */
    void setTimeout( int delay );

    /**
     * Reimplemented to reposition the popup.
     */
    virtual void show();

    /**
     * Shows the popup in the given point
     * @since 3.5
     */
    void show(const TQPoint &p);

signals:
    /**
     * Emitted when the popup is clicked.
     */
    void clicked();

    /**
     * Emitted when the popup is clicked.
     */
    void clicked( TQPoint pos );

protected:
    /**
     * This method positions the popup.
     */
    virtual void positionSelf();

    /**
     * Reimplemented to destroy the object when autoDelete() is
     * enabled.
     */
    virtual void hideEvent( TQHideEvent * );

    /**
     * Moves the popup to be adjacent to the icon of the specified rectangle.
     */
    void moveNear( TQRect target );

    /**
     * Reimplemented to detect mouse clicks.
     */
    virtual void mouseReleaseEvent( TQMouseEvent *e );

    /**
     * If no relative window (eg taskbar button, system tray window) is
     * available, use this rectangle (pass it to moveNear()).
     * Basically KWinModule::workArea() with width and height set to 0
     * so that moveNear uses the upper-left position.
     * @return The TQRect to be passed to moveNear() if no other is
     * available.
     */
    TQRect defaultArea() const;

    /**
     * Updates the transparency mask. Unused if PopupStyle == Boxed
     * @since 3.5
     */
    void updateMask();

    /**
     * Overwrite to paint the border when PopupStyle == Balloon.
     * Unused if PopupStyle == Boxed
     */
    virtual void paintEvent( TQPaintEvent* pe );

private:
    void init( int popupStyle );

    WId window;
    TQWidget *msgView;
    TQBoxLayout *topLayout;
    int hideDelay;
    TQTimer *hideTimer;

    TQLabel *ttlIcon;
    TQLabel *ttl;
    TQLabel *msg;

    bool m_autoDelete;

    /* @internal */
    class Private;
    Private *d;
};

#endif // KPASSIVEPOPUP_H

// Local Variables:
// c-basic-offset: 4
// End: