Layout Manager - NXML

This section introduces the layout manager.

What is Nexaweb layout manager
A visual guide to layout managers
Where to use layout managers
How to use Nexaweb layout managers

What is Nexaweb Layout Manager?

Nexaweb Layout Manager is very similar to layout managers that the Java platform provides.

Nexaweb layout managers control the position of child components in a container. (A container is a UI element in a Nexaweb application that can hold child components and to which you may add layout managers and other visual elements (including both containers and components) in order to create the application’s visual appearance.)

Different layout managers provide different resizing behaviors. The predefined Nexaweb layout managers include:

BorderLayout
BoxLayout
CardLayout
FlowLayout
FreeLayout
GridLayout

You can use one layout manager or combine several of them in the same container to achieve the UI design you desire. Each layout manager has its own special attributes

that you can set to achieve different layout results. You can also assign generic attributes to child components - for example, margin and layout manager specific attributes such as hAlign for gridLayout, flex for boxLayout - to assist layout managers to create the layout that you want. If you do not specify a layout manager, Nexaweb Studio uses flowLayout - the simplest layout manager, that arranges components horizontally or vertically in the order in which you place them within the container - as the default. If a predefined layout cannot satisfy your needs, you can create a customized layout. See Plugin-in documentation for more details.

The quickest way for you to get your application to look the way you want is to learn how the layout managers work. For an example of the different layout managers either import into Studio (Using Eclipse’s Import wizard) or build and deploy the Sample Explorer part of the samples included in the Nexaweb Platform 4.0 installation.

A Visual Guide to Layout Managers

BorderLayout

A BorderLayout places components in up to five areas: north, south, west, east, and center. Components placed in north and south stretch horizontally. Components placed in the west and the east stretch vertically. Components placed in center stretch in both directions, so that the remaining space fills with the center component. You can place child components in these areas by specifying components attribute borderPosition. The possible values for borderPosition attribute include: as expected, north, west, center, east and south. The following example xml represents the window shown above:

<window title="window" width="350" height="200">
    <borderLayout/>
    <button borderPosition="north" text="North"/>
    <button borderPosition="west" text="West"/>
    <button borderPosition="center" text="Center"/>
    <button borderPosition="east" text="East"/>
    <button borderPosition="south" text="South"/>
</window>

As this example shows, child components expand themselves to fill the area in which they reside. If you resize the window, the components resize themselves as well to fill the area. BorderLayout ignores the size of component placed in the center area so that the component can fill any available space. Components placed in north and south maintain their height as Components placed in west and east maintain their width.

You don't have to put components to all 5 areas. In fact, it is quite common that 2 or 3 areas are enough to get the layout result you want.

BoxLayout

The BoxLayout places components in a single row or column according to the orientation you specify with the orientation attribute. It does not wrap a component to the next row or column if the component's size is over the container's size, whereas flowLayout does wrap the component to available space. By default, boxLayout honors component's size and component will not resize no matter how container's size changes. The following example xml represents the window shown above:

<window title="window" width="350" height="200" margin="5">
    <boxLayout orientation="vertical"/>
    <button text="button 1"/>
    <button text="button 2 - wide"/>
    <textField />
    <comboBox /> 
    <radioButton text="radio button" />
</window>

CardLayout

CardLayout allows you to put different components to a common container, while showing only one of them at a time as you specify with the show attribute. The displayed component occupies the entire space of its parent container. The best example of a cardLayout is a slideshow. As shown in the windows above, clicking Card 1 or Card 2 button sets the show attribute of cardLayout and makes the corresponding component in the deck show up. The following example xml represents the windows shown above:

 <nxml>
  <macro:macro xmlns:macro="http://nexaweb.com/macro" name="showCard1">
    <xu:modifications xmlns:xu="http://nexaweb.com/xupdate">
      <xu:set-attribute select="//cardLayout">
        <xu:attribute name="show" value="card1"/>
      </xu:set-attribute>
    </xu:modifications>
  </macro:macro>
  <macro:macro xmlns:macro="http://nexaweb.com/macro" name="showCard2">
    <xu:modifications xmlns:xu="http://nexaweb.com/xupdate">
      <xu:set-attribute select="//cardLayout">
        <xu:attribute name="show" value="card2"/>
      </xu:set-attribute>
    </xu:modifications>
  </macro:macro>
  <window height="200" title="Window" width="400" >
    <borderLayout gapVertical="5"/>
    <panel height="40" width="100" borderPosition="south" 
           bgColor="#808080">
      <flowLayout align="center"/>
      <button text="Card 1" onCommand="macro://showCard1"/>
      <button text="Card 2" onCommand="macro://showCard2"/>
    </panel>
    <panel height="100" width="100" borderPosition="center" 
           bgColor="#008000">
      <cardLayout show="card2"/>
      <label height="20" text="Card 1" width="100" 
             alignHorizontal="center" alignVertical="center" 
             fontBold="true" fontSize="100" name="card1"/>
      <label height="20" text="Card 2" width="100" 
             alignHorizontal="center" alignVertical="center" 
             fontBold="true" fontSize="100" name="card2"/>
    </panel>
  </window>
</nxml>

FlowLayout

FlowLayout is the default layout manager Nexaweb Studio uses for all containers if you do not specify any other layout manager. It lays out components in a single row or column depending on the position and size specified for each component. FlowLayout starts a new row or column if a component's container isn't sufficiently wide or high. The following example xml represents the window shown above:

<window title="window" width="350" height="200">
    <flowLayout/>
    <button text="button 1"/>
    <textField />
    <comboBox />
    <radioButton text="radio button" />
</window>

FreeLayout

FreeLayout arranges components according to the absolute sizes and positions that you specify for each component. When sizing and positioning components, you need to consider that screen size may vary from one computer to another. Use FreeLayout when other layout managers cannot meet your requirements or when you want to add components to the container with x/y coordinates from a mouse event. The following example xml represents the window shown above:

 <window height="200" title="Window" width="400">

	    <freeLayout/>

	    <button  text="Button"  x="60" y="29"/>

	    <textField text="TextField" x="220" y="59"/>

	    <comboBox x="40" y="79"/>

	    <radioButton text="radioButton" x="100" y="119"/>

	    <link text="link" x="190" y="159"/>

	    <label text="label" x="250" y="109"/>

</window>

GridLayout

GridLayout arranges components row by row in a uniform grid, based on the order in which you add components to the parent container. GridLayout sizes each component the same and the overall grid will exactly fit the parent container. You specify the number of columns in the grid through the columns attribute. In addition to the GridLayout attributes, you can use child component attributes to help sizing and placing child components in the grid. The following example xml represents the window shown above:

 <window height="180" title="Window" width="350">
    <gridLayout columns="3"/>
    <button  text="Button"/>
    <link text="link"/>
    <comboBox/>
    <radioButton text="radioButton"/>
    <textField text="TextField"/>
    <button  text="Button"/>
    <listBox>
        <listItem text="listItem 1"/>
        <listItem text="listItem 2"/>
    </listBox>
    <button text="Button"/>
</window>

GridLayout is patterned after the SWT grid layout. - http://www.eclipse.org/articles/Understanding%20Layouts/Understanding%20Layouts.htm

Where to use Layout Manager?

Each container-like component (panel, desktopPane, rootPane, window, dialog) needs layout manager in order to layout child components, except for the following special components:

scrollPane
tabPane and its only possible child component tab
splitPane and its four possible child components top, bottom, left and right