http://docs.kde.org/
PrevConcepts for use in specialized pluginsNext

Context-dependent plugins

So far we have assumed, all plugins are always meaningful, and all placed in the main menu. However, some plugins are meaningful only (or additionally) in a certain context. For instance a plugin to export the contents of an R X11 graphics device is obviously most useful, when placed in the menu of an X11 device, not in the main menubar. Also, such a plugin should know about the device number that it should operate on, without having to ask the user about this.

We call such plugins context-dependent. Correspondingly, in the .pluginmap file, they are not (or not only) placed in the main <hierarchy> but rather into a <context> element. So far only two different contexts are supported (more will come later): x11 and file import. We will deal with those in turn. Even if you are only interested in the import context, please also read the section on the x11 context, as this is slightly more elaborate.

X11 device context

To use a plugin in the context of an x11 device - that is place it in the menubar of the window you get when you call x11() in the console, first declare it as usual in the .pluginmap file: 

<document [...]>
	<components>
		[...]
		<component id="my_x11_plugin" file="my_x11_plugin.xml" label="An X11 context plugin"/>
		[...]
	</components>

However, you do not need to define it in the hierarchy (you can, if it is also meaningful as a top-level plugin): 

	<hierarchy>
		[...]
	</hierarchy>

Instead, add a definition of the "x11" context, and add it to the menus there: 

	<context id="x11">
		[...]
		<menu id="edit">
			[...]
			<entry id="my_x11_plugin"/>
		</menu>
	</context>
</document>

In the logic section of the plugin xml, you can now declare two <external> properties: devnum and context. context (if declared) will be set to "x11" when the plugin is invoked in this context. devnum will be set to the number of the graphics device to operate on. And that is all.

Import data context

Before reading this section, please make sure to read the section on the X11 device context, as that explains the basic concepts.

The "import" context is used to declare import file filter plugins. You simply place those in a context with id="import" in the .pluginmap file. However, there is one additional twist when declaring these plugins: In order to offer a unified file selection dialog for all supported file types, you need to declare one additional bit of information on your component: 

<document [...]>
	<components>
		[...]
		<component id="my_xyz_import_plugin" file="my_xyz_import_plugin.xml" label="Import XYZ files">
			<attribute id="format" value="*.xyz *.zyx" label="XYZ data files"/>
		</component>
		[...]
	</components>
	<hierarchy>
		[...]
	</hierarchy>
	<context id="import">
		[...]
		<menu id="import">
			[...]
			<entry id="my_xyz_import_plugin"/>
		</menu>
	</context>
	[...]
</document>

The attribute line simply says, that the associate filename extensions for XYZ files are *.xyz or *.zyx, and that the filter should be labeled “XYZ data files” in the file selection dialog.

You can declare two <external> properties in your plugin. filename will be set to the selected file name, and context will be set to "import".