unexist.dev

h1. Sublets\015\012\015\012[[Sublets]] are small "Ruby":http://www.ruby-lang.org scripts that provide data 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*. Additionally "sur":http://unexist.scrapping.cc/projects/sur/wiki can manage installed [[sublets]] in a "rubygems":http://www.rubygems like fashion. A complete list of the [[sublets]] that are available in "sur":http://unexist.scrapping.cc/projects/sur/wiki can be found "here":http://sur.scrapping.cc.\015\012\015\012Writing a [[sublets|sublet]] from scratch is really easy, just create an empty [[sublets|sublet]] with "sur":http://unexist.scrapping.cc/projects/sur/wiki 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":http://unexist.scrapping.cc/rdoc/subtle/index.html and informations about the available unit tests in the [[development]] section.\015\012\015\012h2. Types\015\012\015\012Generally there are two 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":http://en.wikipedia.org/wiki/Inotify) or via socket\015\012\015\012The [[sublet]] data must be of type "String":http://www.ruby-doc.org/core/classes/String.html, everything else will be ignored.\015\012\015\012h2. Hooks\015\012\015\012There are two methods that will be called from [[subtle]] on certain conditions:\015\012\015\012* *click()*: Whenever a mouse button is pressed on a [[sublet|sublets]]. Can have three arguments: button, x, y\015\012* *run()*: Whenever either the interval time is expired or the watched file is modified\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 s.red = Subtle::Color.new("#ff0000")\015\012 s.green = Subtle::Color.new("#00ff00")\015\012 s.blue = Subtle::Color.new("#0000ff")\015\012 s.background = "#303030"\015\012end\015\012\015\012on :run do\015\012 s.data = s.red + "su" + s.green + "bt" + s.blue + "le"\015\012end</code></pre>\015\012\015\012There is also a way to add a "X bitmap":http://en.wikipedia.org/wiki/XBM to a [[Sublets|sublet]]:\015\012\015\012<pre><code class="ruby">configure :iconized do |s|\015\012 s.icon = Subtle::Icon.new("/usr/share/icons/subtle.xbm")\015\012end\015\012\015\012on :run do |s|\015\012 s.data = @icon + "subtle"\015\012end</code></pre>\015\012\015\012A nice collection of this pixmap can be found "here":http://dzen.geekmode.org/dwiki/doku.php?id=dzen:icon-packs.\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 s.data = Time.now.strftime("%d%m%y%H%M") #< Set data\015\012end</code></pre>\015\012\015\012Another example for the "inotify":http://en.wikipedia.org/wiki/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 s.watch(s.file)\015\012end\015\012\015\012on :run do\015\012 begin\015\012 self.data = IO.readlines(@file).first.chop #< Read data and strip\015\012 rescue => err #< Catch error\015\012 puts err\015\012 self.data = "subtle"\015\012 end\015\012end</code></pre>\015\012\015\012The *watch* command also works with "Ruby":http://www.ruby-lang.org sockets, but be aware of blocking I/O:\015\012\015\012<pre><code class="ruby">configure :socket do |s|\015\012 s.socket = TCPSocket.open("localhost", TCPSocket("localhost", 6600)\015\012 s.watch(s.socket)\015\012end\015\012\015\012on :run do |s|\015\012 begin\015\012 s.data = s.socket.readline.chop #< Read data and strip\015\012 rescue => err #< Catch error\015\012 puts err\015\012 s.data = "subtle"\015\012 end\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 :click do |s, x, y, button|\015\012 find_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)}}