back to nexaweb
search
home          reference api          forum          download          blog
community   |   resource center   |   about nexaweb
Layout Panes  
Technology Resources > Developer Guide > Working with Widgets > Layout Panes
This section introduces the Nexaweb layout panes.
1.       What are Nexaweb layout panes?
2.       A visual guide to layout panes
3.       Where to use layout panes
4.       How to use Nexaweb layout panes
 
What are Nexaweb Layout Panes?

Nexaweb layout panes control the position of child components in a container. (A container is a UI element in a Nexaweb application that can hold child components - both containers and components - and to which you may add layout panes and other visual elements in order to create the application’s visual appearance.)
 
 
Different layout panes provide different positioning and resizing behaviors. The predefined Nexaweb layout panes include:
  • freePane
  • borderPane
  • cardPane (Java applications only)
  • gridPane (Java applications only)
  • verticalBoxPane
  • horizontalBoxPane
  • verticalflowPane (Java applications only)
  • horizontalflowPane (Java applications only)
You can use one pane or combine several of them in the same container to achieve the UI design you desire. Each pane has its own special attributes that you can set to achieve different layout results.
 
You can assign generic attributes to child components - for example, margin - and pane specific attributes such as Grid Horizontal Alignment for gridPane, and flex for either of the horizontal- or verticalBoxPanes - to create the layout that you want. If you do not specify a pane, Nexaweb Studio uses freePane - the simplest layout, that allows you to place a component or container wherever you wish within the container - as the default. If a predefined layout pane 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 panes work. For an example of the different layout panes either import into Studio (Using Eclipse’s Import wizard) or build and deploy the UI Explorer part of the samples included in the Nexaweb Platform 4.x installation.

A Visual Guide to Layout Panes

Nexaweb platform provides a universal XAL namespace for all Nexaweb applications and specific namespaces for Nexaweb Java and Ajax applications. The universal namespace provides access to the elements and attributes available for both Java and Ajax application environments, while the Java and Ajax namespaces provide access to the Java or Ajax elements and attributes only. The XML examples provided in this section show the XAL universal namespace. The following table lists all of the available namespaces: 


Application Environment namespace
Java xmlns="http://openxal.org/ui/java"
Ajax xmlns="http://openxal.org/ui/html"
Universal

xmlns="http://openxal.org/ui/"
 

freePane


 

freePane is the default layout pane Nexaweb Studio uses for all containers if you do not specify any other layout pane. It 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 freePane when other panes 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 title="New Window" width="300px" height="300px">
    <freePane>
      <comboBox height="25px" text="Account Type" width="100px" x="45px" y="24px">
        <listBox>
          <listItem text="New Account"/>
          <listItem text="Existing Account"/>
          <listItem text="Search"/>
        </listBox>
      </comboBox>
      <button height="25px" text="Go" width="100px" x="45px" y="60px"/>
      <radioButton height="25px" text="Button On/Off" width="100px" x="170px" y="220px" selected="true"/>
    </freePane>
 </window>
</xal>


borderPane

 

A borderPane 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 the center stretch in both directions, so that the remaining space fills with the center component.  You place child components in these areas by specifying borderPosition when adding the component to the borderPane.  The following example xml represents the window shown above:

<xal xmlns=http://openxal.org/ui>
 <window title="New Window" width="300px" height="300px">
  <borderPane>
   <button height="25px" text="North" width="100px" borderPosition="north"/>
   <button height="25px" text="South" width="100px" borderPosition="south"/>
   <button height="25px" text="East" width="100px" borderPosition="east"/>
   <button height="25px" text="West" width="100px" borderPosition="west"/>
   <button height="25px" text="Center" width="100px" borderPosition="center"/>
  </borderPane>
 </window>
</xal>

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.  borderPane ignores the size of a component placed in the center area so that the component can fill any available space.  Components placed in north and south maintain their height and components placed in west and east maintain their width.

You don't have to put components in all five areas.  Often placing components in two or there areas is sufficient to get the layout result you want.

cardPane

cardPane (available in Java applications only) allows you to put different components to a common container, while showing only one of them at a time. You specify which one to show using the show attribute.  The displayed component occupies the entire space of its parent container. The best example of a cardPane is a slideshow. As shown in the windows above, clicking prev or next 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:

cardPane - UI Example

xal xmlns="http://openxal.org/ui">
  <mco:declarations xmlns:mco="http://openxal.org/core/mco"> 
     <mco:mco id="cardPaneMco" src="CardPaneMco"/>
  </mco:declarations> 
  <window title="New Window" width="300" height="300"> 
   <borderPane>
     <cardPane id="cardPane" borderPosition="center" show="1">
        <button id="button1" text="Button 1" cardName="1"/>
        <button id="button2" text="Button 2" name="2"/>
        <button id="button3" text="Button 3" name="3"/>
        <borderPane id="panel" name="4">
          <button borderPosition="center" id="button4" text="Button 4"/>
        </borderPane> 
     </cardPane>
     <horizontalFlowPane borderPosition="south" align="center">
        <button id="prev" text="prev" onCommand="mco://cardPaneMco.prev( cardPane )"/>
        <button id="next" text="next" onCommand="mco://cardPaneMco.next( cardPane )"/>
     </horizontalFlowPane>
   </borderPane>
  </window>
</xal>

cardPane - MCO Example

import com.nexaweb.client.mco.AbstractMco;
 import com.nexaweb.xml.Element;

 public class CardPaneMco extends AbstractMco{

     //   first card by default is the first card
     int currPage = 0;

     public void next( Element cardPane) { 

         //   increment the current card index
         //   if last card is reached, set to first card
         currPage++;
         if( currPage == cardPane.getChildCount() )
         {
             currPage = 0; 
         }

         //   get the name of the new card to show, and set it on the card pane
         String cardName = ( (Element) cardPane.getChildAt(currPage) ).getAttribute("name");
         cardPane.setAttribute("show", cardName ); 
     }

     public void prev( Element cardPane )
     { 
         //   decrement the current card index
         //   if first card is reached, set to last card
         currPage--;
         if( currPage < 0 )
         {
             currPage = cardPane.getChildCount()-1;
         }

         //   get the name of the new card to show, and set it on the card pane 
         String cardName = ( (Element) cardPane.getChildAt(currPage) ).getAttribute("name");
         cardPane.setAttribute("show", cardName );

     }

 }

gridPane


 
gridPane arranges components row by row in a uniform grid, based on the order in which you add components to the parent container. gridPane 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 gridPane 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:

<xal xmlns=http://openxal.org/ui> 
  <window title="New Window" width="300px" height="300px">
   <gridPane evenlySpace="true" columns="3">
    <button height="25px" text="Button" width="100px"/>
    <link height="20px" text="link"/>
    <comboBox height="25px" text="ComboBox" width="100px">
     <listBox>
      <listItem text="listItem #1"/>
      <listItem text="listItem #2"/>
      <listItem text="listItem #3"/>
     </listBox>
    </comboBox>
    <radioButton height="25px" text="radioButton" width="100px"/>
    <textField height="25px" text="TextField" width="200px"/>
    <button height="25px" text="Button" width="100px"/>
    <listBox height="100px" width="100px">
     <listItem text="listItem #1"/>
     <listItem text="listItem #2"/>
     <listItem text="listItem #3"/>
    </listBox> 
    <button height="25px" text="Button" width="100px"/>
   </gridPane>
  </window>
 </xal>

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

verticalBoxPane

The verticalBoxPane places components in a single column in a vertical orientation.  It does not wrap a component to the next row or column if the component's size is over the container's size, where as verticalFlowPane does wrap the component to available space. By default, verticalBoxPane honors a component's size and the component does not resize if the container's size changes. The following example xml represents the window shown above:

<xal xmlns=http://openxal.org/ui>
  <window title="New Window" width="300px" height="300px" x="5" y="5">
   <verticalBoxPane>
    <button height="25px" text="Button" width="100px"/>
    <button height="25px" text="Button" width="100px"/> 
    <textField height="25px" text="TextField" width="200px"/>
    <label height="20px" text="Label" width="100px"/>
    <comboBox height="25px" text="ComboBox" width="100px">
     <listBox>
      <listItem text="listItem #1"/>
      <listItem text="listItem #2"/>
      <listItem text="listItem #3"/>
     </listBox>
    </comboBox>
   </verticalBoxPane>
  </window>
 </xal>

horizontalBoxPane

The horizontalBoxPane places components in a single row along the horizontal orientation of the container.  It does not wrap components to the next row, as the horizontalFlowPane does, when the size of the total width of the components exceeds the width of the container. By default, horizontalBoxPane honors a component's size and the component does not resize if the container's size changes. The following example xml represents the window shown above:

<xal xmlns=http://openxal.org/ui>
  <window title="New Window" width="300px" height="300px" x="5" y="5">
   <horizonatlBoxPane>
    <button height="25px" text="Button" width="100px"/>
    <button height="25px" text="Button" width="100px"/> 
    <textField height="25px" text="TextField" width="200px"/>
    <label height="20px" text="Label" width="100px"/>
    <comboBox height="25px" text="ComboBox" width="100px">
     <listBox>
      <listItem text="listItem #1"/>
      <listItem text="listItem #2"/>
      <listItem text="listItem #3"/>
     </listBox>
    </comboBox>
   </horizontalBoxPane>
  </window>
 </xal>

 verticalFlowPane

verticalFlowPane lays out components in a single column, aligned from the left, and centering the components to the largest component in the column.  It starts a new column when components fill the vertical space of the container. The following example xml represents the window shown above:

<xal xmlns=http://openxal.org/ui>
  <window title="New Window" width="300px" height="300px">
   <verticalFlowPane>
    <button height="25px" text="Button" width="100px"/>
    <button height="25px" text="Button" width="100px"/>
    <radioButton height="25px" text="radioButton" width="100px"/>
    <comboBox height="25px" text="ComboBox" width="100px">
     <listBox>
      <listItem text="listItem #1"/>
      <listItem text="listItem #2"/>
      <listItem text="listItem #3"/>
     </listBox>
    </comboBox>
    <textField height="25px" text="TextField" width="200px"/>
   </verticalFlowPane>
  </window>
 </xal>

horizontalFlowPane

horizontalFlowPane lays out components in rows that span the horizontal width of the container. horizontalFlowPane separates components within a row by a horizontal gap that you can specify.  horizontalFlowPane places each component in the same row until the total of the width of components in the row and the horizontal gap between them exceeds the width of the container, then begins a new row and places components across that. You can specify the amount of space between rows by indicating a value for the vertical gap. The following example xml represents the window shown above:

<xal xmlns=http://openxal.org/ui>
  <window title="New Window" width="300px" height="300px">
   <horizontalFlowPane gapHorizontal="25" gapVertical="25">
    <button height="25px" text="Button" width="100px" x="100px" y="10px"/>
    <button height="25px" text="Button" width="100px" x="164px" y="53px"/>
    <radioButton height="25px" text="radioButton" width="100px"/>
    <comboBox height="25px" text="ComboBox" width="100px">
     <listBox>
      <listItem text="listItem #1"/>
      <listItem text="listItem #2"/>
      <listItem text="listItem #3"/>
     </listBox>
    </comboBox>
    <textField height="25px" text="TextField" width="200px"/>
   </horizontalFlowPane>
  </window>
 </xal>

Where to Use Layout Panes

Each container-like component (desktopPane, rootPane, window, dialog) has an inherent border layout which takes one child and places that child in the center position of the border layout. When you add a layout pane to the container, the layout pane takes up the center position of the border layout and controls the positioning and sizing of the components and other layout panes placed in it. Thus each container-like component needs a layout pane in order to control the layout of child components, except for the following special components:

  • scrollPane
  • tabPane and its only possible child component tab
  • horizontal- and verticalSplitPane and their four possible child components top, bottom, left and right
(last update - 08-Feb-08)

© Copyright 2005-2008 Nexaweb Technologies Inc. All Rights Reserved.