ruber 0.0.1.1

data/lib/ruber/gui_states_handler.rb

@@ -0,0 +1,231 @@
+=begin 
+    Copyright (C) 2010 by Stefano Crocco   
+    stefano.crocco@alice.it   
+  
+    This program is free software; you can redistribute it andor modify  
+    it under the terms of the GNU General Public License as published by  
+    the Free Software Foundation; either version 2 of the License, or     
+    (at your option) any later version.                                   
+  
+    This program is distributed in the hope that it will be useful,       
+    but WITHOUT ANY WARRANTY; without even the implied warranty of        
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         
+    GNU General Public License for more details.                          
+  
+    You should have received a copy of the GNU General Public License     
+    along with this program; if not, write to the                         
+    Free Software Foundation, Inc.,                                       
+    59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             
+=end
+
+require 'facets/boolean'
+
+module Ruber
+
+=begin rdoc
+Module which provides a mechanism to enable/disable actions basing on whether
+some 'states' are *true* or *false*. This functionality is similar to that provided
+by the KDE XML GUI framework, but much more flexible.
+
+A state is simply a string to which a *true* or *false* value is associated. For
+example, the value associated with a state called <tt>"current_document_modified"</tt> 
+should be set to *true* whenever the current document becomes modified and to
+*false* when it's saved. Through the rest of this documentation, the expression
+<i>the value of the state</i> will mean <i>the true or false value associated with
+the state</i>.
+  
+The system works this way: an action
+is registered using the <tt>register_action_handler</tt> method. To do
+so, a block (called a _handler_) and a list of states the action depends on are
+supplied.
+
+The value of a state is modified using the <tt>change_state</tt> method. That method
+will call the handlers of every action depending on the changed state, passing it
+a list of all known states, and enables or disable them according to the value
+returned by the block.
+
+Whenever this module is included in a class derived from <tt>Qt::Object</tt>, it
+will define a signal with the following signature <tt>ui_state_changed(QString, bool)</tt>,
+which will be emitted from the <tt>state_changed</tt> method. The signal won't be
+defined if the module _extends_ an object (even if it is <tt>Qt::Object</tt>).
+
+<b>Note:</b> before using any of the functionality provided by this module, you
+must call the <tt>initialize_states_handler</tt> method. This is usually done in
+the +initialize+ method of the including class.
+=end
+  module GuiStatesHandler
+    
+    Data = Struct.new :action, :handler, :extra_id #:nodoc:
+    
+=begin rdoc
+Override of +Module#included+ which is called whenever the module is included in
+another module or class.
+
+If _other_ is a class derived from <tt>Qt::Object</tt>, it defines the <tt>ui_state_changed(QString, bool)</tt>
+signal.
+=end
+    def self.included other
+      other.send :signals, 'ui_state_changed(QString, bool)' if other.ancestors.include?(Qt::Object)
+    end
+    
+=begin rdoc
+Makes an action known to the system, telling it on which states it depends and
+which handler should be used to decide whether the action should be enabled or
+not.
+
+_action_ is a <tt>Qt::Action</tt> or derived object. _states_ is an array of strings
+and/or symbols or a single string or symbol. Each string/symbol represents the
+name of a state _action_ depends on (that is, a state whose value concurs in
+deciding whether _action_ should be enabled or not).
+
+_blk_ is the handler associated with _action_. It takes a single argument, which
+will be a hash having the names of the states as keys and their values as values,
+and returns a true value if, basing on the values of the states, _action_ should
+be enabled and a false value if it shouldn't.
+
+_option_ contains some options. One is <tt>:check</tt>: if *true*, the handler
+will be called (and the action enabled or disabled) immediately after registering
+it; if it's false, nothing will be done until one of the states in _states_ 
+changes. The other option is <tt>:extra_id</tt>. If not *nil*, it is an extra value
+used to identify the action (see <tt>remove_action_handler_for</tt> for more information).
+
+If the block is not given and _states_ is a string, a symbol or an array with only
+one element, then a default handler is generated (if _states_ is an array with
+more than one element, +ArgumentError+ is raised). The default handler returns the
+same value as the state value. If the only state starts with a <tt>!</tt>, instead,
+the leading exclamation mark is removed from the name of the state and the generated
+handler returns the opposite of the state value (that is, returns *true* if the
+state is *false* and vice versa).
+
+<b>Note:</b> even if states can be specified as symbols, they're actually always
+converted to strings.
+
+====Examples
+
+In all the following examples, <tt>action_handler</tt> is an instance of a class
+which includes this module.
+
+This registers an handler for an action which depends on the two states 'a' and
+'b'. The action should be enabled when 'a' is *true* and 'b' is *false* or when
+'a' is *false*, regardless of 'b'.
+
+  action_handler.register_action_handler KDE::Action.new(nil), ['a', 'b'] do |states|
+    if states['a'] and !states['b'] then true
+    elsif !states['a'] then true
+    else false
+    end
+  end
+  
+This registers an action depending only on the state 'a' which should be enabled
+when 'a' is *true* and disabled when 'a' is *false*.
+
+  action_handler.register_action_handler KDE::Action.new(nil), ['a'] do |states|
+    states['a']
+  end
+
+Here we could also have passed simply the string 'a' as second argument. Even easier,
+we could have omitted the block, relying on the default handler that would have
+been generated:
+  action_handler.register_action_handler KDE::Action.new(nil), 'a'
+
+Here, still using the default handler, register an handler for an action which
+depends only on the state 'a' but needs to be enabled when 'a' is *false* and 
+disabled when it's *true*.
+  action_handler.register_action_handler KDE::Action.new(nil), '!a'
+=end
+    def register_action_handler action, states, options = {:check => true}, &blk
+      states = Array(states)
+      states = states.map &:to_s
+      if !blk and states.size > 1
+        raise ArgumentError, "If more than one state is supplied, a block is needed" 
+      elsif !blk
+        if states[0].start_with? '!'
+          states[0] = states[0][1..-1]
+          blk = Proc.new{|s| !s[states[0]]}
+        else blk = Proc.new{|s| s[states[0]]}
+        end
+      end
+      data = Data.new(action, blk, options[:extra_id])
+      states.each{|s| @gui_state_handler_handlers[s.to_s] << data}
+      if options[:check]
+        action.enabled = blk.call @gui_state_handler_states
+      end
+    end
+  
+=begin rdoc
+Remove the existing handlers for actions matching _action_ and <i>extra_id</i>.
+
+_action_ may be either a <tt>Qt::Action</tt> or a string. If it is a <tt>Qt::Action</tt>,
+then only the handlers for that object will be removed (actually, there usually
+is only one handler).
+    
+If _action_ is a string, all handlers for actions whose
+<tt>object_name</tt> is _action_ will be removed. In this case, the <i>extra_id</i>
+parameter can be used narrow the list of actions to remove (for example, if there
+are more than one action with the same name but different <tt>extra_id</tt>s). If
+<tt>extra_id</tt> isn't *nil*, then only actions whose <tt>object_name</tt> is
+_action_ and which were given an <tt>extra_id</tt> equal to <i>extra_id</i> will
+be removed.
+=end
+    def remove_action_handler_for action, extra_id = nil
+      if action.is_a? KDE::Action
+        @gui_state_handler_handlers.each_value do |v|
+          v.delete_if{|d| d.action.same? action}
+        end
+      elsif extra_id
+        @gui_state_handler_handlers.each_value do |v|
+          v.delete_if{|d| d.action.object_name == action and d.extra_id == extra_id}
+        end
+      else
+        @gui_state_handler_handlers.each_value do |v|
+          v.delete_if{|d| d.action.object_name == action}
+        end
+      end
+      @gui_state_handler_handlers.delete_if{|k, v| v.empty?}
+    end
+
+=begin rdoc
+Sets the value associated with the state _state_ to _value_, then calls the
+handlers of all actions depending on _state_ and enables or disables them according
+to the returned value. If *self* is an instance of <tt>Qt::Object</tt>, it also
+emits the <tt>ui_state_changed(QString, bool)</tt> signal, passing _state_ and 
+_value_ (converted to bool) as arguments.
+
+_state_ can be either a string or symbol (in this case, it'll be converted to string).
+_value_ can be any value. It will be converted to *true* or *false* according to
+the usual ruby rules before being used.
+=end
+    def change_state state, value
+      state = state.to_s
+      value = value.to_bool
+      @gui_state_handler_states[state] = value
+      @gui_state_handler_handlers[state].each do |d| 
+        d.action.enabled = d.handler.call @gui_state_handler_states
+      end
+      emit ui_state_changed state, value if self.is_a?(Qt::Object)
+    end
+    alias_method :set_state, :change_state
+    
+=begin rdoc
+Returns the value associated with the state _name_. If the value of the state
+has never been set using <tt>change_state</tt>, *nil* will be returned.
+=end
+    def state name
+      @gui_state_handler_states[name.to_s]
+    end
+    alias_method :gui_state, :state
+    
+    private
+    
+=begin rdoc
+Initializes the instance variables used by the module. It must be called before
+any other method in the module is used.
+=end
+    def initialize_states_handler
+      @gui_state_handler_states = {}
+      @gui_state_handler_handlers = Hash.new{|h, k| h[k] = []}
+    end
+    
+  end
+  
+end

data/lib/ruber/kde_config_option_backend.rb

@@ -0,0 +1,167 @@
+=begin 
+    Copyright (C) 2010 by Stefano Crocco   
+    stefano.crocco@alice.it   
+  
+    This program is free software; you can redistribute it andor modify  
+    it under the terms of the GNU General Public License as published by  
+    the Free Software Foundation; either version 2 of the License, or     
+    (at your option) any later version.                                   
+  
+    This program is distributed in the hope that it will be useful,       
+    but WITHOUT ANY WARRANTY; without even the implied warranty of        
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         
+    GNU General Public License for more details.                          
+  
+    You should have received a copy of the GNU General Public License     
+    along with this program; if not, write to the                         
+    Free Software Foundation, Inc.,                                       
+    59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             
+=end
+
+require 'facets/boolean'
+require 'facets/kernel/deep_copy'
+
+module Ruber
+
+=begin rdoc
+Backend for SettingsContainer which saves the options using the KDE configuration
+system (namely, <tt>KDE::Config</tt>).
+
+To allow to store values of types which the KDE configuration system can't handle
+(for example, hashes or symbols), those values are converted to strings using YAML
+on writing and converted back to their original values on reading. This also happens
+when the value of the option and its default value are of different classes (the
+reason for this is that otherwise the object would be converted to the class of 
+the default value when calling <tt>KDE::ConfigGroup#read_entry</tt>).
+
+To know which options are stored as YAML strings and which aren't, an extra option
+is written to file. It's store in the "Ruber Internal" group under the "Yaml options"
+key and contains a list of the options which have been stored in YAML format. Each
+entry of this option has the form "group_name/option_name".
+
+Group names and option names are converted to a more human friendly form before
+being written to the file: underscores are replaced by spaces and the first letters
+of all the words are capitalized.
+
+---
+TODO: it seems that writing and reading some kind of options doesn't work for the ruby bindings,
+while it works in C++ (for example, fonts). To work around this, I've changed a
+bit the code where the actual read and write was done. I've asked on the mailing
+list about this. When I get an answer, I'll see how to better fix this.
+=end
+  class KDEConfigSettingsBackend
+    
+=begin rdoc
+An array containing the classes which can be handled directly by KDE::Config.
++Array+ isn't included because whether it can be handled or not depends on its
+contents.
+=end
+    RECOGNIZED_CLASSES = [Qt::Variant, String, Qt::Font, Qt::Point, Qt::Rect,
+                          Qt::Size, Qt::Color, Fixnum, Bignum, TrueClass, FalseClass,
+                          Float, Qt::DateTime, Qt::Time]
+    
+=begin rdoc
+Creates a new KDEConfigSettingsBackend. _filename_ is the name of the file where
+the options will be stored, while _mode_ is the open flag to pass to
+<tt>KDE::SharedConfig#open_config</tt>. If _filename_ is not given, the global config
+object is used.
+
+<b>Note:</b> this class uses <tt>KDE::SharedConfig</tt>, rather than a regular
+<tt>KDE::Config</tt>. This means that if another instance of this class is created
+for the same file, they'll share the configuration object.
+=end
+    def initialize filename = nil, mode = KDE::Config::FullConfig
+      @config = if filename then KDE::SharedConfig.open_config filename, mode
+      else KDE::Global.config
+      end
+      yaml_options = @config.group('Ruber Internal').read_entry('Yaml options', [])
+      @yaml_options = yaml_options.map{|o| o.split('/').map( &:to_sym)}
+    end
+
+=begin rdoc
+Returns the option corresponding to _opt_. _opt_ is an option object with
+the characteristics specified in SettingsContainer#add_option. If an option with
+the same name and value of _opt_ isn't stored in the file, the option
+default value will be returned
+=end
+    def [] opt
+      grp = KDE::ConfigGroup.new @config, humanize(opt.group)
+      return opt.default.deep_copy unless grp.has_key(humanize(opt.name))
+      if @yaml_options.include? [opt.group, opt.name] or !recognized_value?(opt.default)
+        YAML.load grp.read_entry humanize(opt.name), ''
+#       else res = grp.read_entry humanize(opt.name), opt.default
+      else (grp.read_entry humanize(opt.name), Qt::Variant.from_value(opt.default)).value
+      end
+    end
+
+=begin rdoc
+Writes the options back to the file. _options_ is a
+hash with option objects as keys and the corresponding values as entries. There
+are two issues to be aware of:
+* if one of the options in _options_ has a value which is equal to its default
+  value, it won't be written to file
+* _options_ is interpreted as only containing the options which might have changed:
+  any option already in the file but not contained in _options_ is left unchanged
+  
+This method also updates the list of options written in YAML format, both in memory
+and on file.
+=end
+    def write opts
+      opts.each_pair do |opt, value|
+        if opt.default == value
+          @config.group(humanize(opt.group)).delete_entry humanize(opt.name)
+          next
+        elsif need_yaml? opt, value
+          @config.group(humanize(opt.group)).write_entry(humanize(opt.name), YAML.dump(value))
+          @yaml_options << [opt.group, opt.name]
+#         else @config.group(humanize(opt.group)).write_entry(humanize(opt.name), value)
+        else @config.group(humanize(opt.group)).write_entry(humanize(opt.name), Qt::Variant.from_value(value))
+        end
+      end
+      @yaml_options.uniq!
+      @config.group('Ruber Internal').write_entry('Yaml options', @yaml_options.map{|i| i.join('/')})
+      @config.sync
+    end
+    
+    private
+
+=begin rdoc
+Returns the human-friendly version of the _data_ (which must be a string or symbol).
+This is obtained by replacing all underscores with spaces and capitalizing the
+first letter of each word.
+=end
+    def humanize data
+      data.to_s.split('_').map{|s| s.capitalize}.join ' '
+    end
+
+=begin rdoc
+Tells whether the object _value_ is recognized by <tt>KDE::ConfigGroup</tt>. It
+returns *true* if the object's class is included in <tt>RECOGNIZED_CLASSES</tt>
+or if it is an array and all its entries are of classes included in that array
+and *false* otherwise.
+=end
+    def recognized_value? value
+      if RECOGNIZED_CLASSES.include? value.class then true
+      elsif value.is_a? Array then value.all?{|v| RECOGNIZED_CLASSES.include? v.class}
+      else false
+      end
+    end
+    
+=begin rdoc
+Tells whether the value _value_ for the option represented by the option object
+_opt_ needs to be stored using YAML or not. In particular, this returns *true*
+if the value can't be handled by <tt>KDE::ConfigGroup</tt> or if the class of _value_
+and that of the default value of the option differ (except in the case when one
+is *true* and the other is *false*) and *false* otherwise.
+=end
+    def need_yaml? opt, value
+      if !recognized_value? value then return true
+      elsif value.class == opt.default.class then return false
+      elsif value.bool? and opt.default.bool? then return false
+      else return true
+      end
+    end
+    
+  end
+  
+end

data/lib/ruber/kde_sugar.rb

@@ -0,0 +1,249 @@
+=begin 
+    Copyright (C) 2010 by Stefano Crocco   
+    stefano.crocco@alice.it   
+  
+    This program is free software; you can redistribute it andor modify  
+    it under the terms of the GNU General Public License as published by  
+    the Free Software Foundation; either version 2 of the License, or     
+    (at your option) any later version.                                   
+  
+    This program is distributed in the hope that it will be useful,       
+    but WITHOUT ANY WARRANTY; without even the implied warranty of        
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         
+    GNU General Public License for more details.                          
+  
+    You should have received a copy of the GNU General Public License     
+    along with this program; if not, write to the                         
+    Free Software Foundation, Inc.,                                       
+    59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             
+=end
+
+require 'yaml'
+
+module KDE
+  
+  class Url
+    
+    yaml_as "tag:ruby.yaml.org,2002:KDE::Url"
+    
+    def self.yaml_new cls, tag, val
+      KDE::Url.new val
+    end
+    
+    def to_yaml opts = {}
+      YAML.quick_emit(self, opts) do |out|
+        out.scalar taguri, to_encoded.to_s, :plain
+      end
+    end
+    
+    def _dump _
+      to_encoded.to_s
+    end
+    
+    def self._load str
+      self.new str
+    end
+    
+    def local_file?
+      is_local_file
+    end
+    
+  end
+
+  class TabWidget
+
+    include QtEnumerable
+
+    def empty?
+      count == 0
+    end
+
+    def each
+      count.times{|i| yield widget( i )}
+    end
+    alias_method :each_widget, :each
+
+    alias_method :tabs, :to_a
+
+  end
+
+  class ConfigGroup
+
+    include QtEnumerable
+  
+    def each_key
+      key_list.each{|k| yield k}
+    end
+    alias_method :each, :each_key
+
+  end
+
+  class IconLoader
+    
+    def self.load_pixmap name, hash = {}
+      args = {:null_icon => true, :group => Small, :size => 0, :state => DefaultState, :overlays => []}
+      args.merge! hash
+      pix = global.load_icon name, args[:group], args[:size], args[:state],
+args[:overlays], nil, args[:null_icon]
+    end
+
+    def self.load_mime_type_pixmap name, hash = {}
+      args = {:group => Small, :size => 0, :state => DefaultState, :overlays => []}
+      args.merge! hash
+      pix = global.load_mime_type_icon name, args[:group], args[:size], args[:state],
+args[:overlays], nil
+    end
+
+    def self.load_icon name, hash = {}
+      pix = load_pixmap name, hash
+      Qt::Icon.new pix
+    end
+
+    def self.pixmap_path name, group = Small, allow_null = true
+      global.icon_path name, group, allow_null
+    end
+
+  end
+
+  class ListWidget
+
+    include QtEnumerable
+    
+    def each
+      count.times{|i| yield item(i)}
+    end
+
+  end
+  
+  class CmdLineArgs
+
+    def files
+      res = []
+      count.times{|i| res << ::File.expand_path(arg(i))}
+      res
+    end
+    
+  end
+  
+  class InputDialog
+    
+    DEFAULT = {:value => '', :parent => nil, :validator => nil, :mask => '',
+               :whats_this => '', :completion_list => []}
+    
+    def self.get_text caption = '', label = '', args = {}
+      args = DEFAULT.merge args
+      getText caption, label, args[:value], nil, args[:parent], args[:validator],
+          args[:mask], args[:whats_this], args[:completion_list]
+    end
+    
+  end
+  
+  class XMLGUIClient
+    
+=begin rdoc
+  Changes the GUI state _state_, by calling KDE::XMLGUIClient#stateChanged. If
+  _value_ is a true value, stateChanged will be called with KDE::XMLGUIClient::StateNoReverse,
+  if it is *false* or *nil*, it will be called with KDE::XMLGUIClient::StateReverse.
+  
+  Returns KDE::XMLGUIClient::StateNoReverse or KDE::XMLGUIClient::StateReverse,
+  depending on which argument was passed to stateChanged
+=end
+    def change_state state, value
+      value = value ? StateNoReverse : StateReverse
+      stateChanged(state, value)
+      value
+    end
+    
+=begin rdoc
+  Changes the GUI state _state_, by calling KDE::XMLGUIClient#stateChanged. If
+  _value_ is a true value, stateChanged will be called with KDE::XMLGUIClient::StateNoReverse,
+  if it is *false* or *nil*, it will be called with KDE::XMLGUIClient::StateReverse.
+  
+  Unlike change_state, this method recursively changes the state of child clients,
+  calling their global_change_state method, if defined, or their stateChanged method
+  otherwise.
+=end
+    def global_change_state state, value
+      res = change_state state, value
+      child_clients.each do |c| 
+        if c.respond_to? :global_change_state then c.global_change_state state, value
+        else c.send :stateChanged, state, res
+        end
+      end
+      res
+    end
+    
+  end
+  
+  class MimeType
+    
+=begin rdoc
+Compares *self* with the string _str_. The comparison works as follows:
+* if _str_ doesn't start with <tt>!</tt> or <tt>=</tt>, it works as
+  <tt>KDE::MimeType#is</tt>
+* if _str_ starts with <tt>!</tt>, returns the oppsite of <tt>KDE::MimeType#is</tt>
+* if _str_ starts with <tt>=</tt>, makes an exact match between _str_ and <tt>self.name</tt>
+* if _str_ starts with <tt>!=</tt> or <tt>=!</tt>, makes an exact match and inverts
+  it
+=end
+    def =~ str
+      str = str.sub(/^([!=]{0,2})/, '')
+      case $1
+      when '!' then !(self.is str)
+      when '=' then self.name == str
+      when '!=', '=!' then !(self.name == str)
+      else self.is str
+      end
+    end
+    
+  end
+  
+  class Application
+    
+=begin rdoc
+Executes the block between calls to <tt>set_override_cursor</tt> and 
+<tt>restore_override_cursor</tt>. The override cursor used is _cursor_.
+
+This method returns the value returned by the block
+=end
+    def self.with_override_cursor cursor = Qt::Cursor.new(Qt::WaitCursor)
+      begin
+      set_override_cursor cursor
+      res = yield
+      ensure restore_override_cursor
+      end
+      res
+    end
+    
+=begin rdoc
+The same as KDE::Application.with_override_cursor
+=end
+    def with_override_cursor cursor = Qt::Cursor.new(Qt::WaitCursor), &blk
+      KDE::Application.with_override_cursor cursor, &blk
+    end
+    
+  end
+  
+  class ComboBox
+    
+    include QtEnumerable
+    
+=begin rdoc
+Returns an array containing the text of all items in the combo box
+=end
+    def items
+      count.times.map{|i| item_text(i)}
+    end
+    
+=begin rdoc
+Calls the block for each item. If no block is given, returns an +Enumerator+ which
+does the same
+=end
+    def each &blk
+      blk ? items.each(&blk) : items.each
+    end
+    
+  end
+
+end
+