Difference between revisions of "Development/Tutorials/Plasma/RubyApplet"

Jump to: navigation, search
(New page: This tutorial shows how to create your own Plasmoids using the Ruby scripting language. ==The desktop file== The desktop file is the entry-point to our applet. It does define what the ap...)
 
 
(10 intermediate revisions by 5 users not shown)
Line 1: Line 1:
This tutorial shows how to create your own Plasmoids using the Ruby scripting language.
+
 
 +
 
 +
Warning: This tutorial is outdated. It doesn't work on KDE 4.2. This article is being kept for future translation to the current way of developing a Ruby Plasma applet. If you're looking for a tutorial on how to write a Plasma applet in Ruby on KDE 4.2 and later, have a look at the [[Development/Tutorials/Plasma/Ruby/GettingStarted|Getting Started]] tutorial.
 +
 
 +
==Abstract==
 +
 
 +
This tutorial shows how to create your own Plasma Widget/Applet/Plasmoid using the Ruby scripting language.  
 +
 
 +
See also:
 +
* [http://www.kdedevelopers.org/node/3560 Writing Plasma Applets in C# and Ruby]
 +
* [http://websvn.kde.org/trunk/KDE/kdebindings/ruby/plasma/examples/ Ruby and Plasma examples]
 +
* [[Development/Tutorials/Qt4_Ruby_Tutorial|Qt4 Ruby Tutorial]]
 +
* [[Development/Tutorials/Plasma|Plasma Tutorials]]
  
 
==The desktop file==
 
==The desktop file==
Line 5: Line 17:
 
The desktop file is the entry-point to our applet. It does define what the applet is for and how it should be loaded and handled by plasma.
 
The desktop file is the entry-point to our applet. It does define what the applet is for and how it should be loaded and handled by plasma.
  
[[http://websvn.kde.org/trunk/KDE/kdebindings/ruby/plasma/examples/applets/webapplet/plasma-ruby-applet-web.desktop?view=markup plasma-ruby-applet-web.desktop]]
+
For our webbrowser applet we use the [http://websvn.kde.org/trunk/KDE/kdebindings/ruby/plasma/examples/applets/webapplet/plasma-ruby-applet-web.desktop?view=markup plasma-ruby-applet-web.desktop] desktop file which looks like;
  
<code>
+
<syntaxhighlight lang="ini">
 
[Desktop Entry]
 
[Desktop Entry]
 
Name=Ruby Web Browser
 
Name=Ruby Web Browser
Line 19: Line 31:
 
X-KDE-PluginInfo-Name=plasma-ruby-web-applet
 
X-KDE-PluginInfo-Name=plasma-ruby-web-applet
  
X-KDE-PluginInfo-Version=pre0.1
+
X-KDE-PluginInfo-Version=0.1
 
X-KDE-PluginInfo-Category=Web
 
X-KDE-PluginInfo-Category=Web
 
X-KDE-PluginInfo-Depends=QtRuby
 
X-KDE-PluginInfo-Depends=QtRuby
 
X-KDE-PluginInfo-License=GPL
 
X-KDE-PluginInfo-License=GPL
 
X-KDE-PluginInfo-EnabledByDefault=true
 
X-KDE-PluginInfo-EnabledByDefault=true
</code>
+
</syntaxhighlight>
  
 
The important parts within those desktop service file are the referenced X-KDE-Library which will be loaded on request and is responsible for executing our with X-KDE-PluginKeyword defined Ruby scrip file. Our applet will be known by Plasma under the unique name "plasma-ruby-web-applet".
 
The important parts within those desktop service file are the referenced X-KDE-Library which will be loaded on request and is responsible for executing our with X-KDE-PluginKeyword defined Ruby scrip file. Our applet will be known by Plasma under the unique name "plasma-ruby-web-applet".
Line 30: Line 42:
 
==The Ruby Script==
 
==The Ruby Script==
  
It follows the Ruby scripting code which does implement the whole functionality to display a webbrowser within the applet and to allow to browse around.
+
It follows the Ruby scripting code which does implement the whole functionality to display a webbrowser within the applet and to browse around those content.
  
[[http://websvn.kde.org/trunk/KDE/kdebindings/ruby/plasma/examples/applets/webapplet/web_applet.rb?view=markup web_applet.rb]]
+
The [http://websvn.kde.org/trunk/KDE/kdebindings/ruby/plasma/examples/applets/webapplet/web_applet.rb?view=markup web_applet.rb] ruby script looks like;
  
<code ruby>
+
<syntaxhighlight lang="ruby">
# import the plasma-applet functionality which we need to implement our own applet.
+
# import the plasma-applet functionality which we need to
 +
# implement our own webbrowser applet.
 
require 'plasma_applet'
 
require 'plasma_applet'
  
# we define an own module
+
# We define an own module
 
module PlasmaRubyWebApplet
 
module PlasmaRubyWebApplet
  
   # the WebApplet class does implement the Plasma::Applet
+
   # The WebApplet class does implement a Plasma::Applet.
 
   class WebApplet < Plasma::Applet
 
   class WebApplet < Plasma::Applet
  
     # slots used by our applet.
+
     # The both slots used by our applet.
     slots 'dataUpdated(QString,Plasma::DataEngine::Data)',
+
     slots 'load(QUrl)',
          'load(QUrl)',
+
 
           'loadFinished(bool)'
 
           'loadFinished(bool)'
  
     # constructor.
+
     # Constructor for our WebApplet class.
 
     def initialize(parent, args)
 
     def initialize(parent, args)
 
       super
 
       super
 
     end
 
     end
  
     # on initialization this method will be called.
+
     # On initialization this method will be called by plasma. Here we
 +
    # are able to do expensive initialization work to show something
 +
    # within our applet.
 
     def init
 
     def init
 +
      # Let's start with a nice default size.
 
       resize(600, 400)
 
       resize(600, 400)
  
 +
      # Create the Browser widget which will display the content
 +
      # of webpages.
 
       @page = Plasma::WebContent.new(self)
 
       @page = Plasma::WebContent.new(self)
 
       @page.page = Qt::WebPage.new(@page)
 
       @page.page = Qt::WebPage.new(@page)
 
       @page.page.linkDelegationPolicy = Qt::WebPage::DelegateAllLinks
 
       @page.page.linkDelegationPolicy = Qt::WebPage::DelegateAllLinks
       @page.page.settings.setAttribute(Qt::WebSettings::LinksIncludedInFocusChain, true)
+
       @page.page.settings.setAttribute(
 +
        Qt::WebSettings::LinksIncludedInFocusChain, true)
  
       connect(@page, SIGNAL('loadFinished(bool)'), self, SLOT('loadFinished(bool)'))
+
      # Connect signals the webbrowser provides with own functions.
       connect(@page.page, SIGNAL('linkClicked(QUrl)'), self, SLOT('load(QUrl)'))
+
       connect(@page, SIGNAL('loadFinished(bool)'),
 
+
              self, SLOT('loadFinished(bool)'))
      @page.mainFrame.setScrollBarPolicy(Qt::Horizontal, Qt::ScrollBarAlwaysOff)
+
       connect(@page.page, SIGNAL('linkClicked(QUrl)'),
      @page.mainFrame.setScrollBarPolicy(Qt::Vertical, Qt::ScrollBarAlwaysOff)
+
              self, SLOT('load(QUrl)'))
  
 +
      # Start browsing some webpage
 
       @page.url = Qt::Url.new("http://dot.kde.org/")
 
       @page.url = Qt::Url.new("http://dot.kde.org/")
 
     end
 
     end
  
     # this method will be called if something should be drawn. our applet doesn't do
+
     # This method will be called once the user clicks on a link.
    # there anything since we don't draw anything by our own here.
+
    # We just load the defined URL-address and let the
    def paintInterface(p, option, rect)
+
     # webbrowser-page display the content.
    end
+
 
+
    # this method will be called once the user clicks on a link. we just load the
+
     # defined url and display it.
+
 
     def load(url)
 
     def load(url)
 
       puts "Loading #{url.toString}"
 
       puts "Loading #{url.toString}"
Line 84: Line 99:
 
     end
 
     end
  
     # this method will be called once loading a page finished.
+
     # This method will be called once loading a page finished.
 
     def loadFinished(success)
 
     def loadFinished(success)
 
       puts "page loaded #{@page.page.currentFrame.url.toString}"
 
       puts "page loaded #{@page.page.currentFrame.url.toString}"
 
     end
 
     end
  
     # this method will be called each time a constraint changed. the for us most
+
     # This method will be called each time a constraint changed. the
     # interesting constraints are;
+
     # for us most interesting constraints are;
 
     # * LocationConstraint if the location of the applet changed
 
     # * LocationConstraint if the location of the applet changed
     # * ScreenConstraint if the screen on which the applet is located on changed
+
     # * ScreenConstraint if the screen on which the applet is located
 +
    #  on changed
 
     # * SizeConstraint if the size of the applet changed
 
     # * SizeConstraint if the size of the applet changed
 
     # * ImmutableConstraint if the applet got locked/unlocked
 
     # * ImmutableConstraint if the applet got locked/unlocked
 
     def constraintsEvent(constraints)
 
     def constraintsEvent(constraints)
 
       if constraints.to_i & Plasma::SizeConstraint.to_i
 
       if constraints.to_i & Plasma::SizeConstraint.to_i
 +
        # if the size of the Applet changed, then resize also the
 +
        # webbrowser.
 
         @page.resize(size())
 
         @page.resize(size())
 
       end
 
       end
Line 103: Line 121:
 
   end
 
   end
 
end
 
end
</code>
+
</syntaxhighlight>
  
==Installing the applet==
+
That was already all the code needed to implement our own webbrowser Applet using the Ruby language. The in this sample used [http://doc.trolltech.com/4.4/qtwebkit.html webbrowser] does provide additional functionality to use optional a full powered webbrowser or adopt it to your needings.
  
To install the applet the [[http://websvn.kde.org/trunk/KDE/kdebindings/ruby/plasma/examples/applets/webapplet/CMakeLists.txt?view=markup CMakeLists.txt]] is used. It basicly does copy the both files above to the right locations
+
==Install and test the Applet==
  
<code>
+
To install the Applet the [http://websvn.kde.org/trunk/KDE/kdebindings/ruby/plasma/examples/applets/webapplet/CMakeLists.txt?view=markup CMakeLists.txt] is used. It basically does copy the both files above to the right locations. Translated to command-line arguments it would look like;
cp plasma-ruby-applet-web.desktop `kde4-config --install services`
+
cp web_applet.rb `kde4-config --install data`/plasma_ruby_web_applet/
+
</code>
+
  
what installs the both files for all users. If you like to have them accessible only from within one user, then just copy those both files to your $KDEHOME where the command "kde4-config --localprefix" should provide you a hint where that may be :)
+
<syntaxhighlight lang="bash">
 +
sudo cp plasma-ruby-applet-web.desktop `kde4-config --install services`
 +
sudo mkdir `kde4-config --install data`/plasma_ruby_web_applet/
 +
sudo cp web_applet.rb `kde4-config --install data`/plasma_ruby_web_applet/
 +
</syntaxhighlight>
  
To take a look at your applet or test it during the developing, you can fire up;
+
what installs the both files to the global installation directory to make hem available for all users on your sysem. If you like to have them accessible only from within one user, then just copy those both files to the users $KDEHOME (the command "kde4-config --localprefix" should provide you a hint where that may be).
  
<code>
+
To take a look at your applet or test it during development, you can;
 +
 
 +
<syntaxhighlight lang="bash">
 
kbuildsycoca4
 
kbuildsycoca4
 
plasmoidviewer plasma-ruby-web-applet
 
plasmoidviewer plasma-ruby-web-applet
</code>
+
</syntaxhighlight>
 +
 
 +
where the kbuildsycoca4 does rebuild the desktop-cache to update changes done to the desktop file. The plasmoidviewer is a tool that allows you to start and view your applet outside of plasma.
 +
[[Media:Example.ogg]]
  
where the kbuildsycoca4 does rebuild the desktop-cache to update changes done at the desktop file. The plasmoidviewer is a tool that allows you to start and view your applet outside of plasma.
+
[[Category:Ruby]]

Latest revision as of 16:32, 15 July 2012


Warning: This tutorial is outdated. It doesn't work on KDE 4.2. This article is being kept for future translation to the current way of developing a Ruby Plasma applet. If you're looking for a tutorial on how to write a Plasma applet in Ruby on KDE 4.2 and later, have a look at the Getting Started tutorial.

Contents

[edit] Abstract

This tutorial shows how to create your own Plasma Widget/Applet/Plasmoid using the Ruby scripting language.

See also:

[edit] The desktop file

The desktop file is the entry-point to our applet. It does define what the applet is for and how it should be loaded and handled by plasma.

For our webbrowser applet we use the plasma-ruby-applet-web.desktop desktop file which looks like;

[Desktop Entry]
Name=Ruby Web Browser
Icon=internet-web-browser
 
Type=Service
ServiceTypes=Plasma/Applet
 
X-KDE-Library=krubypluginfactory
X-KDE-PluginKeyword=plasma_ruby_web_applet/web_applet.rb
X-KDE-PluginInfo-Name=plasma-ruby-web-applet
 
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-Category=Web
X-KDE-PluginInfo-Depends=QtRuby
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true

The important parts within those desktop service file are the referenced X-KDE-Library which will be loaded on request and is responsible for executing our with X-KDE-PluginKeyword defined Ruby scrip file. Our applet will be known by Plasma under the unique name "plasma-ruby-web-applet".

[edit] The Ruby Script

It follows the Ruby scripting code which does implement the whole functionality to display a webbrowser within the applet and to browse around those content.

The web_applet.rb ruby script looks like;

# import the plasma-applet functionality which we need to
# implement our own webbrowser applet.
require 'plasma_applet'
 
# We define an own module
module PlasmaRubyWebApplet
 
  # The WebApplet class does implement a Plasma::Applet.
  class WebApplet < Plasma::Applet
 
    # The both slots used by our applet.
    slots 'load(QUrl)',
          'loadFinished(bool)'
 
    # Constructor for our WebApplet class.
    def initialize(parent, args)
      super
    end
 
    # On initialization this method will be called by plasma. Here we
    # are able to do expensive initialization work to show something
    # within our applet.
    def init
      # Let's start with a nice default size.
      resize(600, 400)
 
      # Create the Browser widget which will display the content
      # of webpages.
      @page = Plasma::WebContent.new(self)
      @page.page = Qt::WebPage.new(@page)
      @page.page.linkDelegationPolicy = Qt::WebPage::DelegateAllLinks
      @page.page.settings.setAttribute(
        Qt::WebSettings::LinksIncludedInFocusChain, true)
 
      # Connect signals the webbrowser provides with own functions.
      connect(@page, SIGNAL('loadFinished(bool)'),
              self, SLOT('loadFinished(bool)'))
      connect(@page.page, SIGNAL('linkClicked(QUrl)'),
              self, SLOT('load(QUrl)'))
 
      # Start browsing some webpage
      @page.url = Qt::Url.new("http://dot.kde.org/")
    end
 
    # This method will be called once the user clicks on a link.
    # We just load the defined URL-address and let the
    # webbrowser-page display the content.
    def load(url)
      puts "Loading #{url.toString}"
      @page.url = url
    end
 
    # This method will be called once loading a page finished.
    def loadFinished(success)
      puts "page loaded #{@page.page.currentFrame.url.toString}"
    end
 
    # This method will be called each time a constraint changed. the
    # for us most interesting constraints are;
    # * LocationConstraint if the location of the applet changed
    # * ScreenConstraint if the screen on which the applet is located
    #   on changed
    # * SizeConstraint if the size of the applet changed
    # * ImmutableConstraint if the applet got locked/unlocked
    def constraintsEvent(constraints)
      if constraints.to_i & Plasma::SizeConstraint.to_i
        # if the size of the Applet changed, then resize also the
        # webbrowser.
        @page.resize(size())
      end
    end
 
  end
end

That was already all the code needed to implement our own webbrowser Applet using the Ruby language. The in this sample used webbrowser does provide additional functionality to use optional a full powered webbrowser or adopt it to your needings.

[edit] Install and test the Applet

To install the Applet the CMakeLists.txt is used. It basically does copy the both files above to the right locations. Translated to command-line arguments it would look like;

sudo cp plasma-ruby-applet-web.desktop `kde4-config --install services`
sudo mkdir `kde4-config --install data`/plasma_ruby_web_applet/
sudo cp web_applet.rb `kde4-config --install data`/plasma_ruby_web_applet/

what installs the both files to the global installation directory to make hem available for all users on your sysem. If you like to have them accessible only from within one user, then just copy those both files to the users $KDEHOME (the command "kde4-config --localprefix" should provide you a hint where that may be).

To take a look at your applet or test it during development, you can;

kbuildsycoca4
plasmoidviewer plasma-ruby-web-applet

where the kbuildsycoca4 does rebuild the desktop-cache to update changes done to the desktop file. The plasmoidviewer is a tool that allows you to start and view your applet outside of plasma. Media:Example.ogg


This page was last modified on 15 July 2012, at 16:32. This page has been accessed 14,506 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