aboutsummaryrefslogtreecommitdiffstats
path: root/server/src/main/java/com/vaadin/ui/CustomComponent.java
blob: 73715d1224519cd2524a0825f5612bbdd0e80336 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
/*
 * Copyright 2000-2016 Vaadin Ltd.
 *
 * Licensed 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 com.vaadin.ui;

import java.util.Collections;
import java.util.Iterator;

import com.vaadin.shared.customcomponent.CustomComponentState;

/**
 * Custom component provides a simple implementation of the {@link Component}
 * interface to allow creating new UI components by composition of existing
 * server-side components.
 *
 * <p>
 * The component is used by inheriting the CustomComponent class and setting the
 * composition root component. The composition root must be set with
 * {@link #setCompositionRoot(Component)} before the CustomComponent is used,
 * such as by adding it to a layout, so it is preferable to set it in the
 * constructor.
 * </p>
 *
 * <p>
 * The composition root itself can contain more components. The advantage of
 * wrapping it in a CustomComponent is that its details, such as interfaces, are
 * hidden from the users of the component, thereby contributing to information
 * hiding.
 * </p>
 *
 * <p>
 * The CustomComponent does not display the caption of the composition root, so
 * if you want to have it shown in the layout where the custom component is
 * contained, you need to set it as caption of the CustomComponent.
 * </p>
 *
 * <p>
 * The component expands horizontally and has undefined height by default.
 * </p>
 *
 * @author Vaadin Ltd.
 * @since 3.0
 */
@SuppressWarnings("serial")
public class CustomComponent extends AbstractComponent
        implements HasComponents {

    /**
     * The root component implementing the custom component.
     */
    private Component root = null;

    /**
     * Constructs a new custom component.
     *
     * <p>
     * Note that you must set the composition root before the component can be
     * used, preferably in the constructor.
     * </p>
     */
    public CustomComponent() {
        // Expand horizontally by default
        setWidth(100, Unit.PERCENTAGE);
    }

    /**
     * Constructs a new custom component.
     *
     * @param compositionRoot
     *            the root of the composition component tree. It must not be
     *            null.
     */
    public CustomComponent(Component compositionRoot) {
        this();
        setCompositionRoot(compositionRoot);
    }

    /**
     * Returns the composition root.
     *
     * @return the Component Composition root.
     */
    protected Component getCompositionRoot() {
        return root;
    }

    /**
     * Sets the composition root for the component.
     *
     * <p>
     * You must set the composition root to a non-null value before the
     * component can be used. You can change it later.
     * </p>
     *
     * @param compositionRoot
     *            the root of the composition component tree.
     */
    protected void setCompositionRoot(Component compositionRoot) {
        if (compositionRoot != root) {
            if (root != null && equals(root.getParent())) {
                // remove old component
                root.setParent(null);
            }
            if (compositionRoot != null) {
                // set new component
                if (compositionRoot.getParent() != null) {
                    // If the component already has a parent, try to remove it
                    AbstractSingleComponentContainer
                            .removeFromParent(compositionRoot);
                }
                compositionRoot.setParent(this);
            }
            root = compositionRoot;
            markAsDirty();
        }
    }

    /* Basic component features ------------------------------------------ */

    @Override
    public Iterator<Component> iterator() {
        if (getCompositionRoot() != null) {
            return Collections.singletonList(getCompositionRoot()).iterator();
        } else {
            return Collections.<Component> emptyList().iterator();
        }
    }

    /**
     * Gets the number of contained components.
     *
     * @return the number of contained components (zero or one)
     */
    public int getComponentCount() {
        return (root != null ? 1 : 0);
    }

    @Override
    protected CustomComponentState getState() {
        return (CustomComponentState) super.getState();
    }

    @Override
    protected CustomComponentState getState(boolean markAsDirty) {
        return (CustomComponentState) super.getState(markAsDirty);
    }

}