API reference - Class PluginFactoryNotation used in Ruby API documentation 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, main_window, 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
Public methods
Detailed descriptionvoid 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. 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). 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 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" 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. [virtual] void config_finalizeDescription: 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. [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. void createDescription: 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. [virtual,const] Plugin ptr create_plugin(Manager ptr manager,MainWindow ptr main_window,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. void destroyDescription: Explicitly destroy the object Explicitly destroy the object on C++ side if it was owned by the Ruby interpreter. Subsequent access to this object will throw an exception. If the object is not owned by Ruby, this method will do nothing. [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. void has_tool_entry=(bool f)Description: Enables to 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. [virtual] void initialized(MainWindow ptr main_window)Description: Gets called when the plugin singleton is initialized, i.e. when the application has been started.
[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. [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. [static] PluginFactory newDescription: Creates a new object of this class 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. void register(int position,string name,string title,string icon)Description: Registers the plugin factory
This version also allows to register 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. [virtual] void uninitialized(MainWindow ptr main_window)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. |