Hi,

sorry for not responding earlier, but we've been quite busy on our mission.

I try to clarify as best as I can.

Generally I try to avoid asynchronous events (dispatching an event
and listening for it), if not required.

In terms of the mechanisms you mentioned, there should be some
documentation in the ASDocs, but I agree it may be confusing if the
difference between similar mechanisms is not explained.

1. VisualGraph.draw()

This does a full layout calculation (from scratch) and draws it. You want
to call this if you change layout parameters or layouts, of if nodes or
edges
have been added or removed or if the visibility of nodes has changed.
Some of these functions will call draw() automatically.

In short: full layout calculation and drawing

2. VisualGraph.refresh()

Sets _layouter.layoutChanged to true and calls invalidateDisplayList() on
the
VGraph.

This results in a redraw of all edges, but only the edges. This is required
everytime,
if node positions change and therefore the edges need to be redrawn to
connect again,
you can call it also if edge parameters change for some reason.

In short: redraws the egdes (no layout calculation and drawing of nodes)

3. ILayouter.layoutChanged:Boolean

Every layouter implements the layoutChanged property, which may be
set to true of false. Normally the layouter sets it to true, after it
has recalculated the layout and moved the nodes.

It is primarily used by the edgeRenderer, because the edge renderer checked
if the layout has changed, in order to decide whether to do anything or
not.
If the layout did not change, it does not have to redraw edges.
If the layout did change and the edges are redrawn the layouter then sets
_layouter.layoutChanged to false.

In order to force a redrawing of edges the refresh() method sets it to true
before calling invalidateDisplayList.

From the application side, ILayouter.layoutChanged should not be used
(and there shouldn't be a need to use it anyway, use refresh() instead).

In short: Mechanism for the layouter to tell the edgeRenderer to actually
do something.

4. invalidateDisplayList()

This is a standard public method of any UIComponent. It invalidates the
current display list of the object, causing the subsequent call to
updateDisplayList() during the next rendering cycle.

updateDisplayList is a protected Method from Canvas.

The implementation of the edgeRendering works as follows:

VisualGraph is a derived class from Canvas, thus being able to
override the updateDisplayList() method.

In this overridden method, a call to render the edges is inserted
before super.updateDisplayList() is called.

This enabled the VGraph to redraw the edges every time an update
of the display list is required. This idea was taken from Mark Sheppard
Springgraph implementation and I think it is required to allow smooth
scrolling
and dragging and dropping of nodes.

In short: calling invalidateDisplayList() will make flashplayer to call
updateDisplayList
on the object during the next rendering cycle. If also
_layouter.layoutChanged is true,
it will result in a redrawing of the edges.

There should not be any need to call invalidateDisplayList() manually
(except in the
refresh case, where it is used to force a redraw of edges).

5. vGraphChanged

Now this is the only event of the mechanisms. This event is dispatched by
the VGraph
in case any of its public properties have changed. This event can be used
by the
application to update labels. (e.g. a label that shows the number of
visible nodes).

I hope it is more clear now.

Cheers,
Daniel
--
Daniel Lang - la...@un.org - DM/OCSS/ITSD/QARMS - +1 917 367 5338

-----Jason BELLONE/UNOG/GVA/UNO wrote: -----

To: Daniel Lang/NY/UNO@UNHQ
From: Jason BELLONE/UNOG/GVA/UNO
Date: 10/26/2007 10:38AM
cc: "Nitin Lamba" <nitin...@gmail.com>
Subject: Visual Graph Questions

Daniel,

Can you add some clarity to Nitin's query about the event model code base:

"I've gone back and forth but I still don't think I fully understand the
event model in the codebase. We seem to be using several mechanisms such as
draw(), refresh(), set _layoutChanged to true, vGraphChanged,
invalidateDisplayList, etc. Can you share your thoughts on what to use
when? "

Thanks,

Jason