Writing your own tool
(→AbstractAdminTool) |
m (→AbstractAdminTool) |
||
| Line 46: | Line 46: | ||
More detailed description of methods and a few more methods that you can override can be found in the [[AbstractAdminTool]] page. | More detailed description of methods and a few more methods that you can override can be found in the [[AbstractAdminTool]] page. | ||
| − | If the tool | + | If the tool execution can take a long time, you should try to provide some feedback for the user. Use the log method to show messages. You should also periodically check if the user has aborted the execution. To do this call forceStop method. If returns true, you should abort the execution and return from execute as soon as possible. |
== Tool context == | == Tool context == | ||
Revision as of 13:48, 29 January 2007
It is possible to make your own tools for Wandora. To make your own tool you need to make a Java class that implements the AdminTool interface. Most of the time easiest way to do this is to extend the AbstractAdminTool class which implements AdminTool interface and provides some commonly used methods.
AbstractAdminTool
The simplest way to make your own tool is to extend AbstractAdminTool class and then implement and override a few methods. Following table lists methods that are most often overridden.
| Method | Description |
|---|---|
| execute(WandoraAdmin,Context) | Main method of the tool. In all cases you must implement this method. It should perform all processing of the tool. You can open dialogs for user input if you want to. |
| getName() | This method returns the name of the tool. You should override this method to return the name of your tool. |
| getDescription() | This method returns a description of what the tool will do. You should override this method to return a proper description of your tool. |
| getType() | This method returns the type of the tool which should be one of "generic", "import", "export" or "extract". Default implementation returns "generic" and unless you are making some other kind of tool you don't need to override this method. |
| getMenuIcon() | This method returns the icon to use in menus. If you want to use something else than the default icon, override this method. |
Each tool must have a constructor with no parameters. If you need to do some kind of initialization for the tool, you need to override a few more methods.
| Method | Description |
|---|---|
| initialize(...) | Initializes the tool. This is called always after the tool object is created. The method receives as its parameters the WandoraAdmin object, an Options object containing all saved options and a String containing the prefix this tool should use when accessing and saving options. |
| isConfigurable() | Tells if this tools provides a dialog where user can configure the tool. Default implementation returns false so you need to override this if you want the user to be able to configure the tool. |
| configure(...) | If this tool is configurable, this method must be overridden to show the configuration dialog. After user closes the dialog, all options should be written in the options using the prefix given as a parameter. Best way to do this is to call the next method after the dialog is closed. |
| writeOptions(...) | If this tool is configurable, this method must be overridden to write all current options using the prefix given as parameter. Unlike previous method, this method shouldn't open any dialogs or expect user interaction. |
More detailed description of methods and a few more methods that you can override can be found in the AbstractAdminTool page.
If the tool execution can take a long time, you should try to provide some feedback for the user. Use the log method to show messages. You should also periodically check if the user has aborted the execution. To do this call forceStop method. If returns true, you should abort the execution and return from execute as soon as possible.
Tool context
The execute method receives a Context object as one of its parameters. The context contains objects the tool should modify or inspect. There are many kinds of contexts a tool can use. If the tool modifies topics, then it will probably want to use one of the topic contexts. If it modifies associations then it should use an association context. Depending on what kind of context is used, the context will contain different kinds of objects. You should set the preferred context before invocation of the tool. Best place to do this is in tool constructor. To set the context call setContext method with a new context object. Following table lists some of the more commonly used contexts. Package for all built in contexts is com.gripstudios.applications.wandora.admin.contexts.
| Context object | Description |
|---|---|
| LayeredTopicContext | The default context of AbstractAdminTool. The context objects of this context are topics, LayeredTopics to be more specific. If user has selected some topics from a table, context will be those selected topics. It can also be the topic that is currently open or a selected topic in the topic tree. Most of the time this is exactly what the user would expect it to be. |
| TopicContext | Same as LayeredTopicContext but context objects are not topics of the currently selected layer. They will always be Topic objects but might be any implementation of that class. In some cases you want to perform an action specifically on topics of the selected layer in which case you should use this context. |
| ApplicationContext | This context always contains the currently open topic. It will be a LayeredTopic. |
| AssociationContext | This context returns the selected associations in an association table or the associations of the selected topics or the current topic. |
