Borderlayout"

From Documentation
m (correct highlight (via JWB))
(10 intermediate revisions by 4 users not shown)
Line 10: Line 10:
 
= Employment/Purpose =
 
= Employment/Purpose =
  
The layout component is a nested component. The parent component is <tt>borderlayout</tt>, and its children components include <tt>north</tt>, <tt>south</tt>, <tt>center</tt>, <tt>west</tt>, and <tt>east</tt>. All extra space is placed in the center area. The combination of children components of <tt>borderlayout</tt> is free.
+
The layout component is a nested component. The parent component is <code>borderlayout</code>, and its children components include <code>north</code>, <code>south</code>, <code>center</code>, <code>west</code>, and <code>east</code>. All extra space is placed in the center area. The combination of children components of <code>borderlayout</code> is free.
  
 
A borderlayout could be nested to another borderlayout (actually, almost all kinds of components) to form a complicated layout.
 
A borderlayout could be nested to another borderlayout (actually, almost all kinds of components) to form a complicated layout.
Line 66: Line 66:
 
Borderlayout divides its child components into to five areas: North, South, East, West and Center. The heights of North and South are firstly decided, the remainder space is then given to Center as its height. Note that East and West also takes on the height of Center.  
 
Borderlayout divides its child components into to five areas: North, South, East, West and Center. The heights of North and South are firstly decided, the remainder space is then given to Center as its height. Note that East and West also takes on the height of Center.  
  
{| border="1px" | width="100%" | cellspacing="0"
+
{| class='wikitable' | width="100%"
 
|-
 
|-
 
| [[Image:DrBorderlayout.png]]
 
| [[Image:DrBorderlayout.png]]
Line 92: Line 92:
 
=== flex ===
 
=== flex ===
 
Layout region shares the height of Borderlayout with a distributing sequence of: North, South and Center while the heights of East and West takes on the height of Center. In the previous sample, the div in the layout region does not take up all of layout region's space. In order for the child to occupy the whole area, please set vflex="1" to the child component.
 
Layout region shares the height of Borderlayout with a distributing sequence of: North, South and Center while the heights of East and West takes on the height of Center. In the previous sample, the div in the layout region does not take up all of layout region's space. In order for the child to occupy the whole area, please set vflex="1" to the child component.
{| border="1px" | width="100%" | cellspacing="0"
+
{| class='wikitable' | width="100%"
 
|-
 
|-
 
| [[Image:DrBorderlayout_flex.png]]
 
| [[Image:DrBorderlayout_flex.png]]
 
|
 
|
<source lang="xml" high="12,15">
+
<source lang="xml" highlight="12,15">
 
<borderlayout width="100px" height="100px">
 
<borderlayout width="100px" height="100px">
 
<north>
 
<north>
Line 120: Line 120:
 
*The height of Center depends on Borderlayout but not on its child, therefore, the height of Center will not be expanded by the growing size of its child components. If Center's height is too short for it's child, Center will cut out the contents of it's child, hence, to avoid this, specify autoscroll="true" to Center in order to assign Center to handle the scrolling.
 
*The height of Center depends on Borderlayout but not on its child, therefore, the height of Center will not be expanded by the growing size of its child components. If Center's height is too short for it's child, Center will cut out the contents of it's child, hence, to avoid this, specify autoscroll="true" to Center in order to assign Center to handle the scrolling.
  
{| border="1px" | width="100%" | cellspacing="0"
+
{| class='wikitable' | width="100%"
 
|-
 
|-
 
| [[Image:DrBorderlayout_Center_scrolling.png]]
 
| [[Image:DrBorderlayout_Center_scrolling.png]]
 
|
 
|
<source lang="xml" high="8">
+
<source lang="xml" highlight="8">
 
<borderlayout width="300px" height="300px">
 
<borderlayout width="300px" height="300px">
 
<north>
 
<north>
Line 145: Line 145:
 
|}
 
|}
  
since 7.0.0
+
{{versionSince| 7.0.0}}
  
 
The autoscroll attribute will create floating scrollbar and it is not visible unless user mouse over on the region. To turn off the floating scrollbar and use browser's default scrollbar, please add the following configuration in zk.xml.
 
The autoscroll attribute will create floating scrollbar and it is not visible unless user mouse over on the region. To turn off the floating scrollbar and use browser's default scrollbar, please add the following configuration in zk.xml.
Line 154: Line 154:
 
</library-property>
 
</library-property>
 
</source>
 
</source>
 +
 +
'''Note:''' the value of org.zkoss.zul.nativebar is true by default (since 7.0.2)
  
 
===Grown by children ===
 
===Grown by children ===
 
*To make Borderlayout dependable on the size of its child components, [[ZK_Developer's_Reference/UI_Patterns/Hflex_and_Vflex#Minimum_Flexibility|vflex feature]] is applied. Specify vflex="min" to each layout region and Borderlayout.
 
*To make Borderlayout dependable on the size of its child components, [[ZK_Developer's_Reference/UI_Patterns/Hflex_and_Vflex#Minimum_Flexibility|vflex feature]] is applied. Specify vflex="min" to each layout region and Borderlayout.
{| border="1px" | width="100%" | cellspacing="0"
+
{| class='wikitable' | width="100%"
 
|-
 
|-
 
| [[Image:DrBorderlayout_grow.png]]
 
| [[Image:DrBorderlayout_grow.png]]
 
|
 
|
<source lang="xml" high="1,2,5,8">
+
<source lang="xml" highlight="1,2,5,8">
 
<borderlayout width="300px" vflex="min">
 
<borderlayout width="300px" vflex="min">
 
<north vflex="min">
 
<north vflex="min">
Line 184: Line 186:
 
===  Borderlayout in a container===
 
===  Borderlayout in a container===
 
*Almost all containers' heights depend on their child components, however, the height of Borderlayout does not expand accordingly to the sizes of its child components, therefore, when placing Borderlayout in a container, users have to specify a fixed height in order for Borderlayout to be visible.
 
*Almost all containers' heights depend on their child components, however, the height of Borderlayout does not expand accordingly to the sizes of its child components, therefore, when placing Borderlayout in a container, users have to specify a fixed height in order for Borderlayout to be visible.
<source lang="xml" high="3">
+
<source lang="xml" highlight="3">
 
<zk>
 
<zk>
 
<window title="win" border="normal">
 
<window title="win" border="normal">
Line 208: Line 210:
 
</source>
 
</source>
 
*The default height of Borderlayout is dependent on its parent component, therefore, users can also put Borderlayout in a container with a fixed height.
 
*The default height of Borderlayout is dependent on its parent component, therefore, users can also put Borderlayout in a container with a fixed height.
<source lang="xml" high="2">
+
<source lang="xml" highlight="2">
 
<zk>
 
<zk>
 
<window title="win" border="normal" height="200px">
 
<window title="win" border="normal" height="200px">
Line 233: Line 235:
  
 
=Properties=
 
=Properties=
== AnimationDisabled==
+
== AnimationDisabled ==
 +
{{versionSince| 5.0.8}}
 
You can specify this property to true to disable the animation effects of this component.
 
You can specify this property to true to disable the animation effects of this component.
Since 5.0.8
 
 
=== Configure to Disable the Animation Effects as Default ===
 
=== Configure to Disable the Animation Effects as Default ===
  
If you prefer to disable the animation effects as default, you could configure ZK by adding the following to <tt>/WEB-INF/zk.xml</tt>
+
If you prefer to disable the animation effects as default, you could configure ZK by adding the following to <code>/WEB-INF/zk.xml</code>
  
 
<source lang="xml">
 
<source lang="xml">
 
<library-property>
 
<library-property>
<name>org.zkoss.zul.borderlayout.animation.disabed</name>
+
<name>org.zkoss.zul.borderlayout.animation.disabled</name>
 
<value>true</value>
 
<value>true</value>
 
</library-property>
 
</library-property>
 
</source>
 
</source>
  
  Since 5.0.8
 
 
=Supported Events=
 
=Supported Events=
  
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
Line 265: Line 266:
 
=Use Cases=
 
=Use Cases=
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Description !! Example Location
 
! Version !! Description !! Example Location
 
|-
 
|-
Line 275: Line 276:
 
=Version History=
 
=Version History=
 
{{LastUpdated}}
 
{{LastUpdated}}
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
Line 285: Line 286:
 
| Feb 14, 2012
 
| Feb 14, 2012
 
| The flex attribute has been deprecated, please set vflex="1" to the child component in order to occupy the whole area.
 
| The flex attribute has been deprecated, please set vflex="1" to the child component in order to occupy the whole area.
 +
|-
 +
| 7.0.2
 +
| April 2014
 +
| Due to the better user-firendly for the scrollbar layout, we changed the org.zkoss.zul.nativebar of the library property to true by default for Grid, Listbox, Tree and Borderlayout component.
 
|}
 
|}
  
 
{{ZKComponentReferencePageFooter}}
 
{{ZKComponentReferencePageFooter}}

Revision as of 09:24, 18 January 2022

Borderlayout

Employment/Purpose

The layout component is a nested component. The parent component is borderlayout, and its children components include north, south, center, west, and east. All extra space is placed in the center area. The combination of children components of borderlayout is free.

A borderlayout could be nested to another borderlayout (actually, almost all kinds of components) to form a complicated layout.

Example

ZKCompRef Borderlayout.jpg

<borderlayout height="450px">
	<north title="North" maxsize="300" size="50%" splittable="true" collapsible="true">
		<borderlayout>
			<west title="West" size="25%" flex="true" maxsize="250" splittable="true" collapsible="true">
				<div style="background:#B8D335">
					<label value="25%"
						style="color:white;font-size:50px" />
				</div>
			</west>
			<center border="none">
				<div style="background:#E6D92C" vflex="1">
					<label value="25%"
						style="color:white;font-size:50px" />
				</div>
			</center>
			<east size="50%" border="none">
				<label value="Here is a non-border"
					style="color:gray;font-size:30px" />
			</east>
		</borderlayout>
	</north>
	<center border="0">
		<borderlayout>
			<west maxsize="600" size="30%" border="0" splittable="true">
				<div style="background:#E6D92C" vflex="1">
					<label value="30%"
						style="color:white;font-size:50px" />
				</div>
			</west>
			<center>
				<label value="Here is a border"
					style="color:gray;font-size:30px" />
			</center>
			<east title="East" size="30%" collapsible="true">
				<div style="background:#B8D335"  vflex="1">
					<label value="30%"
						style="color:white;font-size:50px" />
				</div>
			</east>
		</borderlayout>
	</center>
</borderlayout>

How to Layout

Borderlayout divides its child components into to five areas: North, South, East, West and Center. The heights of North and South are firstly decided, the remainder space is then given to Center as its height. Note that East and West also takes on the height of Center.

DrBorderlayout.png
<borderlayout width="100px" height="100px">
	<north>
		<div style="background:#008db7;color:white;">N</div>
	</north>
	<south>
		<div style="background:#112f37;color:white;">S</div>
	</south>
	<center>
		<div>C</div>
	</center>
	<east>
		<div style="background:#f2f2f2;">E</div>
	</east>
	<west>
		<div style="background:#f2f2f2;">W</div>
	</west>
</borderlayout>

flex

Layout region shares the height of Borderlayout with a distributing sequence of: North, South and Center while the heights of East and West takes on the height of Center. In the previous sample, the div in the layout region does not take up all of layout region's space. In order for the child to occupy the whole area, please set vflex="1" to the child component.

DrBorderlayout flex.png
<borderlayout width="100px" height="100px">
	<north>
		<div style="background:#008db7;color:white;">N</div>
	</north>
	<south>
		<div style="background:#112f37;color:white;">S</div>
	</south>
	<center>
		<div>C</div>
	</center>
	<east>
		<div vflex="1" style="background:#f2f2f2;">E</div>
	</east>
	<west>
		<div vflex="1" style="background:#f2f2f2;">W</div>
	</west>
</borderlayout>

Scrolling

  • The height of Center depends on Borderlayout but not on its child, therefore, the height of Center will not be expanded by the growing size of its child components. If Center's height is too short for it's child, Center will cut out the contents of it's child, hence, to avoid this, specify autoscroll="true" to Center in order to assign Center to handle the scrolling.
DrBorderlayout Center scrolling.png
<borderlayout width="300px" height="300px">
	<north>
		<div height="100px"  style="background:#008db7;color:white;">N</div>
	</north>
	<south>
		<div height="100px"  style="background:#112f37;color:white;">S</div>
	</south>
	<center autoscroll="true">
		<div height="200px">C</div>
	</center>
	<east flex="true">
		<div width="30px" style="background:#f2f2f2;">E</div>
	</east>
	<west flex="true">
		<div width="20px" style="background:#f2f2f2;">W</div>
	</west>
</borderlayout>

Since 7.0.0

The autoscroll attribute will create floating scrollbar and it is not visible unless user mouse over on the region. To turn off the floating scrollbar and use browser's default scrollbar, please add the following configuration in zk.xml.

<library-property>
    <name>org.zkoss.zul.nativebar</name>
    <value>true</value>
</library-property>

Note: the value of org.zkoss.zul.nativebar is true by default (since 7.0.2)

Grown by children

  • To make Borderlayout dependable on the size of its child components, vflex feature is applied. Specify vflex="min" to each layout region and Borderlayout.
DrBorderlayout grow.png
<borderlayout width="300px" vflex="min">
	<north vflex="min">
		<div height="100px"  style="background:#008db7;color:white;">N</div>
	</north>
	<south vflex="min">
		<div height="100px"  style="background:#112f37;color:white;">S</div>
	</south>
	<center vflex="min">
		<div height="200px">C</div>
	</center>
	<east flex="true">
		<div width="30px" style="background:#f2f2f2;">E</div>
	</east>
	<west flex="true">
		<div width="20px" style="background:#f2f2f2;">W</div>
	</west>
</borderlayout>

Borderlayout in a container

  • Almost all containers' heights depend on their child components, however, the height of Borderlayout does not expand accordingly to the sizes of its child components, therefore, when placing Borderlayout in a container, users have to specify a fixed height in order for Borderlayout to be visible.
<zk>
	<window title="win" border="normal">
		<borderlayout height="200px">
			<north>
				<div style="background:blue">N</div>
			</north>
			<south>
				<div style="background:blue">S</div>
			</south>
			<center>
				<div>C</div>
			</center>
			<east>
				<div style="background:yellow">E</div>
			</east>
			<west>
				<div style="background:yellow">W</div>
			</west>
		</borderlayout>
	</window>
</zk>
  • The default height of Borderlayout is dependent on its parent component, therefore, users can also put Borderlayout in a container with a fixed height.
<zk>
	<window title="win" border="normal" height="200px">
		<borderlayout>
			<north>
				<div style="background:blue">N</div>
			</north>
			<south>
				<div style="background:blue">S</div>
			</south>
			<center>
				<div>C</div>
			</center>
			<east>
				<div style="background:yellow">E</div>
			</east>
			<west>
				<div style="background:yellow">W</div>
			</west>
		</borderlayout>
	</window>
</zk>

Properties

AnimationDisabled

Since 5.0.8 You can specify this property to true to disable the animation effects of this component.

Configure to Disable the Animation Effects as Default

If you prefer to disable the animation effects as default, you could configure ZK by adding the following to /WEB-INF/zk.xml

<library-property>
	<name>org.zkoss.zul.borderlayout.animation.disabled</name>
	<value>true</value>
</library-property>

Supported Events

Name
Event Type
None None

Supported Children

* North,  South,  Center,  West,  East

Use Cases

Version Description Example Location
     

Version History

Last Update : 2022/01/18


Version Date Content
5.0.8 August 11, 2011 Added a way to disable the animation of borderlayout.
6.0.0 Feb 14, 2012 The flex attribute has been deprecated, please set vflex="1" to the child component in order to occupy the whole area.
7.0.2 April 2014 Due to the better user-firendly for the scrollbar layout, we changed the org.zkoss.zul.nativebar of the library property to true by default for Grid, Listbox, Tree and Borderlayout component.


Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.