Sublets » History » Version 44

Anonymous, 05/24/2010 12:01 AM

1 44
h1. Sublets\015\012\015\012{{>toc}}\015\012\015\012[[Sublets]] are small "Ruby": scripts written in a small "DSL": that can provide things like system information for the [[panel]]. They are well included in the main loop of [[subtle]] and are *limited* to 1s of execution time for safety reasons. \015\012\015\012h2. Installing a sublet\015\012\015\012The available [[sublets]] officially supported can be found "here": and need to be installed in @$XDG_DATA_HOME/subtle/sublets@. [[subtle]] will load any [[sublet]] from there in order of the files.\015\012\015\012To ease managing [[sublets]] there is "sur":, a script that works in a "rubygems":http://www.rubygems like fashion.\015\012\015\012h2. Writing a sublet\015\012\015\012Starting a [[sublets|sublet]] from scratch is really easy, just create an empty [[sublets|sublet]] either with "sur": like @sur template foo@ or with any editor of your choice. A [[sublet]] has some base functions and can access [[subtle]] itself via [[subtlext]]. A compending list of the classes with it's functionality can be found in "rdoc": and informations about the available unit tests in the [[hacking]] section.\015\012\015\012h3. Types\015\012\015\012Generally there are two different types of [[Sublets|sublets]]:\015\012\015\012* [[sublets]] that are updated by given interval in seconds (default 60s)\015\012* [[sublets]] that are updated when a file is modified (via "inotify": or via socket\015\012\015\012The [[sublet]] data *must* be of type "String":, everything else will be ignored.\015\012\015\012h3. Events\015\012\015\012[[Sublets]] are event driven, so there are some specific events only for [[sublets]] and it's also possible to use any existing [[Hooks|hook]].\015\012\015\012*Specific events:*\015\012\015\012| *&#58;mouse_over* | Whenever the pointer is over the [[sublet]] |\015\012| *&#58;mouse_down* | Whenever the pointer is pressed on the [[sublet]]. Can have three arguments: x, y, button. |\015\012| *&#58;mouse_out*  | Whenever the pointer leaves the [[sublet]] |\015\012| *&#58;run*        | Whenever either the interval time is expired |\015\012| *&#58;unload*     | Whenever the sublet will be unloaded |\015\012| *&#58;watch*      | Whenever the watched file is modified/socket has data ready |\015\012\015\012h3. Customization\015\012\015\012The color of the ouput of a [[sublet|Sublets]] can be changed in this way:\015\012\015\012<pre><code class="ruby">configure :colorful do |s|\015\012        ="#ff0000")\015\012      ="#00ff00")\015\012       ="#0000ff")\015\012  s.background = "#303030"\015\012end\015\012\015\012on :run do\015\012 = + "su" + + "bt" + + "le"\015\012end</code></pre>\015\012\015\012There is also a way to add a "X bitmap": to a [[Sublets|sublet]]:\015\012\015\012<pre><code class="ruby">configure :iconized do |s|\015\012  s.icon ="/usr/share/icons/subtle.xbm")\015\012end\015\012\015\012on :run do |s|\015\012 = @icon + "subtle"\015\012end</code></pre>\015\012\015\012A nice collection of this pixmap can be found "here":\015\012\015\012_[[Subtle]] will add a padding of 3px left and right of the pixmap, so keep that in mind when using the click hooks._\015\012\015\012h3. Examples\015\012\015\012Below is the code of a shipped [[sublet|sublets]] that displays the time. It should be really straight forward:\015\012\015\012<pre><code class="ruby">configure :clock do |s|\015\012  s.interval = 60 #< Set interval time\015\012end\015\012\015\012on :run do |s|\015\012 ="%d%m%y%H%M") #< Set data\015\012end</code></pre>\015\012\015\012Another example for the "inotify": [[sublets|sublet]] which is also included within [[subtle]]:\015\012\015\012<pre><code class="ruby">configure :notify do |s|\015\012  s.file = "/tmp/watch"\015\012\015\012end\015\012\015\012on :run do\015\012  begin\015\012 = IO.readlines(@file).first.chop #< Read data and strip\015\012  rescue => err #< Catch error\015\012    puts err\015\012 = "subtle"\015\012  end\015\012end</code></pre>\015\012\015\012The *watch* command also works with "Ruby": sockets, but be aware of blocking I/O:\015\012\015\012<pre><code class="ruby">configure :socket do |s|\015\012  s.socket ="localhost", 6600)\015\012\015\012end\015\012\015\012on :watch do |s|\015\012  begin\015\012 = s.socket.readline.chop #< Read data and strip\015\012  rescue => err #< Catch error\015\012    puts err\015\012 = "subtle"\015\012  end\015\012end\015\012\015\012on :run do |s|\015\012  #  Do nothing\015\012end</code></pre>\015\012\015\012_[[Subtle]] will automatically set sockets to O_NONBLOCK._\015\012\015\012And finally an example with a click callback:\015\012\015\012<pre><code class="ruby">configure :click do |s|\015\012  s.interval = 999 #< Do nothing\015\012end\015\012\015\012on :mouse_down do |s, x, y, button|\015\012  Subtlext::Client["xterm"].raise\015\012  puts x, y, button\015\012end\015\012\015\012on :run do |s|\015\012  # Do nothing here\015\012end</code></pre>