You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pivot.apache.org by sm...@apache.org on 2011/11/15 12:59:49 UTC

svn commit: r1202146 - in /pivot/trunk/wtk/src/org/apache/pivot/wtk: Button.java ListView.java Renderer.java Spinner.java TableView.java TreeView.java

Author: smartini
Date: Tue Nov 15 11:59:48 2011
New Revision: 1202146

URL: http://svn.apache.org/viewvc?rev=1202146&view=rev
Log:
PIVOT-818, updated/clarified JavaDoc for classes implementing/extending Renderer

Modified:
    pivot/trunk/wtk/src/org/apache/pivot/wtk/Button.java
    pivot/trunk/wtk/src/org/apache/pivot/wtk/ListView.java
    pivot/trunk/wtk/src/org/apache/pivot/wtk/Renderer.java
    pivot/trunk/wtk/src/org/apache/pivot/wtk/Spinner.java
    pivot/trunk/wtk/src/org/apache/pivot/wtk/TableView.java
    pivot/trunk/wtk/src/org/apache/pivot/wtk/TreeView.java

Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Button.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Button.java?rev=1202146&r1=1202145&r2=1202146&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Button.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Button.java Tue Nov 15 11:59:48 2011
@@ -35,7 +35,7 @@ public abstract class Button extends Com
     }
 
     /**
-     * Button data renderer interface.
+     * {@link Renderer} interface to customize the appearance of data in a Button.
      */
     public interface DataRenderer extends Renderer {
         /**

Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ListView.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ListView.java?rev=1202146&r1=1202145&r2=1202146&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ListView.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ListView.java Tue Nov 15 11:59:48 2011
@@ -61,7 +61,7 @@ public class ListView extends Component 
     }
 
     /**
-     * List item renderer interface.
+     * {@link Renderer} interface to customize the appearance of items in a ListView.
      */
     public interface ItemRenderer extends Renderer {
         /**

Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Renderer.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Renderer.java?rev=1202146&r1=1202145&r2=1202146&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Renderer.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Renderer.java Tue Nov 15 11:59:48 2011
@@ -21,6 +21,66 @@ import org.apache.pivot.collections.Dict
 /**
  * Base interface for "renderers". Renderers are used to customize the
  * appearance of a component's content.
+ *
+ * <p>There are several components in Pivot that accept an arbitrary Java
+ * object or objects to show as part of their appearance, such as the label
+ * of a {@link LinkButton}, the items in a the drop-down menu of a {@link
+ * ListButton}, or the cells in a {@link TableView}. By default these
+ * components know how to display strings, but you can define a custom
+ * renderer to change the default behaviour and/or use non-string data.
+ *
+ * <p>The exact details of the renderer subinterfaces differ according to the
+ * needs of the component, but they all use the the following framework:
+ *
+ * <ul>
+ * <li>A <code>render</code> method, which is called when the component
+ * needs to discover the appearance of a data item, and </li>
+ * <li>A <code>toString</code> method, which is called when the user wants
+ * to navigate via keyboard. (This, of course, may not make sense for data
+ * that do not contain an apparent textual component.)</li>
+ * </ul>
+ *
+ * <p>The <code>render</code> method is called during layout and paint
+ * operations. It is passed the data object to be rendered, the component
+ * performing the rendering, and possibly additional parameters giving
+ * context specific to the component, such as whether the object is
+ * "selected", or the relative location of a cell inside the component. The
+ * renderer's job is to change its internal state using the data object and
+ * be prepared to respond to subsequent calls querying the size of the
+ * rendering or to paint it. Some components may also call the
+ * <code>render</code> method with an object of <code>null</code> when
+ * doing layout, if it makes the assumption that all the data elements will
+ * be the same size in one or both dimensions, such as the elements of a
+ * list.
+ *
+ * <p>Although not strictly required, the most convenient way to define a
+ * renderer is by subclassing a <code>Component</code>, since Components
+ * are already able to respond to layout and paint methods. That means all
+ * the <code>render</code> method has to do is to modify the Component to
+ * include the visually interesting part(s) of the data object in an
+ * appropriate place, such as by setting the text of a Label to an
+ * identifying string from the object, or setting the image of an ImageView
+ * to an icon contained in the object.
+ *
+ * <p>N.B. If you base a renderer on a Component, you need to call validate on
+ * it in order for it to paint correctly, because your renderer doesn't
+ * have a parent to take care of that for you. Since all components that
+ * call renderers call <code>setSize</code> before calling
+ * <code>paint</code>, the canonical way to handle this is by including the
+ * following override in your renderer:
+ * <pre>     @Override
+ *     public void setSize(int width, int height) {
+ *         super.setSize(width, height);
+ *         validate();
+ *     }</pre>
+ * <p>Note that you don't always need the additional parameters to
+ * <code>render</code> if your renderer is simple enough. For example,
+ * {@link ListView} passes parameters that tell whether the item is
+ * selected or highlighted, but it also sets the background of the area
+ * occupied by the renderer according to those parameters. Thus, if your
+ * render has a transparent background, the selection state will be
+ * apparent. Of course, you may want to adjust font or border colors within
+ * the renderer to be harmonious with that different background.
  */
 public interface Renderer extends ConstrainedVisual {
     /**

Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Spinner.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Spinner.java?rev=1202146&r1=1202145&r2=1202146&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Spinner.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Spinner.java Tue Nov 15 11:59:48 2011
@@ -35,7 +35,7 @@ import org.apache.pivot.wtk.content.Spin
 @DefaultProperty("spinnerData")
 public class Spinner extends Container {
     /**
-     * Spinner renderer interface.
+     * {@link Renderer} interface to customize the appearance of the data in a Spinner.
      */
     public interface ItemRenderer extends Renderer {
         /**

Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/TableView.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/TableView.java?rev=1202146&r1=1202145&r2=1202146&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/TableView.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/TableView.java Tue Nov 15 11:59:48 2011
@@ -492,7 +492,7 @@ public class TableView extends Component
     }
 
     /**
-     * Table cell renderer interface.
+     * {@link Renderer} interface to customize the appearance of a cell in a TableView.
      */
     public interface CellRenderer extends Renderer {
         /**
@@ -544,7 +544,7 @@ public class TableView extends Component
     }
 
     /**
-     * Table view header data renderer interface.
+     * {@link Renderer} interface to customize the appearance of the header of a TableView
      */
     public interface HeaderDataRenderer extends Renderer {
         /**

Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/TreeView.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/TreeView.java?rev=1202146&r1=1202145&r2=1202146&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/TreeView.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/TreeView.java Tue Nov 15 11:59:48 2011
@@ -88,7 +88,7 @@ public class TreeView extends Component 
     }
 
     /**
-     * Tree view node renderer interface.
+     * {@link Renderer} interface to customize the appearance of items in a TreeView.
      */
     public interface NodeRenderer extends Renderer {
         /**