Effects

The term "effects" refers to Pivot's support for customizing the appearance or behavior of a component, often over a timed interval producing an "animation". Pivot's primary support for effects is provided by two types of classes: decorators and transitions.

Decorators allow an application alter the appearance of a component beyond what is supported by the component's styles or any custom renderers the component might support. For example, a decorator could be used to blur the main window of an application when a modal dialog is open, or render the image shown by an image view in grayscale rather than full color.

The following example demonstrates a number of stock Pivot decorators by attaching the selected decorator to an ImageView component:

The BXML source for the example is shown below (there is no associated Java source):

            
            <Window title="Decorators" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns:effects="org.apache.pivot.wtk.effects"
                xmlns="org.apache.pivot.wtk">
                <TablePane>
                    <columns>
                        <TablePane.Column width="1*"/>
                        <TablePane.Column width="-1"/>
                    </columns>

                    <TablePane.Row>
                        <Border styles="{padding:2}">
                            <BoxPane preferredWidth="480" preferredHeight="480"
                                styles="{horizontalAlignment:'center', verticalAlignment:'top', padding:6}">
                                <ImageView bxml:id="imageView" image="/org/apache/pivot/tutorials/IMG_0725_2.jpg"/>
                            </BoxPane>
                        </Border>

                        <BoxPane orientation="vertical" styles="{padding:6, spacing:6}">
                            <bxml:define>
                                <ButtonGroup bxml:id="decoratorButtonGroup">
                                    <buttonGroupListeners>
                                        function selectionChanged(buttonGroup) {
                                            var selection = buttonGroup.getSelection();

                                            if (selection != null) {
                                                var decorator = selection.getUserData().get("decorator");
                                                imageView.getDecorators().removeAll();

                                                if (decorator != null) {
                                                    imageView.getDecorators().add(decorator);
                                                }
                                            }
                                        }
                                    </buttonGroupListeners>
                                </ButtonGroup>
                            </bxml:define>

                            <RadioButton buttonData="None" buttonGroup="$decoratorButtonGroup" selected="true"/>

                            <RadioButton buttonData="Blur" buttonGroup="$decoratorButtonGroup">
                                <userData>
                                    <decorator>
                                        <effects:BlurDecorator/>
                                    </decorator>
                                </userData>
                            </RadioButton>

                            <RadioButton buttonData="Fade" buttonGroup="$decoratorButtonGroup">
                                <userData>
                                    <decorator>
                                        <effects:FadeDecorator opacity="0.33"/>
                                    </decorator>
                                </userData>
                            </RadioButton>

                            <RadioButton buttonData="Grayscale" buttonGroup="$decoratorButtonGroup">
                                <userData>
                                    <decorator>
                                        <effects:GrayscaleDecorator/>
                                    </decorator>
                                </userData>
                            </RadioButton>

                            <RadioButton buttonData="Reflection" buttonGroup="$decoratorButtonGroup">
                                <userData>
                                    <decorator>
                                        <effects:ReflectionDecorator/>
                                    </decorator>
                                </userData>
                            </RadioButton>

                            <RadioButton buttonData="Saturation" buttonGroup="$decoratorButtonGroup">
                                <userData>
                                    <decorator>
                                        <effects:SaturationDecorator multiplier="2.5"/>
                                    </decorator>
                                </userData>
                            </RadioButton>

                            <RadioButton buttonData="Shade" buttonGroup="$decoratorButtonGroup">
                                <userData>
                                    <decorator>
                                        <effects:ShadeDecorator color="#ff0000" opacity="0.33"/>
                                    </decorator>
                                </userData>
                            </RadioButton>

                            <RadioButton buttonData="Watermark" buttonGroup="$decoratorButtonGroup">
                                <userData>
                                    <decorator>
                                        <effects:WatermarkDecorator text="Watermark" font="Arial BOLD 24"
                                            opacity="0.33"/>
                                    </decorator>
                                </userData>
                            </RadioButton>
                        </BoxPane>
                    </TablePane.Row>
                </TablePane>
            </Window>
            
        

Notice that decorators are allowed to paint outside of a component's bounds (which a component generally is not). This allows decorators to be used to create the reflection effect shown in the example, or to paint a drop shadow (in fact, the drop shadows that appear beneath Pivot windows are produced by the DropShadowDecorator class).

Next: Transitions