[vtk-developers] Generated doc for wrapper interfaces

[Jim Peterson]

Thanks David,
I guess we need to call for a volunteer to give us some idea what these 
classes are trying to do. Maybe if the original author is out there they 
could give us some hints.
I have used both vtkCanvas and VtkRenderWindowPanel, I cannot find a 
significant difference in behavior. There is a comment in 
vtkRenderWindowPanel that says:

// vtkRenderWindowPanel is a vtkCanvas which allows additional
// vtkRenderers to be added.  vtkPanel and vtkCanvas force you to
// add actors to the internal vtkRenderer.  vtkRenderWindowPanel
// always renders, even if the internal renderer has no visible actors.

I am not sure how I would test this behavior. I did an inventory of the 
set of methods implemented in the vtkPanel, vtkCanvas and 
vtkRenderWindowPanel. The set of methods provided by the three java 
interface classes I am aware of are:

vtkPanel (extends Canvas) methods:

        void addWindowSetObserver(Observer obs) -- ??
        void addNotify() -- invokes super.addNotify(), sets rendering to 
false.
        vtkRenderer GetRenderer() -- returns the ren variable.
        vtkRenderWindow GetRenderWindow() -- returns the rw variable
        void HardCopy(String filename, int mag) -- appears to write an 
image of the current window.
        boolean IsWindowSet() -- returns current windowset variable status.
        void InteractionModeTranslate() -- invoked from mousePressed()
        void InteractionModeRotate() -- invoked from mousePressed()
        void InteractionModeZoom() -- invoked from mousePressed()
        void keyPressed(KeyEvent e) -- appears to implement r, u, w and 
s keystroke events.
        void keyReleased(KeyEvent e) -- empty method
        void keyTyped(KeyEvent e) -- empty method.
        void LightFollowCameraOff() -- sets variable LightFollowCamera to 0
        void LightFollowCameraOn() -- sets variable LightFollowCamera to 1
        void lock() -- invokes jni lock().
        void mouseClicked(MouseEvent e) -- empty method
        void mouseDragged(MouseEvent e) -- appears to perform camera 
interactions. Test shows default interactor supports Switch interactor 
functions (c, a, t, and j).
        void mouseEntered(MouseEvent e) -- invokes this.requestFocus()
        void mouseExited(MouseEvent e) -- empty method
        void mouseMoved(MouseEvent e) -- saves lastX and lastY
        void mousePressed(MouseEvent e) -- Selects and sets interaction 
mode based in mouse buttons and keys.
        void mouseReleased(MouseEvent e) -- sets desired update rate to .01.
        void paint(Graphics g) -- invokes this.Render()
        void pickActor(int x, int y) -- Creates a picker, performs 
picker.PickProp() using the current location and the current renderer.
        void removeNotify() -- sets rendering to true, invokes 
super.removeNotify()
        void removeWindowSetObserver(Observer obs) -- ??
        void Render() -- calls rw.Render()
        void Report() -- writes some statistics to the java log.
        void resetCamera() -- calls ren.resetCamera() within lock.
        void resetCameraClippingRange() -- calls 
ren.resetCamerClippingRange() within lock.
        void setSize(int x, int y) -- calls super.setSize() then 
rw.setSize() within lock.
        void unlock() -- invokes jni unlock()
        void update(Graphics g) -- calls paint(g)
        void UpdateLight() -- resets light position and focal point to 
match variable cam.


vtkCanvas (extends vtkPanel) methods:

        void addToBoxWidget(vtkProp3D prop) -- ?? adds property to 
vtkBoxWidget, calls placeWidget().
        void addToPlaneWidget(vtkProp3D prop) -- ?? adds property to 
vtlPlaneWidget, calls placeWidget().
        void BeginBoxInteraction() -- callback, writes to log only.
        void BeginPlaneInteraction() -- callback, writes to log only.
        void DestroyTimer() -- asserts timer is stopped.
        vtkGenericRenderWindowInteractor getIren() -- returns variable iren.
        void keyPressed(KeyEvent e) -- overrides vtkPanel, sets iren 
event information, calls iren.KeyPressEvent() then iren.CharEvent() only 
of visible actors.
        void keyReleased(KeyEvent e) -- overrides vtkPanel, also empty 
method.
        void keyTyped(KeyEvent e) -- overrides vtkPanel, also empty method.
         void mouseClicked(MouseEvent e) -- overrides vtkPanel, empty method
        void mouseDragged(MouseEvent e) -- overrides vtkPanel, sets 
interaction values in iren, then invokes iren.MouseMoveEvent().
        void mouseEntered(MouseEvent e) -- Overrides vtkPanel, invokes 
this.requestFocus() then iren.EnterEvent();
        void mouseExited(MouseEvent e) -- Overrides vtkPanel, invokes 
iren.ExitEvent().
        void mouseMoved(MouseEvent e) -- Overrides vtkPanel, saves lastX 
and lastY, sets and invokes iren.MouseMoveEvent().
        void mousePressed(MouseEvent e) -- Overrides vtkPanel, Sets then 
tests for and invokes left, Middle or Right button press events in iren.
        void mouseReleased(MouseEvent e) -- Overrides vtkPanel, sets 
then tests for and invokes left, Middle, or Right button release events 
in iren.
       void setInteractorStyle(vtkInteractorStyle style) -- Sets 
supplied interaction style in interactor. default appears to be the 
switch interactor.
        void setSize(int x, int y) -- calls super setSize, then 
rw.SetSize(), iren.SetSize() and iren.Configure()
        void StartTimer() -- asserts timer is started.

vtkRenderWindowPanel (extends vtkCanvas) Methods
       
        void Render() -- overrides vtkPanel, removes test for visible 
actors for render. also light update.
        void mousePressed(MouseEvent e) -- overrides vtkCanvas, removes 
test for visible actor passes events to iren.
        void mouseDragged(MouseEvent e) -- overrides vtkCanvas, removes 
test for visible actor passes events to iren.
        void keyPressed(KeyEvent e); -- Overrides vtkCanvas passes event 
to iren even if no visible actors

There also seems to me to be a philosophical difference between the 
mouse and keypress event implementations between vtkPanel and vtkCanvas 
/ vtkRenderWindowPanel. I realize all of these classes may be in the 
"work in progress" category. If anyone can shed some insight in how 
these tools are intended to be used, I am sure we would all appreciate it.

Only vtkRenderWindowPanel has any class level documentation. I am 
unclear why anyone would use vtkPanel without either vtkCanvas or 
vtkRenderWindowPanel. I also fail to understand the box widget and plane 
widget functions in vtkCanvas.  If anyone can shed some light it would 
be appreciated.

Thanks in advance,
Jim

David Gobbi wrote:
> Hi Jim,
>
> The python helper classes have inline documentation that can be viewed 
> with python's help() command.  The python and tcl wrappers both 
> include documentation from all the VTK C++ headers, as well.
>
> For Java, the first step would be to add javadoc comments to vtkPanel 
> and vtkCanvas.  This could be done by anyone.  The second step would 
> be to change the cmake files so that they use the javadoc tools to 
> convert the comments to html.
>
>   David
>
> On Sun, Dec 5, 2010 at 11:49 AM, Jim Peterson <jimcp at cox.net 
> <mailto:jimcp at cox.net>> wrote:
>
>     All,
>     I added a java example
>     (http://www.vtk.org/Wiki/VTK/Examples/Java/Interaction/SphereInteractorPanel)
>     to the vtk wiki that uses the vtkCanvas interface class and I
>     noticed there is nowhere for the doxygen link to go for the vtk
>     class used named vtkCanvas. This appears to be true for all of the
>     java classes in the <vtkhome>/wrapping/java/vtk directory. those
>     classes are  included in the vtk package created with the
>     VTK_WRAP_JAVA option as if they are a part of vtk to the java
>     user. I noticed there is no vtkCanvas, or the class it extends
>     vtkPanel, Class documentation in Doxygen, and there is no useful
>     javadoc created for these classes during the build.
>     What would need to happen to document the set of java functions in
>     these and any other wrapper specific classes?
>
>     thanks for any ideas,
>     Jim Peterson
>
>     _______________________________________________
>     Powered by www.kitware.com <http://www.kitware.com>
>
>     Visit other Kitware open-source projects at
>     http://www.kitware.com/opensource/opensource.html
>
>     Follow this link to subscribe/unsubscribe:
>     http://www.vtk.org/mailman/listinfo/vtk-developers
>
>