home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kpanelapplet.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-10-08  |  13.4 KB  |  396 lines
  1. /*****************************************************************
  2.  
  3. Copyright (c) 2000 Matthias Elter
  4.  
  5. Permission is hereby granted, free of charge, to any person obtaining a copy
  6. of this software and associated documentation files (the "Software"), to deal
  7. in the Software without restriction, including without limitation the rights
  8. to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9. copies of the Software, and to permit persons to whom the Software is
  10. furnished to do so, subject to the following conditions:
  11.  
  12. The above copyright notice and this permission notice shall be included in
  13. all copies or substantial portions of the Software.
  14.  
  15. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16. IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  18. AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  19. AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  20. CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21.  
  22. ******************************************************************/
  23.  
  24. #ifndef __kpanelapplet_h__
  25. #define __kpanelapplet_h__
  26.  
  27. class KConfig;
  28. class QPopupMenu;
  29.  
  30. #include <qframe.h>
  31. #include <kconfig.h>
  32.  
  33. /**
  34.  * @short %KDE Panel Applet class
  35.  *
  36.  * Panel applets
  37.  *   @li Are small applications living in the %KDE panel.
  38.  *   @li Are implemented as DSOs (Dynamic Shared Objects).
  39.  *
  40.  * Note: For security and stability reasons the panel won't load
  41.  * untrusted third party applets directly into its namespace but via an
  42.  * external wrapper process.
  43.  *
  44.  * The panel locates available applets by searching for applet desktop
  45.  * files in (ALL_DIRS)/share/apps/kicker/applets. Every panel applet should
  46.  * install a desktop file there to be recognized by the panel.
  47.  *
  48.  * Besides standard keys like "Name", "Comment" and "Icon" there are
  49.  * two panel applet specific keys:
  50.  *
  51.  * \b X-KDE-Library \n
  52.  *
  53.  * Used by the panel to locate the applet DSO (Dynamic Shared Object)
  54.  * Example: X-KDE-Library=libexampleapplet
  55.  *
  56.  * \b X-KDE-UniqueApplet \n
  57.  *
  58.  * Similar to KApplication and KUniqueApplication there are
  59.  * two types of panel applets. Use unique applets when it makes no
  60.  * sence to run more than one instance of a applet in the panel. A
  61.  * good example for unique applets is the taskbar applet.  Use normal
  62.  * applets when you need instance specific configuration. An example
  63.  * is the koolclock applet where you might want to run two instances
  64.  * in your panel, one configured as analog clock, the other one as
  65.  * digital clock. X-KDE-UniqueApplet is a boolean key which defaults
  66.  * to "false".  Example: X-KDE-UniqueApplet=true
  67.  *
  68.  * Back to panel applet DSOs, the following conventions are used for %KDE:
  69.  * Name:    lib<appletname>applet.la
  70.  * LDFLAGS: -module -no-undefined
  71.  *
  72.  * To implement a panel applet it is not enough to write a class
  73.  * inheriting from KPanelApplet but you also have to provide a
  74.  * factory function in your DSO.  A sample factory function could look
  75.  * like this:
  76.  *
  77.  * \code
  78.  *
  79.  * extern "C"
  80.  * {
  81.  *     KPanelApplet* init(QWidget *parent, const QString& configFile)
  82.  *     {
  83.  *         KGlobal::locale()->insertCatalogue("exampleapplet");
  84.  *         return new ExampleApplet(configFile, KPanelApplet::Normal,
  85.  *                       KPanelApplet::About | KPanelApplet::Help | KPanelApplet::Preferences,
  86.  *                       parent, "exampleapplet");
  87.  *     }
  88.  * }
  89.  *
  90.  * \endcode
  91.  *
  92.  * Note: Don't change the factory function signature or the panel will
  93.  * fail to load your applet.
  94.  *
  95.  * @author Matthias Elter <elter@kde.org>
  96.  **/
  97. class KDEUI_EXPORT KPanelApplet : public QFrame
  98. {
  99.     Q_OBJECT
  100.  
  101. public:
  102.  
  103.     /**
  104.      * This enum describes the type of the applet.
  105.      */
  106.     enum Type { Normal = 0, Stretch };
  107.     /**
  108.      * This enum holds flags which can be ORed together to describe
  109.      * which items the context menu over the applet handle contains.
  110.      */
  111.     // KDE4: Merge these with KPanelExtension's enums
  112.     enum Action { About = 1, Help = 2, Preferences = 4, ReportBug = 8 };
  113.     enum Position { pLeft = 0, pRight, pTop, pBottom };
  114.     enum Alignment { LeftTop = 0, Center, RightBottom };
  115.     enum Direction { Up = 0, Down, Left, Right };
  116.  
  117.     /**
  118.      * Constructs a KPanelApplet just like any other widget.
  119.      *
  120.      * @param configFile The configFile handed over in the factory function.
  121.      * @param t The applet type().
  122.      * @param actions Standard RMB menu actions supported by the applet (see action() ).
  123.      * @param parent The pointer to the parent widget handed over in the factory function.
  124.      * @param name A Qt object name for your applet.
  125.      * @param f Window control flags
  126.      **/
  127.     KPanelApplet(const QString& configFile, Type t = Normal,
  128.                  int actions = 0, QWidget *parent = 0, const char *name = 0,
  129.                  WFlags f = 0);
  130.  
  131.     /**
  132.      * Destructor.
  133.      **/
  134.     ~KPanelApplet();
  135.  
  136.     /**
  137.      * Returns a suggested width for a given height.
  138.      *
  139.      * Every applet should reimplement this function.
  140.      *
  141.      * Depending on the panel orientation the height (horizontal panel) or the
  142.      * width (vertical panel) of the applets is fixed.
  143.      * The exact values of the fixed size component depend on the panel size.
  144.      *
  145.      * On a horizontal panel the applet height is fixed, the panel will
  146.      * call widthForHeight(int height) with @p height
  147.      * equal to 'the fixed applet height'
  148.      * when laying out the applets.
  149.      *
  150.      * The applet can now choose the other size component (width)
  151.      * based on the given height.
  152.      *
  153.      * The width you return is granted.
  154.      **/
  155.     virtual int widthForHeight(int height) const { return height; }
  156.  
  157.     /**
  158.      * @return A suggested height for a given width.
  159.      *
  160.      * Every applet should reimplement this function.
  161.      *
  162.      * Depending on the panel orientation the height (horizontal panel) or the
  163.      * width (vertical panel) of the applets is fixed.
  164.      * The exact values of the fixed size component depend on the panel size.
  165.      *
  166.      * On a vertical panel the applet width is fixed, the panel will
  167.      * call heightForWidth(int width) with @p width
  168.      * equal to 'the fixed applet width'
  169.      * when laying out the applets.
  170.      *
  171.      * The applet can now choose the other size component (height)
  172.      * based on the given width.
  173.      *
  174.      * The height you return is granted.
  175.      **/
  176.     virtual int heightForWidth(int width) const { return width; }
  177.  
  178.     /**
  179.      * Always use this KConfig object to save/load your applet's configuration.
  180.      *
  181.      * For unique applets this config object will write to a config file called
  182.      * \<appletname\>rc in the user's local %KDE directory.
  183.      *
  184.      * For normal applets this config object will write to a instance specific config file
  185.      * called \<appletname\>\<instanceid\>rc in the user's local %KDE directory.
  186.      **/
  187.     KConfig* config() const { return _config; }
  188.     KSharedConfig::Ptr sharedConfig() const;
  189.  
  190.     /**
  191.      * @return Type indicating the applet's type.
  192.      * Type
  193.      **/
  194.     Type type() const { return _type; }
  195.  
  196.     /**
  197.      * @return int indicating the supported RMB menu actions.
  198.      * Action
  199.      **/
  200.     int actions() const { return _actions; }
  201.  
  202.     /**
  203.      * Generic action dispatcher. Called  when the user selects an item
  204.      * from the applet's RMB menu.
  205.      *
  206.      * Reimplement this function to handle actions.
  207.      *
  208.      * For About, Help, Preferences and ReportBug, use the convenience handlers
  209.      * ref about(), help(), preferences(), reportBug()
  210.      *
  211.      **/
  212.     virtual void action( Action a );
  213.  
  214.     /**
  215.      * @return the applet's custom menu, usually the same as the context menu, or 0 if none
  216.      * see setCustomMenu(QPopupMenu*)
  217.      */
  218.     const QPopupMenu* customMenu() const;
  219.  
  220.     /**
  221.      * @internal
  222.      **/
  223.     void setPosition( Position p );
  224.     /**
  225.      * @internal
  226.      **/
  227.     void setAlignment( Alignment a );
  228.  
  229. signals:
  230.     /**
  231.      * Emit this signal to make the panel relayout all applets, when
  232.      * you want to change your width (horizontal panel) or
  233.      * height (vertical panel).
  234.      *
  235.      * The panel is going to relayout all applets based on their
  236.      * widthForHeight(int height) (horizontal panel) or
  237.      * heightForWidth(int width) (vertical panel).
  238.      *
  239.      * Please note that the panel may change the applet's location
  240.      * if the new widthForHeight(int height) (horizontal panel) or
  241.      * heightForWidth(int width) (vertical panel) does not fit into the
  242.      * current panel layout.
  243.      **/
  244.     void updateLayout();
  245.  
  246.     /**
  247.      * Request keyboard focus from the panel.
  248.      * @deprecated
  249.      **/
  250.     void requestFocus();
  251.  
  252.     /**
  253.      * Request keyboard focus from the panel. Applets should never call this directly
  254.      * but rather call needsFocus(bool)
  255.      * @see needsFocus
  256.      * @param focus activate the window and ensure the panel remains visible when true
  257.      * Each and ever time a requestFocus(true) is emitted, it MUST be paired eventually
  258.      * with a requestFocus(false) otherwise the panel may end up never hiding
  259.      * @since 3.4
  260.      **/
  261.     void requestFocus(bool focus);
  262.  
  263. protected:
  264.  
  265.     /**
  266.      * Is called when the user selects "About" from the applet's RMB menu.
  267.      * Reimplement this function to launch a about dialog.
  268.      *
  269.      * Note that this is called only when your applet supports the About action.
  270.      * See Action and KPanelApplet().
  271.      **/
  272.     virtual void about() {}
  273.  
  274.     /**
  275.      * Is called when the user selects "Help" from the applet's RMB menu.
  276.      * Reimplement this function to launch a manual or help page.
  277.      *
  278.      * Note that this is called only when your applet supports the Help action.
  279.      * See Action and KPanelApplet().
  280.      **/
  281.     virtual void help() {}
  282.  
  283.     /**
  284.      * Is called when the user selects "Preferences" from the applet's RMB menu.
  285.      * Reimplement this function to launch a preferences dialog or kcontrol module.
  286.      *
  287.      * Note that this is called only when your applet supports the preferences action.
  288.      * See Action and KPanelApplet().
  289.      **/
  290.     virtual void preferences() {}
  291.  
  292.     /**
  293.      * Is called when the user selects "Report bug" from the applet's RMB menu.
  294.      * Reimplement this function to launch a bug reporting dialog.
  295.      *
  296.      * Note that this is called only when your applet supports the ReportBug
  297.      * action.
  298.      * See Action and KPanelApplet()
  299.      **/
  300.    virtual void reportBug() {}
  301.  
  302.     /**
  303.      * @return the applet's orientation. (horizontal or vertical)
  304.      **/
  305.     Orientation orientation() const;
  306.     /**
  307.      * @return the applet's position. (top, left, bottom, or right)
  308.      **/
  309.     Position position() const { return _position; }
  310.     /**
  311.      * @return the applet's alignment. (top/left, center, or bottom/right)
  312.      **/
  313.     Alignment alignment() const { return _alignment; }
  314.  
  315.     /**
  316.      * The panel on which this applet resides has changed its position.
  317.      * Reimplement this change handler in order to adjust the look of your
  318.      * applet.
  319.      **/
  320.     virtual void positionChange( Position p );
  321.  
  322.     /**
  323.      * The panel on which this applet resides has changed its alignment.
  324.      * Reimplement this change handler in order to adjust the look of your
  325.      * applet.
  326.      **/
  327.     virtual void alignmentChange( Alignment /*a*/ ) {}
  328.  
  329.     /**
  330.      * Use this method to set the custom menu for this applet so that it can be shown
  331.      * in the applet handle menu and other appropriate places that the applet many not itself
  332.      * be aware of. The applet itself is still responsible for deleting and managing the
  333.      * the menu.
  334.      *
  335.      * If the menu is deleted during the life of the applet, be sure to call this method again
  336.      * with the new menu (or 0) to avoid crashes
  337.      */
  338.     void setCustomMenu(const QPopupMenu*);
  339.  
  340.     /**
  341.      * Register widgets that can receive keyboard focus with this this method
  342.      * This call results in an eventFilter being places on the widget.
  343.      * @param widget the widget to watch for keyboard focus
  344.      * @param watch whether to start watching the widget, or to stop doing so
  345.      * @since 3.4
  346.      */
  347.     void watchForFocus(QWidget* widget, bool watch = true);
  348.  
  349.     /**
  350.      * Call this whenever focus is needed or not needed. You do not have to call this method
  351.      * for widgets that have been registered with watchForFocus
  352.      * @param focus whether to or not to request focus
  353.      * @since 3.4
  354.      */
  355.     void needsFocus(bool focus);
  356.  
  357.     /**
  358.      * The orientation changed to @p orientation. Reimplement this
  359.      * change handler in order to adjust the look of your applet.
  360.      *
  361.      * @deprecated Reimplement positionChange instead.
  362.      **/
  363.     // FIXME: Remove for KDE 4
  364.     virtual KDE_DEPRECATED void orientationChange( Orientation /* orientation*/) {}
  365.  
  366.     /**
  367.      * A convenience method that translates the position of the applet into which
  368.      * direction to show a popup.
  369.      **/
  370.     Direction popupDirection();
  371.  
  372.     /**
  373.      * The popup direction changed to @p direction. Reimplement this
  374.      * change handler in order to adjust the look of your applet.
  375.      *
  376.      * @deprecated Reimplement positionChange instead.
  377.      **/
  378.     // FIXME: Remove for KDE 4
  379.     virtual KDE_DEPRECATED void popupDirectionChange( Direction /*direction*/ ) {}
  380.  
  381.     bool eventFilter(QObject *, QEvent *);
  382.  
  383. private:
  384.     Type         _type;
  385.     Position     _position;
  386.     Alignment    _alignment;
  387.     KConfig*     _config;
  388.     int          _actions;
  389. protected:
  390.     virtual void virtual_hook( int id, void* data );
  391.     class KPanelAppletPrivate;
  392.     KPanelAppletPrivate *d;
  393. };
  394.  
  395. #endif
  396.