.TH "KPassivePopup" 3 "28 Jan 2004" "kdeui Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KPassivePopup \- A dialog-like popup that displays messages without interupting the user.  

.PP
.SH SYNOPSIS
.br
.PP
\fC#include <kpassivepopup.h>\fP
.PP
Inherits \fBQFrame\fP.
.PP
.SS "Public Slots"

.in +1c
.ti -1c
.RI "void \fBsetTimeout\fP (int delay)"
.br
.RI "\fISets the delay for the popup is removed automatically. \fP"
.ti -1c
.RI "virtual void \fBshow\fP ()"
.br
.RI "\fIReimplemented to reposition the popup. \fP"
.in -1c
.SS "Signals"

.in +1c
.ti -1c
.RI "void \fBclicked\fP ()"
.br
.RI "\fIEmitted when the popup is clicked. \fP"
.ti -1c
.RI "void \fBclicked\fP (\fBQPoint\fP pos)"
.br
.RI "\fIEmitted when the popup is clicked. \fP"
.in -1c
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fBKPassivePopup\fP (\fBQWidget\fP *parent=0, const  char *name=0, WFlags f=0)"
.br
.RI "\fICreates a popup for the specified widget. \fP"
.ti -1c
.RI "\fBKPassivePopup\fP (WId parent, const  char *name=0, WFlags f=0)"
.br
.RI "\fICreates a popup for the specified window. \fP"
.ti -1c
.RI "virtual \fB~KPassivePopup\fP ()"
.br
.RI "\fICleans up. \fP"
.ti -1c
.RI "void \fBsetView\fP (\fBQWidget\fP *child)"
.br
.RI "\fISets the main view to be the specified widget (which must be a child of the popup). \fP"
.ti -1c
.RI "void \fBsetView\fP (const  \fBQString\fP &caption, const  \fBQString\fP &text=QString::null)"
.br
.RI "\fICreates a standard view then calls \fBsetView\fP(QWidget*) . \fP"
.ti -1c
.RI "virtual void \fBsetView\fP (const  \fBQString\fP &caption, const  \fBQString\fP &text, const  \fBQPixmap\fP &icon)"
.br
.RI "\fICreates a standard view then calls \fBsetView\fP(QWidget*) . \fP"
.ti -1c
.RI "\fBQVBox\fP * \fBstandardView\fP (const  \fBQString\fP &caption, const  \fBQString\fP &text, const  \fBQPixmap\fP &icon, \fBQWidget\fP *parent=0L)"
.br
.RI "\fIReturns a widget that is used as standard view if one of the \fBsetView()\fP methods taking the \fBQString\fP arguments is used. \fP"
.ti -1c
.RI "\fBQWidget\fP * \fBview\fP () const "
.br
.RI "\fIReturns the main view. \fP"
.ti -1c
.RI "int \fBtimeout\fP () const "
.br
.RI "\fIReturns the delay before the popup is removed automatically. \fP"
.ti -1c
.RI "virtual void \fBsetAutoDelete\fP (bool autoDelete)"
.br
.RI "\fIEnables / disables auto-deletion of this widget when the \fBtimeout\fP occurs. \fP"
.ti -1c
.RI "bool \fBautoDelete\fP () const "
.br
.in -1c
.SS "Static Public Member Functions"

.in +1c
.ti -1c
.RI "\fBKPassivePopup\fP * \fBmessage\fP (const  \fBQString\fP &text, \fBQWidget\fP *parent, const  char *name=0)"
.br
.RI "\fIConvenience method that displays popup with the specified message beside the icon of the specified widget. \fP"
.ti -1c
.RI "\fBKPassivePopup\fP * \fBmessage\fP (const  \fBQString\fP &caption, const  \fBQString\fP &text, \fBQWidget\fP *parent, const  char *name=0)"
.br
.RI "\fIConvenience method that displays popup with the specified caption and message beside the icon of the specified widget. \fP"
.ti -1c
.RI "\fBKPassivePopup\fP * \fBmessage\fP (const  \fBQString\fP &caption, const  \fBQString\fP &text, const  \fBQPixmap\fP &icon, \fBQWidget\fP *parent, const  char *name=0, int timeout=-1)"
.br
.RI "\fIConvenience method that displays popup with the specified icon, caption and message beside the icon of the specified widget. \fP"
.ti -1c
.RI "\fBKPassivePopup\fP * \fBmessage\fP (const  \fBQString\fP &caption, const  \fBQString\fP &text, const  \fBQPixmap\fP &icon, WId parent, const  char *name=0, int timeout=-1)"
.br
.RI "\fIConvenience method that displays popup with the specified icon, caption and message beside the icon of the specified window. \fP"
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "virtual void \fBpositionSelf\fP ()"
.br
.RI "\fIThis method positions the popup. \fP"
.ti -1c
.RI "virtual void \fBhideEvent\fP (\fBQHideEvent\fP *)"
.br
.RI "\fIReimplemented to destroy the object when \fBautoDelete\fP() is enabled. \fP"
.ti -1c
.RI "void \fBmoveNear\fP (\fBQRect\fP target)"
.br
.RI "\fIMoves the popup to be adjacent to the icon of the specified rectangle. \fP"
.ti -1c
.RI "virtual void \fBmouseReleaseEvent\fP (\fBQMouseEvent\fP *e)"
.br
.RI "\fIReimplemented to detect mouse clicks. \fP"
.ti -1c
.RI "\fBQRect\fP \fBdefaultArea\fP () const "
.br
.RI "\fIIf no relative window (e.g. \fP"
.in -1c
.SH "Detailed Description"
.PP 
A dialog-like popup that displays messages without interupting the user. 

The simplest uses of KPassivePopup are by using the various \fBmessage\fP() static methods. The position the popup appears at depends on the type of the parent window:
.PP
.IP "\(bu" 2
Normal Windows: The popup is placed adjacent to the icon of the window. 
.IP "\(bu" 2
System Tray Windows: The popup is placed adjact to the system tray window itself. 
.IP "\(bu" 2
Skip Taskbar Windows: The popup is placed adjact to the window itself if it is visible, and at the edge of the desktop otherwise.
.PP
The most basic use of KPassivePopup displays a popup containing a piece of text: 
.PP
.nf

    \fBKPassivePopup::message\fP( ''This is the message'', this );
 
.PP
 We can create popups with titles and icons too, as this example shows: 
.PP
.nf

    \fBQPixmap\fP px;
    px.load( ''hi32-app-logtracker.png'' );
    \fBKPassivePopup::message\fP( ''Some title'', ''This is the main text'', px, this );
 
.PP
 For more control over the popup, you can use the \fBsetView\fP(\fBQWidget\fP *) method to create a custom popup. 
.PP
.nf

    KPassivePopup *pop = new KPassivePopup( parent );
.PP
.PP
.PP
.nf
    \fBQVBox\fP *vb = new QVBox( pop );
    (void) new \fBQLabel\fP( ''<b>Isn't this great?</b>'', vb );
.PP
.PP
.PP
.nf
    \fBQHBox\fP *box = new QHBox( vb );
    (void) new \fBQPushButton\fP( ''Yes'', box );
    (void) new \fBQPushButton\fP( ''No'', box );
.PP
.PP
.PP
.nf
    pop->setView( vb );
    pop->\fBshow()\fP;
 
.PP
.PP
\fBVersion:\fP
.RS 4
\fBId\fP.RS 4
\fBkpassivepopup.h\fP,v 1.11 2002/11/15 12:29:38 amantia Exp 
.RE
.PP
.RE
.PP
\fBSince:\fP
.RS 4
3.1 
.RE
.PP
\fBAuthor:\fP
.RS 4
Richard Moore, rich@kde.org 
.RE
.PP

.PP
Definition at line 59 of file kpassivepopup.h.
.SH "Constructor & Destructor Documentation"
.PP 
.SS "KPassivePopup::KPassivePopup (\fBQWidget\fP * parent = 0, const char * name = 0, WFlags f = 0)"
.PP
Creates a popup for the specified widget. Definition at line 28 of file kpassivepopup.cpp.
.PP
References KStdAccel::name().
.PP
Referenced by message().
.SS "KPassivePopup::KPassivePopup (WId parent, const char * name = 0, WFlags f = 0)"
.PP
Creates a popup for the specified window. Definition at line 36 of file kpassivepopup.cpp.
.PP
References KStdAccel::name().
.SS "KPassivePopup::~\fBKPassivePopup\fP ()\fC [virtual]\fP"
.PP
Cleans up. Definition at line 52 of file kpassivepopup.cpp.
.SH "Member Function Documentation"
.PP 
.SS "void KPassivePopup::setView (\fBQWidget\fP * child)"
.PP
Sets the main view to be the specified widget (which must be a child of the popup). Definition at line 56 of file kpassivepopup.cpp.
.PP
References QBoxLayout::addWidget(), KDialog::marginHint(), and KDialog::spacingHint().
.PP
Referenced by message(), and setView().
.SS "void KPassivePopup::setView (const \fBQString\fP & caption, const \fBQString\fP & text = QString::null)"
.PP
Creates a standard view then calls \fBsetView\fP(QWidget*) . Definition at line 110 of file kpassivepopup.cpp.
.PP
References setView().
.SS "void KPassivePopup::setView (const \fBQString\fP & caption, const \fBQString\fP & text, const \fBQPixmap\fP & icon)\fC [virtual]\fP"
.PP
Creates a standard view then calls \fBsetView\fP(QWidget*) . Definition at line 67 of file kpassivepopup.cpp.
.PP
References setView(), and standardView().
.SS "\fBQVBox\fP * KPassivePopup::standardView (const \fBQString\fP & caption, const \fBQString\fP & text, const \fBQPixmap\fP & icon, \fBQWidget\fP * parent = 0L)"
.PP
Returns a widget that is used as standard view if one of the \fBsetView()\fP methods taking the \fBQString\fP arguments is used. You can use the returned widget to customize the passivepopup while keeping the look similar to the 'standard' passivepopups.
.PP
After customizing the widget, pass it to \fBsetView\fP( QWidget* )
.PP
\fBParameters:\fP
.RS 4
\fIparent\fP The parent widget used for the returned \fBQVBox\fP. If left 0L, then 'this', i.e. the passive popup object will be used.
.RE
.PP
\fBReturns:\fP
.RS 4
a \fBQVBox\fP containing the given arguments, looking like the standard passivepopups. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsetView( QWidget * )\fP 
.PP
\fBsetView( const QString&, const QString& )\fP 
.PP
\fBsetView( const QString&, const QString&, const QPixmap& )\fP 
.RE
.PP
Definition at line 74 of file kpassivepopup.cpp.
.PP
References QString::isEmpty(), QPixmap::isNull(), QLabel::setAlignment(), QFont::setBold(), QLabel::setFont(), QLabel::setPixmap(), QHBox::setSpacing(), QHBox::setStretchFactor(), and KDialog::spacingHint().
.PP
Referenced by setView().
.SS "\fBQWidget\fP* KPassivePopup::view () const\fC [inline]\fP"
.PP
Returns the main view. Definition at line 117 of file kpassivepopup.h.
.SS "int KPassivePopup::timeout () const\fC [inline]\fP"
.PP
Returns the delay before the popup is removed automatically. Definition at line 122 of file kpassivepopup.h.
.SS "void KPassivePopup::setAutoDelete (bool autoDelete)\fC [virtual]\fP"
.PP
Enables / disables auto-deletion of this widget when the \fBtimeout\fP occurs. The default is false. If you use the class-methods \fBmessage()\fP, auto-delection is turned on by default. Definition at line 122 of file kpassivepopup.cpp.
.PP
Referenced by message().
.SS "bool KPassivePopup::autoDelete () const\fC [inline]\fP"
.PP
\fBReturns:\fP
.RS 4
true if the widget auto-deletes itself when the \fBtimeout\fP occurs. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsetAutoDelete\fP 
.RE
.PP
Definition at line 136 of file kpassivepopup.h.
.SS "\fBKPassivePopup\fP * KPassivePopup::message (const \fBQString\fP & text, \fBQWidget\fP * parent, const char * name = 0)\fC [static]\fP"
.PP
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. 
.PP
\fBSee also:\fP
.RS 4
\fBsetAutoDelete\fP 
.RE
.PP
Definition at line 260 of file kpassivepopup.cpp.
.PP
References KStdAccel::name().
.PP
Referenced by message().
.SS "\fBKPassivePopup\fP * KPassivePopup::message (const \fBQString\fP & caption, const \fBQString\fP & text, \fBQWidget\fP * parent, const char * name = 0)\fC [static]\fP"
.PP
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. 
.PP
\fBSee also:\fP
.RS 4
\fBsetAutoDelete\fP 
.RE
.PP
Definition at line 265 of file kpassivepopup.cpp.
.PP
References message(), and KStdAccel::name().
.SS "\fBKPassivePopup\fP * KPassivePopup::message (const \fBQString\fP & caption, const \fBQString\fP & text, const \fBQPixmap\fP & icon, \fBQWidget\fP * parent, const char * name = 0, int timeout = -1)\fC [static]\fP"
.PP
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. 
.PP
\fBSee also:\fP
.RS 4
\fBsetAutoDelete\fP 
.RE
.PP
Definition at line 247 of file kpassivepopup.cpp.
.PP
References hideDelay, KPassivePopup(), KStdAccel::name(), setAutoDelete(), setView(), and show().
.SS "\fBKPassivePopup\fP * KPassivePopup::message (const \fBQString\fP & caption, const \fBQString\fP & text, const \fBQPixmap\fP & icon, WId parent, const char * name = 0, int timeout = -1)\fC [static]\fP"
.PP
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. 
.PP
\fBSee also:\fP
.RS 4
\fBsetAutoDelete\fP 
.RE
.PP
Definition at line 271 of file kpassivepopup.cpp.
.PP
References hideDelay, KPassivePopup(), KStdAccel::name(), setAutoDelete(), setView(), and show().
.SS "void KPassivePopup::setTimeout (int delay)\fC [slot]\fP"
.PP
Sets the delay for the popup is removed automatically. Setting the delay to 0 disables the \fBtimeout\fP, if you're doing this, you may want to connect the \fBclicked\fP() signal to the hide() slot. Setting the delay to -1 makes it use the default value. Definition at line 115 of file kpassivepopup.cpp.
.PP
References QTimer::changeInterval(), and QTimer::isActive().
.SS "void KPassivePopup::show ()\fC [virtual, slot]\fP"
.PP
Reimplemented to reposition the popup. Definition at line 137 of file kpassivepopup.cpp.
.PP
References positionSelf(), and QTimer::start().
.PP
Referenced by message().
.SS "void KPassivePopup::clicked ()\fC [signal]\fP"
.PP
Emitted when the popup is clicked. Referenced by mouseReleaseEvent().
.SS "void KPassivePopup::clicked (\fBQPoint\fP pos)\fC [signal]\fP"
.PP
Emitted when the popup is clicked. 
.SS "void KPassivePopup::positionSelf ()\fC [protected, virtual]\fP"
.PP
This method positions the popup. Definition at line 175 of file kpassivepopup.cpp.
.PP
References defaultArea(), NETSize::height, QRect::isNull(), moveNear(), NETRect::pos, QRect::setRect(), NETRect::size, NETSize::width, NETPoint::x, and NETPoint::y.
.PP
Referenced by show().
.SS "void KPassivePopup::hideEvent (\fBQHideEvent\fP *)\fC [protected, virtual]\fP"
.PP
Reimplemented to destroy the object when \fBautoDelete\fP() is enabled. Definition at line 154 of file kpassivepopup.cpp.
.PP
References QTimer::stop().
.SS "void KPassivePopup::moveNear (\fBQRect\fP target)\fC [protected]\fP"
.PP
Moves the popup to be adjacent to the icon of the specified rectangle. Definition at line 213 of file kpassivepopup.cpp.
.PP
References QRect::height(), KIO::move(), QRect::topLeft(), QRect::width(), QPoint::x(), and QPoint::y().
.PP
Referenced by positionSelf().
.SS "void KPassivePopup::mouseReleaseEvent (\fBQMouseEvent\fP * e)\fC [protected, virtual]\fP"
.PP
Reimplemented to detect mouse clicks. Definition at line 127 of file kpassivepopup.cpp.
.PP
References clicked(), and QMouseEvent::pos().
.SS "\fBQRect\fP KPassivePopup::defaultArea () const\fC [protected]\fP"
.PP
If no relative window (e.g. taskbar button, system tray window) is available, use this rectangle (pass it to \fBmoveNear\fP()). Basically \fBKWinModule::workArea()\fP with width and height set to 0 so that moveNear uses the upper-left position. 
.PP
\fBReturns:\fP
.RS 4
The \fBQRect\fP to be passed to \fBmoveNear\fP() ifno other is available. 
.RE
.PP
Definition at line 161 of file kpassivepopup.cpp.
.PP
References NETRect::pos, QRect::setRect(), NETPoint::x, and NETPoint::y.
.PP
Referenced by positionSelf().

.SH "Author"
.PP 
Generated automatically by Doxygen for kdeui Library from the source code.
