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.
| new PluginFactory ptr | new | Creates a new object of this class |
| [const] | PluginFactory ptr | _const_cast | Returns a non-const reference to self. | |
| void | _create | Ensures the C++ object is created | ||
| void | _destroy | Explicitly 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 | _manage | Marks the object as managed by the script side. | ||
| void | _unmanage | Marks the object as no longer owned by the script side. | ||
| void | add_config_menu_item | (string menu_name, string insert_pos, string title, string cname, string cvalue) | Adds a configuration menu item | |
| void | add_menu_entry | (string menu_name, string insert_pos) | Specifies a separator | |
| void | add_menu_entry | (string symbol, string menu_name, string insert_pos, string title) | Specifies a menu item | |
| void | add_menu_item_clone | (string symbol, string menu_name, string insert_pos, string copy_from) | Specifies a menu item as a clone of another one | |
| void | add_option | (string name, string default_value) | Specifies configuration variables. | |
| void | add_submenu | (string menu_name, string insert_pos, string title) | Specifies a menu item or sub-menu | |
| [virtual] | void | config_finalize | Gets called after a set of configuration events has been sent | |
| [virtual] | bool | configure | (string name, string value) | Gets called for configuration events for the plugin singleton |
| [virtual,const] | new Plugin ptr | create_plugin | (Manager ptr manager, Dispatcher ptr dispatcher, LayoutView ptr view) | Creates the plugin |
| void | has_tool_entry= | (bool f) | Enables or disables the tool bar entry | |
| [virtual] | void | initialized | (Dispatcher ptr dispatcher) | Gets called when the plugin singleton is initialized, i.e. when the application has been started. |
| [virtual,const] | bool | menu_activated | (string symbol) | Gets called when a menu item is selected |
| void | register | (int position, string name, string title) | Registers the plugin factory | |
| void | register | (int position, string name, string title, string icon) | Registers the plugin factory | |
| [virtual] | void | uninitialized | (Dispatcher ptr dispatcher) | Gets called when the application shuts down and the plugin is unregistered |
| void | add_menu_entry | (string symbol, string menu_name, string insert_pos, string title, bool sub_menu) | Use of this method is deprecated | |
| void | create | Use of this method is deprecated. Use _create instead | ||
| void | destroy | Use of this method is deprecated. Use _destroy instead | ||
| [const] | bool | destroyed? | Use of this method is deprecated. Use _destroyed? instead | |
| [const] | bool | is_const_object? | Use of this method is deprecated. Use _is_const_object? instead |
_const_cast | Signature: [const] PluginFactory ptr _const_cast Description: Returns a non-const reference to self. Basically, this method allows turning a const object reference to a non-const one. This method is provided as last resort to remove the constness from an object. Usually there is a good reason for a const object reference, so using this method may have undesired side effects. This method has been introduced in version 0.29.6. | ||||||||
_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
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
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
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: | ||||||||
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.
| ||||||||
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: | ||||||||
register | (1) Signature: void register (int position, string name, string title) Description: Registers the plugin factory
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
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
This event can be used to free resources allocated with this factory singleton. |