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, 395 insertions, 0 deletions

diff --git a/kdeui/kpanelapplet.h b/kdeui/kpanelapplet.h
new file mode 100644
index 000000000..fa0d3adbb
--- /dev/null
+++ b/kdeui/kpanelapplet.h
@@ -0,0 +1,395 @@
+/*****************************************************************
+
+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 __kpanelapplet_h__
+#define __kpanelapplet_h__
+
+class KConfig;
+class QPopupMenu;
+
+#include <qframe.h>
+#include <kconfig.h>
+
+/**
+ * @short %KDE Panel Applet class
+ *
+ * Panel applets
+ *   @li Are small applications living in the %KDE panel.
+ *   @li Are implemented as DSOs (Dynamic Shared Objects).
+ *
+ * Note: For security and stability reasons the panel won't load
+ * untrusted third party applets directly into its namespace but via an
+ * external wrapper process.
+ *
+ * The panel locates available applets by searching for applet desktop
+ * files in (ALL_DIRS)/share/apps/kicker/applets. Every panel applet should
+ * install a desktop file there to be recognized by the panel.
+ *
+ * Besides standard keys like "Name", "Comment" and "Icon" there are
+ * two panel applet specific keys:
+ *
+ * \b X-KDE-Library \n
+ *
+ * Used by the panel to locate the applet DSO (Dynamic Shared Object)
+ * Example: X-KDE-Library=libexampleapplet
+ *
+ * \b X-KDE-UniqueApplet \n
+ *
+ * Similar to KApplication and KUniqueApplication there are
+ * two types of panel applets. Use unique applets when it makes no
+ * sence to run more than one instance of a applet in the panel. A
+ * good example for unique applets is the taskbar applet.  Use normal
+ * applets when you need instance specific configuration. An example
+ * is the koolclock applet where you might want to run two instances
+ * in your panel, one configured as analog clock, the other one as
+ * digital clock. X-KDE-UniqueApplet is a boolean key which defaults
+ * to "false".  Example: X-KDE-UniqueApplet=true
+ *
+ * Back to panel applet DSOs, the following conventions are used for %KDE:
+ * Name:    lib<appletname>applet.la
+ * LDFLAGS: -module -no-undefined
+ *
+ * To implement a panel applet it is not enough to write a class
+ * inheriting from KPanelApplet but you also have to provide a
+ * factory function in your DSO.  A sample factory function could look
+ * like this:
+ *
+ * \code
+ *
+ * extern "C"
+ * {
+ *     KPanelApplet* init(QWidget *parent, const QString& configFile)
+ *     {
+ *         KGlobal::locale()->insertCatalogue("exampleapplet");
+ *         return new ExampleApplet(configFile, KPanelApplet::Normal,
+ *                       KPanelApplet::About | KPanelApplet::Help | KPanelApplet::Preferences,
+ *                       parent, "exampleapplet");
+ *     }
+ * }
+ *
+ * \endcode
+ *
+ * Note: Don't change the factory function signature or the panel will
+ * fail to load your applet.
+ *
+ * @author Matthias Elter <elter@kde.org>
+ **/
+class KDEUI_EXPORT KPanelApplet : public QFrame
+{
+    Q_OBJECT
+
+public:
+
+    /**
+     * This enum describes the type of the applet.
+     */
+    enum Type { Normal = 0, Stretch };
+    /**
+     * This enum holds flags which can be ORed together to describe
+     * which items the context menu over the applet handle contains.
+     */
+    // KDE4: Merge these with KPanelExtension's enums
+    enum Action { About = 1, Help = 2, Preferences = 4, ReportBug = 8 };
+    enum Position { pLeft = 0, pRight, pTop, pBottom };
+    enum Alignment { LeftTop = 0, Center, RightBottom };
+    enum Direction { Up = 0, Down, Left, Right };
+
+    /**
+     * Constructs a KPanelApplet just like any other widget.
+     *
+     * @param configFile The configFile handed over in the factory function.
+     * @param t The applet type().
+     * @param actions Standard RMB menu actions supported by the applet (see action() ).
+     * @param parent The pointer to the parent widget handed over in the factory function.
+     * @param name A Qt object name for your applet.
+     * @param f Window control flags
+     **/
+    KPanelApplet(const QString& configFile, Type t = Normal,
+                 int actions = 0, QWidget *parent = 0, const char *name = 0,
+                 WFlags f = 0);
+
+    /**
+     * Destructor.
+     **/
+    ~KPanelApplet();
+
+    /**
+     * Returns a suggested width for a given height.
+     *
+     * Every applet should reimplement this function.
+     *
+     * Depending on the panel orientation the height (horizontal panel) or the
+     * width (vertical panel) of the applets is fixed.
+     * The exact values of the fixed size component depend on the panel size.
+     *
+     * On a horizontal panel the applet height is fixed, the panel will
+     * call widthForHeight(int height) with @p height
+     * equal to 'the fixed applet height'
+     * when laying out the applets.
+     *
+     * The applet can now choose the other size component (width)
+     * based on the given height.
+     *
+     * The width you return is granted.
+     **/
+    virtual int widthForHeight(int height) const { return height; }
+
+    /**
+     * @return A suggested height for a given width.
+     *
+     * Every applet should reimplement this function.
+     *
+     * Depending on the panel orientation the height (horizontal panel) or the
+     * width (vertical panel) of the applets is fixed.
+     * The exact values of the fixed size component depend on the panel size.
+     *
+     * On a vertical panel the applet width is fixed, the panel will
+     * call heightForWidth(int width) with @p width
+     * equal to 'the fixed applet width'
+     * when laying out the applets.
+     *
+     * The applet can now choose the other size component (height)
+     * based on the given width.
+     *
+     * The height you return is granted.
+     **/
+    virtual int heightForWidth(int width) const { return width; }
+
+    /**
+     * Always use this KConfig object to save/load your applet's configuration.
+     *
+     * For unique applets this config object will write to a config file called
+     * \<appletname\>rc in the user's local %KDE directory.
+     *
+     * For normal applets this config object will write to a instance specific config file
+     * called \<appletname\>\<instanceid\>rc in the user's local %KDE directory.
+     **/
+    KConfig* config() const { return _config; }
+    KSharedConfig::Ptr sharedConfig() const;
+
+    /**
+     * @return Type indicating the applet's 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 applet's 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 );
+
+    /**
+     * @return the applet's custom menu, usually the same as the context menu, or 0 if none
+     * see setCustomMenu(QPopupMenu*)
+     */
+    const QPopupMenu* customMenu() const;
+
+    /**
+     * @internal
+     **/
+    void setPosition( Position p );
+    /**
+     * @internal
+     **/
+    void setAlignment( Alignment a );
+
+signals:
+    /**
+     * Emit this signal to make the panel relayout all applets, when
+     * you want to change your width (horizontal panel) or
+     * height (vertical panel).
+     *
+     * The panel is going to relayout all applets based on their
+     * widthForHeight(int height) (horizontal panel) or
+     * heightForWidth(int width) (vertical panel).
+     *
+     * Please note that the panel may change the applet's location
+     * if the new widthForHeight(int height) (horizontal panel) or
+     * heightForWidth(int width) (vertical panel) does not fit into the
+     * current panel layout.
+     **/
+    void updateLayout();
+
+    /**
+     * Request keyboard focus from the panel.
+     * @deprecated
+     **/
+    void requestFocus();
+
+    /**
+     * Request keyboard focus from the panel. Applets should never call this directly
+     * but rather call needsFocus(bool)
+     * @see needsFocus
+     * @param focus activate the window and ensure the panel remains visible when true
+     * Each and ever time a requestFocus(true) is emitted, it MUST be paired eventually
+     * with a requestFocus(false) otherwise the panel may end up never hiding
+     * @since 3.4
+     **/
+    void requestFocus(bool focus);
+
+protected:
+
+    /**
+     * Is called when the user selects "About" from the applet's RMB menu.
+     * Reimplement this function to launch a about dialog.
+     *
+     * Note that this is called only when your applet supports the About action.
+     * See Action and KPanelApplet().
+     **/
+    virtual void about() {}
+
+    /**
+     * Is called when the user selects "Help" from the applet's RMB menu.
+     * Reimplement this function to launch a manual or help page.
+     *
+     * Note that this is called only when your applet supports the Help action.
+     * See Action and KPanelApplet().
+     **/
+    virtual void help() {}
+
+    /**
+     * Is called when the user selects "Preferences" from the applet's RMB menu.
+     * Reimplement this function to launch a preferences dialog or kcontrol module.
+     *
+     * Note that this is called only when your applet supports the preferences action.
+     * See Action and KPanelApplet().
+     **/
+    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 and KPanelApplet()
+     **/
+   virtual void reportBug() {}
+
+    /**
+     * @return the applet's orientation. (horizontal or vertical)
+     **/
+    Orientation orientation() const;
+    /**
+     * @return the applet's position. (top, left, bottom, or right)
+     **/
+    Position position() const { return _position; }
+    /**
+     * @return the applet's alignment. (top/left, center, or bottom/right)
+     **/
+    Alignment alignment() const { return _alignment; }
+
+    /**
+     * The panel on which this applet resides has changed its position.
+     * Reimplement this change handler in order to adjust the look of your
+     * applet.
+     **/
+    virtual void positionChange( Position p );
+
+    /**
+     * The panel on which this applet resides has changed its alignment.
+     * Reimplement this change handler in order to adjust the look of your
+     * applet.
+     **/
+    virtual void alignmentChange( Alignment /*a*/ ) {}
+
+    /**
+     * Use this method to set the custom menu for this applet so that it can be shown
+     * in the applet handle menu and other appropriate places that the applet many not itself
+     * be aware of. The applet itself is still responsible for deleting and managing the
+     * the menu.
+     *
+     * If the menu is deleted during the life of the applet, be sure to call this method again
+     * with the new menu (or 0) to avoid crashes
+     */
+    void setCustomMenu(const QPopupMenu*);
+
+    /**
+     * Register widgets that can receive keyboard focus with this this method
+     * This call results in an eventFilter being places on the widget.
+     * @param widget the widget to watch for keyboard focus
+     * @param watch whether to start watching the widget, or to stop doing so
+     * @since 3.4
+     */
+    void watchForFocus(QWidget* widget, bool watch = true);
+
+    /**
+     * Call this whenever focus is needed or not needed. You do not have to call this method
+     * for widgets that have been registered with watchForFocus
+     * @param focus whether to or not to request focus
+     * @since 3.4
+     */
+    void needsFocus(bool focus);
+
+    /**
+     * The orientation changed to @p orientation. Reimplement this
+     * change handler in order to adjust the look of your applet.
+     *
+     * @deprecated Reimplement positionChange instead.
+     **/
+    // FIXME: Remove for KDE 4
+    virtual KDE_DEPRECATED void orientationChange( Orientation /* orientation*/) {}
+
+    /**
+     * A convenience method that translates the position of the applet into which
+     * direction to show a popup.
+     **/
+    Direction popupDirection();
+
+    /**
+     * The popup direction changed to @p direction. Reimplement this
+     * change handler in order to adjust the look of your applet.
+     *
+     * @deprecated Reimplement positionChange instead.
+     **/
+    // FIXME: Remove for KDE 4
+    virtual KDE_DEPRECATED void popupDirectionChange( Direction /*direction*/ ) {}
+
+    bool eventFilter(QObject *, QEvent *);
+
+private:
+    Type         _type;
+    Position     _position;
+    Alignment    _alignment;
+    KConfig*     _config;
+    int          _actions;
+protected:
+    virtual void virtual_hook( int id, void* data );
+    class KPanelAppletPrivate;
+    KPanelAppletPrivate *d;
+};
+
+#endif