Getting to know Batik's codebase

Hi guys.

Hope you’re having a relaxing “interim period”. 

I’d like to make sure you both have a good feeling of
Batik’s codebase
and have started to refine your designs before the coding
time starts,
on May 28.

Have you checked out the source and started to have a poke
around?  Here
is a very brief overview of (the relevant parts of)
Batik’s
architecture:

  ▪ the SVG DOM (org.apache.batik.dom.svg)
    
    These classes implement the SVG DOM.  Most of the
classes in this
    package are named SVGOM*Element, and derive (eventually)
from
    org.apache.batik.dom.AbstractNode, which implements
    org.w3c.dom.Node.  Other classes in this package are for
the SVG
    datatypes, such as SVGOMAnimatedLength (which is an
implementation
    of org.w3c.dom.svg.SVGAnimatedLength).

  ▪ the GVT (org.apache.batik.gvt)

    The GVT is the Graphics Vector Toolkit (I think!). 
It’s a
    collection of classes that can represent graphical
objects in a
    tree-like fashion, which mostly parallels the structure
of the SVG
    document.  For example, for a ‘rect’ element in the
document, which
    is represented by an
org.apache.batik.dom.svg.SVGOMRectElement
    object, there will be a corresponding
org.apache.batik.gvt.ShapeNode
    object that represents the rectangular shape and its
properties.

    A GVT tree is usually rooted by a
    org.apache.batik.gvt.CanvasGraphicsNode.  Each
GraphicsNode can be
    painted to a Java2D java.awt.Graphics2D object, which is
how objects
    get painted into the JSVGCanvas component.

  ▪ the bridge (org.apache.batik.bridge)

    The bridge classes are used to build (and keep in sync)
GVT objects
    from the SVG DOM objects.  The main class that runs this
process is
    org.apache.batik.bridge.GVTBuilder.  Each SVG DOM object
has a
    corresponding bridge class, for example there is the
    org.apache.batik.bridge.SVGRectElementBridge, which is
in charge of
    building a ShapeNode from the SVGOMRectElement object.

    Each document has an
org.apache.batik.bridge.BridgeContext, which is
    a central point of document handling that the different
bridge
    classes will use.

  ▪ the CSS engine (org.apache.batik.css)

    The CSS engine implements the style handling rules in a
document.
    As well stylesheets and inline style with
style="" attributes, the
    SVG presentation attributes (such as fill=""
and font-size="") are
    handled by the CSS engine.  Whenever a bridge object
needs to get
    some styling information when building a GVT object,
it’ll query the
    CSS engine for the property’s current value.  For
example, see the
   
org.apache.batik.bridge.AbstractGraphicsNodeBridge#buildGrap
hicsNode
    method.  (AbstractGraphicsNodeBridge is the base class
for all
    bridges that create an
org.apache.batik.GraphicsNode—basically, for
    all graphical SVG elements.  It calls some methods in
CSSUtilities
    (which in turn queries the
org.apache.batik.css.engine.CSSEngine
    object) for values of various properties, such as
'opacity' and
    'clip-path'.  These property values are then set on the
    corresponding GraphicsNode object.

  ▪ the animation engine (org.apache.batik.anim)

    The animation engine classes are responsible for
“ticking” the
    document and modifying the relevant SVG DOM objects
representing
    attributes on SVG elements (or the relevant CSS
properties, if it’s
    an attributeType="CSS" animation).

    The classes in org.apache.batik.anim.timing handle all
of the timing
    requirements of SMIL Animation
(begin/end/dur/repeat/etc.
    attributes), and classes in org.apache.batik.anim.values
represent
    values in the animations of the various types (numbers,
colours,
    lengths, length lists, etc.).  The classes that
represent each
    individual animation are
org.apache.batik.anim.*Animation.

    org.apache.batik.anim.AnimationEngine (and its
specialisation,
    org.apache.batik.bridge.SVGAnimationEngine) is the main
driver of
    animations in the document.  It handles adding and
removing
    animations, ensuring they will be evaluated in the
correct order,
    and update each animated attribute/property every
“tick” by querying
    each *Animation object for its current value based on
the current
    document time.

  ▪ the JSVGCanvas (org.apache.batik.swing)

    This is the SVG viewing component that’s used in the
main part of
    Squiggle.  It is essentially a component that can have a
GVT tree
    rendered on it, which also kicks off the bridge objects
to generate
    that GVT tree from an SVG document.

  ▪ the DOMViewer (org.apache.batik.util.gui)

    The DOMViewer class which you’ll probably be
interested in seeing is
    just a Swing component that inspects the current state
of the SVG
    document and represents it with a tree along with a
table of
    attribute/property values.

Obviously this’ll be a lot to digest if you’re new to
the code.  I
suggest you trace through a rendering of a document to see
how the flow
of control works between all these classes.  A good place to
set your
IDE up to break on might be
org.apache.batik.swing.svg.AbstractJSVGComponent#installSVGD
ocument.

I think it’ll be good for you guys also to have a look
through the SVG
1.1 spec (http://www.w3.org/TR/SVG1
1/) if you haven’t done so already.

As always, just ask on the batik-dev mailing list if you
have any
questions.

Are you guys going to have a wiki or blog or something to
document your
progress?  There’s no requirement to, but it may be useful
for me (and
the other devs) to see where you’re at.

In a few weeks, before the coding start date, we can discuss
the
logistics of how your code is going to be added in to the
existing
codebase (a series of patches, a branch, directly in the
trunk, or
whatever).

Cameron

-- 
Cameron McCormack, http://mcc.id.au/
	xmpp:heycamjabber.org  ▪  ICQ 26955922  ▪  MSN cammcc.id.au

------------------------------------------------------------
---------
To unsubscribe, e-mail: batik-dev-unsubscribexmlgraphics.apache.org
For additional commands, e-mail: batik-dev-helpxmlgraphics.apache.org

Hi Cameron,

On 5/1/07, Cameron McCormack <cammcc.id.au> wrote:
> Hi guys.
>
> Hope you're having a relaxing "interim
period". 
>
> I'd like to make sure you both have a good feeling of
Batik's codebase
> and have started to refine your designs before the
coding time starts,
> on May 28.

The "interim period" is going just fine. I have
downloaded
batik-1_7beta (I used 1.6 before) from SVN and done some
browsing
through the code, especially the DOMViewer class. I've been
trying
some of the stuff on the Viewer, and would appreciate your
comments on
some of the following issues.

1) Regarding the tree:
Adding pop-up menu to the nodes in the tree, containing
"remove" and
"add new node" items. Remove option would remove
selected nodes from
the document (as well as from the tree). Add new node option
would
open the dialog, from which the node type and the node
attributes have
to be chosen (and maybe some other options), and append that
node as a
child to the selected node from the tree. The issues here
are the
compatibility of the parent node and the appended one,
determining the
required attributes according to the node type, filling the
values of
the attributes with valid values etc.

2) The attributes (name/value) table:
Making the the value column of the table editable, so the
attribute
values can be changed; Adding the pop-up menu to remove and
add new
attribute through a dialog.

3) Making the text area for comment, text or cdata_section
node editable.

4) Tracking the changes of the document structure. As
Thomas
suggested, adding Mutation Event Listeners would manage the
update of
DOMViewer whenever the document structure changes, including
using the
DOMViewer itself to change the document.

> Obviously this'll be a lot to digest if you're new to
the code.  I
> suggest you trace through a rendering of a document to
see how the flow
> of control works between all these classes.  A good
place to set your
> IDE up to break on might be
>
org.apache.batik.swing.svg.AbstractJSVGComponent#installSVGD
ocument.
>
> I think it'll be good for you guys also to have a look
through the SVG
> 1.1 spec (http://www.w3.org/TR/SVG1
1/) if you haven't done so already.
>
> As always, just ask on the batik-dev mailing list if
you have any
> questions.

I plan to continue working on these issues, as well as to
browse
deeper into the Batik's architecture.

> Are you guys going to have a wiki or blog or something
to document your
> progress?  There's no requirement to, but it may be
useful for me (and
> the other devs) to see where you're at.

I can create a wiki page (perhaps http://www.wikidot.com ?)
or share a
document on the google docs.

Ivan

------------------------------------------------------------
---------
To unsubscribe, e-mail: batik-dev-unsubscribexmlgraphics.apache.org
For additional commands, e-mail: batik-dev-helpxmlgraphics.apache.org

Hey Ivan.

Ivan Andjelkovic:
> The "interim period" is going just fine. I
have downloaded
> batik-1_7beta (I used 1.6 before) from SVN and done
some browsing
> through the code, especially the DOMViewer class. I've
been trying
> some of the stuff on the Viewer, and would appreciate
your comments on
> some of the following issues.

Cool, ok.  (Sorry about the detail in replying…)

> 1) Regarding the tree:
> Adding pop-up menu to the nodes in the tree, containing
"remove" and
> "add new node" items. Remove option would
remove selected nodes from
> the document (as well as from the tree). Add new node
option would
> open the dialog, from which the node type and the node
attributes have
> to be chosen (and maybe some other options), and append
that node as a
> child to the selected node from the tree. The issues
here are the
> compatibility of the parent node and the appended one,
determining the
> required attributes according to the node type, filling
the values of
> the attributes with valid values etc.

Yeah that sounds like a good start.  If using pop-up menus,
you could
just ensure that only the menu items corresponding to
compatible node
types are enabled/visible.

> 2) The attributes (name/value) table:
> Making the the value column of the table editable, so
the attribute
> values can be changed; Adding the pop-up menu to remove
and add new
> attribute through a dialog.
>
> 3) Making the text area for comment, text or
cdata_section node editable.

Yup.

> 4) Tracking the changes of the document structure. As
Thomas
> suggested, adding Mutation Event Listeners would manage
the update of
> DOMViewer whenever the document structure changes,
including using the
> DOMViewer itself to change the document.

Yes, I think using the standard DOM mutation listeners would
be best for
tracking changes to the document structure.  (For the CSS
properties,
you’ll have to use a CSSEngineListener on the CSSEngine.)

> I plan to continue working on these issues, as well as
to browse
> deeper into the Batik's architecture.

Great.

> >Are you guys going to have a wiki or blog or
something to document your
> >progress?  There's no requirement to, but it may be
useful for me (and
> >the other devs) to see where you're at.
> 
> I can create a wiki page (perhaps http://www.wikidot.com ?)
or share a
> document on the google docs.

There’s also an Apache wiki you can use:

  http://wiki
.apache.org/xmlgraphics-batik/

It’s not pretty, but a good thing is that updates to pages
there send
notification mails to batik-dev.  I’d suggest using that
over an
external site, if a wiki is what you’d like to use.

-- 
Cameron McCormack, http://mcc.id.au/
	xmpp:heycamjabber.org  ▪  ICQ 26955922  ▪  MSN cammcc.id.au

------------------------------------------------------------
---------
To unsubscribe, e-mail: batik-dev-unsubscribexmlgraphics.apache.org
For additional commands, e-mail: batik-dev-helpxmlgraphics.apache.org

Hi Cameron,

I have been working on creating those pop - ups, updating
the view in
the Viewer when the document changes and editing the tree,
the table
and the text area.
Here are some issues so far:

1. Allowing the "don't live track" option might
cause the Viewer to
become incompatibile with the document - for example some
nodes or
attributes might have been removed from the document, but
are still
shown in the Viewer, etc.
If so, there wouldn't be much sense to allow editing. But
anyway there
are few possibilities here:
a) Allow the "don't live track" option anyway. In
this case
compatibility of the document shown in the Viewer and the
document
itself has to be determined
when the Viewer is used for editing the document. If
incompatibile -
send some notification that document cannot be edited due
incompatibility with the Viewer...
b) Set the Viewer to be "always_dynamic" and
always live - track
the document.
c) An addition to b) is implementation of command pattern to
allow
undo and redo actions for the changes on the document.
I think of c) as the most useful.

2. If the document is shown on JSVGCanvas, then the updates
of the DOM
should be called using the UpdateManager. Adding a method
setCanvas(JSVGCanvas canvas) instead of setDocument(...)
would allow
the Viewer to get the canvas anytime and perform the update
using the
canvas's UpdateManager. This way there would be no need of
calling the
setDocument(...) method explicitly outside of the Viewer.
a) But still setDocument(...)  would remain public to handle
the
existing code...
b) New method setCanvas(...) would be available for tracking
the
changes on the canvas where the document is displayed.


Ivan

------------------------------------------------------------
---------
To unsubscribe, e-mail: batik-dev-unsubscribexmlgraphics.apache.org
For additional commands, e-mail: batik-dev-helpxmlgraphics.apache.org

Hey Ivan.

Ivan Andjelkovic:
> I have been working on creating those pop - ups,
updating the view in
> the Viewer when the document changes and editing the
tree, the table
> and the text area.
> Here are some issues so far:
> 
> 1. Allowing the "don't live track" option
might cause the Viewer to
> become incompatibile with the document - for example
some nodes or
> attributes might have been removed from the document,
but are still
> shown in the Viewer, etc.
> If so, there wouldn't be much sense to allow editing.
But anyway there
> are few possibilities here:
> a) Allow the "don't live track" option
anyway. In this case
> compatibility of the document shown in the Viewer and
the document
> itself has to be determined
> when the Viewer is used for editing the document. If
incompatibile -
> send some notification that document cannot be edited
due
> incompatibility with the Viewer...
> b) Set the Viewer to be "always_dynamic" and
always live - track
> the document.
> c) An addition to b) is implementation of command
pattern to allow
> undo and redo actions for the changes on the document.
> I think of c) as the most useful.

That’s a good point.  I do like the idea of being able to
browse the
“history” of the document–is that what you mean by the
undo and redo
actions?  Would you also include changes made by scripts in
the
document?  Either way, editing would have to be restricted
to when
viewing the “up to date” document.

> 2. If the document is shown on JSVGCanvas, then the
updates of the DOM
> should be called using the UpdateManager. Adding a
method
> setCanvas(JSVGCanvas canvas) instead of
setDocument(...) would allow
> the Viewer to get the canvas anytime and perform the
update using the
> canvas's UpdateManager. This way there would be no need
of calling the
> setDocument(...) method explicitly outside of the
Viewer.
> a) But still setDocument(...)  would remain public to
handle the
> existing code...
> b) New method setCanvas(...) would be available for
tracking the
> changes on the canvas where the document is displayed.

Hmm.  I think giving the JSVGCanvas explicitly to the Viewer
is giving
too much information to it.  At this point, all the Viewer
component
needs is the document and a way to schedule the
modifications to the
document (i.e., dispatching a runnable to the
UpdateManager’s queue).
Perhaps later, you (or Jasleen) will need access to other
things too
(like the CSSEngine).  Perhaps an interface to provide this
information
to the Viewer would be better?  If not, then maybe just give
the
BridgeContext to the Viewer (from which you can get access
to the
UpdateManager)?

-- 
Cameron McCormack, http://mcc.id.au/
	xmpp:heycamjabber.org  ▪  ICQ 26955922  ▪  MSN cammcc.id.au

------------------------------------------------------------
---------
To unsubscribe, e-mail: batik-dev-unsubscribexmlgraphics.apache.org
For additional commands, e-mail: batik-dev-helpxmlgraphics.apache.org

Hi everyone,

> Actually, I don't think editing would have to be
restricted to
> then.  If you have rolled back changes the document is
in the state
> it was in earlier.  Admittedly doing that may break a
lot of scripts
> but heck any editing of the document without being
careful is likely
> to do that.
> 
> Perhaps a better question would be if you include
script
> modifications (and I'm not sure it's a good idea just
because of
> memory consumption, certainly it needs to be a UI
option to
> turn of tracking history for dynamic documents) what
would be
> your granularity.  Having undo one script change would
likely
> be almost useless.  I was thinking that you might group
all script
> changes between user changes into one 'extra' undo
block. 

Initially I was thinking of remembering every single change
on the
document and putting it into the history (history size would
be
initially set), and offering an option to allow undo of a
single change
or a custom number of last changes to the document.

The problem appears when the changes in the document are 
frequent in a short period, and some changes that are 
"not of interest" are remembered - each one as a
separate change. 
For example a value of an attribute can be changed many
times 
in a row. Grouping all these changes to a separate change
would 
discard the changes "not of interest". 
If this is what you meant by granularity, then I think the
issue might
be finding a way to create the "groups" of
changes. 


> Also depending on how you implement updates, you have
the issue
> that even when live tracking a change to the document
may have made
> the change you were about to apply to the document
invalid.  I'm
> actually thinking that the Viewer may need to 'pause'
the document
> when it goes into 'edit' mode.  There is a good
question of how
> best to have the user signal the move into edit mode. 
Should it
> be a 'check box' in the UI.  Should it happen
automatically if you
> click on a field (to start an edit) or try to
create/delete elements?

I meant to refresh the view in the Viewer through mutation 
events. If the user edits the document through the Viewer,
the document 
changes, mutation events are fired and the view in the
Viewer refreshes. 
Do you think I need to 'pause' the document? How do I do
that?

I have also created a wiki and put some of the things there
http://wiki.apache.org/xmlgraphics-batik/IvanAn
djelkovic-gsoc2007

Ivan
-- 
View this message in context: http://www.nabble.com/Getting-t
o-know-Batik%27s-codebase-tf3673369.html#a10794127
Sent from the Batik - Dev mailing list archive at
Nabble.com.


------------------------------------------------------------
---------
To unsubscribe, e-mail: batik-dev-unsubscribexmlgraphics.apache.org
For additional commands, e-mail: batik-dev-helpxmlgraphics.apache.org

Hi Ivan.

Ivan Andjelkovic:
> Initially I was thinking of remembering every single
change on the
> document and putting it into the history (history size
would be
> initially set), and offering an option to allow undo of
a single change
> or a custom number of last changes to the document.
> 
> The problem appears when the changes in the document
are 
> frequent in a short period, and some changes that are 
> "not of interest" are remembered - each one
as a separate change. 
> For example a value of an attribute can be changed many
times 
> in a row. Grouping all these changes to a separate
change would 
> discard the changes "not of interest". 
> If this is what you meant by granularity, then I think
the issue might
> be finding a way to create the "groups" of
changes. 

I think that is what Thomas meant by granularity.  Maybe it
would be
excessive to store every single DOM mutation, and that
grouping them in
blocks of script runs would be more helpful.  Maybe the
interface could
support both, allowing the user to jump forward/back a group
of
mutations or a single mutation at a time?

Thomas DeWeese:
> > Also depending on how you implement updates, you
have the issue
> > that even when live tracking a change to the
document may have made
> > the change you were about to apply to the document
invalid.  I'm
> > actually thinking that the Viewer may need to
'pause' the document
> > when it goes into 'edit' mode.  There is a good
question of how
> > best to have the user signal the move into edit
mode.  Should it
> > be a 'check box' in the UI.  Should it happen
automatically if you
> > click on a field (to start an edit) or try to
create/delete elements?

Ivan Andjelkovic:
> I meant to refresh the view in the Viewer through
mutation 
> events. If the user edits the document through the
Viewer, the document 
> changes, mutation events are fired and the view in the
Viewer refreshes. 
> Do you think I need to 'pause' the document? How do I
do that?

I think the issue would be that if for example you inserted
a new rect
element into the document, it would start off with no
attributes and
would thus be invalid, and an error message would pop up. 
Pausing the
document would stop processing and you could resume it once
the user has
written the proper attributes on the element.

You can pause/resume the document with the suspendRedraw
and
unsuspendRedraw methods on the SVGSVGElement object.

> I have also created a wiki and put some of the things
there
> http://wiki.apache.org/xmlgraphics-batik/IvanAn
djelkovic-gsoc2007

Great!

-- 
Cameron McCormack, http://mcc.id.au/
	xmpp:heycamjabber.org  ▪  ICQ 26955922  ▪  MSN cammcc.id.au

------------------------------------------------------------
---------
To unsubscribe, e-mail: batik-dev-unsubscribexmlgraphics.apache.org
For additional commands, e-mail: batik-dev-helpxmlgraphics.apache.org