diff options
Diffstat (limited to 'kdeui/kpanelextension.h')
| -rw-r--r-- | kdeui/kpanelextension.h | 345 |
1 files changed, 0 insertions, 345 deletions
diff --git a/kdeui/kpanelextension.h b/kdeui/kpanelextension.h deleted file mode 100644 index d1131638d..000000000 --- a/kdeui/kpanelextension.h +++ /dev/null @@ -1,345 +0,0 @@ -/***************************************************************** - -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__ - -#include <tqframe.h> -#include <kdelibs_export.h> - -class TQPopupMenu; -class KConfig; -class KPanelExtensionPrivate; - -/** - * @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(TQWidget *parent, const TQString& 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 TQFrame -{ - 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 TQString& configFile, Type t = Normal, - int actions = 0, TQWidget *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 TQSize tqsizeHint(Position /*p*/, TQSize 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 tqsetAlignment( 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(TQPopupMenu*) - * @since 3.4 - */ - TQPopupMenu* 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 tqalignment. (left/top, center, or right/bottom) - **/ - Alignment tqalignment() const { return _tqalignment; } - - /** - * @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 tqalignment. - * 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(TQPopupMenu*); - - /** - * 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 _tqalignment; - KConfig* _config; - int _actions; -protected: - virtual void virtual_hook( int id, void* data ); -private: - KPanelExtensionPrivate *d; -}; - -#endif |