summaryrefslogtreecommitdiffstats
path: root/kdeui/kpanelextension.h
diff options
context:
space:
mode:
Diffstat (limited to 'kdeui/kpanelextension.h')
-rw-r--r--kdeui/kpanelextension.h346
1 files changed, 346 insertions, 0 deletions
diff --git a/kdeui/kpanelextension.h b/kdeui/kpanelextension.h
new file mode 100644
index 000000000..2ff1a5133
--- /dev/null
+++ b/kdeui/kpanelextension.h
@@ -0,0 +1,346 @@
+/*****************************************************************
+
+Copyright (c) 2000 Matthias Elter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+******************************************************************/
+
+#ifndef __kpanelextension_h__
+#define __kpanelextension_h__
+
+class QPopupMenu;
+class KConfig;
+class KPanelExtensionPrivate;
+
+#include <qframe.h>
+
+#include <kdelibs_export.h>
+
+/**
+ * @short %KDE Panel Extension class
+ *
+ * Panel extensions
+ * @li Are small applications living in the Window Manager dock managed by the panel.
+ * @li Are implemented as DSOs (Dynamic Shared Objects).
+ *
+ * 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 recognized by the panel.
+ *
+ * Besides standard keys like "Name", "Comment" and "Icon" there are
+ * two panel extension specific keys:
+ *
+ * \b X-KDE-Library \n
+ *
+ * Used by the panel to locate the extension DSO (Dynamic Shared Object)
+ * Example: X-KDE-Library=libexampleextension
+ *
+ * \b X-KDE-UniqueExtension \n
+ *
+ * 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:
+ *
+ * \code
+ *
+ * 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");
+ * }
+ * }
+ *
+ * \endcode
+ *
+ * Note: Don't change the factory function signature or the panel will
+ * fail to load your extension.
+ *
+ * @author Matthias Elter <elter@kde.org>
+ **/
+class KDEUI_EXPORT KPanelExtension : public QFrame
+{
+ Q_OBJECT
+
+public:
+
+ /// The type of the extension (TODO)
+ enum Type { Normal = 0, Stretch };
+ // KDE4: Merge these with KPanelApplet's enums
+ /// An action to be taken sometime.
+ enum Action { About = 1, Help = 2, Preferences = 4, ReportBug = 8 };
+ enum Position { Left = 0, Right, Top, Bottom, Floating };
+ enum Alignment { LeftTop = 0, Center, RightBottom };
+ /// @since 3.1
+ enum Size { SizeTiny = 0, SizeSmall, SizeNormal, SizeLarge, SizeCustom };
+
+ /**
+ * Constructs a KPanelExtension just like any other widget.
+ *
+ * @param configFile The configFile handed over in the factory function.
+ * @param t The extension type().
+ * @param actions Standard RMB menu actions supported by the extension (see action() ).
+ * @param parent The pointer to the parent widget handed over in the factory function.
+ * @param name A Qt object name for your extension.
+ **/
+ KPanelExtension(const QString& configFile, Type t = Normal,
+ int actions = 0, QWidget *parent = 0, const char *name = 0);
+
+ /**
+ * Destructor.
+ **/
+ ~KPanelExtension();
+
+ /**
+ * Returns the preferred size for a given Position.
+ *
+ * Every extension should reimplement this function.
+ *
+ * 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.
+ **/
+ virtual QSize sizeHint(Position /*p*/, QSize maxsize) const { return maxsize; }
+
+ /**
+ * Always use this KConfig object to save/load your extensions configuration.
+ *
+ * For unique extensions this config object will write to a config file called
+ * \<extensionname\>rc in the users local KDE directory.
+ *
+ * For normal extensions this config object will write to a instance specific config file
+ * called \<extensionname\>\<instanceid\>rc in the users local KDE directory.
+ **/
+ KConfig* config() const { return _config; }
+
+ /**
+ * @return Type indicating the extensions type.
+ * Type
+ **/
+ Type type() const { return _type; }
+
+ /**
+ * @return int indicating the supported RMB menu actions.
+ * Action
+ **/
+ int actions() const { return _actions; }
+
+ /**
+ * 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()
+ *
+ **/
+ virtual void action( Action a );
+
+
+ /**
+ * Reimplement this function to set a preferred dock position for your extension.
+ * The extension manager will try to place new instances of this extension according
+ * to this setting.
+ * @return Position
+ **/
+ virtual Position preferedPosition() const { return Bottom; }
+
+ /**
+ * @internal
+ **/
+ void setPosition( Position p );
+ /**
+ * @internal
+ **/
+ void setAlignment( Alignment a );
+ /**
+ * @internal
+ * @since 3.1
+ **/
+ void setSize( Size size, int customSize );
+
+ /**
+ * @return the extension's size
+ * @since 3.1
+ **/
+ Size sizeSetting() const;
+
+ /**
+ * @return the custom sizel setting in pixels
+ * @since 3.1
+ **/
+ int customSize() const;
+
+ /**
+ * @return the extension's custom menu, usually the same as the context menu, or 0 if none
+ * @see setCustomMenu(QPopupMenu*)
+ * @since 3.4
+ */
+ QPopupMenu* customMenu() const;
+
+ /**
+ * @return whether or not to set a desktop geometry claiming strut for this panel
+ * defaults to true
+ * @see setReservetrut(bool)
+ * @since 3.4
+ */
+ bool reserveStrut() const;
+
+signals:
+ /**
+ * 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 preferred size.
+ **/
+ void updateLayout();
+
+ /**
+ * Emit this signal to make the panel maintain focus, e.g. don't autohide
+ * @since 3.4
+ **/
+ void maintainFocus(bool);
+
+protected:
+
+ /**
+ * 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.
+ **/
+ virtual void about() {}
+
+ /**
+ * 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.
+ **/
+ virtual void help() {}
+
+ /**
+ * 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.
+ **/
+ virtual void preferences() {}
+
+ /**
+ * 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.
+ **/
+ virtual void reportBug() {}
+
+ /**
+ * @return the extension's position. (left, right, top, bottom)
+ **/
+ Position position() const { return _position; }
+
+ /**
+ * @return the extension's alignment. (left/top, center, or right/bottom)
+ **/
+ Alignment alignment() const { return _alignment; }
+
+ /**
+ * @return the extensions orientation. (horizontal or vertical)
+ **/
+ Orientation orientation();
+
+ /**
+ * @return the appropriate size in pixels for the panel
+ * @since 3.1
+ */
+ int sizeInPixels() const;
+
+ /**
+ * This extension has changed its position.
+ * Reimplement this change handler in order to adjust the look of your
+ * applet.
+ **/
+ virtual void positionChange( Position ) {}
+
+ /**
+ * This extension has changed its alignment.
+ * Reimplement this change handler in order to adjust the look of your
+ * applet.
+ **/
+ virtual void alignmentChange( Alignment ) {}
+
+ /**
+ * 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. The extension itself is still responsible for deleting and managing the
+ * the menu.
+ *
+ * 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
+ * @since 3.4
+ */
+ void setCustomMenu(QPopupMenu*);
+
+ /**
+ * Use this method to set the return value for reserveStrut
+ * @see reserveStrut
+ * @since 3.4
+ */
+ void setReserveStrut(bool shouldUseStrut);
+
+private:
+ Type _type;
+ Position _position;
+ Alignment _alignment;
+ KConfig* _config;
+ int _actions;
+protected:
+ virtual void virtual_hook( int id, void* data );
+private:
+ KPanelExtensionPrivate *d;
+};
+
+#endif