.TH "KPanelExtension" kde3 "11 Jun 2005" "Version Version 3.4.1" "kdeui Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KPanelExtension \- KDE Panel Extension class  

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

.in +1c
.ti -1c
.RI "enum \fBType\fP { \fBNormal\fP =  0, \fBStretch\fP }"
.br
.ti -1c
.RI "enum \fBAction\fP { \fBAbout\fP =  1, \fBHelp\fP =  2, \fBPreferences\fP =  4, \fBReportBug\fP =  8 }"
.br
.ti -1c
.RI "enum \fBPosition\fP { \fBLeft\fP =  0, \fBRight\fP, \fBTop\fP, \fBBottom\fP, \fBFloating\fP }"
.br
.ti -1c
.RI "enum \fBAlignment\fP { \fBLeftTop\fP =  0, \fBCenter\fP, \fBRightBottom\fP }"
.br
.ti -1c
.RI "enum \fBSize\fP { \fBSizeTiny\fP =  0, \fBSizeSmall\fP, \fBSizeNormal\fP, \fBSizeLarge\fP, \fBSizeCustom\fP }"
.br
.in -1c
.SS "Signals"

.in +1c
.ti -1c
.RI "void \fBupdateLayout\fP ()"
.br
.ti -1c
.RI "void \fBmaintainFocus\fP (bool)"
.br
.in -1c
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fBKPanelExtension\fP (const \fBQString\fP &configFile, \fBType\fP t=Normal, int actions=0, \fBQWidget\fP *parent=0, const char *name=0)"
.br
.ti -1c
.RI "\fB~KPanelExtension\fP ()"
.br
.ti -1c
.RI "virtual \fBQSize\fP \fBsizeHint\fP (Position, \fBQSize\fP maxsize) const "
.br
.ti -1c
.RI "\fBKConfig\fP * \fBconfig\fP () const "
.br
.ti -1c
.RI "\fBType\fP \fBtype\fP () const "
.br
.ti -1c
.RI "int \fBactions\fP () const "
.br
.ti -1c
.RI "virtual void \fBaction\fP (Action a)"
.br
.ti -1c
.RI "virtual Position \fBpreferedPosition\fP () const "
.br
.ti -1c
.RI "void \fBsetPosition\fP (Position p)"
.br
.ti -1c
.RI "void \fBsetAlignment\fP (Alignment a)"
.br
.ti -1c
.RI "void \fBsetSize\fP (\fBSize\fP size, int customSize)"
.br
.ti -1c
.RI "\fBSize\fP \fBsizeSetting\fP () const "
.br
.ti -1c
.RI "int \fBcustomSize\fP () const "
.br
.ti -1c
.RI "\fBQPopupMenu\fP * \fBcustomMenu\fP () const "
.br
.ti -1c
.RI "bool \fBreserveStrut\fP () const "
.br
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "virtual void \fBabout\fP ()"
.br
.ti -1c
.RI "virtual void \fBhelp\fP ()"
.br
.ti -1c
.RI "virtual void \fBpreferences\fP ()"
.br
.ti -1c
.RI "virtual void \fBreportBug\fP ()"
.br
.ti -1c
.RI "Position \fBposition\fP () const "
.br
.ti -1c
.RI "Alignment \fBalignment\fP () const "
.br
.ti -1c
.RI "Orientation \fBorientation\fP ()"
.br
.ti -1c
.RI "int \fBsizeInPixels\fP () const "
.br
.ti -1c
.RI "virtual void \fBpositionChange\fP (Position)"
.br
.ti -1c
.RI "virtual void \fBalignmentChange\fP (Alignment)"
.br
.ti -1c
.RI "void \fBsetCustomMenu\fP (\fBQPopupMenu\fP *)"
.br
.ti -1c
.RI "void \fBsetReserveStrut\fP (bool shouldUseStrut)"
.br
.ti -1c
.RI "virtual void \fBvirtual_hook\fP (int id, void *data)"
.br
.in -1c
.SH "Detailed Description"
.PP 
KDE Panel Extension class 

Panel extensions 
.PD 0

.IP "\(bu" 2
Are small applications living in the Window Manager dock managed by the panel. 
.IP "\(bu" 2
Are implemented as DSOs (Dynamic Shared Objects).
.PP
Note: For security and stability reasons the panel won't load untrusted third party extensions directly into its namespace but via an external wrapper process.
.PP
The panel locates available extensions by searching for extension desktop files in (ALL_KDEDIRS)/share/apps/kicker/extensions. Every panel extension should install a desktop file there to be recognized by the panel.
.PP
Besides standard keys like 'Name', 'Comment' and 'Icon' there are two panel extension specific keys:
.PP
\fBX-KDE-Library\fP 
.br
.PP
Used by the panel to locate the extension DSO (Dynamic Shared Object) Example: X-KDE-Library=libexampleextension
.PP
\fBX-KDE-UniqueExtension\fP 
.br
.PP
Similar to \fBKApplication\fP and \fBKUniqueApplication\fP there are two types of panel extensions. Use unique extensions when it makes no sence to run more than one instance of an extension in the panel. A good example for unique extensions is the taskbar extension. Use normal extensions when you need instance specific configuration. An example is a subpanel extension where you might want to run more than one instances. X-KDE-UniqueExtension is a boolean key which defaults to 'false'. Example: X-KDE-UniqueExtension=true
.PP
Back to panel extension DSOs, the following conventions are used for \fBKDE\fP: Name: lib<extensionname>extension.la LDFLAGS: -module -no-undefined
.PP
To implement a panel extension it is not enough to write a class inheriting from KPanelExtension but you also have to provide a factory function in your DSO. A sample factory function could look like this:
.PP
.PP
.nf
 extern 'C'
 {
     KPanelExtension* init(QWidget *parent, const QString& configFile)
     {
         KGlobal::locale()->insertCatalogue('exampleextension');
         return new ExampleExtension(configFile, KPanelExtension::Normal,
                       KPanelExtension::About | KPanelExtension::Help | KPanelExtension::Preferences,
                       parent, 'exampleextension');
     }
 }
.fi
.PP
.PP
Note: Don't change the factory function signature or the panel will fail to load your extension.
.PP
\fBAuthor:\fP
.RS 4
Matthias Elter <elter@kde.org> 
.RE
.PP

.PP
Definition at line 98 of file kpanelextension.h.
.SH "Member Enumeration Documentation"
.PP 
.SS "\fBenum\fP \fBKPanelExtension::Type\fP"
.PP
The type of the extension (TODO). 
.PP
Definition at line 105 of file kpanelextension.h.
.SS "\fBenum\fP \fBKPanelExtension::Size\fP"
.PP
\fBSince:\fP
.RS 4
3.1 
.RE
.PP

.PP
Definition at line 111 of file kpanelextension.h.
.SH "Constructor & Destructor Documentation"
.PP 
.SS "KPanelExtension::KPanelExtension (const \fBQString\fP & configFile, \fBType\fP t = \fCNormal\fP, int actions = \fC0\fP, \fBQWidget\fP * parent = \fC0\fP, const char * name = \fC0\fP)"
.PP
Constructs a KPanelExtension just like any other widget. 
.PP
\fBParameters:\fP
.RS 4
\fIconfigFile\fP The configFile handed over in the factory function. 
.br
\fIt\fP The extension \fBtype()\fP. 
.br
\fIactions\fP Standard RMB menu actions supported by the extension (see \fBaction()\fP ). 
.br
\fIparent\fP The pointer to the parent widget handed over in the factory function. 
.br
\fIname\fP A \fBQt\fP object name for your extension. 
.RE
.PP

.PP
Definition at line 47 of file kpanelextension.cpp.
.PP
References QFrame::setFrameStyle().
.SS "KPanelExtension::~\fBKPanelExtension\fP ()"
.PP
Destructor. 
.PP
Definition at line 61 of file kpanelextension.cpp.
.SH "Member Function Documentation"
.PP 
.SS "virtual \fBQSize\fP KPanelExtension::sizeHint (Position, \fBQSize\fP maxsize) const\fC [inline, virtual]\fP"
.PP
Returns the preferred size for a given Position. 
.PP
Every extension should reimplement this function.
.PP
Depending on the panel position the extensions can choose a preferred size for that location in the Window Manager Dock. Please note that the size can not be larger than the maxsize given by the handler. 
.PP
Definition at line 139 of file kpanelextension.h.
.SS "\fBKConfig\fP* KPanelExtension::config () const\fC [inline]\fP"
.PP
Always use this \fBKConfig\fP object to save/load your extensions configuration. 
.PP
For unique extensions this config object will write to a config file called <extensionname>rc in the users local \fBKDE\fP directory.
.PP
For normal extensions this config object will write to a instance specific config file called <extensionname><instanceid>rc in the users local \fBKDE\fP directory. 
.PP
Definition at line 150 of file kpanelextension.h.
.SS "\fBType\fP KPanelExtension::type () const\fC [inline]\fP"
.PP
\fBReturns:\fP
.RS 4
Type indicating the extensions type. Type 
.RE
.PP

.PP
Definition at line 156 of file kpanelextension.h.
.SS "int KPanelExtension::actions () const\fC [inline]\fP"
.PP
\fBReturns:\fP
.RS 4
int indicating the supported RMB menu actions. #Action 
.RE
.PP

.PP
Definition at line 162 of file kpanelextension.h.
.SS "void KPanelExtension::action (Action a)\fC [virtual]\fP"
.PP
Generic action dispatcher. 
.PP
Called when the user selects an item from the extensions RMB menu.
.PP
Reimplement this function to handle actions.
.PP
For About, Help, Preferences and ReportBug use the convenience handlers ref \fBabout()\fP, \fBhelp()\fP, \fBpreferences()\fP, \fBreportBug()\fP 
.PP
Definition at line 89 of file kpanelextension.cpp.
.PP
References about(), help(), preferences(), and reportBug().
.SS "virtual Position KPanelExtension::preferedPosition () const\fC [inline, virtual]\fP"
.PP
Reimplement this function to set a preferred dock position for your extension. 
.PP
The extension manager will try to place new instances of this extension according to this setting. 
.PP
\fBReturns:\fP
.RS 4
Position 
.RE
.PP

.PP
Definition at line 183 of file kpanelextension.h.
.SS "\fBKPanelExtension::Size\fP KPanelExtension::sizeSetting () const"
.PP
\fBReturns:\fP
.RS 4
the extension's size 
.RE
.PP
\fBSince:\fP
.RS 4
3.1 
.RE
.PP

.PP
Definition at line 109 of file kpanelextension.cpp.
.SS "int KPanelExtension::customSize () const"
.PP
\fBReturns:\fP
.RS 4
the custom sizel setting in pixels 
.RE
.PP
\fBSince:\fP
.RS 4
3.1 
.RE
.PP

.PP
Definition at line 114 of file kpanelextension.cpp.
.SS "\fBQPopupMenu\fP * KPanelExtension::customMenu () const"
.PP
\fBReturns:\fP
.RS 4
the extension's custom menu, usually the same as the context menu, or 0 if none 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsetCustomMenu(QPopupMenu*)\fP 
.RE
.PP
\fBSince:\fP
.RS 4
3.4 
.RE
.PP

.PP
Definition at line 141 of file kpanelextension.cpp.
.SS "bool KPanelExtension::reserveStrut () const"
.PP
\fBReturns:\fP
.RS 4
whether or not to set a desktop geometry claiming strut for this panel defaults to true 
.RE
.PP
\fBSee also:\fP
.RS 4
setReservetrut(bool) 
.RE
.PP
\fBSince:\fP
.RS 4
3.4 
.RE
.PP

.PP
Definition at line 151 of file kpanelextension.cpp.
.PP
References position().
.SS "void KPanelExtension::updateLayout ()\fC [signal]\fP"
.PP
Emit this signal to make the panel relayout all extensions in the dock, when you want to change the extensions size. 
.PP
The panel is going to relayout all extensions based on their preferred size. 
.SS "void KPanelExtension::maintainFocus (bool)\fC [signal]\fP"
.PP
Emit this signal to make the panel maintain focus, e.g. 
.PP
don't autohide 
.PP
\fBSince:\fP
.RS 4
3.4 
.RE
.PP

.SS "virtual void KPanelExtension::about ()\fC [inline, protected, virtual]\fP"
.PP
Is called when the user selects 'About' from the extensions RMB menu. 
.PP
Reimplement this function to launch a about dialog.
.PP
Note that this is called only when your extension supports the About action. See #Action. 
.PP
Definition at line 249 of file kpanelextension.h.
.PP
Referenced by action().
.SS "virtual void KPanelExtension::help ()\fC [inline, protected, virtual]\fP"
.PP
Is called when the user selects 'Help' from the extensions RMB menu. 
.PP
Reimplement this function to launch a manual or help page.
.PP
Note that this is called only when your extension supports the Help action. See #Action. 
.PP
Definition at line 258 of file kpanelextension.h.
.PP
Referenced by action().
.SS "virtual void KPanelExtension::preferences ()\fC [inline, protected, virtual]\fP"
.PP
Is called when the user selects 'Preferences' from the extensions RMB menu. 
.PP
Reimplement this function to launch a preferences dialog or kcontrol module.
.PP
Note that this is called only when your extension supports the preferences action. See #Action. 
.PP
Definition at line 267 of file kpanelextension.h.
.PP
Referenced by action().
.SS "virtual void KPanelExtension::reportBug ()\fC [inline, protected, virtual]\fP"
.PP
Is called when the user selects 'Report bug' from the applet's RMB menu. 
.PP
Reimplement this function to launch a bug reporting dialog.
.PP
Note that this is called only when your applet supports the ReportBug action. See #Action. 
.PP
Definition at line 277 of file kpanelextension.h.
.PP
Referenced by action().
.SS "Position KPanelExtension::position () const\fC [inline, protected]\fP"
.PP
\fBReturns:\fP
.RS 4
the extension's position. (left, right, top, bottom) 
.RE
.PP

.PP
Definition at line 282 of file kpanelextension.h.
.PP
Referenced by reserveStrut().
.SS "Alignment KPanelExtension::alignment () const\fC [inline, protected]\fP"
.PP
\fBReturns:\fP
.RS 4
the extension's alignment. (left/top, center, or right/bottom) 
.RE
.PP

.PP
Definition at line 287 of file kpanelextension.h.
.SS "Qt::Orientation KPanelExtension::orientation ()\fC [protected]\fP"
.PP
\fBReturns:\fP
.RS 4
the extensions orientation. (horizontal or vertical) 
.RE
.PP

.PP
Definition at line 101 of file kpanelextension.cpp.
.SS "int KPanelExtension::sizeInPixels () const\fC [protected]\fP"
.PP
\fBReturns:\fP
.RS 4
the appropriate size in pixels for the panel 
.RE
.PP
\fBSince:\fP
.RS 4
3.1 
.RE
.PP

.PP
Definition at line 119 of file kpanelextension.cpp.
.SS "virtual void KPanelExtension::positionChange (Position)\fC [inline, protected, virtual]\fP"
.PP
This extension has changed its position. 
.PP
Reimplement this change handler in order to adjust the look of your applet. 
.PP
Definition at line 305 of file kpanelextension.h.
.SS "virtual void KPanelExtension::alignmentChange (Alignment)\fC [inline, protected, virtual]\fP"
.PP
This extension has changed its alignment. 
.PP
Reimplement this change handler in order to adjust the look of your applet. 
.PP
Definition at line 312 of file kpanelextension.h.
.SS "void KPanelExtension::setCustomMenu (\fBQPopupMenu\fP *)\fC [protected]\fP"
.PP
Use this method to set the custom menu for this extensions so that it can be shown at the appropriate places/times that the extension many not itself be aware of. 
.PP
The extension itself is still responsible for deleting and managing the the menu.
.PP
If the menu is deleted during the life of the extension, be sure to call this method again with the new menu (or 0) to avoid crashes 
.PP
\fBSince:\fP
.RS 4
3.4 
.RE
.PP

.PP
Definition at line 146 of file kpanelextension.cpp.
.SS "void KPanelExtension::setReserveStrut (bool shouldUseStrut)\fC [protected]\fP"
.PP
Use this method to set the return value for reserveStrut. 
.PP
\fBSee also:\fP
.RS 4
\fBreserveStrut\fP 
.RE
.PP
\fBSince:\fP
.RS 4
3.4 
.RE
.PP

.PP
Definition at line 156 of file kpanelextension.cpp.

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