Shed 3.5.4-SNAPSHOT API

Shed is a plugin into NetBeans platform that adds an editor for .lap file.

See:
Description

Packages

cz.cuni.pogamut.posh	Package for classes for adding a new data object (.lap) into the NetBeans platform.
cz.cuni.pogamut.posh.explorer	This package contains classes that can search for nodes of the plan (nodes=AP/C/action/sense) and GUI explorers that allow user to manipulate them.
cz.cuni.pogamut.posh.nblexer	Classes necessary for adding lexer into NetBeans platform. These classes add token highlighting support into NetBeans that can be changed in Tools - Option - Fons & Colors.
cz.cuni.pogamut.posh.nbparser	This package contains classes responsible on-the-fly parsing of Yaposh plan in text view.
cz.cuni.pogamut.posh.view	Text view of Yaposh editor.
cz.cuni.pogamut.shed
cz.cuni.pogamut.shed.presenter	This package contains factories and interfaces related to presentation of widgets in the scene.
cz.cuni.pogamut.shed.view	Package contains MultiViewElement and its description for Visual view of Shed.
cz.cuni.pogamut.shed.widget	Various widgets used for displaying the Yaposh tree.
cz.cuni.pogamut.shed.widget.editor	Inplace editors for various widgets.

Shed is a plugin into NetBeans platform that adds an editor for .lap file. The editor is a MultiView CloneableTopComponent with two MultiViewElements. The first view is a visual view, where user can see the plan as sort-of tree with palette on the right side that displays and manipulates nodes of the plan. The second view is a text view, it displayes source of the plan with token highlighting and when plan has a syntax error, it displayes error hint red exclamation mark on the line where parsing error was detencetd.

DataObject

In order to add editor of a new type into NetBeans, plugin must create a new DataObject, Shed has PoshDataObject for the lap files. The data object gets FileObject with the plan and its job is to provide cookies according to capability of the PoshDataObject. It basically uses support class to provide cookies - OpenCookie, EditorCookie, SaveCookie and few others. Cookie is basically a capability of DataObject, e.g. SaveCookie has a method save() tha can save the PoshDataObject. In newer versions of NetBeans, cookies are being replaced by Lookup.

The plugin also must add resolver for .lap files, so NetBeans can determine when to use the PoshDataObject for lap files, the resolver is specified in layer.xml, along with templates of plan and few other things.

Model View Presenter

The visual view is displaying the plan using ShedScene, it basically takes ShedWidgetFactory, plugs IPresenterFactory(more precisely ShedPresenterFactory) into it and that creates the scene. The ShedScene is using model-View-Presenter for showing the plan, displayed part of the plan is represented by some sort of Widget (there is a lot of envelopes, but actual rectangle nodes showing info are ShedWidget). The Widget has a IPresenter that has registered all sorts of listeners during and the presenter is used to update the Widget according to the underlying changes it's notified about (thanks to listeners). Widget is passive element, the IPresenter must listen when changes to the widget should be made and update the widget accordingly. When the Widget shoudl be removed from the scene, its presenter unregisters all its listeners.

Example: Trigger — The trigger has a widget representing the trigger (ShedTriggerEnvelope, subclass of AbstractShedEnvelope) and a presenter TriggerPresenter. The envelope contains widgets representing the senses of trigger. The presenter register itself = it sets presenter of the widget to itself and adds itself as listener for changes to the element of the plan that contains the trigger (trigger is just a structure holding the senses, not a node of the plan). When the node with trigger adds (or delete/move) a new sense, the presenter is notified about new child of node, checks that it is sense and if it is, it creates new widget representing the sense into the envelope to reflect the changes of the underlying structure.

ShedScene and its creation

ShedScene is displaying the plan as kind of tree. It has four layers: background (white, nothing in it), widget(all widgets representing the plan), connection (contains arrows between the widgets) and drag and drop (DnD) layer. At the start, scene contains two envelopes: ShedTriggerEnvelope for goal of the DC and ShedDrivesEnvelope for the drives of the plan. Both envelopes are empty, no senses, no drives. Add empty plan to the mix, no goal, no drives, no AP nothing. Now register create goal presenter and associate it with goal envelope of the scene and create DC presenter and associate it with the drives envelope. Envelope and underlying structures are in sync and you can start adding drives and other stuff into the plan, the presenter will make sure that scene reflects the changes of the plan.

There is a LapSceneFactory that can create the scene and do the whole initialization.

Content of the plugin

• Yaposh DataObject — class for loading/saving files from the .lap files into a NetBeans dataobject
• MultiView editor with two views — Visual view and Text view.
• Token highlighter — Text view of Shed is a descendant of CloneableEditor, it to detect tokens in the text and display then using different colors.
• Yaposh parser — Shed continuously parses the Text view of Shed and displays detected parsing errors using exclamation mark on the right side of editor, it is mostly wrapper for original parser from SPOSH-Core.
• Explorer — Shed is attached to the NetBeans and can crawl through classses available to the project. Primitives of the Yaposh plan are classes implementing interface IAction or ISense. Shed has a set of GUI panels called explorers, each type of node in Yaposh plan has its own explorer. The explorer for AP/C will display all patterns/competences and explorers for actions/senses will display list of classes that implement IAction/ISense and are on the project classpath.
• Widgets — Different widgets that are displaying the Yaposh tree in the Visual view. Widget has associated presenter responsible for keeping the widget up to date with the data in the Yaposh tree. The Shed is using ShedWidgetFactory and IPresenterFactory for creation of the widgets.
• Presenters — Each widget has a presenter that is responsible for listening on nodes of the Yaposh tree and updating the widget. It also provides list of accept actions for drag and drop, list of context menu actions and the edit action of the widget (doubleclick). Presenters are created by the factory, so ShedWidgetFactory can create same Yaposh tree scene with different behaviors.
• Inplace editors — nodes of Yaposh plan in visual have properties (e.g. name or parameters) that can be changed. Editors that can change these properties are called inplace editors, because they appear when user double clicks on the node in the scene. Differnt nodes have different editors.