Root container

When you create a form, you cannot put widgets directly into this form. You need a container that will become a seat for all other form elements - containers and widgets. That is a root container.

Most container provided by Lycia Form Designer (except for TabPage) can serve as a root container. The most frequent choice is GridPanel.

Form XML code:

In the XML, there is a <form.rootContainer> tag to which all other tags are placed:

For example,

Other containers are then placed inside the root container:

CSS element selector code:

Most commonly used form properties:

classNames

identifier

Most commonly used theme properties: depend on the definite container used as the root one

How to add a root container

What to remember when selecting a root container

Layout restrictions for root containers

Conversion equivalents for root containers (from .per to .fm2)

Populating root containers by ui methods

How to add a root container

To add a root container to your form, you

Step 0. Consider and select what container will suit your needs best.

Step 1. Select this container among other containers in Palette.

Step 2. Drop the selected container into your form.

In the short video below, you will see how to add a GridPanel as a root container to the form:

What to remember when selecting a root container

When selecting a root container, you must carefully consider what tasks will be performed by the form because the choice of the root container affects heavily resizing and layout possibilities for your form at runtime.

For example,

• BorderPanel can incorporate only upto 5 elements - containers or widgets. However, every container included in BorderPanel can hold as many elements as necessary.
• CoordPanel cannot be resized.
• GroupBox can store only one element (though typically this element is another container).
• You can elements to a StackPanel only in one direction - in a column or in a row (to the right).
• Tab can store only TabPage containers.
• TabPage can store only one element (though this element can be another container).

More details can be obtained from the pages about different containers.

Layout restrictions for root containers

Lycia imposes some restrictions on the layout of root containers:

1. If any element (including root containers) has horizontal/vertical alignments other than STRETCH, its size must be defined by a) its size properties or b) the size of its descendents.
2. Root containers with horizontal/vertical alignments set to STRETCH ignore any size properties when opened in the full-screen mode.

3. Root container with horizontal/vertical alignments set to STRETCH must have some size specified when opened in a bordered window. If no size is specified, the root container will get the default size of 600x400 px.

More details about existing layout rules are here.

Conversion equivalents for root containers (from .per to .fm2)

With Lycia, you do not need to recreate your .per forms - you can easily convert them in LyciaStudio or via the command line tools.

In LyciaStudio, there are two options for converting .per forms into .fm2 - Convert to CoordPanel and Convert to GridPanel:

If you convert a .per form with a SCREEN layout and want to get an .fm2 form with GridPanel used as root container, you can do it by qform:

qform --scrcompat file_name.per

The table below summarizes what container you will get when .per forms are converted into .fm2:

Populating root containers by ui methods

You can populate any form with containers and widgets by ui methods - but this form must already have a root container.

Here is an example how to add containers and widgets to a root container:

4gl source file

MAIN

    DEFINE gl ui.GridLength

    DEFINE grid, grid2 ui.GridPanel

    DEFINE btn1, btn2 ui.Button

    DEFINE gr, gr2 DYNAMIC ARRAY OF ui.GridRowDefinition

    DEFINE gc, gc2 DYNAMIC ARRAY OF ui.GridColumnDefinition

    DEFINE rLocation ui.GridItemLocation

    DEFINE ArrayOfElementsForGrid2 DYNAMIC ARRAY OF ui.AbstractUIElement

    DEFINE gr_item ui.GridRowDefinition

    DEFINE gc_item ui.GridColumnDefinition

 

  OPEN WINDOW w1 WITH FORM "test" ATTRIBUTE(BORDER)

  LET grid = ui.GridPanel.ForName("rootContainer")

  CALL grid.SetPreferredSize(["600px","600px"])

  #ALL GridRowDefinition and GridColumnDefinition WILL BE AUTO

  CALL gl.SetGridLengthType("Auto")

  CALL gr_item.SetGridLength(gl)

  CALL gc_item.SetGridLength(gl)

  #CREATE TWO GRID ROWS

  CALL gr.append(gr_item)

  CALL gr.append(gr_item)

  CALL grid.SetGridRowDefinitions(gr)

  #CREATE ONE GRID COLUMN

  CALL gc.append(gc_item)

  CALL grid.SetGridColumnDefinitions(gc)

  

#CREATE BUTTON IN ROOTCONTAINER, IN CELL 0,0

  LET btn1 = ui.Button.Create("bt1", "rootContainer")

  LET rLocation.GridHeight = 1

  LET rLocation.GridWidth = 1

  LET rLocation.GridX = 0

  LET rLocation.GridY = 0

  CALL btn1.SetGridItemLocation(rLocation)

  CALL btn1.SetPreferredSize(["150px", "100px"])

  CALL btn1.SetText("Button1 in root")

  CALL btn1.SetEnable(TRUE)

  

#CREATE CHILD GRID CONTAINER IN ROOTCONTAINER

  LET grid2 = ui.GridPanel.Create("child_grid_id", "rootContainer")

  #DEFINE LOCATION OF CHILD GRID PANEL IN ROOTCONTAINER GRIDPANEL

  CALL grid2.SetGridItemLocation([0, 1, 1, 1])

  CALL grid2.SetPreferredSize(["200px", "200px"])

  #ADD ONE ROW AND ONE COLUMN TO grid2

  CALL gr2.append(gr_item)

  CALL gc2.append(gc_item)

  CALL grid2.SetGridRowDefinitions(gr2)

  CALL grid2.SetGridColumnDefinitions(gc2)

 

#CREATE BUTTON AS A SEPARATE WIDGET

  LET btn2 = ui.Button.Create("bt2")

  CALL btn2.SetGridItemLocation([0, 0, 1, 1])

  CALL btn2.SetPreferredSize(["350px", "200px"])

  CALL btn2.SetText("Button2 in CHILD GRID")

  CALL btn2.SetEnable(TRUE)

  #grid2 DOESN'T HAVE ANY ELEMENTS YET

  #AFTER CREATING A ui.Button OBJECT, WE INSERT IT IN GRIDPANEL

  LET ArrayOfElementsForGrid2 = grid2.GetItems()

  CALL ArrayOfElementsForGrid2.append(btn2) #ADD BUTTON

  CALL grid2.SetItems(ArrayOfElementsForGrid2) #PUSH ALL ITEMS BACK TO GRID

CALL fgl_getkey()

END MAIN

.fm2 form

<?xml version="1.0" encoding="UTF-8"?>

<form xmlns="http://namespaces.querix.com/2015/fglForms" title="New Form">

<form.rootContainer>

<GridPanel identifier="rootContainer" visible="true"/>

</form.rootContainer>

</form>

Related articles

Lycia Form Designer

Containers

ui methods

qform