wfo-advanced extension framework (original) 28 apr 97 1 the d-2d extension framework what's an...

WFO-Advanced Extension Framework (original) 28 Apr 971

The D-2D Extension Framework

• What's an extension?• Features and current extensions• What’s a framework?• Notation• Composition of an extension• Making an extension

– Information files– Static/nonstatic extensions– Framework classes

> Class Extension> Class InteractiveDepictableExt> EditableElement classes> ExtFactory

• Tips and Tricks


What's an Extension?

• Like a “smart” depictableIt doesn’t just read and display data; it can exhibit customized behavior that you program

• Interactive– Display graphic elements overlaid with other depictables– Forecaster can interact with these elements

• Can display floating dialog boxes using any toolkit• Built inside a framework


D-2D Extensions

• Points• Baselines• Home • Distance Bearing• Distance Speed • Alert Area Editor• WarnGen


What’s a Framework?

• A framework is…A set of cooperating classes that makes up a reusable design for a specific class of software. A framework provides architectural guidance by partitioning the design into abstract classes and defining their responsibilities and collaborations. A developer customizes the framework to a particular application by subclassing and composing instances of framework classes.

Design Patterns by Gamma et al., Addison-Wesley 1995. • To make an extension, you

– Subclass from an Extension base class– Compose instances of other classes within an Extension

subclass• The architecture imposed by the extension framework

is what makes developing extensions easy. The hard part is designing the framework.


Notation

Aggregation:

BaseClass

DerivedClass

ClassName

method()

data

AbstractClass

abstractMeth()

ComposingClass ComposedClass

ComposingClass MoreThanOne

Reference:

Class Class

anObject

objReference anotherObject

data


Example of Notation Use

// Define an interface for generic program compilers:class Compiler {public: virtual void compile() = 0;};

// A specific compiler:class FortranCompiler {public: FortranCompiler(Programs& p) : _p(p) { _errors = new ErrorList; } virtual void compile (); ErrorList getErrors ();private: Program _p; ErrorList* _errors;};

// A container for program errors:class ErrorList {public: void addError(Error e);private: Error* _errorArray;};


Example of Notation Use

Program FortranCompiler

void compile()ErrorList getErrors()

_p

Program _pErrorList _errors;

_errorsErrorList Error

Compiler

void compile()

void addError()

Error*_errorArray


Composition of an Extension

• An extension is identified by an extension key. • An extension draws into one or more interactive

depictables.• All depictables are identified by depict keys.• Interactive depictables contain editable elements.

The name is misleading: they are optionally editable by the forecaster.

• One or more extension objects (with the same or different extension keys) may reside in a single process.

• A process containing extensions is an extension process.• Each extension process has exactly one extension factory,

which creates and destroys extensions as necessary.• An extension process communicates with exactly one IGC,

which serves one display panel in D-2D.


Making an Extension

1. Pick an extension key for your new extension. Pick depict key(s) for your interactive depictable(s). Record these keys and add a menu entry for your extension.

2. Subclass the Extension class.– Contains the logic of the extension– Tells the IGC what to draw– Receives events indicating forecaster interaction with

on-screen elements

Extension

WarnGen Baselines LatLonLocator


Making an Extension

3. Query (or receive InteractiveDepictableExt object(s).– Your canvas– Create EditableElement objects (points, lines,

polygons, etc.) and add them to the canvas

1. Use the ExtFactory to register your extension.2. Compile, link, and install.

LatLonLocator InteractiveDepictExt EditableElement

Extension


Information Files: Extension Key

• Each extension gets a unique extension key.• Pick a new extension key, which is a small

nonnegative integer.• Add an entry to the extension information file.

$FXA_HOME/data/extensionInfo.txt• These keys are not site-specific.• The format of the file is:

key | name | executable | prestart | depict key | coordinate select– key is the extension key – name is the name of the extension, and isn’t used by the software– executable is the name of the program file to run that contains the

extension– prestart tells whether to prestart the process– depict key is the depict key of the interactive depictable used by

the extension; may be more than one, separated by commas– coordinate select tells whether to send coordinate selection

events to the extension object


Extension Information

• Example from extensionInfo.txt:1 | Warning Generator |warnGen | y | 12000 | n5 | Baselines |baselines | n | 12002 | n6 | Points |points | n | 12003 | n7 | Home Location |home | n | 12004 | n8 | Distance Bearing |disBearing | n | 12005 | n9 | Distance Speed |disSpeed | n | 12006 | n10 | Alert Area 1 Editor |alertAreaEditor | n | 12007 | y11 | Alert Area 2 Editor |alertAreaEditor | n | 12008 | y12 | Lat/Lon Locator |miniExtensions | n | 12009 | n13 | City Locator |miniExtensions | n | 12010 | n

fxa IGC_Process

warnGen

warnGen

WarnGen

IGC_Process

IGC_Process

miniExtensions

SpotterInfo

warnGen

WarnGen

miniExtensions

SpotterInfo

LatLonLocator


Information Files: Depict Key

• Extensions are started when their matching depictables are loaded.

• Pick a new depict key to identify the depictable.• Depict keys for interactive depictables are in the

range 12000 – 12999.• Unlike extension keys, depict keys are site-specific,

but the range 12000 – 12999 is part of the national deployment of D2D.

As a result, you add them to$FXA_HOME/data/localization/nationalData/depictInfo.manual


File Format for Depictable Information

• The format is:key | type | blank | blank | maps | 1 | long | short | 1 | 0 | 1 | color– key is the depict key, in the range 12000 - 12999– type is either 46 (static interactive depictable) or 12 (nonstatic)– blank fields should be blank: spaces or tabs are fine– maps is a comma-separated list of depict keys of maps to load

when this product (extension) is loaded, or 0 to mean use the default maps for the scale

– long is the long name of the product (used in the legend)– short is the short name (used in the history list, defaults to the long

name if left blank)– color is an optional color to use for the product: if blank, it defaults

to the next overlay color• With regard to interactive depictables, “product” means

“extension.”This is a key point: extensions are started as the result of product loads.)


Static versus Nonstatic

• Static interactive depictables display data that do not vary with time– Examples of non-time-varying data:

> Distances over land> City data (varies at a pace much slower than typically

displayed by D2D)– Simplifies and optimizes the way an extension works:

> To an extension, there’s only one frame, no matter how many frames the forecaster has selected> Reduces amount of interprocess communication

• Nonstatic interactive depictables show time-varying data– Examples of time-varying data:

> Storm tracks> Isobars

– Extension becomes more complex:> Exposed to all frames forecaster has selected> Must respond to changes in frame length and auto-updates


Static versus Nonstatic

• Extensions using static interactive depictables are static extensions.

• Likewise, nonstatic extensions use nonstatic interactive depictables.


Information Files: Product Buttons

• Menu entries in D-2D that load products are called product buttons.

• Product buttons identified by product button keys, which are integers.

• Product button keys map to depict keys, depending on the scale.

• Format:key | depict-keys | label | not used> key is the product button key> depict-keys is a comma-separated list of depict keys, one for each scale> label is the label to use on the entry on the D2D menus

• Example:101 | 921, 911, 801, 0, 0, 0 | IR Windowmeans that if the forecaster selects “IR Window” (aka product button key 101) from the menu, the system will load the product with depict key 921 if the scale is 0, 911 if the scale is 1, and 801 if the scale is 2. If the scale is 3, 4, or 5, the product button appears disabled.


Product Button Keys and Extensions

• Because extensions are loaded (started) like any other product, they also need an entry in the product button key table.

• Like depict keys, product button keys are site-specific.But the range of product button keys for extensions is part of the

national configuration of D-2D• To add an entry, edit

$FXA_HOME/data/localization/nationalData/productButtonInfo.txt

• Use the range of keys reserved for extensions (which is, conveniently, the same range reserved for depict keys): 12000 – 12999.

• Example:12002 | 12002,12002,12002,12002,12002,12002 | Baselines |Not Used12009 | 0, 0, 0, 0,12300,12301 | Spotter Info|Not Used

• Shortcut: if there are fewer depict keys than scales, the last key repeats for remaining scales:

12002 | 12002 | Baselines |Not Used


Information Files: Menus

• The file $FXA_HOME/data/localization/nationalData/dataMenus.txt specifies the layout of products (including extensions) on the D2D menus.

• Edit this file and add an entry for your extension.• The syntax is simple; see the file for details.• Add your entry by product button key, not depict key or

extension key.• Example:

menu: “Tools”productButton: 12002 # BaselinesproductButton: 12005 # Distance BearingproductButton: 12006 # Distance SpeedproductButton: 12009 # Lat/Lon locator


Restart D-2D

• The files– extensionInfo.txt– depictInfo.txt– productButtonInfo.txt– dataMenus.txt

are read once, at start-up time of the D-2D display software. After making changes, you must restart D-2D in order for the system to see your updates.


Developing Extensions

• Derive your own extension class from class Extension. • Override virtual methods in the class. These are

callbacks: when the extension framework detects an event for your extension, it calls one of the virtual methods.

• It’s like a user interface toolkit: in Motif, you pass a pointer to a callback function, which is called when the user clicks the button, types a value, drags a slider, etc.

• It’s an object-oriented callback: the method signature and name is set for you; you provide the object.

• Class Extension strictly isn’t an abstract class (no pure virtual methods).

• Every callback method has “reasonable” default behavior.


Developing Extensions

• To implement a callback method, declare it in your extension class and provide whatever implementation is appropriate.

• You can override the default behavior in its entirety, or augment it.

• To augment a method, do whatever’s necessary for your extension, then call the base implementation:

class MyExtension : public Extension {public: ... virtual void editedPoint(EditablePoint* p, bool ignored) { // Augment: do something with p p->setAnnotation(“Hello, world.”); // Call base implementation: Extension::editedPoint(p, ignored);};

• It is, however, rare that you’ll augment the default behavior.


The Extension Methods

class Extension {public: ExtensionKey extensionKey() const; DepictKey depictKey() const; const IPC_Target& igcProcess() const; bool isActive() const;

void deactivate();

void toggleOverlay(DepictKey, bool);

virtual void activeStateChanged(bool); virtual void editedPoint(EditablePoint*, bool); virtual void editedLine(EditableLine*, bool); virtual void editedPolygon(EditablePolygon, bool); virtual void editedPolyline(EditablePolyline, bool); virtual void deletedElement(EditableElement*);

virtual void locationSelected(const LatLonCoord&, const LatLonCoord&);

virtual void handleIntDepictSeqChanged(SeqOfPtr<InteractiveDepictExt*> deleted, SeqOfPtr<InteractiveDepictExt*> oldDepicts, SeqOfPtr<InteractiveDepictExt*> newDepicts);

virtual void handleEditingEnabled(); virtual void handleEditingDisabled();

short activeIntDepictIndex() const;


The Extension Methods

protected: Extension(ExtensionKey, DepictKey, IPC_Target);

const SeqOfPtr<InteractiveDepictExt*>& interactiveDepictables() const; InteractiveDepictableExt* intDepictForTime(const DataTime&); int intDepictFrameIndex(const DataTime&);

const CartDomain2D<float>& screenExtent() const;

DisplayService _displayService;};

Class DisplayService {public: void activate(); void deactivate(); void toggleOverlay(DepictKey, bool);};

• The DisplayService class:


Constructing an Extension

• First, derive your own extension class:#include “Extension.H”class LatLonLocator : public Extension {};

• Implement the constructor and make it public:class LatLonLocator : public Extension {public: LatLonLocator(ExtensionKey ek, DepictKey dk, IPC_Target igcProcess) : Extension(ek, dk, igcProcess) { }};

• In your constructor, you can do any initialization needed by your extension.– Open files– Open network connections– Prepare data structures– Or nothing at all


Constructing an Extension

• What we’ve built so far:

Extension

LatLonLocator


Drawing

• To draw onto an overlay in an IGC window, you need a canvas.

• Your canvas is an “interactive depictable”– It’s a depictable, like any other– Unlike any other, it supports interactivity: items you draw can

be designated as editable by the forecaster– You are notified when such items are edited.

• For a nonstatic extension, there’s one interactive depictable per frame.

• For a static extension, there’s only one interactive depictable always.

• You draw by creating “editable elements” and adding them to the interactive depictable.

• You create editable elements in world coordinates: latitude and longitude.


Class InteractiveDepictableExt

• The extension half of a class is shared between an extension and the IGC process.

• The class:class InteractiveDepictableExt {public: DepictKey depictKey() const; const DataTime& dataTime() const; DataTime frameTime(); SeqOf<DepictKey> overlays(); SeqOfPtr<EditablePoint*> points() const; SeqOfPtr<EditableLine*> lines() const; SeqOfPtr<EditablePolygon*> polygons() const; SeqOfPtr<EditablePolyline*> polylines() const; DictKP<UniqueID, EditableElement*> elements() const;

void setNominalMarker(Marker marker); void newElement(EditableElement* element); void deleteElement(UniqueID elementID);

static void refreshIGC(bool, const IPC_Target& igcProcess);};

• To use it:#include “InteractiveDepictExt.H”


Semantics of Drawing

• Drawing a new item:1. Create the editable element:

EditablePoint* p = new editablePoint(...);

2. Add it to the interactive depictable:depictable->newElement (p);

• Modifying an existing item:1. Modify the element in whatever way:

p->setAnnotation(“New annotation”);

2. Add it to the interactive depictable again:depictable->newElement(p);

• Removing an item:depictable->deleteElement(p);


Unique IDs

• Editable elements are assigned unique IDs.• Unique IDs are generated by creating objects of class

UniqueID.• You don’t have to assign the ID – an editable element

does that itself.• Unique IDs avoid pointer semantics between the

address spaces of an extension and the corresponding IGC process.

• They’re also used to create shared editable elements.• They enable an interactive depictable to differentiate

between a new element and a modification to an existing element.


When to Draw

• Whenever you have access to InteractiveDepictableExt objects.

• To get access to InteractiveDepictableExt objects:– Call Extension::interactiveDepictables– Call Extension::intDepictForTime– Override Extension::handleIntDepictSeqChanged

• But not from the constructor or destructor.• Often, you’ll draw inside the Extension::editedPoint,

editedLine, etc. methods.• Mainly you’ll draw when the framework calls your

overridden definition of Extension::handleIntDepictSeqChanged.

• This is the most important method in the extension framework, and probably the most confusing.


Handling Changes in the Int Depict Sequence

• In almost every extension you will want to override Extension::handleIntDepictSeqChanged.

• This method is called when an extension first starts up, after the constructor.

Giving you an opportunity to draw your initial elements.• For nonstatic extensions, it’s also called whenever the

frame sequence is lengthened or shortened, or when an auto-update occurs.

Giving you an opportunity to react to new frame times, or the forecaster changing the frame count.

• For static extensions, it’s called once for the lifetime of the extension.

• It’s passed three sequences to pointers to:– Depictables to be deleted– Depictables that already existed– Newly created depictables


When the Int Depict Sequence Changes

• Frame count shortened from 5 to 3:

2 deleted, 3 old, none new.• Frame count lengthened from 3 to 5:

None deleted, 3 old, 2 new.• Auto-update

1 deleted, 4 old, 1 new.

10:00 11:0010:15 10:30 10:45 11:0010:00 10:15 10:30 10:45

11:0010:30 10:45 10:00 10:15 11:0010:30 10:45

10:00 11:0010:15 10:30 10:45 11:0010:00 10:15 10:30 10:45 11:15


Initial Drawing

• Do it inside of Extension::handleIntdepictSeqChanged.• Example:class LatLonLocator : public Extension {public: LatLonLocator(ExtensionKey ek, DepictKey dk,IPC_Target igcProcess) : Extension(ek, dk, igcProcess) { } virtual void handlIntdepictSeqChanged(SeqOfPtr<InteractiveDepictableExt*>dels, SeqOfPtr<InteractiveDepictableExt*> olds, SeqOfPtr<InteractiveDepictableExt*> news);};

And in LatLonLocator.C:#include “LatLonLocator.H”void LatLonLocator::handleIntDepictSeqChanged(SeqOfPtr<InteractiveDepictExt*> SeqOfPtr<InteractiveDepictExt*>, SeqOfPtr<InteractiveDepictExt*> news) { char buf[64];

LatLonCoord coord(39.76833, -104.4437); sprintf(buf, “%g,%g”, coord.lat, coord.lon); Marker m(Marker::X_ICON); EditablePoint* p; p = new EditablePoint(coord, m, buf); news[0]->newElement(point);};


LatLonLocator InteractiveDepictExt EditableElement

Extension

Initial Drawing

• Again, what we’ve seen so far:


“Editable” Elements

• Points, lines, polygons, and polylines, defined by a family of classes:

• To use them,#include “EditableElements.H”

Extension

EditablePoint EditableLine EditablePointSeq

EditablePolylineEditablePolygon


Properties of Editable Elements

• Specified in world coordinates, not window-system coordinates.

• Editable by default.• Optional text annotation.• Optionally deletable by the forecaster.• Moveable by forecaster if editable.• Moveable by extension any time.• Markers (editing handles) appear when editable:

• Markers available in three sizes and may be filled.• See Marker.H for details.

X CROSS_HAIRS CIRCLE BULLSEYE SQUARE TRIANGLE


Editable Element Methods

class EditableElement {public: const TextString& annotation() const; const UniqueID& id() const; bool editable() const; bool deletable() const;

void setEditable(bool); void setAnnotation(const TextString&); void setDeletable(bool);

virtual void move(LatLonDelta) = 0; virtual void undoLastMove() = 0;

virtual void setMarker(const Marker&) = 0; const Marker& marker();};


Shared Editable Elements

• Useful for static data inside a nonstatic depictable sequence.

• Allows the same element to be added to multiple frames (multiple interactive depictables).

• For example, the warning box in WarnGen is static, but the storm centroid isn’t:

• Achieved by adding an element with the same unique ID to each interactive depictable.

10:00 10:06 10:12 10:18


Advantages of Shared Elements

• Less programming: if the forecaster edits an element in one frame, you don’t have to programmatically propagate that change to the other frames, which reduces...

• Interprocess communication overhead.


Editable Element Events

• You use editable elements to convey data but also to allow the forecaster to interact with the extension.

• The Extension::editedPoint, editedLine, etc. methods tell you when the forecaster interacts with (edits) a point, line, etc. Override these methods to take action when an element is edited.

• The forecaster editing an element means:– Moving it– Adding or removing a vertex– Moving a vertex

• Changing the overlay color or line style doesn’t constitute editing.

• Deleting an element is different from editing an element.


Reacting to Editable Element Events

• How you react to such an event depends on the extension.

• Example: WarnGen– Moving a point recomputes the storm track, and redraws

the track line and tick marks. It also redistributes the storm centroid points in each frame.

– Moving or reshaping the warning box recomputes the counties/zones affected by the warning.

• Examples: Points and Baselines– Moving a point or baseline saves the new location in the

point/baseline files and notifies all clients awaiting updates on those files that they’ve changed.

• Our example: latitude/longitude locator– Moving the point should update the annotation with the

new latitude/longitude.


Overriding the editedPoint Method

Class LatLonLocator : public Extension {public: LatLonLocator(ExtensionKey ek, DepictKey dk, IPC_Target igcProcess) : Extension(ek, dk, igcProcess) { } virtual void handleIntDepictSeqChanged(SeqOfPtr<InteractiveDepictableExt*>dels, SeqOfPtr<InteractiveDepictableExt*> olds, SeqOfPtr<InteractiveDepictableExt*> news); virtual void editedPoint(EditablePoint* p, bool ignored);};

void LatLonLocator::editedPoint(EditablePoint* p, bool) { char buf [64];

LatLonCoord coord(p->location()); sprintf(buf, “%g, %g”, coord.lat, coord.lon); p->setAnnotation(buf);

// Not really a new element ... a modified element: interactiveDepictables()[0]->newElement(p);};

• And in LatLonLocator.C:


Integrating an Extension

• In order for the IGC to be able to create extension objects in an extension process, you need to register your extension class with the extension factory.

• The extension factory is a singleton object that constructs and destroys all extensions. It’s part of the extension framework.

• You register an extension creator with the factory.• An extension creator is an object of a class derived from

AbstractExtCreator that knows how to create extensions. A specific ExtCreator object will create your extension when its corresponding depict key is loaded in the IGC.


Using the Extension Factory

• Register your extension creator with the extension factory in the filescope part of the implementation(.C, .cc, .c++, .cxx) file for your extension

• Example:

#include “LatLonLocator.H”#include “ExtFactory.H”#include “ExtCreator.H”

const ExtensionKey LatLonLocator_Key = 12;

static bool dummy = getExtFactory()->registerExtCreator(LatLonLocator_Key, new ExtCreator<LatLonLocator>);


Class/Object Diagrams

Extension

LatLonLocator InteractiveDepictExt

• Classes

• Objects

EditableElement

aLatLonLocator

anIntDepictExt

anEditablePoint


Location Selection

• An extension may ask for selected location events.• Forecaster selects a location by single-clicking or using

the popup menu.• A location may be a single point or an area specified by

two points.• To enable these events, set the last field to “y” in

extensionInfo.txt.• Then, override the Extension::locationSelected method.• Used by the Alert Area Editor to toggle on/off alert cells.


Tricks and Tips: Speeding Up Drawing

• Adding/modifying editable elements happens immediately.

• If you have lots of elements, the IGC will lag while drawing.

• Call this (static) method:InteractiveDepictExt::refreshIGC(false, igcProcess());

from within your extension code before making lots of changes. This will buffer the element updates.

• CallInteractiveDepictExt::refreshIGC(true, igcProcess());

to send all the requests at once. The IGC will draw all the elements in a single refresh.

• The WarnGen and Alert Area Editor extensions rely on this technique for efficient operation.


Tips and Tricks: Running a Lone IGC

• Testing an extension with a full D-2D running is a bit painful because of all the resources (memory, CPU) a full D-2D uses.

• You can run just an IGC process without a full D-2D.• Type:

IGC_Processwith your DISPLAY, FXA_HOME, FXA_DATA, and other environment variables appropriately set.

• A single IGC window will appear. To load your extension, first make sure the window has the keyboard focus. Then type:[depict-key]

where depict-key is the depict key of the interactive depictable that goes with your extension.

• Other keyboard commands are available.


Summary

• What’s an extension and how a framework works.• Composition of an extension.• Making an extension with a running example

– Information files to modify– Difference between static/nonstatic extensions– Classes to use

> Constructing a derived Extension class> Callback methods in class Extension> How and when to draw using EditableElement classes and

class InteractiveDepictableExt> Shared elements> Using the ExtFactory and ExtCreator classes

• Tips and Tricks


End Notes

This document was created April 1997, probably by Sean Kelly. The material was used for a presentation to the Taiwan CWB, and is included in a spiral-bound document titled “WFO-Advanced Seminar.” It was recreated December 2005 by John Osborn from a hard copy. The most recent edits are by Joe Wakefield, March 2006.

wfo-advanced extension framework (original) 28 apr 97 1 the d-2d extension framework what's an...

Documents

framework slide

d extension framework

extension objects

extension base class

different extension

class errorlist

class compiler

p errorlist