Development/Tutorials/Plasma4/Ruby/SimplePasteApplet: Difference between revisions

    From KDE TechBase
    m (URL update)
    (First step by step API example, have yet to find out how to use other properties as 'text' (from add text property to button) is to generic.)
    Line 220: Line 220:
    </code>
    </code>


    == Where to go from here ==
    == Reading API reference documentation ==


    Now that you have this simple but working Ruby Plasma applet, you can expand it. You can start by trying out some of the other Plasma widgets available. The official [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/hierarchy.html Plasma API] is unfortunately written for C++. But with a little imagination and some logic you should be able to make use of it.
    Now that you have this simple but working Ruby Plasma applet, you can expand it. You can start by trying out some of the other Plasma widgets available. The official [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/hierarchy.html Plasma API] is unfortunately written for C++. But with a little imagination and some logic you should be able to make use of it.


    You could also try looking at some [http://websvn.kde.org/trunk/KDE/kdeexamples/plasma/ruby/ Ruby Plasma examples]. These are written a bit different then the example described above, but they should still be useful.
    Still reading this tutorial? Let's take it step by step then.
     
    Look through the Plasma API hierachy and find the LineEdit class. At the top of its own page is a listing of the available Signals. Duplicate the code for the button signal in your text editor and reuse that code to make your line edit variable also paste the typed content to the clipboard when the return key on the keyboard is being pressed. Save and run your code (in KDE 4.2 you must not forget to update manualy, in KDE 4.3 you can run 'Plasmoidviewer' when Konsole is pointing to the the folder / directory of your Applet). My clipboard missed a few pastes but both the button and pressing return worked. Look a bit lower on the Class page for LineEdit: the C++ code to signal an action looks different then the Ruby signal you copied and the Ruby signal you composed yourself, but it does list in which KDE version the signal has become available.
     
    Now you know how to let your Plasma Applet react to any signal and you know how to find all available signals in Plasma.
     
    == Where to go from here ==
     
    Now you could also try looking at some [http://websvn.kde.org/trunk/KDE/kdeexamples/plasma/ruby/ Ruby Plasma examples]. These are written a bit different then the example described above, but they should still be useful.


    If you have any questions about Plasma development there are several ways to ask for help. First of all there is the [https://mail.kde.org/mailman/listinfo/plasma-devel Plasma  mailinglist]. Secondly you can hop by on IRC, #plasma on irc.freenode.org. As a third option you could try asking you question on the [http://forum.kde.org/ KDE forums].
    If you have any questions about Plasma development there are several ways to ask for help. First of all there is the [https://mail.kde.org/mailman/listinfo/plasma-devel Plasma  mailinglist]. Secondly you can hop by on IRC, #plasma on irc.freenode.org. As a third option you could try asking you question on the [http://forum.kde.org/ KDE forums].


    Good luck, and don't forget to publish your Plasma applet on kde-look.org!
    Good luck, and don't forget to publish your Plasma applet on kde-look.org!

    Revision as of 18:31, 19 October 2009

    Abstract

    This tutorial will explain how to make simple KDE Plasma applet using Ruby. The applet will be a simple version of the paste applet. It will allow the user to put a bit of text on the clipboard.

    Getting started

    Before you get started you need to make sure to have the following installed on your computer.

    • KDE 4.2 or later
    • Ruby 1.8
    • KDE Ruby bindings and Plasma scriptengine

    These packages can usually be installed through your distributions package manager.

    Package layout

    Plasma applets written in Ruby can be distributed as a plasmoid package. A minimal Ruby plasmoid package has the following structure:

    • contents/
      • code/
        • main.rb
    • metadata.desktop

    The Ruby code for the plasmoid should be put in a file called main.rb in the contents/code folder of your package. The metadata.desktop file holds metadata about your plasmoid. This includes your name, name of your applet and a description. The metadata.desktop file is in the common .desktop file format, which looks a lot like an old INI file.

    A minimal metadata.desktop file looks like this:

    [Desktop Entry] Name=Simple Ruby applet Comment=This is a simple applet written in Ruby Icon=chronometer Type=Service ServiceTypes=Plasma/Applet

    X-Plasma-API=ruby-script X-Plasma-MainScript=code/main.rb

    X-KDE-PluginInfo-Author=Me [email protected] X-KDE-PluginInfo-Name=ruby-test X-KDE-PluginInfo-Version=0.1 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

    Code

    Let's first start with the most basic Ruby applet and work from there. Every Plasma applet you're going to make in Ruby has to have a class which inherits the PlasmaScripting::Applet class. You can think of this as your main class for your applet. It will always have at least two methods, initialize and init. While these two seem very similar, there is an important difference. The initialize method is Ruby's default constructor. It will be called by the Ruby interpreter when an object of your class gets initialized (a.k.a. constructed). The init method gets called by Plasma. Plasma calls this method after the applet has been loaded. You can therefore assume that everything is set up when init is called, while with initialize, you only know your applet class is ready.

    Start your code file with requiring 'plasma_applet' and opening a module. A minimal Ruby Plasma applet looks like this:

    require 'plasma_applet'

    module RubyTest

     class Main < PlasmaScripting::Applet
       def initialize parent
         super parent
       end
    
       def init
         set_minimum_size 150, 150
       end
     end
    

    end

    The module name must match the name you specify in metadata.desktop on the X-KDE-PluginInfo-Name line. The name ruby-test translates to a module name of RubyTest.

    The only line in the init method now is set_minimum_size. This, as the name suggests, sets the minimum size for the applet.

    To run your applet, you have two options. You can install it first, and then run it. Or, if you're running KDE 4.3 or later, just run it.

    Installing your appliet

    This is where plasmapkg comes in. It's a small tool which installs and upgrades Plasma packages. To put your code in a package, create a package structure as described in the above section. Outside the package folder run plasmapkg -i <package folder name>, plasmapkg will now install your applet.

    mkdir ruby-test-applet cd ruby-test-applet

    1. Copy or create metadata.desktop

    mkdir contents cd contents mkdir code cd code

    1. Copy or create main.rb

    cd ../../.. plasmapkg -i ruby-test-applet

    plasmapkg can install and upgrade Plasma packages. Since you've now installed your applet, you need to upgrade it after making changes. This isn't much different then installing, just use the -u commandline switch instead of -i.

    Running your applet

    You can run your applet using a tool called plasmoidviewer.

    KDE 4.2

    In KDE 4.2 plasmoidviewer takes the name of an installed applet as a parameter. The name of your applet is specified with the X-KDE-PluginInfo-Name line in your metadata.desktop file. You should be able to view your applet after installing it.

    plasmoidviewer ruby-test

    KDE 4.3

    In KDE 4.3 plasmoidviewer still accepts the name of an installed applet as a parameter. But it can also run without a parameter. It will then try to run a plasmoid from the current directory. In order for this to work, the current directory should have the metadata.desktop file, the contents folder and the name of the directory should exactly match the name of the applet as specified in metadata.desktop.

    plasmoidviewer

    A label on an applet

    When you have a very basic applet running, you can go two ways. You can put QWidgets on your applet, or draw the applet yourself by implementing the paintInterface method. I like to use standard widgets most of the time, so we're going to place some QWidgets on the plasma applet.

    Plasma has a couple of themed widgets. A list can be found in the Plasma API. To place these widgets on your applet, you need a layout. The layout you'll be using most of the time will be the GraphicsLinearLayout, which basically puts your widgets in a horizontal or vertical line.

    When putting a Plasma::Label on an applet in a GraphicsLinearLayout, you'll get the following code:

    require 'plasma_applet'

    module RubyTest

     class Main < PlasmaScripting::Applet
       def initialize parent
         super parent
       end
    
       def init
         set_minimum_size 150, 150
    
         label = Plasma::Label.new self
         label.text = 'This is a label on a plasmoid, hello Plasma!'
    
         layout = Qt::GraphicsLinearLayout.new self
         self.layout = layout
         layout.add_item label
       end
     end
    

    end

    In the init method we create a Plasma::Label and assign it a text. The first argument to the constructor of Plasma::Label (the new) is the parent of the label, in this case our applet. Next we create a GraphicsLinearLayout, assign it to the applet and put our label on it.

    Tip
    In Ruby, instance variables always begin with an '@' character. All variables without an '@' are local variables. Variables with two @ signs are class (a.k.a. static) variables.


    Tip
    The Ruby keyword self is a reference to the current instance of the class you're in. You can compare it with the this keyword in other languages like C++ and Java.


    To view your applet, run plasmapkg -u <folder name> and plasmoidviewer <plasmoid name>.

    plasmapkg -u ruby-test-applet plasmoidviewer ruby-test

    This will show you a nice and simple Hello World in Plasma.

    A line edit and a button

    Let's continue by adding a line edit and a button with some functionality.

    To add a line edit widget we can use the Plasma::LineEdit class. This class is a basic KLineEdit (a text field with one line) themed for Plasma. To add it to our applet, we do the same as with the label. But since we want the line edit to be empty, we don't set a text.

    Next is a push button. We can use the Plasma::PushButton class for that. Adding it is exactly the same as adding the label.

    With a line edit and button in place, we should let the button do something when it's clicked. Qt, the library on which KDE is based, uses a mechanism called 'signals and slots'. You could compare it to action or event handlers in other languages or frameworks. Normally, one would connect a certain signal (event) to a certain slot (event handler method). Since we're using Ruby, we can't only do that, we can connect a signal to a code block. The syntax for this is easy:

    button.connect(SIGNAL(:clicked)) do

     # do something
    

    end

    Now, when the button gets clicked, the code in the block gets executed.

    Tip
    The Ruby language has the concept of code blocks. These are anonymous functions which you can supply to a method. A code block gets executed when the receiving method calls it.


    We will do something simple when the button gets pressed. Qt makes it very easy to put some text on the clipboard, so let's do that. To put text on the clipboard we need Qt::Application.clipboard. This object has the very convenient method text= which puts text on the clipboard.

    Putting it all together, we have to following code:

    require 'plasma_applet'

    module RubyTest

     class Main < PlasmaScripting::Applet
       def initialize parent
         super parent
       end
    
       def init
         set_minimum_size 150, 150
    
         layout = Qt::GraphicsLinearLayout.new Qt::Vertical, self
         self.layout = layout
    
         label = Plasma::Label.new self
         label.text = 'This plasmoid will copy the text you enter below to the clipboard.'
         layout.add_item label
    
         line_edit = Plasma::LineEdit.new self
         layout.add_item line_edit
    
         button = Plasma::PushButton.new self
         button.text = 'Copy to clipboard'
         layout.add_item button
    
         button.connect(SIGNAL(:clicked)) do
           Qt::Application.clipboard.text = line_edit.text
         end
       end
    
     end
    

    end

    Reading API reference documentation

    Now that you have this simple but working Ruby Plasma applet, you can expand it. You can start by trying out some of the other Plasma widgets available. The official Plasma API is unfortunately written for C++. But with a little imagination and some logic you should be able to make use of it.

    Still reading this tutorial? Let's take it step by step then.

    Look through the Plasma API hierachy and find the LineEdit class. At the top of its own page is a listing of the available Signals. Duplicate the code for the button signal in your text editor and reuse that code to make your line edit variable also paste the typed content to the clipboard when the return key on the keyboard is being pressed. Save and run your code (in KDE 4.2 you must not forget to update manualy, in KDE 4.3 you can run 'Plasmoidviewer' when Konsole is pointing to the the folder / directory of your Applet). My clipboard missed a few pastes but both the button and pressing return worked. Look a bit lower on the Class page for LineEdit: the C++ code to signal an action looks different then the Ruby signal you copied and the Ruby signal you composed yourself, but it does list in which KDE version the signal has become available.

    Now you know how to let your Plasma Applet react to any signal and you know how to find all available signals in Plasma.

    Where to go from here

    Now you could also try looking at some Ruby Plasma examples. These are written a bit different then the example described above, but they should still be useful.

    If you have any questions about Plasma development there are several ways to ask for help. First of all there is the Plasma mailinglist. Secondly you can hop by on IRC, #plasma on irc.freenode.org. As a third option you could try asking you question on the KDE forums.

    Good luck, and don't forget to publish your Plasma applet on kde-look.org!