Class: Ruber::GuiPlugin

Inherits:
Plugin show all
Defined in:
lib/ruber/plugin.rb

Overview

Base class for all plugins which provide a GUI (that is, menu or toolbar entries).

Direct Known Subclasses

ExternalProgramPlugin, RubyRunner::RubyInterpretersPlugin

Constant Summary

Constants inherited from Plugin

LICENSES

Instance Attribute Summary

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, #load_settings, #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, #shutdown, #update_project

Constructor Details

- (GuiPlugin) initialize(psf)

Creates an instance and initializes the GUI with the plugin

Parameters:



134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/ruber/plugin.rb', line 134

def initialize psf
  super
  @gui = KDE::XMLGUIClient.new Ruber[:main_window]
  @gui.send :set_XML_file, psf.ui_file
# TODO when the KDE::ComponentData which takes a KDE::AboutData constructor
# works, construct the KDE::ComponentData using the value returned by the about_data
# method. As the following lines are (hopefully) temporarily, I only add the minimum
# to make the plugins show correctly in the shortcuts editor dialog.
  @gui.component_data = KDE::ComponentData.new Qt::ByteArray.new(plugin_name.to_s)
  data = @gui.component_data.about_data
  data.program_name = KDE.ki18n(@plugin_description.about.human_name)
  setup_actions
  Ruber[:main_window].factory.add_client @gui
end

Instance Method Details

- (KDE::ActionCollection) action_collection

The action collection used to contain the plugin’s actions

Returns:

  • (KDE::ActionCollection) —

    the action collection used to contain the plugin’s actions



161
162
163
 
# File 'lib/ruber/plugin.rb', line 161

def action_collection
  @gui.action_collection
end

- (Boolean) execute_action(name, *args)

Executes the action with a given name, if it belongs to the plugin’s action collection

To execute the action, this method first checks whether it is included in the actions entry of the PSF. If so, then the associated slot is directly called, passing *args as argument. If the action is not included in that entry, then the action object is forced to emit a signal according to its class: toggled(bool) for a KDE::ToggleAction, triggered() for a KDE::Action, and @triggered(*args) for all other actions.

If a plugin needs a different behaviour, for example because the slot connected to the action uses Qt::Object.sender, and thus can only be called from a signal, you’ll need to override this method and have the action emit the signal. To do so, you can use the following code:

bc.

a = action_collection.action(name) a.instance_evalsignal_name(arg)

where name is the name of the action, signal_name is the name of the signal to emit and arg is the argument of the signal (you can pass more than one argument, if needed).

If the slot is called directly, args are the arguments to be passed to the slot. If the signal is emitted, args are the arguments passed to the signal.

Note: emitting the signal can (in rare cases) have unwanted results. This can happen if there are more than one slot connected to the signal, in which case all of them will be called. Usually, this shouldn’t be an issue since it’s common to connect only one signal to each action, but it can happen. This is why this method prefers to call the slot directly, whenever possible.

Parameters:

  • name (String, Symbol) —

    the name of the action to execute

  • args (<Object>) —

    the arguments to pass to the slot or the signal

Returns:

  • (Boolean) —

    true if an action called name was found and false otherwise



202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/ruber/plugin.rb', line 202

def execute_action name, *args
  data = plugin_description.actions[name.to_s]
  if data
    slot = data.slot.sub(/\(.*/, '')
    instance_eval(data.receiver).send slot, *args
    true
  elsif (action = action_collection.action(name))
    if action.class == KDE::ToggleAction then KDE::ToggleAction
      action.instance_eval{emit toggled(*args)}
    elsif action.class == KDE::Action 
      action.instance_eval{emit triggered()}
    else action.instance_eval{emit triggered(*args)}
    end
    true
  else false
  end
end

- (nil) register_action_handler(name, check = true, &blk) (private)

Registers an UI action handler with the main window

It works like Ruber::GuiStatesHandler#register_action_handler but doesn’t require to specify neither the plugin (which will be self) nor the action object, which will be retrieved from the plugin’s action collection nor the states which are taken from the states entry of the PSF entry corresponding to the action

Note: to use this method, the action description in the PSF must include the states entry (the state entry isn’t used).

when the action handler is registered changes

Parameters:

  • name (String) —

    the name of the action for which the action handler is registered

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

    whether or not the state of the action should be checked

  • blk (Proc) —

    the block to call when one of the states the action depends on

Returns:

  • (nil)

See Also:



252
253
254
255
256
257
258
259
 
# File 'lib/ruber/plugin.rb', line 252

def register_action_handler name, check = true, &blk
  action = @gui.action_collection.action name
  states = @plugin_description.actions[name].states
  if action
    Ruber[:main_window].register_action_handler action, states, :check => check, :extra_id => self, &blk
  end
  nil
end

- (nil) setup_actions (private)

Override of PluginLike#setup_actions

It works as the base class method but doesn’t need the action collection

Returns:

  • (nil) 


229
230
231
 
# File 'lib/ruber/plugin.rb', line 229

def setup_actions
  super @gui.action_collection
end

- (nil) unload

Removes the GUI provided by this plugin from the application’s GUI

Returns:

  • (nil) 


153
154
155
156
 
# File 'lib/ruber/plugin.rb', line 153

def unload
  @gui.factory.remove_client @gui
  super
end