summaryrefslogtreecommitdiffstats
path: root/documentation/components/components-interfaces.asciidoc
blob: 2c1fa3f260b8ae2c03ee97e3c4f7ab41d12fab46 (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
---
title: Interfaces and Abstractions
order: 2
layout: page
---

[[components.interfaces]]
= Interfaces and Abstractions

((("interfaces")))
Vaadin user interface components are built on a skeleton of interfaces and
abstract classes that define and implement the features common to all components
and the basic logic how the component states are serialized between the server
and the client.

This section gives details on the basic component interfaces and abstractions.
The layout and other component container abstractions are described in
<<../layout/layout-overview.asciidoc#layout.overview,"Managing Layout">>.
The interfaces that define the Vaadin data model are described in <<../datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding Components to Data">>.

[[figure.components.interfaces]]
.Component interfaces and abstractions
image::img/component-abstractions.png[width=100%, scaledwidth=100%]

All components are connectors that connect to the client-side widgets.

((("[classname]#Serializable#")))
In addition to the interfaces defined within the Vaadin framework, all
components implement the [classname]#java.io.Serializable# interface to allow
serialization. Serialization is needed in many clustering and cloud computing
solutions.

[[components.interfaces.component]]
== [classname]#Component# Interface

((("[interfacename]#Component# interface")))
The [interfacename]#Component# interface is paired with the
[classname]#AbstractComponent# class, which implements all the methods defined
in the interface.

=== Component Tree Management

Components are laid out in the user interface hierarchically. The layout is
managed by layout components, or more generally components that implement the
[classname]#ComponentContainer# interface. Such a container is the parent of the
contained components.

The [methodname]#getParent()# method allows retrieving the parent component of a
component. While there is a [methodname]#setParent()#, you rarely need it as you
usually add components with the [methodname]#addComponent()# method of the
[classname]#ComponentContainer# interface, which automatically sets the parent.

A component does not know its parent when the component is still being created,
so you can not refer to the parent in the constructor with
[methodname]#getParent()#.

Attaching a component to an UI triggers a call to its [methodname]#attach()#
method. Correspondingly, removing a component from a container triggers calling
the [methodname]#detach()# method. If the parent of an added component is
already connected to the UI, the [methodname]#attach()# is called immediately
from [methodname]#setParent()#.

[source, java]
----
public class AttachExample extends CustomComponent {
    public AttachExample() {
    }

    @Override
    public void attach() {
        super.attach(); // Must call.

        // Now we know who ultimately owns us.
        ClassResource r = new ClassResource("smiley.jpg");
        Image image = new Image("Image:", r);
        setCompositionRoot(image);
    }
}
----

The attachment logic is implemented in [classname]#AbstractComponent#, as
described in <<components.interfaces.abstractcomponent>>.

((("[classname]#Component# interface")))

[[components.interfaces.abstractcomponent]]
== [classname]#AbstractComponent#

((("[classname]#AbstractComponent#", id="term.components.interfaces.abstractcomponent", range="startofrange")))

[classname]#AbstractComponent# is the base class for all user interface
components. It is the (only) implementation of the [classname]#Component#
interface, implementing all the methods defined in the interface. When
creating a new component, you should extend [classname]#AbstractComponent# or
one of its subclasses.

(((range="endofrange", startref="term.components.interfaces.abstractcomponent")))