DpHipeComponents < Public

Public Web>DpHipe>DpHipeComponents (2014-02-18, AlvarGarcia) (raw view)
<!-- ANALYTICS CODE - DO NOT EDIT -->
%INCLUDE{"%ATTACHURL%/GoogleAnalytics.txt" raw="on"}%
<!-- END OF ANALYTICS CODE -->
<!--
   * Set TOPICTITLE = Adding components to existing views
-->

| *PDF Version* | [[%SCRIPTURLPATH%/genpdf%SCRIPTSUFFIX%/%WEB%/%TOPIC%?pdforientation=portrait&pdftoclevels=2][Portrait]] | [[%SCRIPTURLPATH%/genpdf%SCRIPTSUFFIX%/%WEB%/%TOPIC%?pdforientation=landscape&pdftoclevels=2][Landscape]] |

%ICON{"help"}% *Did you spot something wrong or missing on this page? If you have an account on this TWiki, you can fix it yourself by editing the page. If you don't have an account, you can leave a message at the bottom of the page to tell us about it. Thank you in advance!*

---+ !!Adding components to existing views

%STARTINCLUDE%
<!-- summary -->
The contents of certain views can be extended by developers, such as the _Outline View_ and the _Editor Area_. Both are examples of the system reacting on a data selection made by the user.

Here we explain how you can contribute to the outline view and the editor area.
%STOPINCLUDE%

%TOC%

%STARTSECTION{"contrGuide"}%

<br clear="all"/>
<!--
   Some short-cuts
   * Set DRMROOT = http://herschel.esac.esa.int/hcss-doc-12.0/index.jsp#hcss_drm:
   * Set VIEWABLE   = [[%DRMROOT%herschel.ia.gui.kernel.part.Viewable][Viewable]]
   * Set VIEWPART   = [[%DRMROOT%herschel.ia.gui.kernel.parts.ViewPart][ViewPart]]
   * Set REGISTRY   = [[DpHipeRegistry][Extension Registry]]
   * Set INIT_PY    = =__init__.py=
   * Set SELISTENER = [[%DRMROOT%herschel.ia.gui.kernel.SiteEventListener][SiteEventListener]]

   * Set VARIABLES_VIEW    = [[%DRMROOT%herschel.ia.gui.apps.views.variables.VariablesView][VariablesView]]
   * Set OUTLINE_VIEW      = [[%DRMROOT%herschel.ia.gui.apps.views.outline.OutlineView][OutlineView]]
   * Set OUTLINE_COMPONENT = [[%DRMROOT%herschel.ia.gui.apps.views.outline.OutlineComponent][OutlineComponent]]
   * Set OBJECT_OUTLINE         = [[%DRMROOT%herschel.ia.gui.apps.components.outline.ObjectOutline][ObjectOutline]]
   * Set ARRAY_DATA_OUTLINE = [[%DRMROOT%herschel.ia.dataset.gui.views.ArrayDataOutline][ArrayDataOutline]]
   * Set DATASET_OUTLINE = [[%DRMROOT%herschel.ia.dataset.gui.views.CompositeDatasetOutline][CompositeDatasetOutline]]
   * Set PRODUCT_OUTLINE = [[%DRMROOT%herschel.ia.dataset.gui.views.ProductOutline][ProductOutline]]
   * Set EDITOR_COMPONENT  = [[%DRMROOT%herschel.ia.gui.kernel.parts.EditorComponent][EditorComponent]]
   * Set ABSTRACT_EDITOR_COMPONENT  = [[%DRMROOT%herschel.ia.gui.kernel.parts.AbstractEditorComponent][AbstractEditorComponent]]
   * Set SELECTION_EVENT   = [[%DRMROOT%herschel.ia.gui.kernel.event.SelectionEvent][SelectionEvent]]
   * Set FINE_TIME         = [[%DRMROOT%herschel.share.fltdyn.time.FineTime][FineTime]]
   * Set EXPLORER          = Explorer
-->

#OutlineView
---++ Outline View
<blockquote>

Whenever the user selects a session variable in the %VARIABLES_VIEW%, a %SELECTION_EVENT% is sent around.%BR%
The %OUTLINE_VIEW% is listening to such event and it tries to find the appropriate component that can show the outline information of that variable.

The contract for outline components is:

   * Implement the %OUTLINE_COMPONENT% interface by extending a [[http://docs.oracle.com/javase/6/docs/api/index.html?javax/swing/JComponent.html][javax.swing.JComponent]] (Java 6 for HIPE 11 or older) or [[http://docs.oracle.com/javase/7/docs/api/index.html?javax/swing/JComponent.html][javax.swing.JComponent]] (Java 7 for HIPE 12 or newer).
   * Register your implementation to the %REGISTRY% in the %INIT_PY%

The recommended way of implementing %OUTLINE_COMPONENT% is by extending %OBJECT_OUTLINE%, which provides a table with basic information about the variable.%BR%
Methods ==getExtraTableInfo()== and ==getExtraComponent()== may be overriden as needed for providing extra information about your type.

For example, suppose you want to create an outline for %FINE_TIME% variables to show their contents in the outline view whenever a session variable of that type is selected by the user.

---+++ Component Implementation
<blockquote>
In this example, we simply add an entry to the %OBJECT_OUTLINE% with the contents of the %FINE_TIME%.

<pre>
public class FineTimeOutline extends ObjectOutline {

    @Override
    protected Object[][] getExtraTableInfo() {
        Object time = getSelection().getValue();
        return new Object[][] { { "time", time.toString() } };
    }
}
</pre>
</blockquote>


---+++ Component Registry
<blockquote>
The following snippet would go into your %INIT_PY%:

<pre>
# Register to the variable outline factory
REGISTRY.register(COMPONENT,Extension(
                 "My FineTime Outline",
                 "resides.in.java.package.FineTimeOutline",
                 "factory.outline.variable",
                 "herschel.share.fltdyn.time.FineTime"))</b>

</pre>
See also the %REGISTRY% documentation for more details.

</blockquote>

---+++ Source Code of Basic implementations
<blockquote>
Package ==herschel.ia.dataset.gui== contains some basic implementations for %OUTLINE_COMPONENT% objects:
   * %ARRAY_DATA_OUTLINE%: a simple outline for any array data
   * %DATASET_OUTLINE%: a simple outline for any dataset
   * %PRODUCT_OUTLINE%: a simple outline for any product
   * %INIT_PY%: how the above get registered
</blockquote>

%ICON{tip}% If you have a sub-class of e.g. a product, you can also create a dedicated %OUTLINE_COMPONENT% for that sub-class, which will be picked up instead of the default %PRODUCT_OUTLINE%.

</blockquote>

---+++ FITS Preview Outline
<blockquote>
A special kind of outline is devoted to show previews of FITS files (for images, cubes, spectra...).

This is managed by [[%DRMROOT%herschel.ia.dataset.gui.views.FitsFileOutline][FitsFileOutline]], which reads the product contained in the FITS file in the background, and shows an image preview for it when done.

For this to work properly, any type that is meaningful to produce a preview should:

1. Extend [[%DRMROOT%herschel.ia.gui.kernel.PreviewMaker][herschel.ia.gui.kernel.PreviewMaker]]. For example, for images ([[%DRMROOTherschel.ia.gui.image.Image][herschel.ia.gui.image.Image]]):
<blockquote>
<pre>
import herschel.ia.gui.image.Image;

public class ImagePreviewMaker extends PreviewMaker&lt;Image&gt; {

    // PreviewFactory needs that every preview maker provides a default public constructor
    public ImagePreviewMaker() {
	super(Image.class);
    }

    // Either override this method
    @Override public java.awt.Image makeImage(Object o) {
	if (!(o instanceof Image)) return null;
	Image image = (Image)o;
        // create a Java image from the dataset image object
    }

    // or this one, by returning a visible component that will be used for drawing the image
    @Override protected java.awt.Component makeComponent(Image image) {
        // create a Java component from the dataset image
    }
}
</pre>
</blockquote>
2. Register the preview maker in the corresponding %INIT_PY%:
<blockquote>
<pre>
from herschel.ia.gui.kernel import ExtensionRegistry, Extension, PreviewFactory

REGISTRY.register(PreviewFactory.ID, Extension(
                  "Image preview maker",
                  "herschel.ia.gui.image.ImagePreviewMaker",
                  None,   # unused
                  "herschel.ia.dataset.image.Image"))
</pre>
</blockquote>

</blockquote>

#EditorArea
---++ Editor Area
<blockquote>
The above showed an example of extending the outline view by adding an %OUTLINE_COMPONENT%. Similarly, you can contribute by developing a specific %EDITOR_COMPONENT%.

Editor components are editors (optionally read-only) of data contents of a specific variable that is selected within in the HIPE session.%BR%
They are triggered by double-clicking on a variable, or through the _Open With_ menu. Editor components are opened in the editor area.

The contract for editor components is:

   * Implement the %EDITOR_COMPONENT% interface by extending %ABSTRACT_EDITOR_COMPONENT% or one of its subclasses.
   * Register your implementation to the %REGISTRY% in the %INIT_PY%.

---+++ Simple Example Code
<blockquote>
<pre>
import herschel.ia.gui.kernel.parts.AbstractVariableEditorComponent;

/**
 * Editor component for SomeType.
 */
public class SomeEditorComponent extends AbstractVariableEditorComponent&lt;SomeType&gt; {

    public Icon getComponentIcon() {
	return ...;
    }

    @Override
    protected Class&lt;SomeType&gt; getVariableType() {
	return SomeType.class;
    }

    @Override
    protected boolean makeEditorContent() {
        String name = getKey();
        SomeType value = getValue();
        JComponent content = ...;    // build the content with the provided value
        add(content);
        return true;
    }
}
</pre>
</blockquote>


---+++ Source Code of Basic implementations
<blockquote>
The ==herschel.ia.gui.apps== package contains some basic implementations for %EDITOR_COMPONENT% objects:
   * [[%DRMROOT%herschel.ia.gui.apps.components.editor.ListEditorComponent][ListEditorComponent]]: a simple viewer of lists.
   * [[%DRMROOT%herschel.ia.gui.apps.components.editor.DefaultFileEditorComponent][DefaultFileEditorComponent]]: a simple viewer of a file.
   * %INIT_PY%: how the above get registered.
</blockquote>


---+++ Component Registry
<blockquote>
Editor components need to be registered for telling the types they are interested in. This is to be done within your %INIT_PY%:

<pre>
# Register to the editor component factory
REGISTRY.register(COMPONENT,Extension(
                 "Some editor",
                 "herschel.your.module.views.SomeEditorComponent",
                 "factory.editor.variable",
                 "herschel.your.module.SomeType"))</b>

</pre>

</blockquote>


</blockquote>

%ENDSECTION{"contrGuide"}%

<!--
   * Set ALLOWTOPICCHANGE = Main.RegisteredUsersGroup, Main.TWikiAdminGroup
-->

<hr/>
<!-- COMMENT BOX CODE - DO NOT EDIT -->
<div id="disqus_thread"></div>
<script type="text/javascript">
    var disqus_shortname = 'herscheltwiki'; // required: replace example with your forum shortname

    (function() {
        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
        dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
    })();
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com" class="dsq-brlink">blog comments powered by <span class="logo-disqus">Disqus</span></a>
<!-- END OF COMMENT BOX CODE -->
<hr/>
Topic revision: r23 - 2014-02-18 - AlvarGarcia
Public
Webs
Public
TWiki