Class: Ruber::Autosave::AutosavePlugin

Inherits:
Plugin show all
Defined in:
plugins/autosave/autosave.rb

Overview

Plugin class for the autosave plugin.

Constant Summary

Constants inherited from Plugin

LICENSES

Instance Attribute Summary (collapse)

Attributes included from PluginLike

plugin_description

Instance Method Summary (collapse)

Methods inherited from Plugin

#about_data

Methods included from PluginLike

#add_extensions_to_project, #add_options_to_project, #add_widgets_to_project, #create_tool_widget, #delayed_initialize, #initialize_plugin, #plugin_name, #query_close, #register_options, #register_with_project, #remove_extensions_from_project, #remove_from_project, #remove_options_from_project, #remove_widgets_from_project, #restore_session, #save_settings, #session_data, #setup_action, #setup_actions, #shutdown, #unload, #update_project

API for feature autosave

Methods API

Constructor Details

- (AutosavePlugin) initialize(pdf)

Creates a new instance

Parameters:



96
97
98
99
100
101
102
103
104
 
# File 'plugins/autosave/autosave.rb', line 96

def initialize pdf
  @registered_plugins = {}
  @enabled = true
  @settings = {}
  super
  Ruber[:components].connect SIGNAL('unloading_component(QObject*)') do |c|
    @registered_plugins.delete c.component_name
  end
end

Instance Attribute Details

- (Hash) registered_plugins (readonly)

autosaving is enabled for them as keys

Returns:

  • (Hash) —

    a hash which has the names of registered plugins as keys and whether



89
90
91
 
# File 'plugins/autosave/autosave.rb', line 89

def registered_plugins
  @registered_plugins
end

Instance Method Details

- (Boolean) autosave(plug, what, opts = {}, &blk)

Autosaves the given documents or files.

This is the main method of this class. Whenever a plugin wants some documents to be autosaved, it calls this method passing itself as first argument and a list of the documents to save (or one of the special symbols listed below) as second argument and, optionally some options or a block.

If autosaving is enabled both globally and for the plugin, an attempt will be made to save all the specified documents. If one or more documents can’t be saved, the behaviour depends on the third and fourth argument. If autosaving is disabled, either globally or for the given plugin, this method does nothing.

or its name or one of the symbols listed below.

  • :open_documents: autosave all the open documents (including those which aren’t associated with a file)
  • :documents_with_file: autosave all the open documents which are associated with a file
  • :project_files: autosave all the open documents corresponding to a file belonging to the current project. Note that using this value when there’s no active global project leads to undefined behaviour.

documents can’t be saved.

be saved. If given, it will be given an array containing the unsaved documents as argument.

as soon as one fails to save. By default, this method attempts to save all given documents, regardless of whether saving the other documents was successful or not. (this option will be ignored if a block has been given). It can have the following values:

  • :warn: an information message box describing the error is displayed
  • :ask: a Yes/No message box describing he error is displayed. The return value of the method depends on the choice made by the user

the message box displayed if the :on_failure option is :warn or :ask. If the message box is a Yes/No one, most likely you’ll need to specify this option to describe what will happen if the user chooses Yes and what happens if he chooses No.

was disabled either globally or for the specific plugin. If some documents couldn’t be saved, this method returns false, unless

  • a block was given. In this case, the return value of the block is returned
  • the :on_failure option is :ask. In this case, the returned value is true if the user chose Yes in the message box and false otherwise.

Parameters:

  • plug (PluginLike, Symbol) —

    the plugin requesting to autosave the documents

  • what (<Document>, Symbol) —

    either an array with the documents to autosave

  • opts (Hash) (defaults to: {}) —

    a hash which fine tunes the behaviour in case one of the specified

  • blk (Proc) —

    a block which will be called if some of the documents couldn’t

Options Hash (opts):

  • :stop_on_failure (Boolean) — default: false —

    whether to stop saving documents

  • :on_failure (Symbol) — default: nil —

    what to do if some documents can’t be saved

  • message (String) —

    nil custom text to add to the default message in

Returns:

  • (Boolean) —

    true if all the documents were saved successfully or if autosaving



218
219
220
221
222
223
224
 
# File 'plugins/autosave/autosave.rb', line 218

def autosave plug, what, opts = {}, &blk
  plug = plug.plugin_name if plug.is_a? PluginLike
  return true unless @enabled and @registered_plugins[plug]
  if what.is_a? Array then save_files what, opts, blk
  else send "save_#{what}", opts, blk
  end
end

- (void) load_settings (private)

This method returns an undefined value.

Loads the settings



150
151
152
153
 
# File 'plugins/autosave/autosave.rb', line 150

def load_settings
  super
  @remote_files_policy = Ruber[:config][:autosave, :remote_files]
end

- (Object) register_plugin(plug, default = true)

Makes another plugin known to Autosave.

If the configuration file already has an entry for the plugin plug in the autosave/plugins setting, autosaving will be enabled or not basing on that value. If there’s not such an entry, then autosaving will be enabled if default is true and disabled otherwise.

Note: you have to register a plugin before calling the #autosave method for it.

if the configuration file doesn’t have an entry for it

Parameters:

  • plug (PluginLike, Symbol) —

    the plugin to register or its name

  • default (Boolean) (defaults to: true) —

    whether or not autosaving should be enabled for plug



121
122
123
124
125
126
 
# File 'plugins/autosave/autosave.rb', line 121

def register_plugin plug, default = true
  plug = plug.plugin_name if plug.is_a? PluginLike
  val = @settings.fetch plug, default
  @registered_plugins[plug] = val
  val
end

- (Object) remove_plugin(plug)

Removes a plugin from the list of registered plugins.

Usually, there’s no need to use this method, as registered plugins are automatically removed whenever they’re unloaded.

Note: you can’t call the #autosave method for a plugin which has been removed using this method.

list or its name

Parameters:

  • plug (PluginLike, Symbol) —

    the name of the plugin to remove from the autosave



140
141
142
143
 
# File 'plugins/autosave/autosave.rb', line 140

def remove_plugin plug
  plug = plug.plugin_name if plug.is_a? PluginLike
  @registered_plugins.delete plug
end

- (Boolean) save_doc(doc) (private)

Attempts to save a document

If the document is associated with a remote file, the behaviour will change depending on the value of the autosave/remote_files settings:

  • if it’s :skip then nothing will be done
  • if it’s :ignore then an attempt to save the document will be done, but any failures will be ignored
  • if it’s :normal then the behaviour will be the same as for a local file

Parameters:

  • doc (Document) —

    the document to save

Returns:

  • (Boolean) —

    true if the document was saved successfully and false otherwise. in case of a remote document, it will always return true except when the autosave/remote_files option is set to :normal



339
340
341
342
343
344
345
346
347
348
349
350
 
# File 'plugins/autosave/autosave.rb', line 339

def save_doc doc
  if doc.url.local_file? or doc.url.relative? then doc.save
  else
    case @remote_files_policy
    when :skip then true
    when :ignore
      doc.save
      true
    else doc.save
    end
  end
end

- (Boolean) save_documents_with_file(opts, blk) (private)

Attempts to save all the open documents corresponding to a file.

This method should only be called if autosaving is enabled because it doesn’t take into account the enabled option and always attempt to save the documents.

Parameters:

Returns:



269
270
271
 
# File 'plugins/autosave/autosave.rb', line 269

def save_documents_with_file opts, blk
  save_files Ruber[:world].documents.documents_with_file, opts, blk
end

- (Boolean) save_files(docs, opts, blk) (private)

Attempts to save the documents contained in the array docs.

This method should only be called if autosaving is enabled because it doesn’t take into account the enabled option and always attempt to save the documents.

Parameters:

Returns:



284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
 
# File 'plugins/autosave/autosave.rb', line 284

def save_files docs, opts, blk
  unsaved = []
  docs.each_with_index do |d, i|
    unless save_doc d
      unsaved << d
      if opts[:stop_on_failure]
        unsaved += docs[(i+1)..-1]
        break
      end
    end
  end
  msg = <<-EOS
The following documents couldn't be saved:
#{
  unsaved.map{|d| d.path.empty? ? d.document_name : d.path}
}
  EOS
  if unsaved.empty? then return true
  elsif blk then return blk.call unsaved
  else
    case opts[:on_failure]
    when :warn
      msg << "\n#{opts[:message]}" if opts[:message]
      KDE::MessageBox.sorry Ruber[:main_window], msg
    when :ask
      msg << "\n#{opts[:message]||'Do you want to go on?'}"
      ans = KDE::MessageBox.question_yes_no Ruber[:main_window], msg
      return true if ans == KDE::MessageBox::Yes
    end
  end
  false
end

- (Boolean) save_open_documents(opts, blk) (private)

Attempts to save all the open documents.

This method should only be called if autosaving is enabled because it doesn’t take into account the enabled option and always attempt to save the documents.

Parameters:

Returns:



255
256
257
 
# File 'plugins/autosave/autosave.rb', line 255

def save_open_documents opts, blk
  save_files Ruber[:world].documents, opts, blk
end

- (Boolean) save_project_files(opts, blk) (private)

Attempts to save all the open documents corresponding to a file belonging to the current project.

This method should only be called if autosaving is enabled because it doesn’t take into account the enabled option and always attempt to save the documents.

Parameters:

Returns:



238
239
240
241
242
243
 
# File 'plugins/autosave/autosave.rb', line 238

def save_project_files opts, blk
  docs = Ruber[:world].active_environment.documents.documents_with_file
  prj_files = Ruber[:world].active_project.project_files
  docs = docs.select{|d| prj_files.include? d.path}
  save_files docs, opts, blk
end