選択できるのは25トピックまでです。 トピックは、先頭が英数字で、英数字とダッシュ('-')を使用した35文字以内のものにしてください。

layout-orderedlayout.asciidoc 13KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382
  1. ---
  2. title: VerticalLayout and HorizontalLayout
  3. order: 3
  4. layout: page
  5. ---
  6. [[layout.orderedlayout]]
  7. = [classname]#VerticalLayout# and [classname]#HorizontalLayout#
  8. [classname]#VerticalLayout# and [classname]#HorizontalLayout# are ordered
  9. layouts for laying components out either vertically or horizontally,
  10. respectively. They both extend from [classname]#AbstractOrderedLayout#, together
  11. with the [classname]#FormLayout#. These are the two most important layout
  12. components in Vaadin, and typically you have a [classname]#VerticalLayout# as
  13. the root content of a UI.
  14. [classname]#VerticalLayout# has 100% default width and undefined height, so it
  15. fills the containing layout (or UI) horizontally, and fits its content
  16. vertically. [classname]#HorizontalLayout# has undefined size in both dimensions.
  17. Typical use of the layouts goes as follows:
  18. [source, java]
  19. ----
  20. VerticalLayout vertical = new VerticalLayout ();
  21. vertical.addComponent(new TextField("Name"));
  22. vertical.addComponent(new TextField("Street address"));
  23. vertical.addComponent(new TextField("Postal code"));
  24. layout.addComponent(vertical);
  25. ----
  26. See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.orderedlayout.basic[on-line example, window="_blank"].
  27. In [classname]#VerticalLayout#, the captions of child components are placed above each component, so the layout would look as follows:
  28. image::img/orderedlayout_vertical.png[width=30%, scaledwidth=65%]
  29. [classname]#HorizontalLayout# gives the following layout:
  30. image::img/orderedlayout_horizontal.png[width=80%, scaledwidth=100%]
  31. ifdef::web[]
  32. [[layout.orderedlayout.declarative]]
  33. == Declarative Format
  34. Ordered layouts have the following declarative elements:
  35. |===============
  36. |Component|Element Name
  37. |[classname]#VerticalLayout#|[elementname]#v-verticallayout#
  38. |[classname]#HorizontalLayout#|[elementname]#v-horizontallayout#
  39. |[classname]#FormLayout#|[elementname]#v-formlayout#
  40. |===============
  41. The have the following declarative attributes:
  42. [[layout.orderedlayout.properties.table]]
  43. .Properties and Declarative Attributes
  44. [cols="1,2"]
  45. |===============
  46. |Property|Declarative Attribute
  47. |[parameter]#componentAlignment#|Alignment of a child component is specified in the child with: [literal]#++:left++# (default), [literal]#++:center++#, [literal]#++:right++#, [literal]#++:top++# (default), [literal]##++:middle++##, [literal]##++:bottom++##
  48. |[parameter]#spacing#|[parameter]##spacing##++[=++[replaceable]##<boolean>##++]++
  49. |[parameter]#margin#|[parameter]##margin##++[=++[replaceable]##<boolean>##++]++
  50. |[parameter]#expandRatio#|Expand ratio of a child component is specified in the child with: [parameter]#:expand#++[=++[replaceable]##<integer>##++]++ or [parameter]#:expand# (implies ratio 1)
  51. |===============
  52. They can also have any attributes applicable to super classes.
  53. For example:
  54. [source, html]
  55. ----
  56. <!-- Use margin and spacing -->
  57. <v-vertical-layout size-full margin spacing>
  58. <v-label><b>Hello!</b> - How are you?</v-label>
  59. <!-- Use expand ratio -->
  60. <v-horizontal-layout size-full :expand>
  61. ...
  62. <!-- Use expand ratio -->
  63. <v-table _id="mytable" caption="My Table"
  64. size-full :expand/>
  65. </v-horizontal-layout>
  66. <v-horizontal-layout width-full>
  67. ...
  68. <!-- Use alignment -->
  69. <v-button :right><b>OK</b></v-button>
  70. </v-horizontal-layout>
  71. </v-vertical-layout>
  72. ----
  73. endif::web[]
  74. [[layout.orderedlayout.spacing]]
  75. == Spacing in Ordered Layouts
  76. The ordered layouts can have spacing between the horizontal or vertical cells.
  77. The spacing can be enabled with [methodname]#setSpacing(true)# or declaratively
  78. with the [literal]#++spacing++# attribute.
  79. The spacing as a default height or width, which can be customized in CSS. You
  80. need to set the height or width for spacing elements with
  81. [literal]#++v-spacing++# style. You also need to specify an enclosing rule
  82. element in a CSS selector, such as [literal]#++v-verticallayout++# for a
  83. [classname]#VerticalLayout# or [literal]#++v-horizontallayout++# for a
  84. [classname]#HorizontalLayout#. You can also use [literal]#++v-vertical++# and
  85. [literal]#++v-horizontal++# for all vertically or horizontally ordered layouts,
  86. such as [classname]#FormLayout#.
  87. For example, the following sets the amount of spacing for all [classname]##VerticalLayout##s (as well as [classname]##FormLayout##s) in the UI:
  88. [source, css]
  89. ----
  90. .v-vertical > .v-spacing {
  91. height: 30px;
  92. }
  93. ----
  94. Or for [classname]#HorizontalLayout#:
  95. [source, css]
  96. ----
  97. .v-horizontal > .v-spacing {
  98. width: 50px;
  99. }
  100. ----
  101. [[layout.orderedlayout.sizing]]
  102. == Sizing Contained Components
  103. The components contained within an ordered layout can be laid out in a number of
  104. different ways depending on how you specify their height or width in the primary
  105. direction of the layout component.
  106. [[figure.layout.orderedlayout.size.summary]]
  107. .Component widths in [classname]#HorizontalLayout#
  108. image::img/horizontallayout_sizing.png[width=75%, scaledwidth=100%]
  109. <<figure.layout.orderedlayout.size.summary>> gives a summary of the sizing
  110. options for a [classname]#HorizontalLayout#. The figure is broken down in the
  111. following subsections.
  112. [[layout.orderedlayout.sizing.undefined]]
  113. === Layout with Undefined Size
  114. If a [classname]#VerticalLayout# has undefined height or
  115. [classname]#HorizontalLayout# undefined width, the layout will shrink to fit the
  116. contained components so that there is no extra space between them.
  117. [source, java]
  118. ----
  119. HorizontalLayout fittingLayout = new HorizontalLayout();
  120. fittingLayout.setWidth(Sizeable.SIZE_UNDEFINED, 0); // Default
  121. fittingLayout.addComponent(new Button("Small"));
  122. fittingLayout.addComponent(new Button("Medium-sized"));
  123. fittingLayout.addComponent(new Button("Quite a big component"));
  124. parentLayout.addComponent(fittingLayout);
  125. ----
  126. The both layouts actually have undefined height by default and
  127. [classname]#HorizontalLayout# has also undefined width, while
  128. [classname]#VerticalLayout# has 100% relative width.
  129. If such a vertical layout with undefined height continues below the bottom of a
  130. window (a [classname]#Window# object), the window will pop up a vertical scroll
  131. bar on the right side of the window area. This way, you get a "web page". The
  132. same applies to [classname]#Panel#.
  133. [WARNING]
  134. .A layout that contains components with percentual size must have a defined size!
  135. ====
  136. If a layout has undefined size and a contained component has, say, 100% size,
  137. the component would fill the space given by the layout, while the layout would
  138. shrink to fit the space taken by the component, which would be a paradox. This
  139. requirement holds for height and width separately. The debug window allows
  140. detecting such invalid cases; see
  141. <<dummy/../../../framework/advanced/advanced-debug#advanced.debug.hierarchy,"Inspecting
  142. Component Hierarchy">>.
  143. ====
  144. An exception to the above rule is a case where you have a layout with undefined
  145. size that contains a component with a fixed or undefined size together with one
  146. or more components with relative size. In this case, the contained component
  147. with fixed (or undefined) size in a sense defines the size of the containing
  148. layout, removing the paradox. That size is then used for the relatively sized
  149. components.
  150. ifdef::web[]
  151. The technique can be used to define the width of a [classname]#VerticalLayout#
  152. or the height of a [classname]#HorizontalLayout#.
  153. [source, java]
  154. ----
  155. // Vertical layout would normally have 100% width
  156. VerticalLayout vertical = new VerticalLayout();
  157. // Shrink to fit the width of contained components
  158. vertical.setWidth(Sizeable.SIZE_UNDEFINED, 0);
  159. // Label has normally 100% width, but we set it as
  160. // undefined so that it will take only the needed space
  161. Label label =
  162. new Label("\u2190 The VerticalLayout shrinks to fit "+
  163. "the width of this Label \u2192");
  164. label.setWidth(Sizeable.SIZE_UNDEFINED, 0);
  165. vertical.addComponent(label);
  166. // Button has undefined width by default
  167. Button butt = new Button("\u2190 This Button takes 100% "+
  168. "of the width \u2192");
  169. butt.setWidth("100%");
  170. vertical.addComponent(butt);
  171. ----
  172. See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.orderedlayout.sizing.sizing-undefined-defining[on-line example, window="_blank"].
  173. [[figure.layout.orderedlayout.sizing.undefined.defining]]
  174. .Defining the Size with a Component
  175. image::img/orderedlayout-sizing-undefined.png[width=50%, scaledwidth=75%]
  176. endif::web[]
  177. [[layout.orderedlayout.defined-size]]
  178. === Layout with Defined Size
  179. If you set a [classname]#HorizontalLayout# to a defined size horizontally or a
  180. [classname]#VerticalLayout# vertically, and there is space left over from the
  181. contained components, the extra space is distributed equally between the
  182. component cells. The components are aligned within these cells according to
  183. their alignment setting, top left by default, as in the example below.
  184. [source, java]
  185. ----
  186. fixedLayout.setWidth("400px");
  187. ----
  188. Using percentual sizes for components contained in a layout requires answering
  189. the question, "Percentage of what?" There is no sensible default answer for this
  190. question in the current implementation of the layouts, so in practice, you may
  191. not define "100%" size alone.
  192. [[layout.orderedlayout.expanding]]
  193. === Expanding Components
  194. Often, you want to have one component that takes all the available space left
  195. over from other components. You need to set its size as 100% and set it as
  196. __expanding__ with [methodname]#setExpandRatio()#. The second parameter for the
  197. method is an expansion ratio, which is relevant if there are more than one
  198. expanding component, but its value is irrelevant for a single expanding
  199. component.
  200. [source, java]
  201. ----
  202. HorizontalLayout layout = new HorizontalLayout();
  203. layout.setWidth("400px");
  204. // These buttons take the minimum size.
  205. layout.addComponent(new Button("Small"));
  206. layout.addComponent(new Button("Medium-sized"));
  207. // This button will expand.
  208. Button expandButton = new Button("Expanding component");
  209. // Use 100% of the expansion cell's width.
  210. expandButton.setWidth("100%");
  211. // The component must be added to layout
  212. // before setting the ratio
  213. layout.addComponent(expandButton);
  214. // Set the component's cell to expand.
  215. layout.setExpandRatio(expandButton, 1.0f);
  216. parentLayout.addComponent(layout);
  217. ----
  218. In the declarative format, you need to specify the [literal]#++:expand++#
  219. attribute in the child components. The attribute defaults to expand ratio 1.
  220. Notice that you can not call [methodname]#setExpandRatio()# before you have
  221. added the component to the layout, because it can not operate on an component
  222. that it doesn't yet have.
  223. [[layout.orderedlayout.expandratio]]
  224. === Expand Ratios
  225. If you specify an expand ratio for multiple components, they will all try to use
  226. the available space according to the ratio.
  227. [source, java]
  228. ----
  229. HorizontalLayout layout = new HorizontalLayout();
  230. layout.setWidth("400px");
  231. // Create three equally expanding components.
  232. String[] captions = { "Small", "Medium-sized",
  233. "Quite a big component" };
  234. for (int i = 1; i <= 3; i++) {
  235. Button button = new Button(captions[i-1]);
  236. button.setWidth("100%");
  237. layout.addComponent(button);
  238. // Have uniform 1:1:1 expand ratio.
  239. layout.setExpandRatio(button, 1.0f);
  240. }
  241. ----
  242. As the example used the same ratio for all components, the ones with more
  243. content may have the content cut. Below, we use differing ratios:
  244. [source, java]
  245. ----
  246. // Expand ratios for the components are 1:2:3.
  247. layout.setExpandRatio(button, i * 1.0f);
  248. ----
  249. If the size of the expanding components is defined as a percentage (typically
  250. "100%"), the ratio is calculated from the __overall__ space available for the
  251. relatively sized components. For example, if you have a 100 pixels wide layout
  252. with two cells with 1.0 and 4.0 respective expansion ratios, and both the
  253. components in the layout are set as [methodname]#setWidth("100%")#, the cells
  254. will have respective widths of 20 and 80 pixels, regardless of the minimum size
  255. of the components.
  256. However, if the size of the contained components is undefined or fixed, the
  257. expansion ratio is of the __excess__ available space. In this case, it is the
  258. excess space that expands, not the components.
  259. [source, java]
  260. ----
  261. for (int i = 1; i <= 3; i++) {
  262. // Button with undefined size.
  263. Button button = new Button(captions[i - 1]);
  264. layout4.addComponent(button);
  265. // Expand ratios are 1:2:3.
  266. layout4.setExpandRatio(button, i * 1.0f);
  267. }
  268. ----
  269. It is not meaningful to combine expanding components with percentually defined
  270. size and components with fixed or undefined size. Such combination can lead to a
  271. very unexpected size for the percentually sized components.
  272. [[layout.orderedlayout.percentual]]
  273. === Percentual Sizing
  274. A percentual size of a component defines the size of the component _within its cell_.
  275. Usually, you use "100%", but a smaller percentage or a fixed size
  276. (smaller than the cell size) will leave an empty space in the cell and align the
  277. component within the cell according to its alignment setting, top left by
  278. default.
  279. [source, java]
  280. ----
  281. HorizontalLayout layout50 = new HorizontalLayout();
  282. layout50.setWidth("400px");
  283. String[] captions1 = { "Small 50%", "Medium 50%",
  284. "Quite a big 50%" };
  285. for (int i = 1; i <= 3; i++) {
  286. Button button = new Button(captions1[i-1]);
  287. button.setWidth("50%");
  288. layout50.addComponent(button);
  289. // Expand ratios for the components are 1:2:3.
  290. layout50.setExpandRatio(button, i * 1.0f);
  291. }
  292. parentLayout.addComponent(layout50);
  293. ----