Some days ago we started a little series of articles related to the names of the icons, menus and actions with the article: Names of icons, menus and actions on gvSIG 2.0 (I). We’re going to continue telling some other things that can be interesting for the developers.
When we create a plugin for gvSIG, it’s usually that we want to add some option to the menus, or some button to the button bar of the application. To do this we have to indicate it in the config.xml file, the same that we did it in the previous versions of gvSIG. Nevertheless a new concept has been introduced in the 2.x version. This is the action.
An action, as its name indicates, identify an action that the user can make on gvSIG, without being joined to a menu or a button of the toolbar. The actions can be run or linked from any part of gvSIG, we only have to know its name. The action has a series of associated data:
- A name that identifies it in an only way in all the actions registered in the application.
- A label, that can be used to present this, for example in a button or in a contextual menu.
- A tip, with a short description about the tasks made by the action, to present it in buttons or menus.
- An icon that represents it, to be used for example in buttons.
- A keyboard accelerator associated to the action for the case that it’s needed to.
- An absolute position regarding to the other actions.
- A code associated to this, to calculate when the action must be visible or enable or what is the code associated to the action running.
Having this centralized information associated to an action allows us to have them in a homogeneous way, and it’s not important where they do it from. They always can have the same label, or the same icon, or the same accelerator, or the same position regarding to other actions.
At this way, if we want to present the same action in a menu and a button at the buttons bar we only will have to associate the action to the menu or the bar, and add the rest of the options that they need and that aren’t defined at the action.
The class that represents the action can’t be overwritten by code. It’s a class offered by andami as an own service, and the developer can use it but not overload it… then… How is the associated code provided for an action?
To contribute with the code associated to an action it’s used the extensions mechanism that gvSIG included in the previous versions. An action has:
- A plugin that contains it.
- A Iextension that provides its logic.
- An action-command, to identify the action of the extension.
How to configure the actions and menus
To configure the actions, menus and tool buttons in gvSIG, the config.xml file is used. This file has the general configuration of our plugin: its extensions, the actions, menus, toolbars and buttons.
We are going to suppose that we have an extension that allows us to import images from a folder, like gvSIG point symbols, and we want to add to the Tools menu, Symbology submenu, an entrance Import point symbols. The first step would be to define our action. We are going to see how to do it. Our action would have the following attributes:
- name, that will have the name of the action. In our case we will call it “tools-symbology-import-point-symbols“.
- label, that will have a label that represents the action. This label will be translated to the language that gvSIG is being run, and must be registered at the translations database of the application. In our case we will add “_import_point_symbols“.
- tooltip, with a short description to be used as a tip where it’s needed, we will select “_import_images_from_folder_as_point_symbols“. This string will also be translated before being used.
- icon, here we will write the name of the icon to be used from the icons theme that is loaded in gvSIG. Our extension will usually register an icon by default in the icons theme with the name that we indicate here. We will write “tools-symbology-import-point-symbols“
- position, we will indicate the absolute position respecting the other actions. We will write “900400200“.
- accelerator, where we would indicate what keyboard accelerator we want to associate to this action. The format to specify the keyboard accelerator would be:
modifier + key
without spaces, where modifier would be able to be one or several of the following ones, separated by the “+” character:
And the keys would be:
- Letters from A to Z
- Numbers from 0 to 9
- Strings from F1 to F12
- The DELETE string.
For our example we won’t indicate any accelerating key, and for that we only would leave the value as “” or simply not specifying the attribute.
- action-command, that will be the value sent to our extension when the execute method is invoked. In our case we will write the same that we selected for our action, “tools-symbology-import-point-symbols“
All these aspects would be finally:
<action name="tools-symbology-import-point-symbols" label="_import_point_symbols" tooltip="_import_images_from_folder_as_point_symbols" action-command="tools-symbology-import-point-symbols" icon="tools-symbology-import-point-symbols" position="900400200" accelerator="" />
Once our action is defined, we would be able to use it to be associated to menus or buttons. In our case we had thought to associate it to a menu. To do this, we would have to select the same the menu the same as the action, and then we only would have to fill in the “text“ attribute. It would be something like this:
<menu name="tools-symbology-import-point-symbols" text="tools/Symbology/Import_point_symbols" />
If we also want to add It to the buttons we would be able to create a toolbar and add the button to it. To add the button to the toolbar we would be able to do it at this way:
<tool-bar name="symbology" position="10"> <action-tool name="tools-symbology-import-point-symbols" /> </tool-bar>
With that we would create the toolbar “symbology” if it doesn’t exist, and a button with the data of our action would be added. For that we only have to name the button the same as the action that we had defined.
The three labels that we have seen must be in the label that defines our extension, “extensión“. We are going to see how our “config.xml“ would be able to be written:
<?xml version="1.0" encoding="ISO-8859-1"?> <plugin-config> <libraries library-dir="lib" /> <depends plugin-name="org.gvsig.app" /> <resourceBundle name="text" /> <extensions> <extension class-name="org.gvsig.symbology.app.importsymbols.ImportSymbolsExtension" description="Import images from a folder as point symbols" active="true"> <action name="tools-symbology-import-point-symbols" label="_import_point_symbols" tooltip="_import_images_from_folder_as_point_symbols" action-command="tools-symbology-import-point-symbols" icon="tools-symbology-import-point-symbols" position="900400200" accelerator="" /> <menu name="tools-symbology-import-point-symbols" text="tools/Symbology/Import_point_symbols" /> </extension> </extensions> </plugin-config>