Module: Ruber::PluginLike

Included in:
Application, ConfigManager, MainWindow, Plugin, World::World
Defined in:
lib/ruber/plugin_like.rb

Overview

Module providing basic functionality common to both plugin and core components.

This mainly is an helper module, used to avoid code duplication among the Plugin class and the various core components (Application, MainWindow and so on which *can’t* inherit from Plugin). From a logical point of view, all of the functionality provided by this module should be in the Plugin class, instead.

Note: this module MUST only be included in classes which descend from @Qt::Object@, otherwise it will produce crashes

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#plugin_description ⇒ PluginSpecification (readonly)

Returns the plugins specification object for the plugin.

Returns:



40
41
42
 
# File 'lib/ruber/plugin_like.rb', line 40

def plugin_description
  @plugin_description
end

Instance Method Details

#add_extensions_to_project(prj, forbid_existing = true) ⇒ nil

Adds the project extensions provided by the plugin to a project

Only the extensions matching the project will be added.

If the project already has one of the extensions this method wouold add, it can either raise an exception or ignore the exception. The first behaviour is desirable the first time the plugin’s extensions are added to the project, while the second is useful if this method has already been called for the project. In the first case, the existing extension most likely belongs to another plugin, which may lead to conflict. In the second case, instead, the extension will belong to this plugin, so there’s no risk.

an extension already exists in the project. one of the extension which this method would add

Parameters:

  • prj (Ruber::AbstractProject) —

    the project to add the extensions to

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

    whether to raise an exception or do nothing if

Returns:

  • (nil)

Raises:

  • ArgumentError if forbid_existing is true and the project already has

See Also:



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/ruber/plugin_like.rb', line 287

def add_extensions_to_project prj, forbid_existing = true
  @plugin_description.extensions.each_pair do |name, o|
    unless forbid_existing
      next if prj.extension name
    end
    ext = nil
    if o.is_a? Array
      o = o.find{|i| prj.match_rule? i}
      next unless o
      ext = o.class_obj.new prj
    elsif prj.match_rule? o
      ext = o.class_obj.new prj
    end
    if ext
      ext.plugin = self
      prj.add_extension name, ext
      emit extension_added(name.to_s, prj) rescue nil
    end
  end
end

#add_options_to_project(prj, forbid_existing = true) ⇒ nil

Adds the project options provided by the plugin to a project

Only the options whose rules match the project are added.

If one of the options provided by the plugin (and whose rules matches the project) has already been inserted in the project, this method can either raise an exception or ignore the option. The first behaviour is desirable the first time the plugin’s options are added to the project, while the second is useful if this method has already been called for the project. In the first case, the existing option most likely belongs to another plugin, which may lead to conflict. In the second case, instead, the option will belong to this plugin, so there’s no risk.

an option already exists in the project. by the plugin already exists

Parameters:

  • prj (Ruber::AbstractProject) —

    the project to add the options to

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

    whether to raise an exception or do nothing if

Returns:

  • (nil)

Raises:

  • ArgumentError if forbid_existing is true and one of the options provided

See Also:



196
197
198
199
200
201
202
203
204
205
 
# File 'lib/ruber/plugin_like.rb', line 196

def add_options_to_project prj, forbid_existing = true
  @plugin_description.project_options.values.sort_by{|i| i.order || 0}.each do |o|
    o = o.to_os(prj.obj_binding)
    begin prj.add_option o if prj.match_rule?(o)
    rescue ArgumentError
      raise if forbid_existing
    end
  end
  nil
end

#add_widgets_to_project(prj) ⇒ nil

Adds the project widgets provided by the plugin to a project

Only the widgets matching the project will be added.

Parameters:

Returns:

  • (nil) 


246
247
248
249
250
251
 
# File 'lib/ruber/plugin_like.rb', line 246

def add_widgets_to_project prj
  @plugin_description.project_widgets.each do |w| 
    prj.add_widget w if prj.match_rule? w
  end
  nil
end

#plugin_name ⇒ Symbol Also known as: component_name

Returns the internal name of the plugin.

Returns:

  • (Symbol) —

    the internal name of the plugin



45
46
47
 
# File 'lib/ruber/plugin_like.rb', line 45

def plugin_name
  @plugin_description.name
end

#query_close ⇒ Boolean

Whether or not the plugin allows the application to shut down

If this method returns false for any plugin, the application won’t be closed.

maybe depending on the status of the plugin itself. As an example, the Document List component checks whether there are unsaved documents and asks the user what to do. If the user decides not to close the appplication, the method will return false.

Returns:

  • (Boolean) —

    true. Plugins may override this method and return something else,



108
109
110
 
# File 'lib/ruber/plugin_like.rb', line 108

def query_close
  true
end

#register_with_project(prj) ⇒ nil

Informs a project of the existance of the plugin

The base class implemenetation adds all the known project options, poject widgets and project extensions to the project. If a plugin needs to do something fancy with projects, it can override this method and do it from here, after calling the base class implementation.

Parameters:

Returns:

  • (nil) 


359
360
361
362
363
 
# File 'lib/ruber/plugin_like.rb', line 359

def register_with_project prj
  add_options_to_project prj, true
  add_widgets_to_project prj
  add_extensions_to_project prj, true
end

#remove_extensions_from_project(prj, all = true) ⇒ nil

Remove the extensions provided by the pluging from a project

Depending on the value of all, all the extensions provided by the plugin or only the ones which dont’ match the project are removed. In this case, a multi-class extension will only be removed if the class of the extension object is the same as the one specified in one of the entries which don’t match the project.

Note: to decide whether an extension belongs to the plugin or not, this method checks whether the object returned by the exension’s @plugin@ method is the same as @self@.

only those which don’t match the project

Parameters:

  • prj (Ruber::AbstractProject) —

    the project to remove the extensions from

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

    whether to remove all extensions provided by the plugin or

Returns:

  • (nil)

See Also:



326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/ruber/plugin_like.rb', line 326

def remove_extensions_from_project prj, all = true
  if all
    prj.each_extension.select{|_, v| v.plugin.same? self}.each do |k, _|
      emit removing_extension k.to_s, prj rescue nil
      prj.remove_extension k
      emit extension_removed k.to_s, prj rescue nil
    end
  else
    exts = @plugin_description.extensions
    prj.each_extension.select{|_, v| v.plugin.same? self}.each do |k, o|
      data = exts[k]
      data = data.find{|i| i.class_obj == o.class} if data.is_a? Array
      if !prj.match_rule? data
        emit removing_extension k.to_s, prj rescue nil
        prj.remove_extension k
        emit extension_removed k.to_s, prj rescue nil
      end
    end
  end
  nil
end

#remove_from_project(prj) ⇒ nil

Removes all traces of the plugin from a project

This method is called when the plugin is unloaded or when the project is closed and takes care of removeing all project options, project widgets and project extensions belonging to the plugin from the project.

If a plugin needs to do some other cleanup when removed from a project, it can override this method and do what it needs here (usually before calling super)

Parameters:

Returns:

  • (nil) 


377
378
379
380
381
 
# File 'lib/ruber/plugin_like.rb', line 377

def remove_from_project prj
  remove_options_from_project prj, true
  remove_widgets_from_project prj
  remove_extensions_from_project prj, true
end

#remove_options_from_project(prj, matching = true) ⇒ nil

Removes the project options provided by the plugin from a project

This method can operate in two ways: it can remove from the project all the options it provides whose rules match or don’t match the project. The first behaviour is meant to be used when the plugin is unloaded or the project is closed; the second when the project characteristics change, to remove those options which used to match the project but don’t anymore.

Parameters:

  • prj (Ruber::AbstractProject) —

    the project to remove options from

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

    whether to remove only

Returns:

  • (nil)

See Also:



221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/ruber/plugin_like.rb', line 221

def remove_options_from_project prj, matching = true
  if matching
    @plugin_description.project_options.each_pair do |_, o|
      o = o.to_os(prj.obj_binding)
      prj.remove_option o.group, o.name if prj.match_rule? o
    end
  else
    @plugin_description.project_options.each_pair do |_, o|
      o = o.to_os(prj.obj_binding)
      if prj.has_option?(o.group, o.name) and !prj.match_rule? o
        prj.remove_option o.group, o.name
      end
    end
  end
  nil
end

#remove_widgets_from_project(prj) ⇒ nil

Removes the project widgets provided by the plugin from a project

Parameters:

Returns:

  • (nil) 


259
260
261
262
263
264
 
# File 'lib/ruber/plugin_like.rb', line 259

def remove_widgets_from_project prj
  @plugin_description.project_widgets.each do |w| 
    prj.remove_widget w
  end
  nil
end

#restore_session(cfg) ⇒ Object

Restores the state of the plugin from session management

This method is called by the component manager when a session needs to be restored. Plugins need to override it if they have some state which needs to be restored (there’s no need to call super when overriding, since the base class method does nothing)

Parameters:

  • cfg (Hash) —

    a hash containing the keys stored in the hash returned by #session_data

See Also:



157
158
 
# File 'lib/ruber/plugin_like.rb', line 157

def restore_session cfg
end

#save_settings ⇒ nil

Method called at application shutdown to allow plugins to save their settings

Plugins which need to save some settings need to override this method, as the base class implementation does nothing.

Note: the plugin system calls this method for all plugins before starting unloading them. This means that it’s absolutely safe to access other plugins’ methods, objects, options,… from here

Returns:

  • (nil) 


123
124
125
 
# File 'lib/ruber/plugin_like.rb', line 123

def save_settings
  nil
end

#session_data ⇒ Hash

The data the plugin wants to store when the application is shut down by session management

session manager. The hash returned by this method is empty, so plugin which need to store some information need to override it. Note that the hashes returned by this method from various plugins are merged. To avoid name clashes, you should use unique names for the keys in the hashes. The best way to do this is to return a hash with a single key, named after the plugin, and corresponding to an inner hash containing the information you actually need to store

Returns:

  • (Hash) —

    a hash containing the information which should be stored by the

See Also:



141
142
143
 
# File 'lib/ruber/plugin_like.rb', line 141

def session_data
  {}
end

#shutdown ⇒ nil

Does the required cleanup before the application closes.

This method is also called when the plugin is unloaded when the application is running (for example because the user deselects it from the Choose Plugin dialog). This happens because usually the #unload method needs to do all #shutdown does and more. In the rare eventuality you need to do something before closing the application which shouldn’t be done when unloading the plugin, you can check Application#status and see whether it’s set to @:running@, which means the plugin is being unloaded, or to @:quitting@, which means the application is being closed.

The base class version of this method does nothing.

Returns:

  • (nil) 


65
66
 
# File 'lib/ruber/plugin_like.rb', line 65

def shutdown
end

#unload ⇒ nil

Method called before the plugin is unloaded. It is used to do any needed cleanup.

This method should be overridden by any plugin which needs to do custom cleanup, but it’s important that the base class’s version of the method is called as well (most likely after the custom part).

This basic implementation does the following:

  • calls #shutdown

  • disconnects the #load_settings slot from the config manager Config#settings_changed signal

  • removes all the options belonging to the plugin from the config manager

  • removes all tool widgets belonging to the plugin from the main window

Returns:

  • (nil) 


83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/ruber/plugin_like.rb', line 83

def unload
  shutdown
  if Ruber[:config]
    disconnect Ruber[:config], SIGNAL('settings_changed()'), self, SLOT('load_settings()')
    @plugin_description.config_options.each_key do |g, n| 
      Ruber[:config].remove_option(g.to_sym, n)
    end
  end
  @plugin_description.tool_widgets.each do |w| 
    Ruber[:main_window].remove_tool w.name if w.name
  end
  nil
end

#update_project(prj) ⇒ nil

Ensures that all the project options, widgets and extensions which are provided by the plugin and match the project have been added to it and that none which doesn’t match it have been added

This method is called when one of the characteristics of the project the rules take into account change, so that the plugin always add to the project all the pertinent content

Parameters:

Returns:

  • (nil) 


394
395
396
397
398
399
400
401
 
# File 'lib/ruber/plugin_like.rb', line 394

def update_project prj
  remove_options_from_project prj, false
  add_options_to_project prj, false
  remove_widgets_from_project prj
  add_widgets_to_project prj
  remove_extensions_from_project prj, false
  add_extensions_to_project prj, false
end