Package org.apache.pivot.wtk

Interface Renderer

All Superinterfaces:

ConstrainedVisual, Visual

All Known Subinterfaces:

Button.DataRenderer, ListView.ItemRenderer, Spinner.ItemRenderer, TableView.CellRenderer, TableView.HeaderDataRenderer, TreeView.NodeRenderer

All Known Implementing Classes:

AccordionHeaderDataRenderer, ButtonDataRenderer, CalendarButtonDataRenderer, LinkButtonDataRenderer, ListButtonColorItemRenderer, ListButtonDataRenderer, ListViewColorItemRenderer, ListViewItemRenderer, MenuBarItemDataRenderer, MenuButtonDataRenderer, MenuItemDataRenderer, SpinnerItemRenderer, TableViewBooleanCellRenderer, TableViewCellRenderer, TableViewCheckboxCellRenderer, TableViewDateCellRenderer, TableViewFileSizeCellRenderer, TableViewHeaderDataRenderer, TableViewImageCellRenderer, TableViewMultiCellRenderer, TableViewNumberCellRenderer, TableViewTextAreaCellRenderer, TableViewTriStateCellRenderer, TerraCalendarSkin.MonthSpinnerItemRenderer, TerraFileBrowserSkin.ListButtonDriveRenderer, TerraFileBrowserSkin.ListButtonFileRenderer, TerraFileBrowserSkin.ListViewDriveRenderer, TerraFileBrowserSkin.ListViewFileRenderer, TerraFileBrowserSkin.TableViewFileRenderer, TerraVFSBrowserSkin.ListButtonDriveRenderer, TerraVFSBrowserSkin.ListButtonFileRenderer, TerraVFSBrowserSkin.ListViewDriveRenderer, TerraVFSBrowserSkin.ListViewFileRenderer, TerraVFSBrowserSkin.TableViewFileRenderer, TreeViewNodeRenderer, VerticalButtonDataRenderer

public interface Renderer
extends ConstrainedVisual

Base interface for "renderers". Renderers are used to customize the appearance of a component's content.

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 LinkButton, the items in a the drop-down menu of a ListButton, or the cells in a 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.

The exact details of the renderer subinterfaces differ according to the needs of the component, but they all use the the following framework:

• A render method, which is called when the component needs to discover the appearance of a data item, and
• A toString 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.)

The render 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 render method with an object of null 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.

Although not strictly required, the most convenient way to define a renderer is by subclassing a Component, since Components are already able to respond to layout and paint methods. That means all the render 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.

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 setSize before calling paint, the canonical way to handle this is by including the following override in your renderer:

 @Override public void setSize(int width, int height) {
 super.setSize(width, height); validate(); }

Note that you don't always need the additional parameters to render if your renderer is simple enough. For example, 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.

Method Summary

Modifier and Type	Method	Description
Dictionary<java.lang.String,java.lang.Object>	getStyles()

Methods inherited from interface org.apache.pivot.wtk.ConstrainedVisual

getBaseline, getPreferredHeight, getPreferredSize, getPreferredWidth, setSize, setSize

Methods inherited from interface org.apache.pivot.wtk.Visual

getBaseline, getHeight, getSize, getWidth, paint

Method Detail

getStyles

Dictionary<java.lang.String,java.lang.Object> getStyles()

Returns:

The renderer's style dictionary.