ruber 0.0.5 → 0.0.7

data/lib/ruber/kde_sugar.rb

@@ -19,6 +19,7 @@
 =end
 
 require 'yaml'
+require 'facets/boolean'
 
 module KDE
   
@@ -30,6 +31,27 @@ module KDE
       KDE::Url.new val
     end
     
+=begin rdoc
+Tells whether a string looks like an url pointing to a file
+
+An url is considered to _look like_ an url pointing to a file if it contains a
+scheme part and an authority part, that is, if it starts with a scheme followed
+by two slashes.
+
+If _abs_only_ is *true*, this method returns *true* only if the file path is absolute,
+that is if the scheme is followed by three slashes. If _abs_only_ is *false*, it'll
+return *true* for both absolute and relative paths.
+@param [String] str the string to test
+@param [Boolean] abs_only whether this method should return *true* only if the path
+  is absolute or also for relative paths
+@return [Boolean] *true* if _str_ looks like an URL pointing to a file (or pointing
+  to an absolute file if _abs_only_ is *true*) and *false* otherwise
+=end
+    def self.file_url? str, abs_only = false
+      slash_number = abs_only ? 3 : 2
+      str.match(%r|[\w+.-]+:/{#{slash_number},3}|).to_b
+    end
+    
     def to_yaml opts = {}
       YAML.quick_emit(self, opts) do |out|
         out.scalar taguri, to_encoded.to_s, :plain
@@ -45,7 +67,11 @@ module KDE
     end
     
     def local_file?
-      is_local_file
+      scheme == "file"
+    end
+    
+    def remote_file?
+      !(local_file? or relative?)
     end
     
   end
@@ -123,6 +149,14 @@ args[:overlays], nil
       res
     end
     
+    def urls
+      count.times.inject([]) do |res, i|
+        url = KDE::Url.new u
+        url.path = File.expand_path(u) if url.protocol.empty?
+        res << url
+      end
+    end
+    
   end
   
   class InputDialog

data/lib/ruber/main_window/choose_plugins_dlg.rb

@@ -125,14 +125,14 @@ deselected.
       @ui = Ui::ChoosePluginsWidget.new
       @ui.setupUi self
       
-      dirs = Ruber[:config][:general].plugin_dirs
+      dirs = Ruber[:app].plugin_dirs
       
       @chosen_plugins = Ruber[:config][:general, :plugins].map(&:to_sym)
       loaded = Ruber[:components].plugins.map(&:plugin_name)
       @chosen_plugins.delete_if{|i| !loaded.include? i}
       
       read_plugins dirs
-      res = find_deps(:warning) do |e| 
+      res = find_deps(:sorry) do |e| 
         "There were problems making dependencies. #{create_failure_message e}\nAll plugins will be deselected"
       end
       if res
@@ -170,7 +170,7 @@ deselected.
 =end
     def write_settings
       dirs = @ui.directories.items
-      Ruber[:config][:general,:plugin_dirs] = dirs
+      Ruber[:app].plugin_dirs = dirs
       plugins = []
       @ui.plugins.model.each_row do |r|
         plugins << r[0].data.to_string if  r[0].fully_checked?
@@ -188,7 +188,7 @@ dependency problem occurs, the user is warned and all plugins are deselected
       dirs = Ruber[:config].default :general, :plugin_dirs
       @chosen_plugins = Ruber[:config].default( :general, :plugins).split(',').map{|i| i.to_sym}
       read_plugins dirs
-      res = find_deps(:warning) do |e| 
+      res = find_deps(:sorry) do |e| 
         "There were problems making dependencies. #{create_failure_message e}\nAll plugins will be deselected"
       end
       if res
@@ -248,11 +248,11 @@ an error occurs and no block is passed, the exception is passed on.
 This method returns *nil* if no error occurs and the value returned by the
 message box otherwise.
 =end
-    def find_deps msg_type = :warning
+    def find_deps msg_type = :sorry
       chosen_data = @chosen_plugins.map{|i| @plugin_data[i]}
       begin @needed_plugins = ComponentManager.fill_dependencies chosen_data, @plugin_data.values
       rescue ComponentManager::UnresolvedDep, ComponentManager::CircularDep => e
-        if block_given? then KDE::MessageBox.send(msg_type, yield(e))
+        if block_given? then KDE::MessageBox.send msg_type, nil, yield(e)
         else raise
         end
       end
@@ -308,7 +308,7 @@ to the item _it_.
       if it.check_state == Qt::Checked then @chosen_plugins << name.to_sym
       else @chosen_plugins.delete name.to_sym
       end
-      find_deps{|e| create_failure_message( e) + "\nPlease, be sure to correct the problem before accepting changes" }
+      find_deps{|e| create_failure_message( e) + "\nPlease, be sure to correct the problem before pressing the OK or Apply button" }
       update_plugin_status
     end
     
@@ -320,7 +320,7 @@ If the dependencies aren't respected, the user is warned with a message box.
 =end
     def slot_directories_changed
       new_dirs = @ui.directories.items
-      find_deps{|e| create_failure_message( e) + "\nPlease, be sure to correct the problem before accepting changes" }
+      find_deps{|e| create_failure_message( e) + "\nPlease, be sure to correct the problem before pressing the OK or Apply button" }
       fill_plugin_list
       emit directories_changed
       nil
@@ -337,7 +337,7 @@ happen.
       case e
       when ComponentManager::UnresolvedDep
         deps = e.missing.map do |p1, p2|
-          "#{d}, needed by #{pl.join ', '}"
+          "#{p1}, needed by #{p2.join ', '}"
         end
         "Some dependencies couldn't be satisifed:\n#{deps.join "\n"}"
       when ComponentManager::CircularDep
@@ -350,4 +350,4 @@ happen.
 
   end
 
-end
+end

data/lib/ruber/main_window/hint_solver.rb

@@ -0,0 +1,263 @@
+=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 'ruber/pane'
+require 'ruber/editor/editor_view'
+
+module Ruber
+  
+  class MainWindow
+
+=begin rdoc
+Helper class used by {MainWindow#editor_for} and friends to find out which editor
+should use or where the new editor should be placed according to the hints given
+them
+=end
+    class HintSolver
+
+=begin rdoc
+@param [KDE::TabWidget] tabs the tab widget which contains the tabs
+@param [KParts::PartManager] manager the part manager used by the main window
+@param [Array<EditorView>] view_order an array specifying the order in which views
+  were activated. Most recently activated views corresponds to lower indexes. It's
+  assumed that the main window will keep a reference to this array and update it
+  whenever a view becomes activated
+=end
+      def initialize tabs, manager, view_order
+        @tabs = tabs
+        @part_manager = manager
+        @view_order = view_order
+      end
+      
+=begin rdoc
+Finds the editor to use for a document according to the given hints
+
+If no editor associated with the document and respecting the given hints exists,
+*nil* is returned. This always happens if the @:existing@ hint is @:never@.
+@param [Document] doc the document to retrieve the editor for
+@param hints (see MainWindow#editor_for). See {#MainWindow#editor_for} for the
+  values it can contain. Only the @:existing@ and @:strategy@ entries are used
+@return [EditorView,nil] a view associated with the document which respects the
+  hints or *nil* if such a view doesn't exist
+=end
+      def find_editor doc, hints
+        views = []
+        case hints[:existing]
+        when :never then return nil
+        when :current_tab
+          views = @tabs.current_widget.select{|v| v.document == doc}
+        else @tabs.each{|t| views += t.select{|v| v.document == doc} }
+        end
+        choose_editor doc, views, hints
+      end
+      
+=begin rdoc
+Finds out where a new editor should respect the given hints
+
+The return value tells where the new editor should be placed. If the return value
+is *nil* then the editor should be placed in a new tab; if it's an {EditorView} then
+the editor should be placed in the pane containing the view, splitting it at the
+view
+@param hints (see MainWindow#editor_for). See {#MainWindow#editor_for} for the
+values it can contain. Only the @:newand entry is used
+@return [EditorView, nil] an {EditorView} if the new editor should be placed inside
+  an existing pane. The returned view is the view where it's parent should be split
+  at. If *nil* is returned, the editor should be put in a new tab
+=end
+      def place_editor hints
+        case hints[:new]
+        when :new_tab then nil
+        when :current then @view_order[0]
+        when :current_tab
+          current = @tabs.current_widget
+          current.each_view.to_a[0] if current
+        when Integer
+          pane = @tabs.widget hints[:new]
+          pane.each_view.to_a[0] if pane
+        when EditorView then 
+          view = hints[:new]
+          view.parent.is_a?(Pane) ? view : nil
+        end
+      end
+      
+      private
+      
+=begin rdoc
+Chooses an editor according to the value of the :strategy hint
+
+For each strategy specified in the hint, this method calls a method called @choose_editor_*_strategy@,
+where the @*@ stands for the strategy name.
+
+If there's no editor satsifying the given strategy, then the @:next@ strategy, which
+always gives a result, is used.
+@param [Document] doc the document associated with the editor
+@param [Array<EditorView>] editors a list of the editors to choose among. They should
+  be ordered by tab and, within the same tab, from left to right and top to bottom
+@param hints (see MainWindow#editor_for)
+@return [EditorView,nil] an editor view according to the @:strategy@ hint or *nil*
+  if _editors_ is empty
+=end
+      def choose_editor doc, editors, hints
+        case editors.size
+        when 0 then nil
+        when 1 then editors.first
+        else
+          editor = nil
+          (Array(hints[:strategy]) + [:next]).each do |s|
+            editor = send "choose_editor_#{s}_strategy", doc, editors, hints
+            break if editor
+          end
+          editor
+        end
+      end
+
+      
+=begin rdoc
+A list of all the editors associated with the given document in a pane
+@param [Document] doc the document
+@param [Pane] tab the pane where to look for editors
+@return [Array<EditorView>] the editor views associated with _doc_ in the pane
+  _pane_, in order
+=end
+      def editors_in_tab doc, tab
+        tab.select{|v| v.document == doc}
+      end
+
+=begin rdoc
+Chooses an editor according to the @current@ strategy
+
+@param (see #choose_editor)
+@return [EditorView,nil] the current editor if it is associated with _doc_
+  and *nil* otherwise
+=end
+      def choose_editor_current_strategy doc, editors, hints
+        current = @view_order[0]
+        if current and current.document == doc then current
+        else nil
+        end
+      end
+
+=begin rdoc
+Chooses an editor according to the @current_tab@ strategy
+
+@param (see #choose_editor)
+@return [EditorView,nil] the first editor in the current tab associated with _doc_
+  or *nil* if the current tab doesn't contain any editor associated with _doc_
+=end
+      def choose_editor_current_tab_strategy doc, editors, hints
+        tab = @tabs.current_widget
+        views = tab.find_children(EditorView).select do |c| 
+          c.is_a?(EditorView) and c.document == doc
+        end
+        (views & editors).first
+      end
+
+=begin rdoc
+Chooses an editor according to the @last_current_tab@ strategy
+
+@param (see #choose_editor)
+@return [EditorView,nil] the last editor in the current tab associated with _doc_
+  or *nil* if the current tab doesn't contain any editor associated with _doc_
+=end
+
+      def choose_editor_last_current_tab_strategy doc, editors, hints
+        tab = @tabs.current_widget
+        views = tab.find_children(EditorView).select do |c| 
+          c.is_a?(EditorView) and c.document == doc
+        end
+        (views & editors).last
+      end
+      
+=begin rdoc
+Chooses an editor according to the @next@ strategy
+
+@param (see #choose_editor)
+@return [EditorView] the first editor associated with _doc_ starting from
+  the current tab
+=end
+
+      def choose_editor_next_strategy doc, editors, hints
+        current_index = @tabs.current_index
+        editor = editors.find do |e|
+          pane = e.parent
+          pane = pane.parent_pane while pane.parent_pane
+          @tabs.index_of(pane) >= current_index
+        end
+        editor || editors.first
+      end
+
+=begin rdoc
+Chooses an editor according to the @previous@ strategy
+
+@param (see #choose_editor)
+@return [EditorView] the first editor associated with _doc_ starting from
+  the current tab and going backwards
+=end
+      def choose_editor_previous_strategy doc, editors, hints
+        current_index = @tabs.current_index
+        editor = editors.reverse_each.find do |e|
+          pane = e.parent
+          pane = pane.parent_pane while pane.parent_pane
+          @tabs.index_of(pane) < current_index
+        end
+        editor || editors.last
+      end
+
+=begin rdoc
+Chooses an editor according to the @first@ strategy
+
+@param (see #choose_editor)
+@return [EditorView] the first editor associated with _doc_ starting from
+  the first tab
+=end
+
+      def choose_editor_first_strategy doc, editors, hints
+        editors.first
+      end
+
+=begin rdoc
+Chooses an editor according to the @last@ strategy
+
+@param (see #choose_editor)
+@return [EditorView] the last editor associated with _doc_ starting from
+  the first tab
+=end
+      def choose_editor_last_strategy doc, editors, hints
+        editors.last
+      end
+      
+=begin rdoc
+Chooses an editor according to the @last_used@ strategy
+
+@param (see #choose_editor)
+@return [EditorView] the last activated editor associated with _doc_
+=end
+      def choose_editor_last_used_strategy doc, editors, hints
+        # The || part is there in case there\'s a view in editors which doesn't
+        # appears in the view order. In this case, it's given a fake index which
+        # is greater than all the other possible
+        editors.sort_by{|e| @view_order.index(e) || (@view_order.count + 1)}.first
+      end
+      
+    end
+    
+  end
+  
+end

data/lib/ruber/main_window/main_window.rb

@@ -29,9 +29,12 @@ require 'ruber/gui_states_handler'
 
 require 'ruber/main_window/main_window_internal'
 require 'ruber/main_window/main_window_actions'
+require 'ruber/main_window/hint_solver'
+require 'ruber/main_window/view_manager'
 
 require 'ruber/main_window/status_bar'
 require 'ruber/main_window/workspace'
+require_relative 'ui/workspace_settings_widget'
 
 module Ruber
 
@@ -47,22 +50,24 @@ tool widgets.
     
     include GuiStatesHandler
     
-    extend Forwardable
-##
-# :method: current_document_changed(QObject* obj) [SIGNAL]
-# Signal emitted whenever the current document changes. _obj_ is the new current
-# document and will be <tt>Qt::NilObject</tt> if there's no current document.
-    
-##
-# :method: active_editor_changed(QObject* obj) [SIGNAL]
-# Signal emitted whenever the active editor changes _obj_ is the new active editor
-# and will be <tt>Qt::NilObject</tt> if there's no active editor
-    
+    extend Forwardable    
     
     signals 'current_document_changed(QObject*)', 'active_editor_changed(QObject*)'
         
     slots :load_settings
     
+=begin rdoc
+The default hints used by methods like {#editor_for} and {#editor_for!}
+=end
+    DEFAULT_HINTS = {
+      :exisiting => :always, 
+      :strategy => [:current, :current_tab, :first],
+      :new => :new_tab,
+      :split => :horizontal,
+      :show => true,
+      :create_if_needed => true
+    }.freeze
+    
 =begin rdoc
 The widget which contains the tool widgets.
 
@@ -70,6 +75,8 @@ The primary use of this method is to connect to the signals emitted from the wor
 when a tool widget is raised, shown or hidden. All of its other methods are also
 provided by the MainWindow, so you shouldn't need to access the workspace to use
 them.
+
+@return [Workspace] the workspace associated with the main window
 =end
     attr_reader :workspace
     
@@ -94,48 +101,87 @@ is the plugin description for this object.
       self.central_widget = Workspace.new self
       # We need the instance variable to use it with Forwardable
       @workspace = central_widget 
-      @views = central_widget.instance_variable_get :@views
-      @current_view = nil
-      @active_editor = nil
+      @tabs = central_widget.instance_variable_get :@views
+      @tabs.tabs_closable = Ruber[:config][:workspace, :close_buttons]
+      @view_manager = ViewManager.new @tabs, self
       @auto_activate_editors = true
-      @editors_mapper = Qt::SignalMapper.new self
       @ui_states = {}
       @actions_state_handlers = Hash.new{|h, k| h[k] = []}
       @about_plugin_actions = []
+      @switch_to_actions = []
       @last_session_data = nil
       self.status_bar = StatusBar.new self
       self.connect(SIGNAL('current_document_changed(QObject*)')) do |doc|
-        change_state 'current_document', !doc.nil_object?
+        change_state 'current_document', !doc.nil?
       end
       connect Ruber[:components], SIGNAL('component_loaded(QObject*)'), self, SLOT('add_about_plugin_action(QObject*)')
       connect Ruber[:components], SIGNAL('unloading_component(QObject*)'), self, SLOT('remove_about_plugin_action(QObject*)')
       connect Ruber[:components], SIGNAL('unloading_component(QObject*)'), self, SLOT('remove_plugin_ui_actions(QObject*)')
-      connect @editors_mapper, SIGNAL('mapped(QWidget*)'), self, SLOT('remove_view(QWidget*)')
+      connect @view_manager, SIGNAL('active_editor_changed(QWidget*)'), self, SLOT('slot_active_editor_changed(QWidget*)')
+      connect Ruber[:documents], SIGNAL('document_created(QObject*)'), self, SLOT('document_created(QObject*)')
+      connect Ruber[:documents], SIGNAL('closing_document(QObject*)'), self, SLOT(:update_switch_to_list)
+
       setup_actions action_collection
-      @views.connect(SIGNAL('currentChanged(int)')) do |idx|
-        if @auto_activate_editors then activate_editor idx 
-        else activate_editor nil
-        end
-      end
       Ruber[:projects].connect( SIGNAL('current_project_changed(QObject*)') ) do |prj|
         change_state "active_project_exists", !prj.nil?
-        make_title
+        change_title
       end
+      connect @tabs, SIGNAL('tabCloseRequested(int)'), self, SLOT('close_tab(int)')
       connect Ruber[:projects], SIGNAL('closing_project(QObject*)'), self, SLOT('close_project_files(QObject*)')
-      
       setup_GUI
       create_shell_GUI true
       
       config_obj = Ruber[:config].kconfig
       apply_main_window_settings KDE::ConfigGroup.new( config_obj, 'MainWindow')
       recent_files = KDE::ConfigGroup.new config_obj, 'Recent files'
-      action_collection.action("file_open_recent").load_entries recent_files
+      open_recent_action =action_collection.action("file_open_recent")
+      open_recent_action.load_entries recent_files
+      switch_to_recent_action = action_collection.action("window-switch_to_recent_file")
+      switch_to_recent_action.load_entries recent_files
+      
+      # Synchronize the two menus, so that when the user clears one of them the also
+      # is also cleared
+      connect open_recent_action, SIGNAL(:recentListCleared), switch_to_recent_action, SLOT(:clear)
+      connect switch_to_recent_action, SIGNAL(:recentListCleared), open_recent_action, SLOT(:clear)
+      
       recent_projects = KDE::ConfigGroup.new config_obj, 'Recent projects'
       action_collection.action("project-open_recent").load_entries recent_projects
       status_bar.show
       setup_initial_states
     end
     
+=begin rdoc
+The open tabs
+
+@return [Array<Pane>] a list of the top-level pane for each tab
+=end
+    def tabs
+      @tabs.to_a
+    end
+    
+=begin rdoc
+The views contained in the main window
+
+If a document is given as argument, returns all views associated with the document;
+if no document is given, all views are returned.
+
+The order of the views in the returned list is the activation order: the view
+which was activated more recently is at position 0 in the array, the one activated
+before that is at position 1 and so on. Views which have never been activated are
+at the end of the array, in an arbitrary order
+
+@param [Document,nil] doc the document to return the views for. If *nil*, all the
+  views will be returned
+@return [Array<EditorView>] the views associated with the given document, if any,
+  or all the views, in activation order, from most recently activated to less recently
+  activated
+=end
+    def views doc = nil
+      if doc then @view_manager.activation_order.select{|v| v.document == doc}
+      else @view_manager.activation_order.dup
+      end
+    end
+    
     ##
     # :method: add_tool
     # Adds a tool widget to the main window. See Workspace#add_tool_widget for more information.
@@ -179,186 +225,353 @@ is the plugin description for this object.
     def_delegators :@workspace, :tool_widgets
     
 =begin rdoc
-Returns the editor view for the given document, creating it if needed
+Returns an editor associated with the given document, creating it if needed
+
+If _doc_ is not a document and no document for the file representing by the string
+or URL _doc_ is open, it will be created.
+
+Since there can be more than one editor associated with the document, the optional
+_hints_ argument can be used to specify which one should be returned. If no editor
+exists for the document, or none of the exisiting ones statisfy the @existing@
+hint, a new one will be created, unless the @create_if_needed@ hint is *false*.
 
 @param [Document, String, KDE::Url] doc the document. If it is a string representing
-  an absolute path, the document will be obtained using {DocumentList#document},
-  while for other strings it will be obtained using {DocumentList#document_with_name}
-@return [EditorView,nil] an editor associated with the document or *nil* if _doc_
-  is interpreted as document name but no documents with that name exists
-@raise [ArgumentError] if _doc_ is an absolute path or a @KDE::Url@ but the file
-  doesn't exist
+  a relative path, it'll be considered relative to the current directory. If the
+  string is an Url, it'll be interpreted as such
+@param [Hash] hints options to tailor the algorithm used to retrieve or create the editor
+
+@option hints [Symbol] :existing (:always) when it is acceptable to return an already existing
+  editor. It can be:
+  * @:always@: if there's an existing editor, always use it
+  * @:never@: never use an exisiting editor
+  * @:current_tab@: use an exisiting editor only if it is in the current pane
+@option hints [Boolean] :create_if_needed (true) whether or not a new editor for
+  the given document should be created if none exists. This is different from
+  passing @:always@ as the value of the @:existing@ option because the latter would
+  cause a new editor to be created in case no one already exists for the document
+@option hints [Symbol, Array<Symbol>] :stategy ([:current, :current_tab, :first])
+  how to choose the exisiting editor to use in case there's more than one. If it
+  is an array, the strategies will be applied in turn until one has success.
+  If none of the given strategies succeed, @:first@ will be used. The possible
+  values are
+  * @:current@: if the current editor is associated with _doc_, use it
+  * @:current_tab@: if there are editors associated with _doc_ in the current
+  tab, the first of them will be used
+  * @:last_current_tab@: if there are editors associated with _doc_ in the current
+  tab, the first of them will be used
+  * @:next@: starting from the current tab, the first editor found associated
+  with _doc_ will be used
+  * @:previous@: the first editor associated with _doc_ found by looking in all
+  tabs from the current one in reverse order will be used (the current tab will
+  be the last one where the editor will be looked for)
+  * @:first@: the first editor associated with the document will be used
+  * @:last@: the last editor associated the document will be used
+  
+  This option is only useful when using an existing editor
+@option hints [Symbol,Integer,EditorView] :new (:new_tab) where to place the new editor, if
+  it needs to be created. It can have one of the following values:
+  * @:new_tab@: put the new editor as the single editor in a new tab
+  * @:current@: place the new editor in the pane obtained splitting the 
+  current editor
+  * @:current_tab@: place the new editor in the pane obtained splitting the first
+  editor in the current tab
+  * an integer: place the new editor in the tab associated with that index (0-based),
+  in the pane obtained by splitting the first view
+  * an {EditorView}: place the new editor in the pane obtained splitting the
+  pane associated with the given editor
+
+  This option is only used when when creating a new editor
+@option hints [Symbol] :split (:horizontal) the orientation in which an existing
+  editor should be split to accomodate the new editor. It can be @:horizontal@
+  or @:vertical@. This option is only used when when creating a new editor
+@option hints [Boolean] :show (true) whether the new editor should be shown or
+  not. If it's *false*, the editor won't be placed in any pane. This option is
+  only used when when creating a new editor
+@return [EditorView,nil] an editor associated with the document and *nil* if no
+  editor associated with the given document exists and the @:create_if_needed@ hint is
+  set to *false*.
+@raise [ArgumentError] if _doc_ is a path or a @KDE::Url@ but the corresponding
+  file doesn't exist
 =end
-    def editor_for! doc
+    def editor_for! doc, hints = DEFAULT_HINTS
+      hints = DEFAULT_HINTS.merge hints
+      docs = Ruber[:documents].documents
       unless doc.is_a? Document
-        if doc.is_a? KDE::Url or doc.start_with? '/' then doc = Ruber[:documents].document doc
-        else doc = Ruber[:documents].document_with_name doc
+        unless hints.has_key? :close_starting_document
+          hints[:close_starting_document] = docs.size == 1 && 
+              docs[0].extension(:ruber_default_document).default_document && 
+              docs[0].pristine?
         end
+        url = doc
+        if url.is_a? String
+          url = KDE::Url.new url
+          if url.relative?
+            path = File.expand_path url.path
+            url.path = path
+          end
+        end
+        doc = Ruber[:documents].document url
       end
       return unless doc
-      create_editor_if_needed doc
+      @view_manager.without_activating{@view_manager.editor_for doc, hints}
     end
     
 =begin rdoc
-Similar to <tt>editor_for!</tt> but it doesn't create the document or the editor
-if they don't exist. If a Document for the string _doc_ doesn't exist, or if it
-doesn't have an editor, returns *nil*.
+Returns an editor associated with the given document
+
+It works mostly like {#editor_for!}, but it doesn't attempt to create the document
+if it doesn't exist an always sets the @create_if_needed@ hint to *false*. See
+{#editor_for!} for the values it can contain.
+
+@param (see #editor_for!)
+@return [EditorView,nil] an editor associated with the document and *nil* if no
+editor associated with the given document exists or no document corresponds to _doc_
+@raise [ArgumentError] if _doc_ is a path or a @KDE::Url@ but the corresponding
+file doesn't exist
 =end
-    def editor_for doc
-      doc = Ruber[:documents][doc] if doc.is_a? String
+    def editor_for doc, hints = DEFAULT_HINTS
+      hints = DEFAULT_HINTS.merge hints
+      hints[:create_if_needed] = false
+      unless doc.is_a? Document
+        url = doc
+        if url.is_a? String
+          url = KDE::Url.new url
+          if url.relative?
+            path = File.expand_path url.path
+            url.path = path
+          end
+        end
+        doc = Ruber[:documents].document_for_url url
+      end
       return unless doc
-      doc.view
+      @view_manager.editor_for doc, hints
     end
     
 =begin rdoc
-Returns the active editor, or *nil* if there's no active editor.
-
-<b>Note:</b> strictly speaking, this is not the same as <tt>tab_widget.current_widget</tt>.
-For an editor to be active, it's not enough to be in the current tab, but it also
-need to having been its gui merged with the main window gui.
+The active editor
+    
+The active editor is the editor which has its GUI merged with the main window's.
+This means it is the editor which last received focus and the one which would receive
+focus when the tab widget does. If the focus already is in the tab widget, then
+the active editor is the one whose @is_active_window@ method returns *true*.
 
-TODO: in all places this is called, change the name from <tt>current_view</tt> to
-<tt>active_editor</tt>.
+@return [EditorView,nil] the active editor or *nil* if there's no active editor.
 =end
     def active_editor
-      @active_editor
+      @view_manager.active_editor
     end
+    alias_method :current_editor, :active_editor
+
+=begin rdoc
+Activates an editor
+
+If the editor is not in the current tab, the tab it belongs to becomes active.
+
+Activating an editor means merging its GUI with the main window's GUI, changing
+the title of the main window accordingly and telling the status bar to refer to
+that view.
+    
+After activating the editor, the {#current_document_changed} and {#active_editor_changed}
+signals are emitted.
+@param [EditorView,nil] editor the editor to activate. If *nil*, then the currently active
+  editor will be deactivated
+=end
+  def activate_editor editor
+    tab = @view_manager.tab editor
+    return unless tab
+    @tabs.current_widget = tab
+    return if active_editor == editor
+    @view_manager.make_editor_active editor
+    editor
+  end
     
 =begin rdoc
-Returns the editor in the current tab, or *nil* if there's no tab. Note that this
-may not be the active editor.
+Replaces an editor with another
+
+If the editor to be replaced is the only one associated witha given document and
+the document is modified, the user is asked whether he wants to save it or not. If
+he chooses to abort, the editor is not replaced, otherwise the document is closed.
+
+The new editor is put in the same pane which contained the old one (without splitting
+it).
+
+@overload replace_editor old, new_ed
+  @param [EditorView] old the editor to replace
+  @param [EditorView] new_ed the editor to replace _old_ with
+  @return [EditorView,nil]
+@overload replace_editor old, doc
+  @note whether or not the user needs to be asked about saving the document is determined
+    regardless of the value of _doc_. This means that the user may be asked
+    to save the document even if _doc_ is the same document associated with
+    the view (or the URL corresponding to it). To avoid this, create the replacement
+    editor before calling this method, using @editor_for doc, :existing => :never, :show => false@,
+    then use the overloaded version of this method which takes an editor
+  @param [EditorView] old the editor to replace
+  @param [Document,String,KDE::Url] doc the document to create the editor for or
+    the name of the corresponding file (absolute or relative to the current directory)
+    or the corresponding URL
+  @return [EditorView,nil]
+@return [EditorView,nil] the new editor or *nil* if the user choose to abort
 =end
-    def current_editor
-      @views.current_widget
+    def replace_editor old, editor_or_doc
+      if old.document.views.size == 1
+        return unless old.document.query_close
+        close_doc = true
+      end
+      if editor_or_doc.is_a?(EditorView) then ed = editor_or_doc
+      else ed = editor_for! editor_or_doc, :existing => :never, :show => false
+      end
+      old.parent.replace_view old, ed
+      close_editor old, false
+      ed
     end
     
 =begin rdoc
-Activates an editor. _arg_ can be either the index of a widget in the tab widget
-(for internal uses only) or the editor to activate, or *nil*. If the editor to
-activate is not in the current tab, the tab which contains it will become the current
-one. Activating an editor deactivates the previously active one.
+The toplevel pane corresponding to the given index or editor
 
-Activating an editor means merging its GUI with the main window's GUI, changing
-the title of the main window accordingly and telling the status bar to refer to
-that view. Also, the <tt>current_document_changed</tt> and <tt>active_editor_changed</tt>
-signals are emitted.
+@overload tab idx
+  @param [Integer] idx the index of the tab
+  @return [Pane] the toplevel pane in the tab number _idx_
+@overload tab editor
+  @param [EditorView] editor the editor to retrieve the pane for
+  @return [Pane] the toplevel pane containing the given editor
 =end
-    def activate_editor arg
-      view = arg.is_a?(Integer) ? @views.widget( arg ) : arg
-      @views.current_widget = view if view and @views.current_widget != view
-      deactivate_editor @active_editor if @active_editor != view
-      @active_editor = view
-      if @active_editor
-        gui_factory.add_client @active_editor.doc.view.send(:internal)
-        @active_editor.document.activate
-      end
-      make_title
-      status_bar.view = @active_editor
-      emit current_document_changed @active_editor ?  @active_editor.document : Qt::NilObject
-      emit active_editor_changed @active_editor || Qt::NilObject
+    def tab arg
+      @view_manager.tab arg
     end
     
 =begin rdoc
-  Returns the document associated with the active editor or *nil* if there's no
-  current editor.
-  
-  It's almost the same as <tt>active_editor.doc</tt>, but already takes care of
-  the case when <tt>active_editor</tt> is *nil*.
+The document associated with the active editor
+
+This is a convenience method for @active_editor.document@ which takes care of the
+case when there's no active editor.
+
+@return [Document,nil] the document associated with the active editor or *nil*
+  if there's no active editor
 =end
     def current_document
-      view = @views.current_widget
-      view ? view.doc : nil
+      (ed = active_editor) ? ed.document : nil
     end
+    alias_method :active_document, :current_document
     
 =begin rdoc
-Similar to <tt>editor_for!</tt> but, after having retrieved/created the editor
-view, it activates and gives focus to it and moves the cursor to the line _line_
-and column _col_ (both of them are 0-based indexes).
+Displays an editor for the given document
+
+This method is similar to {#editor_for!} but, after retrieving the editor (creating
+it and/or the document as needed), it activates and gives focus to it and moves
+the cursor to the given position.
+
+@see #editor_for! editor_for! for the possible entries in _hints_
+@param (see #editor_for!)
+@param [Integer,nil] line the line number to move the cursor to (0-based). Ignored if eiter
+  it or _col_ is *nil*
+@param [Integer,nil] col the column number to move the cursor to (0-based). Ignored if eiter
+  it or _col_ is *nil*
+@return [EditorView,nil] the editor which has been activated or *nil* if the
+  editor couldn't be found (or created)
 =end
-    def display_doc doc, line = nil, col = 0
-      ed = editor_for! doc
+    def display_doc doc, line = nil, col = nil, hints = DEFAULT_HINTS
+      ed = editor_for! doc, hints
       return unless ed
       activate_editor ed
       ed.go_to line, col if line and col
       ed.set_focus
+      ed
     end
-    alias display_document display_doc
+    alias_method :display_document, :display_doc
     
 =begin rdoc
-Executes the contents of the block with automatical editor activation disabled.
-This should be used, for example, when more than one editor should be opened at
+Executes the given block without automatically activating an editor whenever the
+current tab changes
+
+This method should be used, for example, when more than one editor should be opened at
 once. Without this, every new editor would become (for a little time) the active
 one, with its gui merged with the main window and so on. This slows things down
 and should be avoided. To do so, you use this method:
-  Ruber[:main_window].without_activating do
+
+bc. Ruber[:main_window].without_activating do
     ed = nil
     files.each do |f|
       ed = Ruber[:main_window].editor_for! f
     end
     Ruber[:main_window].activate_editor ed
   end
-After the block has been called, if there is no editor, or if the current widget
-in the tab widget is different from the active editor, the current widget will
-be activated.
-<b>Note:</b> automatical editor activation will be restored at the end of this
-method (even if exceptions occur).
+
+After calling this method, the focus widget of the current tab gets focus
+
+@note automatical editor activation will be restored at the end of this
+  method (even if exceptions occur).
+@yield the block which should be executed without automatically activating editors
+@return [Object] the value returned by the block
 =end
-    def without_activating
-      begin
-        @auto_activate_editors = false
-        yield
-      ensure 
-        @auto_activate_editors = true
-        if @views.current_index < 0 then activate_editor nil
-        elsif @views.current_widget != @active_editor
-          activate_editor @views.current_widget
-        end
-      end
+    def without_activating &blk
+      @view_manager.without_activating &blk
     end
     
 =begin rdoc
-Closes the editor _ed_, deleting its tab and closing the corresponding document
-and activating the next tab if auto activating is on. If _ask_ is *true*, the document
-will ask whether to save modifications, otherwise it won't
+Closes an editor view
+
+If the editor to be closed is the last editor associated with the document the
+document will be closed. If _ask_ is *true* and the document is modified, the user
+will be asked whether to save or discard the changes and will have the possibility
+of aborting closing the editor (and the document). If _ask_ is false, the document
+will be closed without user interaction.
+
+If there are other editors associated with the document besides the one to close,
+the latter will be closed without affecting the document.
+
+@param [EditorView] editor the editor to close
+@param [Boolean] ask whether or not to ask confirmation from the user if the document
+  associated with _editor_ should be closed
+@return [Boolean] *true* if the editor is closed and *false* if it isn't.
+@note Always use this method to close an editor, rather than calling its {EditorView#close close}
+  method directly, unless you want to leave the corresponding document without a view
 =end
-    def close_editor ed, ask = true
-      ed.document.close_view ed, ask
+    def close_editor editor, ask = true
+      editor_tab = self.tab(editor)
+      has_focus = editor_tab.is_active_window if editor_tab
+      if has_focus
+        views = editor_tab.to_a
+        idx = views.index(editor)
+        new_view = views[idx-1] || views[idx+1]
+      end
+      doc = editor.document
+      if doc.views.size > 1 
+        editor.close
+        true
+      else doc.close ask
+      end
+      focus_on_editor new_view if new_view
     end
     
 =begin rdoc
-  This method is meant to be called in situation where the user may want to save
-  a number of documents, for example when the application is quitting, as it avoids
-  displaying a dialog box for each modified document.
-    
-  _docs_ can be either an array containing the documents which can be saved (documents
-  in it which aren't modified will be ignored) or *nil*. In this case, all the
-  open documents (with or without an open editor) will be taken into account.
-  
-  It displays a dialog where the user can choose, among the documents passed as
-  first argument, which ones he wants to save. The user has three choiches:
-  * save some (or all) the files, then proceed with the operation which has caused
-    the dialog to be shown (for example, quitting the application)
-  * don't save any file and go on with the operation
-  * abort the operation.
-    
-  In the first case, this method attempts to perform save the selected files. If
-  any of them can't be saved, the dialog to choose the files to save will be
-  displayed again, with only those files which couldn't be saved (after informing
-  the user of the failure). The user can again chose which of those files this method
-  should attempt to save again, or whether to abort the operation or skip saving.
-  This will be repeated until all files have been saved or the user gives up
-    
-  In the second and third cases, the method simply returns respectively +true+ or
-  *false*.
-    
-  The value returned by this method is *false* if the user choose to abort the
-  operation and *true* otherwise. Calling methods should act appropriately (for
-  example, if this is called from a method which closes all documents and returns
-  *false*, the documents should't be closed. If it returns true, instead, they
-  should be closed, without asking again to save them).
-    
-  <b>Note:</b> if _docs_ only contains non-modified documents, this method will
-  do nothing and immediately return *true*.
+Asks the user to save multiple documents
+
+This method is meant to be called in situation where the user may want to save
+a number of documents, for example when the application is quitting, as it avoids
+displaying a dialog box for each modified document.
+
+It displays a dialog where the user can choose, among the documents passed as
+first argument, which ones he wants to save. The user has three choiches:
+* save some (or all) the files, then proceed with the operation which has caused
+the dialog to be shown (for example, quitting the application)
+* don't save any file and go on with the operation
+* abort the operation.
+
+In the first case, this method attempts to perform save the selected files. If
+any of them can't be saved, the dialog to choose the files to save will be
+displayed again, with only those files which couldn't be saved (after informing
+the user of the failure). The user can again chose which of those files this method
+should attempt to save again, or whether to abort the operation or skip saving.
+This will be repeated until all files have been saved or the user gives up
+
+In the second and third cases, the method simply returns respectively *true* or
+*false*.
+
+@param [Array<Document>] docs the list of documents to save. If any document isn't
+  modified, it'll be ignored. If no document is mdified, nothing will be done
+@return [Boolean] *true* if the operation which caused the dialog to be shown
+  can be carried on and *false* if the user chose to abort it
 =end
     def save_documents docs = nil
       docs ||= Ruber[:docs]
@@ -380,11 +593,12 @@ will ask whether to save modifications, otherwise it won't
     end
     
 =begin rdoc
-Asks the user whether to save the modified documents and saves the chosen ones.
-Returns *true* all the selected documents where saved and *false* if some of the
-document couldn't be saved.
-MOVE: this should be moved to DocumentList, as there might be documents without
-a window
+Override of {PluginLike#query_close}
+
+It stores the session data retrieved by the component manager in case of session
+saving and does nothing otherwise.
+
+@return [TrueClass]
 =end
     def query_close
       if Ruber[:app].session_saving
@@ -394,18 +608,26 @@ a window
     end
     
 =begin rdoc
-Provides a standard interface to creating a project from a project file named _file_, automatically
-handling the possible exceptions. In particular, a message box will be displayed
-if the project file doesn't exist or if it exists but it's not a valid project file.
-A message box is also displayed if <i>allow_reuse</i> is *false* and the project
-list already contains a project corresponding to _file_. In all cases in which a
-message box is displayed *nil* is returned. Otherwise, the +Project+ object
-corresponding to +file+ is returned.
-
-If a project was created from the project file, it will be made active and the
-old active project (if any) will be closed.
-
-<b>Note:</b> _file_ must be an absolute path.
+Opens a project, displaying amessage boxe in case of errors
+
+This method provides a standard interface for creating a project from a project
+file named, automatically handling the possible exceptions.
+    
+In particular, a message box will be displayed if the project file doesn't exist
+or if it exists but it's not a valid project file.
+
+If the project corresponding to the given file is already open, the behaviour
+depends on the value of _allow_reuse_. If *false*, the user is warned with a message
+box that the project is already open and nothing is done. If _allow_reuse_ is
+*true*, the existing project is returned.
+
+The new project will be made active and the existing one (if any) will be closed
+@param [String] file the absolute path of the project file to open
+@param [Boolean] allow_reuse what to do in case the project associated to _file_
+  is already open. If *true*, the existing project will be returned; if *false*,
+  the user will be warned and *nil* will be returned
+@return [Project,nil] the project associated with _file_ or *nil* if an error occurs
+  (including the project being already open in case _allow_reuse_ is *false*)
 =end
     def safe_open_project file, allow_reuse = false
       prj = Ruber[:projects][file]
@@ -415,38 +637,39 @@ old active project (if any) will be closed.
         return nil
       elsif prj then return prj
       end
+      message = nil
       begin prj = Ruber[:projects].project file
       rescue Project::InvalidProjectFile => ex
-        text = <<-EOS
-#{file} isn't a valid project file. The error reported was:
-#{ex.message}
-        EOS
-        KDE::MessageBox.sorry self, KDE.i18n(text)
-        return nil
-      rescue LoadError
-        KDE::MessageBox.sorry self, KDE.i18n(ex.message)
-        return nil
+        text = "%s isn't a valid project file. The error reported was:\n%s"
+        message = KDE.i18n(text) % [file, ex.message]
+      rescue LoadError then message = KDE.i18n(ex.message)
+      end
+      if prj
+        # The following two lines should be removed when we'll allow more than one project
+        # open at the same time
+        Ruber[:projects].current_project.close if Ruber[:projects].current_project
+        Ruber[:projects].current_project = prj
+        prj
+      else
+        KDE::MessageBox.sorry self, message
+        nil
       end
-# The following two lines should be removed when we'll allow more than one project
-# open at the same time
-      Ruber[:projects].current_project.close if Ruber[:projects].current_project
-      Ruber[:projects].current_project = prj
-      prj
     end
 
 =begin rdoc
-Saves recent files and projects, the position of the splitters and the size of
+Override of {PluginLike#save_settings}
+
+It saves recent files and projects, the position of the splitters and the size of
 the window.
 
-TODO: since restoring window position seems to work correctly in Kate (even if
-there's still an open bug, it seems to work, at least for me) see whether it's
-still necessary to store the window size.
+@return [nil]
 =end
     def save_settings
       @workspace.store_sizes
-# TODO use Ruber[:config] as soon as it works
-#       config = Ruber[:config].kconfig
-      config = KDE::Global.config
+# TODO see if the following line works. Otherwise, remove it and uncomment the one
+# following it
+      config = Ruber[:config].kconfig
+#       config = KDE::Global.config
       recent_files = KDE::ConfigGroup.new config, 'Recent files'
       action_collection.action("file_open_recent").save_entries recent_files
       recent_projects = KDE::ConfigGroup.new config, 'Recent projects'
@@ -454,52 +677,71 @@ still necessary to store the window size.
       config.sync
       c = Ruber[:config][:main_window]
       c.window_size = rect.size
+      nil
     end
     
 =begin rdoc
-Loads the settings (in particular, the default script directory and the
-default project directory)
+Override of {PluginLike#load_settings}
+@return [nil]
 =end
     def load_settings
       c = Ruber[:config][:general]
       @default_script_dir = KDE::Url.from_path c.default_script_directory
       @default_project_dir = KDE::Url.from_path c.default_project_directory
+      @tabs.tabs_closable = Ruber[:config][:workspace, :close_buttons] if @tabs
+      nil
     end
     
 =begin rdoc
-Gives the focus to the current editor view. _ed_ can be:
-* an EditorView
-* any argument acceptable by <tt>editor_for!</tt>
-* *nil*
-In the first two cases, the editor corresponding to _ed_ is activated and given
-focus; in the last case the active editor is given focus.
+Gives focus to an editor view
+
+Giving focus to the editor implies:
+* bringing the tab containing it to the foreground
+* activating the editor
+* giving focus to the editor
+
+@overload focus_on_editor
+  Gives focus to the active editor
+  @return [EditorView,nil]
+@overload focus_on_editor editor
+  @param [EditorView] editor the editor to give focus to
+  @return [EditorView,nil]
+@overload focus_on_editor doc, hints = DEFAULT_HINTS
+  @param [Document, String, KDE::Url] doc the document. If it is a string representing
+    a relative path, it'll be considered relative to the current directory. If the
+    string is an Url, it'll be interpreted as such
+  @param [Hash] hints options to tailor the algorithm used to retrieve or create the editor.
+    See {#editor_for!} for a description of the values it can contain
+  @return [EditorView,nil]
+@return [EditorView,nil] the editor which was given focus or *nil* if no editor
+  received focus
 =end  
-    def focus_on_editor ed = nil
+    def focus_on_editor ed = nil, hints = DEFAULT_HINTS
       if ed
-        ed = editor_for! ed unless ed.is_a? EditorView
-        activate_editor ed if ed
+        ed = editor_for! ed, hints unless ed.is_a? EditorView
+        activate_editor ed
+        ed.set_focus
+      else active_editor.set_focus if active_editor
       end
-      @active_editor.set_focus if @active_editor
+      active_editor
     end
-    
-=begin rdoc
-The directory where to save files which don't belong to a project
-=end
-#     def scripts_directory
-#       @default_script_dir
-#     end
-    
+        
 =begin rdoc
-The directory where to create new projects by default
+@return [String] the default directory where to look for, and create, projects
 =end
     def projects_directory
       @default_project_dir
     end
     
 =begin rdoc
-Executes the action with name _action_ contained in the main window's action collection.
+Executes a given action
+
+@param [String] name the name by which the action has been registered in the
+  main window's @action_collection@
+@param [Array] args a list of parameters to pass to the signal or slot associated
+  to the action
 
-See <tt>GuiPlugin#execute_action</tt> for more details
+@see GuiPlugin#execute_action
 =end
     def execute_action name, *args
       data = plugin_description.actions[name.to_s]
@@ -518,6 +760,20 @@ See <tt>GuiPlugin#execute_action</tt> for more details
       else false
       end
     end
+   
+=begin rdoc
+Settings widget for the workspace group
+=end
+    class WorkspaceSettingsWidget < Qt::Widget
+=begin rdoc
+@param [Qt::Widget,nil] parent the parent widget
+=end
+      def initialize parent = nil
+        super
+        @ui = Ui::WorkspaceSettingsWidgetBase.new
+        @ui.setup_ui self
+      end
+    end
     
   end