Difference between revisions of "Development/Tutorials/Plasma/JavaScript/CheatSheet"

Jump to: navigation, search
m
 
(9 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
{{TutorialBrowser|
 +
 +
series=JavaScript Plasmoids|
 +
 +
name=Getting Data|
 +
 +
name=JavaScript Plasmoid Cheat Sheet|
 +
 +
pre=[[../SystemMonitor|System Monitor: How to access systemmonitor data engine]]|
 +
 +
reading=[[../API|JavaScript Plasmoid API reference]]
 +
}}
 +
 +
 
== Basics ==
 
== Basics ==
  
Line 7: Line 21:
 
* To connect to a signal use <tt>object.signalName.connect(function() {});</tt>
 
* To connect to a signal use <tt>object.signalName.connect(function() {});</tt>
 
* Enumeration values can be used like
 
* Enumeration values can be used like
<code>
+
<syntaxhighlight lang="javascript">
 
if (plasmoid.formFactor() == Vertical) {
 
if (plasmoid.formFactor() == Vertical) {
 
     layout.setOrientation(QtVertical);
 
     layout.setOrientation(QtVertical);
Line 13: Line 27:
 
     layout.setOrientation(QtHorizontal);
 
     layout.setOrientation(QtHorizontal);
 
}
 
}
</code>
+
</syntaxhighlight>
  
 
== Global variables and functions ==
 
== Global variables and functions ==
Line 21: Line 35:
 
* The <tt>loadui</tt> function can be used to load a Qt UI file.  Beware that a relative path is relative to plasma's working directory (in 4.2 at least), and so may not do what you want.
 
* The <tt>loadui</tt> function can be used to load a Qt UI file.  Beware that a relative path is relative to plasma's working directory (in 4.2 at least), and so may not do what you want.
 
* The <tt>print</tt> function prints debug output
 
* The <tt>print</tt> function prints debug output
* There are several ccontructor methods:
+
* There are several constructor methods:
 
** <tt>PlasmaSvg(file, parent)</tt> constructs a <tt>Plasma::Svg</tt>.  The second argument is optional.
 
** <tt>PlasmaSvg(file, parent)</tt> constructs a <tt>Plasma::Svg</tt>.  The second argument is optional.
 
** <tt>PlasmaFrameSvg(file, parent)</tt> constructs a <tt>Plasma:FrameSvg</tt>.  The second argument is optional.
 
** <tt>PlasmaFrameSvg(file, parent)</tt> constructs a <tt>Plasma:FrameSvg</tt>.  The second argument is optional.
Line 38: Line 52:
  
 
* The Name and Comment fields in the <tt>metadata.desktop</tt> file can be translated like <tt>Name[nl]=Hallo JavaScript</tt>
 
* The Name and Comment fields in the <tt>metadata.desktop</tt> file can be translated like <tt>Name[nl]=Hallo JavaScript</tt>
* <tt>plasmoid.i18n()</tt> takes a string (in English) as the first argument, and substitutes in the following arguments to replace %1, %2, %3 etc.  Eg: <tt>plasmoid.i18n("The file is called %1", fileName);</tt>
+
* <tt>i18n()</tt> takes a string (in English) as the first argument, and substitutes in the following arguments to replace %1, %2, %3 etc.  Eg: <tt>i18n("The file is called %1", fileName);</tt>
* <tt>plasmoid.i18nc()</tt> works just the same, but has an extra argument at the start that provides some context for translators.  Eg: <tt>plasmoid.i18nc("Player name - score", "%1 - %2", playerName, score);</tt>
+
* <tt>i18nc()</tt> works just the same, but has an extra argument at the start that provides some context for translators.  Eg: <tt>i18nc("Player name - score", "%1 - %2", playerName, score);</tt>
* <tt>plasmoid.i18np()</tt> is for cases where plural forms might be important.  Eg: <tt>plasmoid.i18np("One image in album %2", "%1 images in album %2", imageCount, albumName);</tt>
+
* <tt>i18np()</tt> is for cases where plural forms might be important.  Eg: <tt>i18np("One image in album %2", "%1 images in album %2", imageCount, albumName);</tt>
* <tt>plasmoid.i18ncp()</tt> is a combination of the previous two.  Eg: <tt>plasmoid.i18ncp("Personal file", "One file", "%1 files", numFiles);</tt>
+
* <tt>i18ncp()</tt> is a combination of the previous two.  Eg: <tt>i18ncp("Personal file", "One file", "%1 files", numFiles);</tt>
  
 
== DataEngines ==
 
== DataEngines ==
Line 52: Line 66:
 
== Services ==
 
== Services ==
  
* DO NOT use <tt>plasmoid.dataEngine("engine name").serviceForSource("source name")</tt> - you will get a dummy service back (in 4.2 at least).
+
* Prior to KDE 4.4, DO NOT use <tt>plasmoid.dataEngine("engine name").serviceForSource("source name")</tt> - you will get a dummy service back. Instead, use <tt>plasmoid.service("engine name", "source name")</tt>
* Instead, use <tt>plasmoid.service("engine name", "source name")</tt>
+
 
 +
=== Notifications ===
 +
 
 +
If you want to use the standard notifications in KDE, you can using Services, with the following code:
 +
 
 +
<syntaxhighlight lang="javascript">
 +
engine = dataEngine("notifications");
 +
service = engine.serviceForSource("notification");
 +
op = service.operationDescription("createNotification");
 +
op["appName"] = "foo";
 +
op["appIcon"] = "konqueror";
 +
op["summary"] = "this is a summary";
 +
op["body"] = "body of notification";
 +
op["timeout"] = 2000;
 +
 
 +
service.startOperationCall(op);
 +
</syntaxhighlight>

Latest revision as of 18:19, 6 May 2013

JavaScript Plasmoid Cheat Sheet
Tutorial Series   JavaScript Plasmoids
Previous   System Monitor: How to access systemmonitor data engine
What's Next   n/a
Further Reading   JavaScript Plasmoid API reference


Contents

[edit] Basics

  • Everything but the metadata.desktop file goes in a directory named contents
  • X-Plasma-MainScript in the metadata.desktop file should point to the main script, relative to the contents directory
  • X-Plasma-DefaultSize in the metadata.desktop file specifies the default widget size in width,height format (eg: 200,100)
  • plasmoidviewer is an immensely useful tool
  • To connect to a signal use object.signalName.connect(function() {});
  • Enumeration values can be used like
if (plasmoid.formFactor() == Vertical) {
    layout.setOrientation(QtVertical);
} else {
    layout.setOrientation(QtHorizontal);
}

[edit] Global variables and functions

  • The plasmoid variable contains all the main plasmoid functionality and represents the main plasmoid widget, and corresponds to the Applet class in C++
  • The startupArguments variable contains any arguments that were passed to the plasmoid when it was started (such as when the plasmoid is registered as a handler for a mimetype)
  • The loadui function can be used to load a Qt UI file. Beware that a relative path is relative to plasma's working directory (in 4.2 at least), and so may not do what you want.
  • The print function prints debug output
  • There are several constructor methods:
    • PlasmaSvg(file, parent) constructs a Plasma::Svg. The second argument is optional.
    • PlasmaFrameSvg(file, parent) constructs a Plasma:FrameSvg. The second argument is optional.
    • QPainter()
    • QGraphicsItem()
    • QTimer()
    • QFont()
    • QRectF()
    • QSizeF()
    • QPoint()
    • LinearLayout() constructs a QGraphicsLinearLayout
    • Url() constructs a KUrl
  • Plus constructors for all the Plasma widgets (eg: IconWidget()).

[edit] Languages

  • The Name and Comment fields in the metadata.desktop file can be translated like Name[nl]=Hallo JavaScript
  • i18n() takes a string (in English) as the first argument, and substitutes in the following arguments to replace %1, %2, %3 etc. Eg: i18n("The file is called %1", fileName);
  • i18nc() works just the same, but has an extra argument at the start that provides some context for translators. Eg: i18nc("Player name - score", "%1 - %2", playerName, score);
  • i18np() is for cases where plural forms might be important. Eg: i18np("One image in album %2", "%1 images in album %2", imageCount, albumName);
  • i18ncp() is a combination of the previous two. Eg: i18ncp("Personal file", "One file", "%1 files", numFiles);

[edit] DataEngines

  • Add a dataUpdate method to plasmoid to receive updates: plasmoid.dataUpdate = function(name, data) { /* ... */ } - data contains an object mapping keys to values
  • plasmoid.dataEngine("engine name").connectSource("source name", plasmoid, 500); updates every half second
  • plasmoid.dataEngine("engine name").connectSource("source name", plasmoid); updates when new data is available
  • plasmaengineexplorer is your friend

[edit] Services

  • Prior to KDE 4.4, DO NOT use plasmoid.dataEngine("engine name").serviceForSource("source name") - you will get a dummy service back. Instead, use plasmoid.service("engine name", "source name")

[edit] Notifications

If you want to use the standard notifications in KDE, you can using Services, with the following code:

engine = dataEngine("notifications");
service = engine.serviceForSource("notification");
op = service.operationDescription("createNotification");
op["appName"] = "foo";
op["appIcon"] = "konqueror";
op["summary"] = "this is a summary";
op["body"] = "body of notification";
op["timeout"] = 2000;
 
service.startOperationCall(op);

This page was last modified on 6 May 2013, at 18:19. This page has been accessed 9,229 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal