Plugin Metadata

From K-3D

Jump to: navigation, search

Overview

Beginning in K-3D 0.7, plugin factories can advertise "metadata", an arbitrary collection of name-value string pairs that provide plugin details that either can't be inferred by querying for interfaces or must be available before the underlying plugin is instantiated. The interpretation of specific names and values is left to other parts of the system, such as the UI layer. By definition, metadata name-value pairs are modeled on XML attributes, including the use of namespaces.

Note: Because the metadata mechanism is extremely flexible, it is critically important that authors document how it is used. In practice, it should only be used when the system requires information about a plugin before instantiating it to be effective.

Specifying Metadata

Metadata is specified by plugin authors when they construct the plugin's factory. Typically, this is done by passing an instance of k3d::iplugin_factory::metadata_t as the final argument to the factory constructor. You can use boost::assign::map_list_of to specify the metadata using an anonymous temporary object for code clarity, as in the following example where two metadata name-value pairs are assigned:

static k3d::application_plugin_factory<panel> factory(
  k3d::uuid(0xcaadef85, 0xb848e17d, 0x9f4c8a8b, 0x15ed410f),
  "NGUIPipelineProfilerPanel",
  _("Provides a panel for profiling execution of the visualization pipeline"),
  "NGUI Panel",
  k3d::iplugin_factory::EXPERIMENTAL,
  boost::assign::map_list_of("ngui:component-type", "panel")("ngui:panel-label", "Pipeline Profiler"));

Querying Metadata

You can use the k3d::iplugin_factory::metadata() method to retrieve the metadata (if any) for a plugin. The return-value is an instance of k3d::iplugin_factory::metadata_t, which can be used like std::map to query for the existence of specific metadata names and values:

There is also an overloaded version of k3d::plugin::factory::lookup() that returns the set of plugin factories that have a specific metadata key with a specific value. This is helpful when metadata is used to "tag" a class of plugins for some particular use, such as NGUI tool plugins.

Currently Defined Namespaces/Names

k3d

The k3d namespace is reserved for use by the K-3D application:

  • k3d:application-start - When present, indicates that an instance of the plugin should be created at application startup and destroyed at application shutdown. If the plugin implements the k3d::iscripted_action interface, its execute() method will be called at startup with the "Command" variable set to the value "startup". At shutdown execute() will be called again with "Command" set to the value "shutdown".
  • k3d:disable-documentation - When present, indicates that this plugin should not be part of the auto-generated wiki documentation.
  • k3d:document-start - When present, indicates that an instance of the plugin should be created whenever a new document is created and destroyed when the document is closed. If the plugin implements the k3d::iscripted_action interface, its execute() method will be called at startup with the "Command" variable set to the value "startup" and the "Document" variable set to the document in-question. At shutdown execute() will be called again with "Command" set to the value "shutdown" and "Document" set the document about to be closed.
  • k3d:load-order - For plugins that overlap in functionality (such as two different bitmap readers, PNGBitmapImporter and ImageMagickBitmapImporter, that can both load PNG files), it may be necessary to establish a stable ordering by which one plugin is "preferred" over another when available.
  • k3d:mime-types - For plugins that operate on a specific type of input file (including readers, writer, importers, exporters, and script engines), contains a whitespace-delimited list of MIME types that are acceptable as input to the plugin.
  • k3d:plugin-class - Required for scripted plugins, ignored for C++ plugins. Allowed class values are "application" or "document", to indicate whether the plugin instance will be associated with a document or not. See Plugin Classes for details.
  • k3d:plugin-type - Required for scripted plugins, ignored for C++ plugins. The plugin type must be the name of an existing scriptable plugin (e.g: "MeshSourceScript", "ActionScript", etc). The named plugin will be instantiated when the user creates an instance of this scripted plugin.
  • k3d:plugin-name - Required for scripted plugins, ignored for C++ plugins. Specifies the name of the scripted plugin, i.e: the name that appears in the Create menu.
  • k3d:plugin-description - Optional for scripted plugins, ignored for C++ plugins. Specifies an optional human-readable description of the scripted plugin, i.e: the tooltip that appears when the mouse is hovered over an item in the Create menu.

ngui

The ngui namespace is reserved for use by the standard user interface plugin:

  • ngui:action - When present, indicates that the plugin should appear within the standard user interface as an "action" that can be performed. When selected by the user, an instance of the plugin is created and immediately destroyed. If the plugin implements the k3d::iscripted_action interface, its execute() method will be called at startup. "Document" and "Node" variables may (or may not) be valid, depending on the context.
  • ngui:application-start - When present, indicates that an instance of the plugin should be created at application startup and destroyed at application shutdown, if the NGUI (standard user interface plugin) is in use. If the plugin implements the k3d::iscripted_action interface, its execute() method will be called at startup with the "Command" variable set to the value "startup". At shutdown execute() will be called again with "Command" set to the value "shutdown".
  • ngui:component-type - Indicates that a plugin is intended for use by the standard user interface. The current allowed values are:
    • "panel" - to designate panel plugins. Requires "ngui:panel-label".
    • "plugin-page" - for custom property page plugins. Requires "ngui:plugin-type".
    • "property-control" - for custom property control plugins. Requires either "ngui:property-type" or "ngui:property-role".
    • "tool" - to designate tool plugins.
    • "dialog" - for dialog-box plugins.
  • ngui:document-start - When present, indicates that an instance of the plugin should be created whenever a new document is created and destroyed when the document is closed, if the NGUI (standard user interface plugin) is in use. If the plugin implements the k3d::iscripted_action interface, its execute() method will be called at startup with the "Command" variable set to the value "startup" and the "Document" variable set to the document in-question. At shutdown execute() will be called again with "Command" set to the value "shutdown" and "Document" set the document about to be closed.
  • ngui:opengl-start - When present, indicates that an instance of the plugin should be created whenever the OpenGL system is initialized, if the NGUI is in use. If the plugin implements the k3d:iscripted_action interface, its execute() method will be called at startup with the "Command" variable set to the value "ngui:opengl-start". Note that the plugin will be deleted immediately afterwards.
  • ngui:panel-label - Specifies a human-readable name for a panel type, which appears in the UI. Required when "ngui:component-type" is "panel".
  • ngui:plugin-type - Specifies a plugin name for custom plugin pages. Required when "ngui:component-type" is "plugin-page".
  • ngui:property-type - Specifies a property type for custom property controls. Used when "ngui:component-type" is "property-control".
  • ngui:property-role - Specifies a property role for custom property controls. Used when "ngui:component-type" is "property-control".

QTUI

  • qtui:application-start
  • qtui:component-type
    • mode
    • panel
    • property-widget
    • window
  • qtui:property-role
  • qtui:property-type
Personal tools