|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360 |
- ---
- title: Layout Formatting
- order: 13
- layout: page
- ---
-
- [[layout.settings]]
- = Layout Formatting
-
- While the formatting of layouts is mainly done with style sheets, just as with
- other components, style sheets are not ideal or even possible to use in some
- situations. For example, CSS does not allow defining the spacing of table cells,
- which is done with the [parameter]#cellspacing# attribute in HTML.
-
- Moreover, as many layout sizes are calculated dynamically in the Client-Side
- Engine of Vaadin, some CSS settings can fail altogether.
-
- [[layout.settings.size]]
- == Layout Size
-
- The size of a layout component can be specified with the
- [methodname]#setWidth()# and [methodname]#setHeight()# methods defined in the
- [classname]#Sizeable# interface, just like for any component. It can also be
- undefined, in which case the layout shrinks to fit the component(s) inside it.
- <<../components/components-features#components.features.sizeable,"Sizing
- Components">> gives details on the interface.
-
- [[figure.layout.settings.size.undefined]]
- .[classname]#HorizontalLayout# with Undefined vs Defined size
- image::img/layout_size_undefined_vs_defined.png[]
-
- Many layout components take 100% width by default, while they have the height
- undefined.
-
- The sizes of components inside a layout can also be defined as a percentage of
- the space available in the layout, for example with
- [methodname]#setWidth("100%");# or with the (most commonly used method)
- [methodname]#setFullSize()# that sets 100% size in both directions. If you use a
- percentage in a [classname]#HorizontalLayout#, [classname]#VerticalLayout#, or
- [classname]#GridLayout#, you will also have to set the component as
- __expanding__, as noted below.
-
-
- [WARNING]
- ====
- __A layout that contains components with percentual size must have a defined
- size__!
-
- If a layout has undefined size and a contained component has, say, 100% size,
- the component will try to fill the space given by the layout, while the layout
- will shrink to fit the space taken by the component, which is a paradox. This
- requirement holds for height and width separately. The debug mode allows
- detecting such invalid cases; see
- <<../advanced/advanced-debug#advanced.debug.hierarchy,"Inspecting
- Component Hierarchy">>.
-
- ====
-
-
-
- For example:
-
-
- [source, java]
- ----
- // This takes 100% width but has undefined height.
- VerticalLayout layout = new VerticalLayout();
-
- // A button that takes all the space available in the layout.
- Button button = new Button("100%x100% button");
- button.setSizeFull();
- layout.addComponent(button);
-
- // We must set the layout to a defined height vertically, in
- // this case 100% of its parent layout, which also must
- // not have undefined size.
- layout.setHeight("100%");
- ----
-
- If you have a layout with undefined height, such as [classname]#VerticalLayout#,
- in a [classname]#UI#, [classname]#Window#, or [classname]#Panel#, and put enough
- content in it so that it extends outside the bottom of the view area, scrollbars
- will appear. If you want your application to use all the browser view, nothing
- more or less, you should use [methodname]#setFullSize()# for the root layout.
-
-
- [source, java]
- ----
- // Create the UI content
- VerticalLayout content = new VerticalLayout();
-
- // Use entire view area
- content.setSizeFull();
-
- setContent(content);
- ----
-
-
- [[layout.settings.size.expanding]]
- == Expanding Components
-
- If you set a [classname]#HorizontalLayout# to a defined size horizontally or a
- [classname]#VerticalLayout# vertically, and there is space left over from the
- contained components, the extra space is distributed equally between the
- component cells. The components are aligned within these cells, according to
- their alignment setting, top left by default, as in the example below.
-
- Often, you don't want such empty space, but want one or more components to take
- all the leftover space. You need to set such a component to 100% size and use
- [methodname]#setExpandRatio()#. If there is just one such expanding component in
- the layout, the ratio parameter is irrelevant.
-
- If you set multiple components as expanding, the expand ratio dictates how large
- proportion of the available space (overall or excess depending on whether the
- components are sized as a percentage or not) each component takes. In the
- example below, the buttons have 1:2:3 ratio for the expansion.
-
- [classname]#GridLayout# has corresponding method for both of its directions,
- [methodname]#setRowExpandRatio()# and [methodname]#setColumnExpandRatio()#.
-
- Expansion is covered in detail in the documentation of the layout components that
- support it. See
- <<layout-orderedlayout#layout.orderedlayout,"VerticalLayout
- and HorizontalLayout">> and
- <<layout-gridlayout#layout.gridlayout,"GridLayout">>
- for details on components with relative sizes.
-
-
- [[layout.settings.alignment]]
- == Layout Cell Alignment
-
- ((("Alignment", id="term.alignment", range="startofrange")))
-
-
- ((("[methodname]#setComponentAlignment()#", id="term.setcomponentalignment", range="startofrange")))
-
-
- When a component in a layout cell has size (width or height) smaller than the
- size of the cell, it will by default be aligned in the top-left corner of the
- cell. You can set the alignment with the [methodname]#setComponentAlignment()#
- method. The method takes as its parameters the component contained in the cell
- to be formatted, and the horizontal and vertical alignment. The component must
- have been added to the layout before setting the alignment.
-
- <<figure.layout.settings.alignment>> illustrates the alignment of components
- within a [classname]#GridLayout#.
-
- [[figure.layout.settings.alignment]]
- .Cell Alignments
- image::img/layout_alignment.png[]
-
- Note that __a component with 100% relative size can not be aligned__, as it will
- take the entire width or height of the cell, in which case alignment is
- meaningless. This should especially be noted with the [classname]#Label#
- component, which has 100% default width, and the text alignment __within__ the
- component is separate, defined by the CSS [literal]#++text-align++# property.
-
- The easiest way to set alignments is to use the constants defined in the
- [classname]#Alignment# class. Let us look how the buttons in the top row of the
- above [classname]#GridLayout# are aligned with constants:
-
-
- [source, java]
- ----
- // Create a grid layout
- GridLayout grid = new GridLayout(3, 3);
-
- grid.setWidth(400, Sizeable.UNITS_PIXELS);
- grid.setHeight(200, Sizeable.UNITS_PIXELS);
-
- Button topleft = new Button("Top Left");
- grid.addComponent(topleft, 0, 0);
- grid.setComponentAlignment(topleft, Alignment.TOP_LEFT);
-
- Button topcenter = new Button("Top Center");
- grid.addComponent(topcenter, 1, 0);
- grid.setComponentAlignment(topcenter, Alignment.TOP_CENTER);
-
- Button topright = new Button("Top Right");
- grid.addComponent(topright, 2, 0);
- grid.setComponentAlignment(topright, Alignment.TOP_RIGHT);
- ...
- ----
-
- The following table lists all the [classname]#Alignment# constants by their
- respective locations:
-
- .Alignment Constants
-
- |===============
- |[parameter]#TOP_LEFT#|[parameter]#TOP_CENTER#|[parameter]#TOP_RIGHT#
- |[parameter]#MIDDLE_LEFT#|[parameter]#MIDDLE_CENTER#|[parameter]#MIDDLE_RIGHT#
- |[parameter]#BOTTOM_LEFT#|[parameter]#BOTTOM_CENTER#|[parameter]#BOTTOM_RIGHT#
-
- |===============
-
-
-
- Another way to specify the alignments is to create an [classname]#Alignment#
- object and specify the horizontal and vertical alignment with separate
- constants. You can specify either of the directions, in which case the other
- alignment direction is not modified, or both with a bitmask operation between
- the two directions.
-
-
- [source, java]
- ----
- Button middleleft = new Button("Middle Left");
- grid.addComponent(middleleft, 0, 1);
- grid.setComponentAlignment(middleleft,
- new Alignment(Bits.ALIGNMENT_VERTICAL_CENTER |
- Bits.ALIGNMENT_LEFT));
-
- Button middlecenter = new Button("Middle Center");
- grid.addComponent(middlecenter, 1, 1);
- grid.setComponentAlignment(middlecenter,
- new Alignment(Bits.ALIGNMENT_VERTICAL_CENTER |
- Bits.ALIGNMENT_HORIZONTAL_CENTER));
-
- Button middleright = new Button("Middle Right");
- grid.addComponent(middleright, 2, 1);
- grid.setComponentAlignment(middleright,
- new Alignment(Bits.ALIGNMENT_VERTICAL_CENTER |
- Bits.ALIGNMENT_RIGHT));
- ----
-
- Obviously, you may combine only one vertical bitmask with one horizontal
- bitmask, though you may leave either one out. The following table lists the
- available alignment bitmask constants:
-
- .Alignment Bitmasks
-
- |===============
- |Horizontal|[parameter]#Bits.ALIGNMENT_LEFT#
- |[parameter]#Bits.ALIGNMENT_HORIZONTAL_CENTER#
- |[parameter]#Bits.ALIGNMENT_RIGHT#
- |Vertical|[parameter]#Bits.ALIGNMENT_TOP#
- |[parameter]#Bits.ALIGNMENT_VERTICAL_CENTER#
- |[parameter]#Bits.ALIGNMENT_BOTTOM#
-
- |===============
-
-
-
- You can determine the current alignment of a component with
- [methodname]#getComponentAlignment()#, which returns an [classname]#Alignment#
- object. The class provides a number of getter methods for decoding the
- alignment, which you can also get as a bitmask value.
-
- [[layout.settings.alignment.size]]
- === Size of Aligned Components
-
- You can only align a component that is smaller than its containing cell in the
- direction of alignment. If a component has 100% width, as some components have
- by default, horizontal alignment does not have any effect. For example,
- [classname]#VerticalLayout# is 100% wide by default and can not therefore be horizontally
- aligned as such. The problem can sometimes be hard to notice, as the content inside a
- [classname]#VerticalLayout# is left-aligned by default.
-
- You usually need to set either a fixed size, undefined size, or less than a 100%
- relative size for the component to be aligned - a size that is smaller than the
- containing layout has.
-
- If you set the size as undefined and the component itself contains components,
- make sure that the contained components also have either undefined or fixed
- size.
-
-
- (((range="endofrange", startref="term.alignment")))
- (((range="endofrange", startref="term.setcomponentalignment")))
-
- [[layout.settings.spacing]]
- == Layout Cell Spacing
-
- The [classname]#VerticalLayout#, [classname]#HorizontalLayout#, and
- [classname]#GridLayout# layouts offer a [methodname]#setSpacing()# method to
- enable or disable spacing between the cells of the layout.
-
- For example:
-
-
- [source, java]
- ----
- VerticalLayout layout = new VerticalLayout();
- layout.setSpacing(false);
- layout.addComponent(new Button("Component 1"));
- layout.addComponent(new Button("Component 2"));
- layout.addComponent(new Button("Component 3"));
- ----
-
- The effect of spacing in [classname]#VerticalLayout# and
- [classname]#HorizontalLayout# is illustrated in <<figure.layout.spacing>>.
-
- [[figure.layout.spacing]]
- .Layout Spacings
- image::img/layout_spacing.png[]
-
- The exact amount of spacing is defined in CSS. If the default is not suitable,
- you can customize it in a custom theme.
-
- In the Valo theme, you can specify the spacing with the
- $v-layout-spacing-vertical and $v-layout-spacing-horizontal parameters, as
- described in
- <<../themes/themes-valo#themes.valo.variables,"Common
- Settings">>. The spacing defaults to the $v-unit-size measure.
-
- When adjusting spacing in other themes, you should note that it is implemented
- in a bit different ways in different layouts. In the ordered layouts, it is done
- with spacer elements, while in the [classname]#GridLayout# it has special
- handling. Please see the sections on the individual components for more details.
-
-
- [[layout.settings.margins]]
- == Layout Margins
-
- Most layout components (with the exception of [classname]#VerticalLayout#) do
- not have any margin around them by default. The ordered layouts, as well as
- [classname]#GridLayout#, support enabling or disabling a margin with
- [methodname]#setMargin()#. This enables CSS classes for each margin in the
- HTML element of the layout component.
-
- In the Valo theme, the margin sizes default to $v-unit-size. You can customize
- them with $v-layout-margin-top, right, bottom, and left. See
- <<../themes/themes-valo#themes.valo.variables,"Common
- Settings">> for a description of the parameters.
-
- To customize the default margins in other themes, you can define each margin
- with the [literal]#++padding++# property in CSS. You may want to have a custom
- CSS class for the layout component to enable specific customization of the
- margins, as is done in the following with the [literal]#++mymargins++# class:
-
- [subs="normal"]
- ----
-
- .**mymargins**.v-margin-left {padding-left: **10**px;}
- .**mymargins**.v-margin-right {padding-right: **20**px;}
- .**mymargins**.v-margin-top {padding-top: **40**px;}
- .**mymargins**.v-margin-bottom {padding-bottom: **80**px;}
- ----
- You can enable only specific margins by passing a [classname]#MarginInfo# to the
- [methodname]#setMargin()#. The margins are specified in clockwise order for top,
- right, bottom, and left margin. The following would enable the left and right
- margins:
-
-
- [source, java]
- ----
- layout.setMargin(new MarginInfo(false, true, false, true));
- ----
-
- The resulting margins are shown in <<figure.layout.margin>> below. The two ways
- produce identical margins.
-
- [[figure.layout.margin]]
- .Layout Margins
- image::img/layout_margin.png[]
-
-
-
-
|