Sublets » History » Version 42

Version 41 (Anonymous, 05/22/2010 02:24 AM) → Version 42/66 (Anonymous, 05/23/2010 11:21 PM)

h1. Sublets\015\012\015\012[[Sublets]] are small "Ruby": scripts written in a small "DSL": that 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\012Additionally there is "sur": for managing [[sublets]] in a "rubygems":http://www.rubygems like fashion. A complete list of the [[sublets]] that are available in "sur": can be found "here":\015\012\015\012Writing a [[sublets|sublet]] from scratch is really easy, just create an empty [[sublets|sublet]] with "sur": like this:\015\012\015\012bq. sur template foo\015\012\015\012A 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\012h2. Types\015\012\015\012Generally there are two different types of [[Sublets|sublets]]:\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\012h2. 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* _&#58;mouse_over_ | Whenever the pointer is over the [[sublet]] |\015\012| *&#58;mouse_down* _&#58;mouse_down_ | Whenever the pointer is pressed on the [[sublet]]. Can have three arguments: x, y, button. |\015\012| *&#58;mouse_out* _&#58;mouse_out_ | Whenever the pointer leaves the [[sublet]] |\015\012| *&#58;run* _&#58;run_ | Whenever either the interval time is expired |\015\012| *&#58;unload* _&#58;unload_ | Whenever the sublet will be unloaded |\015\012| *&#58;watch* _&#58;watch_ | Whenever the watched file is modified/socket has data ready |\015\012\015\012h2. 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\012h2. 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>\015\012{{tocnavi(subtle,Subtler,Quickstart,Grabs)}}