API reference - Class PluginFactory

Notation used in Ruby API documentation

Module: lay

Description: The plugin framework's plugin factory object

Plugins are components that extend KLayout's functionality in various aspects. Scripting support exists currently for providing mouse mode handlers and general on-demand functionality connected with a menu entry.

Plugins are objects that implement the Plugin interface. Each layout view is associated with one instance of such an object. The PluginFactory is a singleton which is responsible for creating Plugin objects and providing certain configuration information such as where to put the menu items connected to this plugin and what configuration keys are used.

An implementation of PluginFactory must at least provide an implementation of create_plugin. This method must instantiate a new object of the specific plugin.

After the factory has been created, it must be registered in the system using one of the register methods. It is therefore recommended to put the call to register at the end of the "initialize" method. For the registration to work properly, the menu items must be defined before register is called.

The following features can also be implemented:

This is a simple example for a plugin in Ruby. It switches the mouse cursor to a 'cross' cursor when it is active:

class PluginTestFactory < RBA::PluginFactory

  # Constructor
  def initialize
    # registers the new plugin class at position 100000 (at the end), with name
    # "my_plugin_test" and title "My plugin test"
    register(100000, "my_plugin_test", "My plugin test")
  end
  
  # Create a new plugin instance of the custom type
  def create_plugin(manager, dispatcher, view)
    return PluginTest.new
  end

end

# The plugin class
class PluginTest < RBA::Plugin
  def mouse_moved_event(p, buttons, prio)
    if prio
      # Set the cursor to cross if our plugin is active.
      set_cursor(RBA::Cursor::Cross)
    end
    # Returning false indicates that we don't want to consume the event.
    # This way for example the cursor position tracker still works.
    false
  end
  def mouse_click_event(p, buttons, prio)
    if prio
      puts "mouse button clicked."
      # This indicates we want to consume the event and others don't receive the mouse click
      # with prio = false.
      return true
    end
    # don't consume the event if we are not active.
    false
  end
end

# Instantiate the new plugin factory.
PluginTestFactory.new

This class has been introduced in version 0.22.

Public constructors

new PluginFactory ptrnewCreates a new object of this class

Public methods

void_createEnsures the C++ object is created
void_destroyExplicitly destroys the object
[const]bool_destroyed?Returns a value indicating whether the object was already destroyed
[const]bool_is_const_object?Returns a value indicating whether the reference is a const reference
void_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
voidadd_config_menu_item(string menu_name,
string insert_pos,
string title,
string cname,
string cvalue)
Adds a configuration menu item
voidadd_menu_entry(string menu_name,
string insert_pos)
Specifies a separator
voidadd_menu_entry(string symbol,
string menu_name,
string insert_pos,
string title)
Specifies a menu item
voidadd_menu_item_clone(string symbol,
string menu_name,
string insert_pos,
string copy_from)
Specifies a menu item as a clone of another one
voidadd_option(string name,
string default_value)
Specifies configuration variables.
voidadd_submenu(string menu_name,
string insert_pos,
string title)
Specifies a menu item or sub-menu
[virtual]voidconfig_finalizeGets called after a set of configuration events has been sent
[virtual]boolconfigure(string name,
string value)
Gets called for configuration events for the plugin singleton
[virtual,const]new Plugin ptrcreate_plugin(Manager ptr manager,
Dispatcher ptr dispatcher,
LayoutView ptr view)
Creates the plugin
voidhas_tool_entry=(bool f)Enables or disables the tool bar entry
[virtual]voidinitialized(Dispatcher ptr dispatcher)Gets called when the plugin singleton is initialized, i.e. when the application has been started.
[virtual,const]boolmenu_activated(string symbol)Gets called when a menu item is selected
voidregister(int position,
string name,
string title)
Registers the plugin factory
voidregister(int position,
string name,
string title,
string icon)
Registers the plugin factory
[virtual]voiduninitialized(Dispatcher ptr dispatcher)Gets called when the application shuts down and the plugin is unregistered

Deprecated methods (protected, public, static, non-static and constructors)

voidadd_menu_entry(string symbol,
string menu_name,
string insert_pos,
string title,
bool sub_menu)
Use of this method is deprecated
voidcreateUse of this method is deprecated. Use _create instead
voiddestroyUse of this method is deprecated. Use _destroy instead
[const]booldestroyed?Use of this method is deprecated. Use _destroyed? instead
[const]boolis_const_object?Use of this method is deprecated. Use _is_const_object? instead

Detailed description

_create

Signature: void _create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

_destroy

Signature: void _destroy

Description: Explicitly destroys the object

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

_destroyed?

Signature: [const] bool _destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

_is_const_object?

Signature: [const] bool _is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

_manage

Signature: void _manage

Description: Marks the object as managed by the script side.

After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.

Usually it's not required to call this method. It has been introduced in version 0.24.

_unmanage

Signature: void _unmanage

Description: Marks the object as no longer owned by the script side.

Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.

Usually it's not required to call this method. It has been introduced in version 0.24.

add_config_menu_item

Signature: void add_config_menu_item (string menu_name, string insert_pos, string title, string cname, string cvalue)

Description: Adds a configuration menu item

Menu items created this way will send a configuration request with 'cname' as the configuration parameter name and 'cvalue' as the configuration parameter value.

This method has been introduced in version 0.27.

add_menu_entry

(1) Signature: void add_menu_entry (string menu_name, string insert_pos)

Description: Specifies a separator

Call this method in the factory constructor to build the menu items that this plugin shall create. This specific call inserts a separator at the given position (insert_pos). The position uses abstract menu item paths and "menu_name" names the component that will be created. See AbstractMenu for a description of the path.

(2) Signature: void add_menu_entry (string symbol, string menu_name, string insert_pos, string title)

Description: Specifies a menu item

symbol:The string to send to the plugin if the menu is triggered
menu_name:The name of entry to create at the given position
insert_pos:The position where to create the entry
title:The title string for the item. The title can contain a keyboard shortcut in round braces after the title text, i.e. "My Menu Item(F12)"

Call this method in the factory constructor to build the menu items that this plugin shall create. This specific call inserts a menu item at the specified position (insert_pos). The position uses abstract menu item paths and "menu_name" names the component that will be created. See AbstractMenu for a description of the path. When the menu item is selected "symbol" is the string that is sent to the menu_activated callback (either the global one for the factory ot the one of the per-view plugin instance).

(3) Signature: void add_menu_entry (string symbol, string menu_name, string insert_pos, string title, bool sub_menu)

Description: Specifies a menu item or sub-menu

Use of this method is deprecated

Similar to the previous form of "add_menu_entry", but this version allows also to create sub-menus by setting the last parameter to "true".

With version 0.27 it's more convenient to use add_submenu.

add_menu_item_clone

Signature: void add_menu_item_clone (string symbol, string menu_name, string insert_pos, string copy_from)

Description: Specifies a menu item as a clone of another one

Using this method, a menu item can be made a clone of another entry (given as path by 'copy_from'). The new item will share the Action object with the original one, so manipulating the action will change both the original entry and the new entry.

This method has been introduced in version 0.27.

add_option

Signature: void add_option (string name, string default_value)

Description: Specifies configuration variables.

Call this method in the factory constructor to add configuration key/value pairs to the configuration repository. Without specifying configuration variables, the status of a plugin cannot be persisted.

Once the configuration variables are known, they can be retrieved on demand using "get_config" from MainWindow or listening to configure callbacks (either in the factory or the plugin instance). Configuration variables can be set using "set_config" from MainWindow. This scheme also works without registering the configuration options, but doing so has the advantage that it is guaranteed that a variable with this keys exists and has the given default value initially.

add_submenu

Signature: void add_submenu (string menu_name, string insert_pos, string title)

Description: Specifies a menu item or sub-menu

This method has been introduced in version 0.27.

config_finalize

Signature: [virtual] void config_finalize

Description: Gets called after a set of configuration events has been sent

This method can be reimplemented and is called after a set of configuration events has been sent to the plugin factory singleton with configure. It can be used to set up user interfaces properly for example.

configure

Signature: [virtual] bool configure (string name, string value)

Description: Gets called for configuration events for the plugin singleton

name:The configuration key
value:The value of the configuration variable
Returns:True to stop further processing

This method can be reimplemented to receive configuration events for the plugin singleton. Before a configuration can be received it must be registered by calling add_option in the plugin factories' constructor.

The implementation of this method may return true indicating that the configuration request will not be handled by further modules. It's more cooperative to return false which will make the system distribute the configuration request to other receivers as well.

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

create_plugin

Signature: [virtual,const] new Plugin ptr create_plugin (Manager ptr manager, Dispatcher ptr dispatcher, LayoutView ptr view)

Description: Creates the plugin

manager:The database manager object responsible for handling database transactions
dispatcher:The reference to the MainWindow object
view:The LayoutView that is plugin is created for
Returns:The new Plugin implementation object

This is the basic functionality that the factory must provide. This method must create a plugin of the specific type.

destroy

Signature: void destroy

Description: Explicitly destroys the object

Use of this method is deprecated. Use _destroy instead

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

destroyed?

Signature: [const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

Use of this method is deprecated. Use _destroyed? instead

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

has_tool_entry=

Signature: void has_tool_entry= (bool f)

Description: Enables or disables the tool bar entry

Initially this property is set to true. This means that the plugin will have a visible entry in the toolbar. This property can be set to false to disable this feature. In that case, the title and icon given on registration will be ignored.

Python specific notes:
The object exposes a writable attribute 'has_tool_entry'. This is the setter.

initialized

Signature: [virtual] void initialized (Dispatcher ptr dispatcher)

Description: Gets called when the plugin singleton is initialized, i.e. when the application has been started.

dispatcher:The reference to the MainWindow object

is_const_object?

Signature: [const] bool is_const_object?

Description: Returns a value indicating whether the reference is a const reference

Use of this method is deprecated. Use _is_const_object? instead

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

menu_activated

Signature: [virtual,const] bool menu_activated (string symbol)

Description: Gets called when a menu item is selected

Usually, menu-triggered functionality is implemented in the per-view instance of the plugin. However, using this method it is possible to implement functionality globally for all plugin instances. The symbol is the string registered with the specific menu item in the add_menu_item call.

If this method was handling the menu event, it should return true. This indicates that the event will not be propagated to other plugins hence avoiding duplicate calls.

new

Signature: [static] new PluginFactory ptr new

Description: Creates a new object of this class

Python specific notes:
This method is the default initializer of the object

register

(1) Signature: void register (int position, string name, string title)

Description: Registers the plugin factory

position:An integer that determines the order in which the plugins are created. The internal plugins use the values from 1000 to 50000.
name:The plugin name. This is an arbitrary string which should be unique. Hence it is recommended to use a unique prefix, i.e. "myplugin::ThePluginClass".
title:The title string which is supposed to appear in the tool bar and menu related to this plugin.

Registration of the plugin factory makes the object known to the system. Registration requires that the menu items have been set already. Hence it is recommended to put the registration at the end of the initialization method of the factory class.

(2) Signature: void register (int position, string name, string title, string icon)

Description: Registers the plugin factory

position:An integer that determines the order in which the plugins are created. The internal plugins use the values from 1000 to 50000.
name:The plugin name. This is an arbitrary string which should be unique. Hence it is recommended to use a unique prefix, i.e. "myplugin::ThePluginClass".
title:The title string which is supposed to appear in the tool bar and menu related to this plugin.
icon:The path to the icon that appears in the tool bar and menu related to this plugin.

This version also allows registering an icon for the tool bar.

Registration of the plugin factory makes the object known to the system. Registration requires that the menu items have been set already. Hence it is recommended to put the registration at the end of the initialization method of the factory class.

uninitialized

Signature: [virtual] void uninitialized (Dispatcher ptr dispatcher)

Description: Gets called when the application shuts down and the plugin is unregistered

dispatcher:The reference to the MainWindow object

This event can be used to free resources allocated with this factory singleton.