Droplets and GridBagLayout

In line with industry standards for GUI presentation, the Droplets API supports a GridBagLayout scheme for the placement of components in the application window. The Droplets GridBag is essentially identical to the GridBagLayout class in the Java language's Abstract Window Toolkit (AWT) package, though the syntax for calling the Droplets GridBag settings is slightly different. In the following pages we'll go over the essentials of programming GUIs with GridBagLayout, including examples of how you would call the various GridBag attributes using the Droplets SDK.

What is GridBagLayout?

GridBagLayout is an object in the Droplets (or Java AWT) API library that determines the location and size of all components within the Droplet application window, based on the settings that you define for the component's GridBag attributes in your code.

All components in a GridBag layout are positioned within a grid that divides the application window into rows and columns, like cells in a spreadsheet. But GridBagLayout allows developers far more flexibility in the design of their application windows than other common layout managers.

This is because components in a GridBagLayout window can take up as many cells in the grid as the developer chooses, and need not be aligned identically to one another. When the Droplets Server starts the application, its GridBag manager object determines the number of rows and columns in the window, the size of all components and the longest row and column in the window — based on the parameters set in the application logic — and automatically positions all components within the application window relative to these parameters.

Furthermore, GridBagLayout allows the developer to determine the exact position of each component within the cell (or cells) that it takes up. If a component is not large enough to encompass the entire cell area allotted to it, GridBagLayout will check the code for an Anchor setting that determines the position of the component within its display area.

Finally, the GridBagLayout also allows you to determine how far your components are placed from the edge of the application window, and how your application window will "fill out" when end-users manually expand or contract the GUI.

Important Note: The application window grid, in which all components are placed within the application window, is distinct from the Droplets API's GridComponent. While the application window grid that we speak of throughout this document encompasses the entire GUI, the GridComponent is a specific type of component which — using the Droplets API — you can place within the application window grid. See the Droplets API documentation for more details on GridComponent.

GridBag Settings

The GridBagLayout scheme provides a number of settings that allow you to customize the look and feel of your components within the application window. In both the Droplets API and Java AWT, developers can manipulate components with the following GridBag settings:

Important note: In this document we go over how to set GridBag parameters in the application logic of your Droplets. It's also possible to over-ride these parameters (using the params.txt file) when you're working with application skins. See the Skinning Droplets document for more information on this.

Placement on the Grid

The first parameters which must be set in the GridBagLayout scheme are the integer variables gridx and gridy, which determine the horizontal and vertical placement of the component within the application window grid.

gridx determines the component's row while gridy determines its column, with gridx=0 being the top row and gridy=0 being the far left column. Important note: You cannot pass negative numbers as arguments to gridx and gridy.

Since GridBag columns and rows need not be of uniform width or height, the GridBagLayout is able to use the gridx and gridy parameters that you pass in to place your components in the appropriate place in the application window relative to one another.

See the next section for information on how to pass gridx/y settings to your components.

Number of Cells

Once you've placed the component on the grid, you can also determine the number of cells which it will take up through the gridwidth and gridheight variables.

Assigning a value of "2" to gridwidth and "1" to gridheight, for example, will place the component within two cells that are side-by-side (one row high and two columns wide). Assigning "1" to gridwidth and "2" to gridheight, on the other hand, will place the component within two cells that are on top of one another (two rows high and one column wide). As with gridx/y, you cannot pass negative numbers as arguments to either gridwidth or gridheight.

Important Note: In order to set gridx/y and gridwidth/height values to your components using Droplets' Java API, you first create a LayoutPlacement object (see the API for details on this class) and enter all four settings as arguments in the following order:

Using the Droplets C++ API, on the other hand, you would instead pass the gridx/y and gridwidth/height settings directly to the constructor as arguments:

Setting the GridX/Y and GridWidth/Height parameters as shown
in the example above results in a button on the top left of the grid
with a width of two columns and a height of one row.

Component Weight

The GridBag uses the variables weightx and weighty to determine your components' display area size relative to their column and row neighbors, as well as how your components expand as the end-user manually enlarges the application window.

When the Droplets Server sends the Client information about GUI presentation at start-up, the Client determines the size of each column and row based on the weight assigned in the application logic to the components which they contain. You can assign any number you like to a component's weight, but it's often easiest to grasp percentages (i.e. two components beside each other in a row could have a weightx of 50 and 50, 40 and 60 or 20 and 80 respectively, depending on how large you want them to be relative to one another). Weight is thus an important factor in how your components will be presented.

Even if you don't need to assign weight to your components for their initial presentation, it is still important to explicitly assign values for these two settings because the default value for both is "0" — meaning that your components won't expand at all, but instead stay clustered together in the center of the window. This is not especially attractive or professional looking, and so the GridBag allows you to customize the expansion and contractions of your components during a user resize.

weightx resizes the components horizontally, while weighty resizes them vertically. Thus if you set weightx=1 and weighty=0 the components will expand horizontally but not vertically. If you set them both to "1", their expansion during resize will be equal both vertically and horizontally. It's worth playing around a bit with weightx and weighty to make sure that your GUI components don't look stretched or distorted during end-user resizes.

Fill

GridBag also has a provision for determining how the component "fills" the space that is defined as its display area in the grid (through gridx/y and gridwidth/height). To this end, you can set the GridBag's fill parameter to one of four values: Horizontal, Vertical, None or Both.

Horizontal: When fill is set to this value, the component takes up the full horizontal width of its cells, but may leave empty space above and below it in the display area.

Vertical: The component takes up the full vertical height of its cells, but may leave empty space on either side of it in the display area.

None: The component remains at its default size, and does not concern itself with the filling of its display area.

Syntax Note: Those who are already familiar with Java AWT's GridBagLayout will want to take note of the syntax change for the Droplets GridBag. With the Droplets API, you assign a value to the fill setting by calling the SetFill() method of Component and its descendants (i.e. specific component types). Thus, you set the fill to Horizontal in a Droplet application thus:

Java: HypotheticalComponent.setFill(Component.FILL_HORIZONTAL);
C++: HypotheticalComponent->SetFill(TDsComponent::nFillHorizontal);

Anchor

When a component does not entirely fill its display area, the anchor setting can be used to determine its exact placement within its assigned cell(s). Valid anchor values follow the points of the compass:

By default, the component is centered within the display cell(s), but this can be over-ridden by explicitly assigning an anchor to the component. The syntax for this would be similar to the previous Fill example:

Java: HypothenticalComponent.setAnchor(Component.ANCHOR_NORTH);
C++: HypotheticalComponent->SetAnchor(TDsComponent::nAnchorNorth);

Of course anchor values must be coordinated with appropriate fill values. For example, it makes no sense to anchor something to the Center, East or West if it is already filling its display cell(s) horizontally. Also keep in mind that (if the component is filling horizontally) anchoring this component to the NorthEast, North or NorthWest will have the identical effect of anchoring it to the top of the display area.

Padding

You can also add a specific amount of padding (in pixels) to your component on all sides, which gives you the flexibility to expand a component from its default size without taking up the entire display area. This is done by assigning values to the ipadx and ipady parameters.

Whatever value you assign to ipadx or ipady, the padding on either side of the component will equal half of that value. In other words, if you assign a value ipadx=20, there will be ten pixels of padding to the left of the component and ten pixels of padding to its right.

Insets

Alternately, you can define a specific amount of distance (in pixels) between the edge of your component and the edge of its display cell(s) by defining an Inset, which governs the minimum amount of space allowed between the two.

This means that whenever the size of the display area exceeds the size of the component plus its insets, there will be even more distance than you define in Inset. But the space between the two will never go lower than the integer value that you have assigned to Inset.

When you call Inset, you must define integer values for all four sides of the component in the following order: Top, Left, Bottom, Right. So the code below:

Java: HypotheticalComponent.setInsets(new Insets(10, 0, 10, 0));
C++: HypotheticalComponent->SetInsets(10, 0, 10, 0);

would create 10-pixel insets at the top and bottom of the component, but no insets to its right or left.

An exception: The Menu Component

One exception to the GridBag scheme for laying out Droplet components is the MenuComponent, which defines a Menu Bar at the top of applications like Droplet Email shown below. It's important to note that a Menu Component by its very definition is always placed by the Droplets Client at the very top of the GUI.

When defining a Menu Component, you create individual menus within the Menu Bar by adding individual menu items to it. Rather than determining their position through GridBag constraints, the Droplets Server places the individual menus within the Menu Bar strictly in the order in which they are added in the application logic. You should thus define and add each menu item in the order in which you want them to appear on the front-end. The Menu Component also has default appearance values corresponding to the other GridBag constraints, and so there's no need to assign it any layout parameters whatsoever — if you do, they will simply be ignored.

Working with Multiple Grids

The GridBag is a powerful GUI layout tool, but many advanced applications still can't operate within a single, all-encompassing GUI grid. A good example of this is Droplet Email, where components in the toolbar are aligned with one another, but shouldn't be restricted to the alignment of the the two tables beneath them:

In this case, you can use the Droplets API to create independent layout grids for each section of your GUI.

This is done through the placement of multiple Panel components in the application's window (Frame or Dialog). By definition, a Panel is a component that acts as a container for other components. Whenever you define an application window, the Droplets Server automatically creates a Main Panel that encompasses the entire window; this allows you to place components in the window in accordance with the GridBag constraints that we've outlined above.

In addition, you can explicitly define additional Panels that will be nested inside the Main Panel, each of which will contain its own layout grid. This is done within the Main Panel's GridBag constraints; for example, the above GUI might be laid out with one Menu Component and three nested panels as follows:

• Create a Menu Component, defining and adding each drop-down item in the menu successively in your application logic, left to right.

• Create a Toolbar Panel with gridx/y set to (0, 0) and gridwidth/height at (2, 1), placing it directly below the menu bar and taking up its entire row (as we'll see below, each row will consist of only two cells). Set its fill to HORIZONTAL so that it takes up the entire horizontal space assigned to it; and its weightx/y to (100, 0) so that it expands horizontally but not vertically when the end-user resizes the GUI.

• Create a Folders Panel with gridx/y set to (0, 1) and gridwidth/height to (1, 1), placing it in the row directly below the toolbar and to the far left, and assigning it a single cell.

• Create a Mail Panel with gridx/y set to (1, 1) and gridwidth/height to (1, 1), placing it directly to the right of the Folders Panel.

• Assign the weightx/y parameters for the Folders and Mail Panels in such a way that the Droplets Server lays them out in the correct proportion. In this case, you could set the weighty setting for both panels to (100) so that they both take up the same amount of vertical space, while at the same time setting weightx to (20) for the Folder Panel and and to (80) for the Mail Panel, which means that the Mail Panel will take up 4/5 of the horizontal space as shown above.

• Set Fill to BOTH for all three panels (all nested panels should completely fill their display areas).

The Droplets GridBag

The Droplets API allows you to harness the power and flexibility of the GridBagLayout scheme for designing application front-ends when writing Droplet-powered applications. In combination with the Droplets Platform's mode of presenting GUI's to the desktop from a client/server setup, the Droplets SDK's GridBag offers developers a familiar, industry-standard mode of laying out their online application front-ends with a maximum of flexibility and sophistication.

To find out more about GridBag and the Droplets API, consult our API documentation. For a demo of the use of Droplets' GridBag in real applications, check out our Droplets Programming Tutorials.