Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

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