Development/Tutorials/Plasma4/RubyApplet

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 implement our own 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
     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

Installing 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.