Development/Tutorials/Plasma4/RubyApplet

Abstract

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 applet is for and how it should be loaded and handled by plasma.

plasma-ruby-applet-web.desktop

[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=pre0.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".

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.

web_applet.rb

1. import the plasma-applet functionality which we need to
2. implement our own webbrowser applet.

require 'plasma_applet'

1. we define an own module

module PlasmaRubyWebApplet

 # the WebApplet class does implement the Plasma::Applet
 class WebApplet < Plasma::Applet

   # the both slots used by our applet.
   slots 'load(QUrl)',
         'loadFinished(bool)'

   # constructor.
   def initialize(parent, args)
     super
   end

   # on initialization this method will be called.
   def init
     # let's start with a nice default size.
     resize(600, 400)

     # create the Browser widget which will display the content.
     @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(@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 and display it.
   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
       @page.resize(size())
     end
   end

 end

end

Install and test the Applet

To install the applet the CMakeLists.txt is used. It basicly does copy the both files above to the right locations

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

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 :)

To take a look at your applet or test it during the developing, you can fire up;

kbuildsycoca4 plasmoidviewer plasma-ruby-web-applet

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.