FlexBuilder 3 Design Model - Introduction

This document gives a brief overview of the design model.

The Design Model is an object model that represents a text document containing MXML code. The object model is a tree of MXMLItem objects. Each MXMLItem corresponds to an MXML tag, a property value, or a special entity like a Binding.

The underlying text document is represented by an ITextProvider interface. Once you have hooked the IMXMLModel and the ITextProvider together, the IMXMLModel automatically keeps itself in sync with the text document, by adding, deleting, or modifiying nodes as required.

You can receive notifications of any change to the IMXMLModel by using addListener to register an object that implements the IMXMLModelListener interface.

The MXMLModel listens for changes in the underlying text document. These changes are typically reported everytime the document is edited - on every keystroke, paste, delete, etc. The MXMLModel responds to these changes in the underlying text document by reparsing the MXML and modifying the minimum possible set of affected MXMLItems, and then reporting the changes to all registered IMXMLModelListeners. Changes are reported as follows:

• changes that only affect whitespace do not affect the tree and are not reported
• if a node's properties change, the node is reported as modified
• if a node is added or deleted, the node is reported as added or deleted
• be aware that a single text change could affect multiple nodes

Editing

You can edit the model by calling various functions in IMXMLModel, and in IMXMLItem and its subclasses, for example:

• IMXMLModel.deleteSelection
• IMXMLModel.newChildTag
• IMXMLModel.newRoot
• IMXMLModel.cut
• IMXMLModel.paste
• IComponentInstance.newProperty
• IContainer.newComponentInstance

An "edit operation" is any API call that modifies any item of the MXML Model (and hence the underlying text document). Edit operations can easily be identified - they all say "throws ModelEditException".

Notifications of model edits are sent to all listeners asynchronously, in other words, the notifications take place *after* the editing function returns to you. Notifications always take place on eclipse's UI thread.

Every edit you make via the MXML Model API is immediately written into the text document, in the form of text edits to the MXML code. If you want a set of edits to be written all at once rather than individually, you can bracket the edits with beginEditBatch and endEditBatch. You can only edit a model that is editable (isEditable() == true). You can only edit MXMLItems that are valid (isValid() == true).

An edit will modify the selection if node(s) are deleted, in which case they are removed from the selection.

The MXMLModel does not have any handling for undo/redo. Rather, we depend on the underlying Text Document to take care of this. The rationale: the underlying text document is the "definitive" version of the MXML - the MXMLModel is merely a derived entity.

When we update the text document, we try to do the "right thing" concerning whitespace - tabs, wrapping, indents, alignment, etc. Generally, inserted material will be indented in a standard way, using the indent values that appear in nearby code. Paste will try preserve formatting of the pasted material, except that it may be re-indented to line up with the new location. We don't alter any whitespace except the whitespace in or near where the edit happenened.

Samples

Here are two Java files that contain examples of using the Design Model API

DesignModelExamples.java shows how to do basic read/write operations to the Design Model

FlexBuilderModelAccess.java shows how an eclipse plugin can get access to an instance of the Design Model

Design Model Functions

Here are all the functions of the Design Model API, grouped into categories.