Editor development

How to develop for the editor.

Introduction

The EAd2 Editor is fundamentally different from the previous one. This document is here to guide you during your first steps.

The packages

This a break-down of the packages

• editor: main launcher, R (generated) image index
• editor control: contains the all-important Controller, which delegates to the EditorConfig, ViewController, EditorModel, ProjectController, NavigationController, ViewController, ScriptManager, and CommandManager.
• editor control change - a not very necessary duplication of standard Swing PropertyChange stuff; used to listen to controllers
• editor control commands - commands for editor actions.
• editor model - main model classes
• editor model nodes - nodes wrapping elements (and other nodes) so that they can be displayed in the editor
• editor model visitor - allows the editor model to build a dependency graph of the engine model, and generate an index for fast search.
• editor view - general view classes; most importantly, EditorWindow. Use registerElementPanelFactory to associate DependencyNode subclasses with appropriate views.
• editor view dock - DockingFrames classes which provide view placement & persistence functionality to the main editor window.
• editor view generic - Field controls. Being worked on; do not use yet.
• editor view menu - Editor main menus
• editor view panel - Panels for the different !DependencyNodes
• editor view scene - Do not touch; being worked on by Angel Serrano & Manuel Freire.

Getting started

The main entry-point is ead.editor.EAdventureEditor. This will launch the editor. Since this project uses Guice for dependency injection, you should imitate the code in ead.editor.EAdventureEditor if you want to create a different main-file, for instance for testing purposes.

You can build the editor using Maven, but it is generally easier to use either !NetBeans or !Eclipse for development. To initialize an !Eclipse workspace, use mvn eclipse:eclipse, and then "import existing project into workspace" with the result.

Adding images and text strings

R.java files are generated and updated by running the ResourceCreator on a suitable directory. A comment in each R.java file describes how it was generated, to make it easy to re-generate it.

For each image in the resources/drawable[-xx_XX] folder of the corresponding project (where the -xx_XX is an optional location-code such as -es_ES or -de_DE)

Therefore, to use a new image called my_image.png from within !Editor code,

1. drop it into a suitable src/main/resources/drawable[-xx_XX] folder
2. re-run the ResourceCreator for that module, which will update the R file
3. access it using Resource.loadImage(R.my_image)

Usage of Resource.loadImage will log any problems and substitute the image for a suitable placeholder.

Text strings

Text strings follow a similar logic. To add a new internationalized text string called my_string, to be used from within ead.editor.my.package, you should

1. create or modify the corresponding src/main/resources/es/eucm/ead/editor/my/package/Messages[_yy_YY].properties java-file (you can take any of the existing ones as a reference)
2. access it using Messages.my_string from within the code; this will be a static String, initialized at application start to the appropriate, internationalized value.

Again, _yy_YY is an optional locale string (such as es_ES or de_DE). Notice that locale strings for Messages must start with an underscore (_ is what Java i18n traditionally uses), while locale strings for drawable folders must start after a dash (- is used for the same purpose in Android development).

I18N and locale resolution

Both R and the multiple Messages classes are statically initialized the first time they are referenced. While initializing, they will use the current locale to select which strings (or Files) to bind for each resource identifier. The class that does the binding is I18N, through its initializeResources and initializeMessages methods. You can call these methods again to re-initialize them, but generally a locale change requires an application re-start.

The default language for the editor is English (en_US). Therefore, only English versions of images should be placed in the default image directory src/main/resources/drawable and in the default string property files src/main/resources/es/eucm/ead/editor/my/package/Messages.properties. To internationalize particular images or strings for, say, Spanish, you would need to define them in src/main/resources/drawable-es_ES or src/main/resources/es/eucm/ead/editor/my/package/Messages_es_ES.properties. If the current locale is es_ES, resource binding will first try to use es_ES versions; if it does not find them, it will look for es versions. And finally, if not found, it will end up using the default versions. There should always be default versions of all strings and image files.

User preferences

The editor has its own preferences system, accessed through the EditorConfig class. You should always grab instances of this class using controller.getConfig().

How to access properties

   EditorConfig ec = controller.getConfig();
   String s = ec.get(EditorConf.MyPropertyName); // returns a string
   int i = ec.getInt(EditorConf.MyPropertyName); // returns an integer
   // and so on for boolean, double, and even string arrays

How to set properties

   EditorConfig ec = controller.getConfig();
   ec.put(EditorConf.MyPropertyName, myPropertyValue);
   // put more properties here ...
   ec.save(null); // <--- do not forget to save afterwards!

To prevent typos and name-clashes, you should always use the EditorConf enum to declare and reference all properties.

User preferences are currently saved in a ead-editor-config.xml file, placed in the current-working-directory of the application. This file is lazily loaded or created the first time that controller.getConfig() is called.

CAVEAT: Preference access is currently not protected against malformed data (for instance, trying to access a string as an int). The preference system is also not thread-safe.