Class: cWebPanel

Properties  Events  Methods    Index of Classes

The Web Framework panel control

Hierarchy

cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseContainer
---------------cWebPanel

Library: Web Application Class Library

Package: cWebPanel.pkg

Description

Use the cWebPanel class to divide the layout of your view or dialog into regions: top, bottom, left, right and center. These panels can then be used to group together different controls.



For example, you may wish to divide a view into a title region (top), a list of items (left), a layout of data entry controls (center) and a column of text (right).

Sample

Object oPanelView is a cWebView
    Set psCaption to "Multi Panel View"
    Set piHeight to 300
    Set piWidth to 300

    Object oTopPanel is a cWebPanel
        Set peRegion to prTop
        Set psBackgroundColor to "Blue"

        Object oTopLabel is a cWebLabel
            Set psCaption to "Top"
            Set psBackgroundColor to "#AAAAFF"
            Set peAlign to alignCenter
        End_Object
    End_Object 

    Object oCenterPanel is a cWebPanel
        Set psBackgroundColor to "Orange"

        Object oCenterLabel is a cWebLabel
            Set psCaption to "Center"
            Set psBackgroundColor to "#FFDDAA"
            Set peAlign to alignCenter
            Set pbFillHeight to True
        End_Object
    End_Object 

    Object oLeftPanel is a cWebPanel
        Set peRegion to prLeft
        Set psBackgroundColor to "#4343FB"
        Set piWidth to 60

        Object oLeftLabel is a cWebLabel
            Set psCaption to "Left"
            Set psBackgroundColor to "#AAAAFF"
            Set peAlign to alignCenter
            Set pbFillHeight to True
        End_Object
    End_Object

    Object oRightPanel is a cWebPanel
        Set peRegion to prRight
        Set psBackgroundColor to "#4343FB"
        Set piWidth to 60

        Object oRightLabel is a cWebLabel
            Set psCaption to "Right"
            Set psBackgroundColor to "#AAAAFF"
            Set peAlign to alignCenter
            Set pbFillHeight to True
        End_Object
    End_Object 

    Object oBottomPanel is a cWebPanel
        Set peRegion to prBottom
        Set psBackgroundColor to "Blue"
        
        Object oBottomLabel is a cWebLabel
            Set psCaption to "Bottom"
            Set psBackgroundColor to "#AAAAFF"
            Set peAlign to alignCenter
        End_Object
    End_Object 
End_Object

The above example illustrates a view that is divided into Top, Bottom, Left, Right and center panels. Each panel then contains a single cWebLabel control.

Object Name

The Web Framework uniquely identifies each web object via a combination of the object hierarchy (object nesting), and object name. This means that web object names must be unique within their parent (i.e. each sibling web object must have a unique name).

Object Placement

Panel controls must be placed within a web container (e.g. cWebPanel, cWebView or cWebModalDialog).

Panels may be siblings of other panel objects; however you may not mix web panels and web controls as sibling objects. For example the following sample demonstrates an invalid layout of web objects:

Object oView is a cWebView
    Set piHeight to 200
    Set piWidth to 400

    // This is "not" a valid layout of web objects!
    Object oTop is a cWebPanel
        Set peRegion to prTop
        Set piHeight to 30
        Set psBackgroundColor to "#CCCCFF"
    End_Object

    Object oCenter is a cWebPanel
        Set peRegion to prCenter
        Set psBackgroundColor to "#CCFFCC"
    End_Object

    Object oButton is a cWebButton
    End_Object
End_Object

The above example declares two sibling panel objects inside a view followed by a sibling button object. Once you begin dividing a view into panel regions you can no longer place controls as direct child objects of that view. Instead, your controls must be placed inside these new regions, i.e. inside the panel objects.

A correct way to write the previous example would be to place the button inside one of the existing panels, or to create a new panel to host the button, for example:

Object oView is a cWebView
    Set piHeight to 200
    Set piWidth to 400

    // This is a valid layout
    Object oTop is a cWebPanel
        Set peRegion to prTop
        Set piHeight to 30
        Set psBackgroundColor to "#CCCCFF"
    End_Object

    Object oCenter is a cWebPanel
        Set peRegion to prCenter
        Set psBackgroundColor to "#CCFFCC"
    End_Object

    Object oBottom is a cWebPanel
        Set peRegion to prBottom
    
        Object oButton is a cWebButton
        End_Object
    End_Object
End_Object


Panel Regions

Create two or more sibling panel objects to divide a parent container into regions. Set peRegion to determine whether a panel is positioned at the top, bottom, left, right or center of its parent container.

No two sibling panel objects can share the same peRegion setting, e.g. you cannot have two top panels that are sibling objects.

The center panel is a special case; it is designed to grow into the remaining space not occupied by the other sibling panels. Any set of sibling panels must contain one (and only one) center panel. The default panel region is center, i.e. peRegion = prCenter

The following examples demonstrate valid and invalid panel layouts:

Invalid:

Object oView is a cWebView
    Set piHeight to 200
    Set piWidth to 400

    // This is an invalid layout
    Object oTop is a cWebPanel
        Set peRegion to prTop
        Set piHeight to 30
        Set psBackgroundColor to "#CCCCFF"
    End_Object

    Object oBottom is a cWebPanel
        Set peRegion to prBottom
        Set piHeight to 170
        Set psBackgroundColor to "#CCFFCC"
    End_Object
End_Object

The above layout is invalid because it does not contain a center panel. A correct way to divide a view into top and bottom regions is as follows:

Object oView is a cWebView
    Set piHeight to 200
    Set piWidth to 400

    Object oTop is a cWebPanel
        Set peRegion to prTop
        Set piHeight to 30
        Set psBackgroundColor to "#CCCCFF"
    End_Object

    Object oBottom is a cWebPanel
        Set peRegion to prCenter
        Set psBackgroundColor to "#CCFFCC"
    End_Object
End_Object

Note that although the second panel is named oBottom, its peRegion value is set to prCenter. peRegion is set to prCenter here for clarity. Since prCenter is the default, setting peRegion value to this setting is redundant. Because a center panel will consume whatever space remains after its sibling panels are rendered, it will effectively become the bottom panel in this layout. It is unnecessary (actually incorrect) to set a piHeight for the center panel.

Another way to divide the view into top and bottom regions would be to create a center and bottom panel.

Panel Size

The size of a panel is determined by a number of factors, such as the contents of the panel and whether there is an explicit height or width setting. The panel size will also depend on the panel's region and the size of the parent container.

Top and Bottom Panel Size

Top and bottom panels will consume the entire width of their parent container. Do not explicitly set the piWidth property of a panel with peRegion setting of prTop or prBottom.

By default, the height of a top or bottom panel will be determined by the height of the controls contained within it.

Set piHeight in a top or bottom panel to give the panel a fixed height (in pixels), regardless of the controls contained within it.

Left and Right Panel Size

Left and right panels will consume the remaining height of their parent container (after subtracting the height of any sibling top or bottom panels). Do not explicitly set the piHeight property of a panel with peRegion setting of prLeft or prRight.

By default, the width of a left or right panel will be determined by the width of the controls contained within it.

Set piWidth in a left or right panel to give the panel a fixed width (in pixels), regardless of the controls contained within it.

Center Panel Size

The size of a center panel is determined by whatever space remains after any sibling top, bottom, left and right panels have been rendered. Do not explicitly set the piHeight or piWidth of a panel with peRegion setting of prCenter.

Resizable Panels

Left and right panels can be resized with the mouse to change the width, while top and bottom panels can be resized to change the height. The center panel will always readjust itself to occupy the remaining space.

Set pbResizable to true in a top, bottom, left or right panel to allow users to resize them with the mouse. The pbResizable property has no meaning in a center panel and it should not be set.

Set piMinHeight in a top or bottom panel to determine the minimum height of a resizable top or bottom panel.

Set piMinWidth in a left or right panel to determine the minimum width of a resizable left or right panel.

Control Layout inside a Panel

Each panel supports its own column layout system to control the layout of any nested control objects (e.g. button, form, grid, treeview, checkbox, etc).
Set piColumnCount to determine the number of layout columns in the panel. For more information, see Positioning and Layout of Controls.

Nested Panels

Each panel can be further subdivided into a set of nested top, bottom, left, right and center panels. The same rules that apply to dividing a view into panels also apply when dividing a panel into sub panels.

Panel sub-division can be useful when your view requires a complicated layout.

Object oRightPanel is a cWebPanel
    Set peRegion to prRight
    Set piWidth to 60

    Object oRightTopPanel is a cWebPanel
        Set peRegion to prTop
        Set psBackgroundColor to "Blue"
        Set piHeight to 50
    End_Object 

    Object oRightBottomPanel is a cWebPanel
        Set peRegion to prCenter
        Set psBackgroundColor to "Red"
    End_Object 
End_Object

In the above example, a right panel is divided into top and bottom regions by nesting a two panels with peRegion settings of prTop and prCenter.

There is no technical limit to how many layers of sub-panel you can create, however more than two levels of sub-panel division could be difficult to manage and is probably of little use.

Color

The color of a panel is determined by the web application's CSS theme (psTheme). You can define additional or replacement CSS styles in your web application's application.css file. Set psCSSClass to the CSS class name you would like to be applied to a panel.

Set psBackgroundColor directly override the control's CSS themed color.

See Also

Styling Web Applications