Development/Tutorials/Plasma4/Ruby/GettingStarted: Difference between revisions
(Fixed a couple of errors. The class should be called 'HelloRuby' to match the 'hello-ruby' applet name, and X-PLasma-API in the .desktop file should be 'ruby-script') |
(Mark for archiving) |
||
(9 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
{{Archived}} | |||
{{Warning|This tutorial uses Qt4 Ruby bindings that no longer work on Qt 5 and KDE Frameworks 5.}} | |||
This is a 'translation' of the Getting Started article on Python and Plasma. For the Python Tutorial see [http://techbase.kde.org/Development/Tutorials/Plasma/Python/GettingStarted here]. | This is a 'translation' of the Getting Started article on Python and Plasma. For the Python Tutorial see [http://techbase.kde.org/Development/Tutorials/Plasma/Python/GettingStarted here]. | ||
Line 8: | Line 11: | ||
The first step for any software project is to set up your project's directory on disk. For this tutorial we are going to create a very simple "hello-ruby" applet. Create a directory on somewhere called <tt>hello-ruby</tt> which in turn contains a <tt>contents</tt> directory which then contains a <tt>code</tt> directory. This command below will do all this. | The first step for any software project is to set up your project's directory on disk. For this tutorial we are going to create a very simple "hello-ruby" applet. Create a directory on somewhere called <tt>hello-ruby</tt> which in turn contains a <tt>contents</tt> directory which then contains a <tt>code</tt> directory. This command below will do all this. | ||
< | <syntaxhighlight lang="bash"> | ||
mkdir -p hello-ruby/contents/code | mkdir -p hello-ruby/contents/code | ||
</ | </syntaxhighlight> | ||
This creates a simple directory structure which also matches the package structure expect by the <tt>plasmapkg</tt> command. More on this later. | This creates a simple directory structure which also matches the package structure expect by the <tt>plasmapkg</tt> command. More on this later. | ||
Line 17: | Line 20: | ||
In the <tt>hello-ruby</tt> directory create a file called <tt>metadata.desktop</tt> and open it in your text editor. Copy the following code into <tt>metadata.desktop</tt>. | In the <tt>hello-ruby</tt> directory create a file called <tt>metadata.desktop</tt> and open it in your text editor. Copy the following code into <tt>metadata.desktop</tt>. | ||
< | <syntaxhighlight lang="ini"> | ||
[Desktop Entry] | [Desktop Entry] | ||
Encoding=UTF-8 | Encoding=UTF-8 | ||
Line 36: | Line 39: | ||
X-KDE-PluginInfo-License=GPL | X-KDE-PluginInfo-License=GPL | ||
X-KDE-PluginInfo-EnabledByDefault=true | X-KDE-PluginInfo-EnabledByDefault=true | ||
</ | </syntaxhighlight> | ||
This <tt>metadata.desktop</tt> file list important information needed by Plasma to load the applet, and also information about what the applet is and who created it. The <tt>Name</tt> field lists the name of the applet. This field can also be listed multiple times as different translations. Here I've just given a Dutch translation of the name. The <tt>[nl]</tt> indicates the language of the field. | This <tt>metadata.desktop</tt> file list important information needed by Plasma to load the applet, and also information about what the applet is and who created it. The <tt>Name</tt> field lists the name of the applet. This field can also be listed multiple times as different translations. Here I've just given a Dutch translation of the name. The <tt>[nl]</tt> indicates the language of the field. | ||
Line 52: | Line 55: | ||
Create a file in the <tt>contents/code</tt> directory called <tt>main.rb</tt>, open it up in your text editor and put this code in it and save it. | Create a file in the <tt>contents/code</tt> directory called <tt>main.rb</tt>, open it up in your text editor and put this code in it and save it. | ||
< | <syntaxhighlight lang="ruby"> | ||
# <Copyright and license information goes here.> | # <Copyright and license information goes here.> | ||
require 'plasma_applet' | require 'plasma_applet' | ||
Line 76: | Line 79: | ||
end | end | ||
end | end | ||
</ | </syntaxhighlight> | ||
This is basically the simplest applet which actually does something. The code starts out with the usual copyright notice and license information which I've actually left out for now. | This is basically the simplest applet which actually does something. The code starts out with the usual copyright notice and license information which I've actually left out for now. | ||
Line 90: | Line 93: | ||
Plasma applets can be packaged in zip files and installed using the <tt>plasmapkg</tt> command line tool. The directory structure which we have used for our project matches that need in the zip file. All we have to do is zip it update. Run the following command from inside the hello-ruby directory. | Plasma applets can be packaged in zip files and installed using the <tt>plasmapkg</tt> command line tool. The directory structure which we have used for our project matches that need in the zip file. All we have to do is zip it update. Run the following command from inside the hello-ruby directory. | ||
< | <syntaxhighlight lang="bash"> | ||
zip -r ../hello-ruby.zip . | zip -r ../hello-ruby.zip . | ||
</ | </syntaxhighlight> | ||
This will create the hello-ruby.zip file in the directory just above the hello-ruby directory. Go to this directory in the shell and run this <tt>plasmapkg</tt> command to install our little hello-ruby applet. | This will create the hello-ruby.zip file in the directory just above the hello-ruby directory. Go to this directory in the shell and run this <tt>plasmapkg</tt> command to install our little hello-ruby applet. | ||
< | <syntaxhighlight lang="bash"> | ||
plasmapkg -i hello-ruby.zip | plasmapkg -i hello-ruby.zip | ||
</ | </syntaxhighlight> | ||
This installs the applet into your home directory. Now we can run it. When developing applets it is more convenient to use the <tt>plasmoidviewer</tt>. This is a little utility which displays an applet in a window instead of you having to use your desktop. This command below will run our applet. | This installs the applet into your home directory. Now we can run it. When developing applets it is more convenient to use the <tt>plasmoidviewer</tt>. This is a little utility which displays an applet in a window instead of you having to use your desktop. This command below will run our applet. | ||
< | <syntaxhighlight lang="bash"> | ||
plasmoidviewer hello-ruby | plasmoidviewer hello-ruby | ||
</ | </syntaxhighlight> | ||
You should now be able to see the fruits of your labor. | You should now be able to see the fruits of your labor. | ||
To uninstall our applet we use <tt>plasmapkg</tt> again with its -r option. | To uninstall our applet we use <tt>plasmapkg</tt> again with its -r option. | ||
< | <syntaxhighlight lang="bash"> | ||
plasmapkg -r hello-ruby | plasmapkg -r hello-ruby | ||
</ | </syntaxhighlight> | ||
== Conclusion == | == Conclusion == | ||
Line 112: | Line 115: | ||
This tutorial covers very basics of developing Plasma applets using Ruby. Most of the material discussed here is boring but important "boilerplate" stuff which stays mostly the same between every applet project. In future tutorials we can move on to move exciting things than just displaying a single line of static text. | This tutorial covers very basics of developing Plasma applets using Ruby. Most of the material discussed here is boring but important "boilerplate" stuff which stays mostly the same between every applet project. In future tutorials we can move on to move exciting things than just displaying a single line of static text. | ||
In the next tutorial we explain how to use Plasma's specialized widgets in your applet instead of manually implementing the <tt>paintInterface</tt> method. | In the next tutorial we explain how to use Plasma's specialized widgets in your applet instead of manually implementing the <tt>paintInterface</tt> method. Find out how in the [[../Using widgets|Using widgets tutorial]]. | ||
== Troubleshooting == | |||
If you have this error message instead of plasmoid: | |||
<pre> | |||
This object could not be created for the following reason: | |||
Could not create a ruby-script ScriptEngine for the Hello Ruby widget. | |||
</pre> | |||
Then make sure that all "ruby kde" depdendencies are installed. In ubuntu for example you should have the next package: | |||
<syntaxhighlight lang="text"> | |||
korundum4 | |||
</syntaxhighlight> | |||
For additional help see [http://techbase.kde.org/Development/Tutorials/Plasma/Python/GettingStarted#Troubleshooting here] |
Latest revision as of 14:12, 31 May 2019
This is a 'translation' of the Getting Started article on Python and Plasma. For the Python Tutorial see here.
Abstract
In this tutorial we'll cover setting up a very simple plasma applet in Ruby, and how to install it and run it, basically the edit, install, run and debug cycle. To follow this you will need to have KDE 4.2 or later installed, and also the ruby support for plasma and related dependencies. I'm going to assume that you are using a unix-style operating system such as Linux of *BSD and aren't adverse to the shell.
Project Structure
The first step for any software project is to set up your project's directory on disk. For this tutorial we are going to create a very simple "hello-ruby" applet. Create a directory on somewhere called hello-ruby which in turn contains a contents directory which then contains a code directory. This command below will do all this.
mkdir -p hello-ruby/contents/code
This creates a simple directory structure which also matches the package structure expect by the plasmapkg command. More on this later.
Metadata.desktop
In the hello-ruby directory create a file called metadata.desktop and open it in your text editor. Copy the following code into metadata.desktop.
[Desktop Entry]
Encoding=UTF-8
Name=Hello Ruby
Name[nl]=Hallo Ruby
Type=Service
ServiceTypes=Plasma/Applet
Icon=chronometer
X-Plasma-API=ruby-script
X-Plasma-MainScript=code/main.rb
X-KDE-PluginInfo-Author=Simon Edwards
X-KDE-PluginInfo-Email=[email protected]
X-KDE-PluginInfo-Name=hello-ruby
X-KDE-PluginInfo-Version=1.0
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Examples
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
This metadata.desktop file list important information needed by Plasma to load the applet, and also information about what the applet is and who created it. The Name field lists the name of the applet. This field can also be listed multiple times as different translations. Here I've just given a Dutch translation of the name. The [nl] indicates the language of the field.
The Type and ServiceType fields identify what kind of thing this desktop file is describing. Here we say that we have a plasma applet.
The Icon field gives the name of the icon to associate with this applet. The icon is typically shown in things such as the "Add widget" dialog in Plasma.
The X-Plasma-API and X-Plasma-MainScript fields are used specifically by Plasma to find the correct script-engine to use when loading and running the applet.
Most of the X-KDE-PluginInfo-* fields give extra information about who created the applet. X-KDE-PluginInfo-Category lists a category which this applet belongs to. http://techbase.kde.org/Projects/Plasma/PIG has a list of acceptable category names.
Main script
Create a file in the contents/code directory called main.rb, open it up in your text editor and put this code in it and save it.
# <Copyright and license information goes here.>
require 'plasma_applet'
module HelloRuby
class Main < PlasmaScripting::Applet
def initialize parent
super parent
end
def init
self.has_configuration_interface = false
resize 125, 125
self.aspect_ratio_mode = Plasma::Square
end
def paintInterface(painter, option, rect)
painter.save
painter.pen = Qt::Color.new Qt::white
painter.draw_text rect, Qt::AlignVCenter | Qt::AlignHCenter, "Hello Ruby!"
painter.restore
end
end
end
This is basically the simplest applet which actually does something. The code starts out with the usual copyright notice and license information which I've actually left out for now.
Next up is the loading of Ruby support in Plasma. Only loading plasma_applet is enough as it will load the rest of the Qt and KDE Ruby bindings. In order to create applets which can be packaged and delivered to users across the network via KDE's Get Hot New Stuff (GHNS) framework, we need to use the PlasmaScripting::Applet class as a base class for our applet.
In our main class the constructor method (initialize) is almost empty and only forwards the call to the superclass. It's recommended to put most of the initialisation code in the init method. After Plasma has constructed and initialised the applet, Plasma will call the init method on the applet to let it continue setting itself up. Our init method is rather short. We just tell Plasma that we don't have a configuration dialog and we set up the initial size of the applet.
The paintInterface method is where we draw our "Hello Ruby" message. First we save the state / settings of the given QPainter object by calling save. Then we set the color to white and use drawText to draw our message. Finally we call restore which resets the QPainter settings back to how it was when paintInterface was called.
Packaging, installing & running
Plasma applets can be packaged in zip files and installed using the plasmapkg command line tool. The directory structure which we have used for our project matches that need in the zip file. All we have to do is zip it update. Run the following command from inside the hello-ruby directory.
zip -r ../hello-ruby.zip .
This will create the hello-ruby.zip file in the directory just above the hello-ruby directory. Go to this directory in the shell and run this plasmapkg command to install our little hello-ruby applet.
plasmapkg -i hello-ruby.zip
This installs the applet into your home directory. Now we can run it. When developing applets it is more convenient to use the plasmoidviewer. This is a little utility which displays an applet in a window instead of you having to use your desktop. This command below will run our applet.
plasmoidviewer hello-ruby
You should now be able to see the fruits of your labor.
To uninstall our applet we use plasmapkg again with its -r option.
plasmapkg -r hello-ruby
Conclusion
This tutorial covers very basics of developing Plasma applets using Ruby. Most of the material discussed here is boring but important "boilerplate" stuff which stays mostly the same between every applet project. In future tutorials we can move on to move exciting things than just displaying a single line of static text.
In the next tutorial we explain how to use Plasma's specialized widgets in your applet instead of manually implementing the paintInterface method. Find out how in the Using widgets tutorial.
Troubleshooting
If you have this error message instead of plasmoid:
This object could not be created for the following reason: Could not create a ruby-script ScriptEngine for the Hello Ruby widget.
Then make sure that all "ruby kde" depdendencies are installed. In ubuntu for example you should have the next package:
korundum4
For additional help see here