|
|
Implement a panel extension.
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:
Used by the panel to locate the extension DSO (Dynamic Shared Object) Example: X-KDE-Library=libexampleextension
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
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.
| enum Type { Normal = 0, Stretch } | Type |
| enum Action { About = 1, Help = 2, Preferences = 4, ReportBug =8 } | Action |
| enum Position { Left = 0, Right, Top, Bottom } | Position |
| KPanelExtension (const QString& configFile, Type t = Normal,
int actions = 0, QWidget *parent = 0, const char *name = 0)
| KPanelExtension |
Construct 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. |
| ~KPanelExtension ()
| ~KPanelExtension |
Destructor.
| QSize sizeHint (Position , QSize maxsize)
| sizeHint |
[const virtual]
Retrieve a 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.
Reimplemented from QFrame.
| KConfig* config ()
| config |
[const]
Always use this KConfig object to save/load your extensions configuration.
For unique extensions this config object will write to a config file called
For normal extensions this config object will write to a instance specific config file
called
| Type type ()
| type |
[const]
Returns: Type indicating the extensions type. Type
| int actions ()
| actions |
[const]
Returns: int indicating the supported RMB menu actions. Action
| void action ( Action a )
| action |
[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 and Preferences, use the convenience handlers ref about(), help(), preferences()
| Position preferedPosition ()
| preferedPosition |
[const 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
| void updateLayout ()
| 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.
| void slotSetPosition (Position p)
| slotSetPosition |
[slot]
Don't reimplement, this is used internally
| void about ()
| about |
[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 and KPanelExtension().
| void help ()
| help |
[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 and KPanelExtension().
| void preferences ()
| preferences |
[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 and KPanelExtension().
| Position position ()
| position |
[protected const]
Returns: the extension's position. (left, right, top, bottom)
| Orientation orientation ()
| orientation |
[protected]
Returns: the extensions orientation. (horizontal or vertical)
| void positionChange ( Position )
| positionChange |
[protected virtual]
The position changed to position. Reimplement this
change handler in order to adjust the look of your extension.