alecs/plasma-framework
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Clean up the APIDOX a little: spelling mistakes, seperating

Browse Source 
the "brief description" from the "main description",
"Reimplemented from QGraphicsView" should be a comment, not
an APIDOX (so Doxygen will copy the original APIDOX down),
added docs for the export macro.


svn path=/trunk/KDE/kdebase/workspace/libs/plasma/; revision=684556
This commit is contained in:
Alex Merry 2007-07-06 22:20:57 +00:00
parent fee185b328
commit 3d4b57b118
1 changed files with 58 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
applet.h
View File

@ -90,15 +90,16 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
KConfigGroup globalAppletConfig() const; KConfigGroup globalAppletConfig() const;
/** /**
* Ensures that the DataEngine named name is loaded and ready to be used * Ensures that the DataEngine named name is loaded and ready to be used.
* *
* @return returns true on success, false on failure * @return returns true on success, false on failure
*/ */
DataEngine* dataEngine(const QString& name); DataEngine* dataEngine(const QString& name);
/** /**
* called when any of the geometry constraints have been updated * Called when any of the geometry constraints have been updated.
* this is always called prior to painting and should be used as an *
* This is always called prior to painting and should be used as an
* opportunity to layout the widget, calculate sizings, etc. * opportunity to layout the widget, calculate sizings, etc.
* *
* Do not call update() from this method; an update() will be triggered * Do not call update() from this method; an update() will be triggered
@ -110,18 +111,21 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
/** /**
* Returns the current form factor the applet is being displayed in. * Returns the current form factor the applet is being displayed in.
*
* @see Plasma::FormFactor * @see Plasma::FormFactor
*/ */
FormFactor formFactor() const; FormFactor formFactor() const;
/** /**
* Returns the location of the scene which is displaying applet. * Returns the location of the scene which is displaying applet.
*
* @see Plasma::Location * @see Plasma::Location
*/ */
Location location() const; Location location() const;
/** /**
* Returns a maximum size hint based on the Corona's space availability * Returns a maximum size hint based on the Corona's space availability.
*
* An applet may choose to violate this size hint, but should try and * An applet may choose to violate this size hint, but should try and
* respect it as much as possible. * respect it as much as possible.
*/ */
@ -129,7 +133,7 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
/** /**
* Returns a list of all known applets in a hash keyed by a unique * Returns a list of all known applets in a hash keyed by a unique
* identifier for each applet * identifier for each applet.
* *
* @return list of applets * @return list of applets
**/ **/
@ -141,15 +145,19 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
bool hasConfigurationInterface(); bool hasConfigurationInterface();
/** /**
* Reimplement this slot to show a configuration dialog and let the user * Reimplement this slot to show a configuration dialog.
* play with the plasmoid options. Called when the user selects the configure entry *
* Let the user play with the plasmoid options.
* Called when the user selects the configure entry
* from the context menu. * from the context menu.
*/ */
virtual void showConfigurationInterface(); virtual void showConfigurationInterface();
/** /**
* Attempts to load an applet, returning a pointer to the applet if * Attempts to load an applet
* successful. The caller takes responsibility for the applet, including *
* Returns a pointer to the applet if successful.
* The caller takes responsibility for the applet, including
* deleting it when no longer needed. * deleting it when no longer needed.
* *
* @param name the plugin name, as returned by KPluginInfo::pluginName() * @param name the plugin name, as returned by KPluginInfo::pluginName()
@ -162,8 +170,10 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
const QStringList& args = QStringList()); const QStringList& args = QStringList());
/** /**
* Attempts to load an applet, returning a pointer to the applet if * Attempts to load an applet
* successful. The caller takes responsibility for the applet, including *
* Returns a pointer to the applet if successful.
* The caller takes responsibility for the applet, including
* deleting it when no longer needed. * deleting it when no longer needed.
* *
* @param info KPluginInfo object for the desired applet * @param info KPluginInfo object for the desired applet
@ -176,6 +186,7 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
/** /**
* This method is called when the interface should be painted. * This method is called when the interface should be painted.
*
* @see QGraphicsItem::paint * @see QGraphicsItem::paint
**/ **/
virtual void paintInterface(QPainter *painter, virtual void paintInterface(QPainter *painter,
@ -185,6 +196,7 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
/** /**
* Returns the user-visible name for the applet, as specified in the * Returns the user-visible name for the applet, as specified in the
* .desktop file. * .desktop file.
*
* @return the user-visible name for the applet. * @return the user-visible name for the applet.
**/ **/
QString name() const; QString name() const;
@ -195,7 +207,7 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
bool immutable() const; bool immutable() const;
/** /**
* Sets whether or not this applet is immutable or not * Sets whether or not this applet is immutable or not.
* *
* @arg immutable true if this applet should not be changable * @arg immutable true if this applet should not be changable
**/ **/
@ -208,22 +220,24 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
bool drawStandardBackground(); bool drawStandardBackground();
/** /**
* Sets whether or not the applet should automatically draw the standard * Sets whether the applet should automatically draw the standard
* background or not. Defaults to false * background.
*
* Defaults to false
**/ **/
void setDrawStandardBackground(bool drawBackground); void setDrawStandardBackground(bool drawBackground);
/** // Reimplemented from QGraphicsItem
* Reimplented from QGraphicsItem
**/
enum { Type = Plasma::AppletType }; enum { Type = Plasma::AppletType };
int type() const { return Type; } int type() const { return Type; }
Q_SIGNALS: Q_SIGNALS:
/** /**
* Emit this signal when your applet needs to take (or lose) keyboard * Emitted when the applet needs to take (or lose) keyboard focus.
* focus. This ensures that autohiding elements stay unhidden and other *
* bits of bookkeeping are performed to ensure proper function. * An applet should emit this signal to ensure that autohiding
* elements stay unhidden and other bits of bookkeeping are
* performed to ensure proper function.
* *
* If you call watchForFocus on your applet, then this is handled for * If you call watchForFocus on your applet, then this is handled for
* the applet and it is not necessary to emit the signal directly. * the applet and it is not necessary to emit the signal directly.
@ -235,38 +249,46 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
protected: protected:
/** /**
* Returns the name of the applet. This will be the same for all * Returns the name of the applet.
* instances of this applet. *
* This will be the same for all instances of this applet.
**/ **/
QString globalName() const; QString globalName() const;
/** /**
* Returns a name unique to the insane of this applet. Useful for * Returns a name unique to the instance of this applet.
* being able to refer directly to a particular applet. Combines the *
* global name with the applet id * Useful for being able to refer directly to a particular
* applet. Combines the global name with the applet id
**/ **/
QString instanceName() const; QString instanceName() const;
/** /**
* Register widgets that can receive keyboard focus with this method * Register widgets that can receive keyboard focus.
* This call results in an eventFilter being places on the widget. *
* Calling this results in an eventFilter being places on the widget.
*
* @param widget the widget to watch for keyboard focus * @param widget the widget to watch for keyboard focus
* @param watch whether to start watching the widget, or to stop doing so * @param watch whether to start watching the widget, or to stop doing so
*/ */
void watchForFocus( QObject *widget, bool watch = true ); void watchForFocus( QObject *widget, bool watch = true );
/** /**
* Call this whenever focus is needed or not needed. You do not have to * Call this whenever focus is needed or not needed.
* call this method for widgets that have been registered with *
* watchForFocus * You do not have to call this method for widgets that have
* been registered with watchForFocus
*
* @see watchForFocus * @see watchForFocus
* @param focus whether to or not to request focus * @param focus whether to or not to request focus
*/ */
void needsFocus(bool focus); void needsFocus(bool focus);
/** /**
* Sets whether or not this applet provides a user interface for configuring * Sets whether or not this applet provides a user interface for
* the applet. It defaults to false, and if true is passed in you should * configuring the applet.
*
* It defaults to false, and if true is passed in you should
* also reimplement showConfigurationInterface() * also reimplement showConfigurationInterface()
* *
* @arg hasInterface whether or not there is a user interface available * @arg hasInterface whether or not there is a user interface available
@ -279,9 +301,7 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
bool eventFilter( QObject *o, QEvent *e ); bool eventFilter( QObject *o, QEvent *e );
private: private:
/** // Reimplemented from QGraphicsItem
* Reimplemented from QGraphicsItem
**/
void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0); void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0);
void init(); void init();
@ -292,6 +312,9 @@ class PLASMA_EXPORT Applet : public QObject, public QGraphicsItem
} // Plasma namespace } // Plasma namespace
/**
* Register an applet when it is contained in a loadable module
*/
#define K_EXPORT_PLASMA_APPLET(libname, classname) \ #define K_EXPORT_PLASMA_APPLET(libname, classname) \
K_EXPORT_COMPONENT_FACTORY( \ K_EXPORT_COMPONENT_FACTORY( \
plasma_applet_##libname, \ plasma_applet_##libname, \