org.apache.pivot.wtk.Renderer Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to you under the Apache License,
* Version 2.0 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.pivot.wtk;
import org.apache.pivot.collections.Dictionary;
/**
* 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 {@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.
*
*
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,
* {@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 {
/**
* Returns the renderer's style dictionary.
*/
public Dictionary getStyles();
}