kdeui Library API Documentation

KPanelExtension Class Reference

Implements a panel extension. KDE Panel Extension class. More...

#include <kpanelextension.h>

Inheritance diagram for KPanelExtension:

Inheritance graph
[legend]
Collaboration diagram for KPanelExtension:

Collaboration graph
[legend]
List of all members.

Public Types

enum  Type { Normal = 0, Stretch }
 The type of the extention (TODO). More...

enum  Action { About = 1, Help = 2, Preferences = 4, ReportBug = 8 }
enum  Position { Left = 0, Right, Top, Bottom }
enum  Alignment { LeftTop = 0, Center, RightBottom }
enum  Size {
  SizeTiny = 0, SizeSmall, SizeNormal, SizeLarge,
  SizeCustom
}
 
Since:
3.1
More...


Signals

void updateLayout ()
 Emit this signal to make the panel relayout all extensions in the dock, when you want to change the extensions size.


Public Member Functions

 KPanelExtension (const QString &configFile, Type t=Normal, int actions=0, QWidget *parent=0, const char *name=0)
 Constructs a KPanelExtension just like any other widget.

 ~KPanelExtension ()
 Destructor.

virtual QSize sizeHint (Position, QSize maxsize) const
 Returns the prefered size for a given Position.

KConfigconfig () const
 Always use this KConfig object to save/load your extensions configuration.

Type type () const
int actions () const
virtual void action (Action a)
 Generic action dispatcher.

virtual Position preferedPosition () const
 Reimplement this function to set a prefered dock position for your extension.

void setPosition (Position p)
void setAlignment (Alignment a)
void setSize (Size size, int customSize)
Size sizeSetting () const
int customSize () const

Protected Member Functions

virtual void about ()
 Is called when the user selects "About" from the extensions RMB menu.

virtual void help ()
 Is called when the user selects "Help" from the extensions RMB menu.

virtual void preferences ()
 Is called when the user selects "Preferences" from the extensions RMB menu.

virtual void reportBug ()
 Is called when the user selects "Report bug" from the applet's RMB menu.

Position position () const
Alignment alignment () const
Orientation orientation ()
int sizeInPixels () const
virtual void positionChange (Position)
 This extension has changed its position.

virtual void alignmentChange (Alignment)
 This extension has changed its alignment.

virtual void virtual_hook (int id, void *data)

Detailed Description

Implements a panel extension. KDE Panel Extension class.

Panel extensions

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.

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 recognised by the panel.

Besides standard keys like "Name", "Comment" and "Icon" there are two panel extension specific keys:

X-KDE-Library

Used by the panel to locate the extension DSO (Dynamic Shared Object) Example: X-KDE-Library=libexampleextension

X-KDE-UniqueExtension

Similar to KApplication and KUniqueApplication 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

Back to panel extension DSOs, the following conventions are used for KDE: Name: lib<extensionname>extension.la LDFLAGS: -module -no-undefined

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:

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"); } }

Note: Don't change the factory function signature or the panel will fail to load your extension.

Author:
Matthias Elter <elter@kde.org>

Definition at line 96 of file kpanelextension.h.


Member Enumeration Documentation

enum KPanelExtension::Type
 

The type of the extention (TODO).

Definition at line 103 of file kpanelextension.h.

Referenced by type().

enum KPanelExtension::Size
 

Since:
3.1

Definition at line 108 of file kpanelextension.h.

Referenced by sizeSetting().


Constructor & Destructor Documentation

KPanelExtension::KPanelExtension const QString configFile,
Type  t = Normal,
int  actions = 0,
QWidget parent = 0,
const char *  name = 0
 

Constructs a KPanelExtension just like any other widget.

Parameters:
configFile The configFile handed over in the factory function.
Type The extension type().
actions Standard RMB menu actions supported by the extension (see action() ).
parent The pointer to the parent widget handed over in the factory function.
name A Qt object name for your extension.

Definition at line 41 of file kpanelextension.cpp.

References KStdAccel::name(), and QFrame::setFrameStyle().

KPanelExtension::~KPanelExtension  ) 
 

Destructor.

Definition at line 55 of file kpanelextension.cpp.


Member Function Documentation

virtual QSize KPanelExtension::sizeHint Position  ,
QSize  maxsize
const [inline, virtual]
 

Returns the prefered size for a given Position.

Every extension should reimplement this function.

Depending on the panel position the extensions can choose a prefered 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.

Definition at line 136 of file kpanelextension.h.

KConfig* KPanelExtension::config  )  const [inline]
 

Always use this KConfig object to save/load your extensions configuration.

For unique extensions this config object will write to a config file called rc in the users local KDE directory.

For normal extensions this config object will write to a instance specific config file called rc in the users local KDE directory.

Definition at line 147 of file kpanelextension.h.

Type KPanelExtension::type  )  const [inline]
 

Returns:
Type indicating the extensions type. Type

Definition at line 153 of file kpanelextension.h.

References Type.

int KPanelExtension::actions  )  const [inline]
 

Returns:
int indicating the supported RMB menu actions. #Action

Definition at line 159 of file kpanelextension.h.

void KPanelExtension::action Action  a  )  [virtual]
 

Generic action dispatcher.

Called when the user selects an item from the extensions RMB menu.

Reimplement this function to handle actions.

For About, Help, Preferences and ReportBug use the convenience handlers ref about(), help(), preferences(), reportBug()

Definition at line 83 of file kpanelextension.cpp.

References about(), help(), preferences(), and reportBug().

virtual Position KPanelExtension::preferedPosition  )  const [inline, virtual]
 

Reimplement this function to set a prefered dock position for your extension.

The extension manager will try to place new instances of this extension according to this setting.

Returns:
Position

Definition at line 180 of file kpanelextension.h.

KPanelExtension::Size KPanelExtension::sizeSetting  )  const
 

Returns:
the extension's size
Since:
3.1

Definition at line 103 of file kpanelextension.cpp.

References Size.

int KPanelExtension::customSize  )  const
 

Returns:
the custom sizel setting in pixels
Since:
3.1

Definition at line 108 of file kpanelextension.cpp.

void KPanelExtension::updateLayout  )  [signal]
 

Emit this signal to make the panel relayout all extensions in the dock, when you want to change the extensions size.

The panel is going to relayout all extensions based on their prefered size.

virtual void KPanelExtension::about  )  [inline, protected, virtual]
 

Is called when the user selects "About" from the extensions RMB menu.

Reimplement this function to launch a about dialog.

Note that this is called only when your extension supports the About action. See #Action.

Definition at line 226 of file kpanelextension.h.

Referenced by action().

virtual void KPanelExtension::help  )  [inline, protected, virtual]
 

Is called when the user selects "Help" from the extensions RMB menu.

Reimplement this function to launch a manual or help page.

Note that this is called only when your extension supports the Help action. See #Action.

Definition at line 235 of file kpanelextension.h.

Referenced by action().

virtual void KPanelExtension::preferences  )  [inline, protected, virtual]
 

Is called when the user selects "Preferences" from the extensions RMB menu.

Reimplement this function to launch a preferences dialog or kcontrol module.

Note that this is called only when your extension supports the preferences action. See #Action.

Definition at line 244 of file kpanelextension.h.

Referenced by action().

virtual void KPanelExtension::reportBug  )  [inline, protected, virtual]
 

Is called when the user selects "Report bug" from the applet's RMB menu.

Reimplement this function to launch a bug reporting dialog.

Note that this is called only when your applet supports the ReportBug action. See #Action.

Definition at line 254 of file kpanelextension.h.

Referenced by action().

Position KPanelExtension::position  )  const [inline, protected]
 

Returns:
the extension's position. (left, right, top, bottom)

Definition at line 259 of file kpanelextension.h.

Alignment KPanelExtension::alignment  )  const [inline, protected]
 

Returns:
the extension's alignment. (left/top, center, or right/bottom)

Definition at line 264 of file kpanelextension.h.

Qt::Orientation KPanelExtension::orientation  )  [protected]
 

Returns:
the extensions orientation. (horizontal or vertical)

Definition at line 95 of file kpanelextension.cpp.

int KPanelExtension::sizeInPixels  )  const [protected]
 

Returns:
the appropriate size in pixels for the panel
Since:
3.1

Definition at line 113 of file kpanelextension.cpp.

virtual void KPanelExtension::positionChange Position   )  [inline, protected, virtual]
 

This extension has changed its position.

Reimplement this change handler in order to adjust the look of your applet.

Definition at line 282 of file kpanelextension.h.

virtual void KPanelExtension::alignmentChange Alignment   )  [inline, protected, virtual]
 

This extension has changed its alignment.

Reimplement this change handler in order to adjust the look of your applet.

Definition at line 289 of file kpanelextension.h.


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.5.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Jan 28 13:03:36 2004 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001