AppBuilder Multiple Layout
Beta Draft
Author: (Author's Name)
Date Last Updated: (Date)
Scheduled Release: (Release Number)


Revision History The following revisions have been made to this document:

Date: (date)
Revision: (rev-no)
Developer: (developer)
Summary of Changes: (summary)


Copyright (C) 2000 by Progress Software Corporation ("PSC"), 14 Oak Park, Bedford, MA 01730, and other contributors as listed below. All Rights Reserved.

The Initial Developer of the Original Code is PSC. The Original Code is Progress IDE code released to open source December 1, 2000.

The contents of this file are subject to the Possenet Public License Version 1.0 (the "License"); you may not use this file except in compliance with the License. A copy of the License is available as of the date of this notice at:

http://www.possenet.org/license.html

Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. You should refer to the License for the specific language governing rights and limitations under the License.


Contributors
Jane Contributor, Joe Contributor


Contents

1 Overview
2 Architecture
2.1 Design-time Layouts
2.2 Run-time Layouts
2.3 Maintaining Layouts
3 Primary Data Structures
4 Primary Algorithms and Processes
5 Advanced Topics
5.1 SmartObject Layouts
5.2 Layout Inheritance
6 Dependencies
7 Source Files
8 Build Process and Requirements
9 Execution Methods
10 Test Requirements and Strategies
11 Supplementary Information
12 Related Documentation


1. Overview

The AppBuilder’s Multiple Layout feature allows you to make adjustments to a procedure file’s interface based on run-time conditions. By default, all procedure files have a master layout that can be thought of as the “compile-time” interface. An alternate layout is based on the master layout, and may contain various adjustments such as size and placement changes to interface components, property changes (e.g., background color) and the insertion or removal of widgets. Each alternate layout is given a unique name and a logical condition that, when satisfied at run-time, will cause the layout to be applied to the interface. This document describes how alternate layouts are maintained internally by the AppBuilder.

2. Architecture

2.1 Design-time Layouts

The information used to define the layout of a procedure’s interface is stored in the form of individual widget properties. At design time, this information is kept in the _L temp-table. Each interface object, or widget, has one _U temp-table record (i.e., the Universal widget record containing basic properties). Each _U record has associated with it one or more _L records: one to describe the default or master layout properties of the widget, and additional _L records to hold the layout properties of any alternate layouts that are defined. Each _L record contains a _LO-NAME field that hold the name of the layout to which it belongs. The name corresponds to a record in the _LAYOUT temp-table, which contains the characteristics of each layout such as the name, the run-time expression used to select the layout, and flags to indicate whether the layout is CHARACTER or GUI based and whether or not the layout is currently active. For more details on the design-time behavior of alternate layouts, refer to the AppBuilder Developer’s Guide.

2.2 Run-time Layouts

When a procedure file is saved in the AppBuilder, all of the layout information is written out to the file. The default or master layout properties are written directly into the associated widget’s definition statement, the parent frame’s definition statement, the AppBuilder-generated Enable_UI internal procedure, and in the run-time settings section. The alternate layout information is written into a special internal procedure with the name {&WINDOW-NAME}-Layouts( ). At run-time, the interface is first constructed using the master layout properties and then the run-time expressions for each alternate layout are evaluated to determine if they should be applied. If the run-time expression for a given alternate layout evaluates to TRUE, then the special internal procedure is called with the associated layout’s name and that layout’s properties are applied. For more details on the run-time behavior of alternate layouts, refer to the AppBuilder Developer’s Guide.

2.3 Maintaining Layouts

When a procedure file is reopened in the AppBuilder, the internal representation of all of the layouts that are defined in the file must be recreated (i.e., the _LAYOUT and _L records). The master layout is rebuilt from the widget property information that is generated by the Analyzer (see the open source document on “AppBuilder Open and Save” for more details) and from any additional information extracted from the run-time settings section. The alternate layouts are rebuilt from parsing the run-time settings section to obtain the information for the _LAYOUT records and from parsing the {&WINDOW-NAME}-Layouts( ) internal procedure to obtain the information for the _L records. Note that the widget definitions themselves must be recreated internally first before the associated layouts can be processed. The main procedure file the AppBuilder uses for opening files is adeuib/_qssuckr.p; the internal procedure Read_Layout_Defs( ) is responsible for parsing and rebuilding the _LAYOUT records; the internal procedure Layout_Reader( ) is responsible for parsing the {&WINDOW-NAME}-Layouts internal procedure and rebuilding the _L records for the alternate layouts.

3. Primary Data Structures

The main data structures used to support layouts in the AppBuilder are the _L and _LAYOUT temp-tables:

Table 1: _LAYOUT Temp Tables

Field Name

Data Type

Description

_LO-NAME*

Character

Name of the layout as it was defined.

_GUI-BASED

Logical

TRUE if the layout is supported on MS-Windows, FALSE if it is a character-mode layout.

_EXPRESSION

Character

The selection expression, as defined when the layout was created, that determines when to apply the layout.

_COMMENT

Character

Descriptive information about the layout, as specified when the layout was created.

_ACTIVE

Logical

TRUE if the layout can be used, FALSE otherwise. By default, this value is always TRUE for the master layout and for any user-defined layout; it is really meant to allow you to disable the Standard Character, MS Windows and Windows 95 layouts.

                                                                                                                    *Primary, Unique index key

Table 2: _L Temp Tables

Field Name

Data Type

Description

_LO-NAME*

Character

Name of the layout (or _LAYOUT) to which this layout belongs.

_u-recid*

Recid

Recid of the Universal widget record (or _U) that this layout modifies.

_3-D

Logical

Basic widget property.

_BGCOLOR

Integer

Basic widget property.

_COL-MULT

Decimal

Used to determine width property.

_COL

Decimal

Basic widget property.

_CONVERT-3D COLORS

Logical

Basic widget property.

_CUSTOM-POSITION

Logical

TRUE when position has been changed in an alternate layout; causes position properties to be disinherited from master layout.

_CUSTOM-SIZE

Logical

TRUE when size has been changed in an alternate layout; causes size properties to be disinherited from master layout.

_EDGE-PIXELS

Integer

Basic widget property.

_FGCOLOR

Integer

Basic widget property.

_FILLED

Logical

Basic widget property.

_FONT

Integer

Basic widget property.

_GRAPHIC-EDGE

Logical

Basic widget property.

_HEIGHT

Decimal

Basic widget property.

_NO-BOX

Logical

Basic widget property.

_NO-FOCUS

Logical

Basic widget property.

_NO-LABELS

Logical

Basic widget property.

_NO-UNDERLINE

Logical

Basic widget property.

_REMOVE-FROM-LAYOUT

Logical

Set to TRUE when an object is “deleted” from an alternate layout.

_ROW

Decimal

Basic widget property.

_ROW-MULT

Decimal

Used to determine the height property.

_SEPARATOR-FGCOLOR

Integer

Basic widget property.

_SEPARATORS

Logical

Basic widget property.

_TITLE-BGCOLOR

Integer

Basic widget property.

_TITLE-FGCOLOR

Integer

Basic widget property.

_VIRTUAL-HEIGHT

Decimal

Basic widget property.

_VIRTUAL-WIDTH

Decimal

Basic widget property.

_WIDTH

Decimal

Basic widget property.

_WIN-TYPE

Logical

TRUE if layout is graphical (i.e., MS-Windows-based), FALSE otherwise.

*Unique key

4 Primary Algorithms and Processes

Refer to the Architecture section for details.

5. Advanced Topics

5.1 SmartObject Layouts

SmartObjects contain their own internal procedures to manage alternate layouts. Refer to the AppBuilder Developer’s Guide for more details.

5.2 Layout Inheritance

When adding , removing, or modifying objects from the master layout at design-time, it is often necessary to propagate the change to any alternate layout definitions – a process called “inheritance” (Refer to the AppBuilder Developer’s Guide for more details on layout inheritance).

When an object is added to the master layout, the corresponding “draw” procedure is called to create the necessary internal temp-table records for the object and visualize it on the display. These “draw” procedures (e.g., adeuib/_drwfill.p for a fill-in) also contain code to create the associated _L records in each of the defined alternate layouts. This code is contained in the file adeuib/_multi_l.i.

When an object is removed from the master layout, the object is effectively deleted from all of the defined layouts for the object’s parent window automatically (objects are not actually deleted; they are marked as such, which causes them to be “hidden” in all layouts). The code to delete an object is in adeuib/delete_u.i.

When an object is modified in the master layout, all of the associated alternate layouts (i.e., _L records for that object) must also be modified accordingly (unless the object has been disinherited in the alternate layout).

6. Dependencies

Care must be taken when making any changes to the implementation of alternate layouts to ensure backward compatibility. The methods used to identify and interpret the individual properties of layouts are delicate and may fail to work properly if changes are made to the structure of the AppBuilder generated code.

7. Source File

This tool uses the following source files:

Source File

Description

adeuib/_layout.w

Dialog box for defining an alternate layout and for selecting the current layout at design time (e.g., Layout->Alternate Layout from the AppBuilder main menu).

adeuib/layout.i

Contains definitions for _L and _LAYOUT temp-tables to support alternate layouts.

adeuib/multi_l.i

Support code for propagating new widget to all layout definitions (included by the “draw” modules, e.g., adeuib/_drwfill.p for fill-ins).

8. Process and Requirements

The alternate layout mechanism is not a stand-alone module; it is an integral part of the AppBuilder tool.

9. Execution Methods

The master layout is created by default whenever a procedure file is created in the AppBuilder. Alternate layouts are defined by selecting the Layout->Alternate Layout menu option on the AppBuilder main menu. This menu option is also used to select the current layout at design time. At run-time, the layout’s predefined selection expression is evaluated to determine if the layout should be applied to the interface. It is also possible to dynamically change layouts at runtime by calling the {&WINDOW-NAME}-Layouts( ) internal procedure. Refer to the AppBuilder Developer’s Guide for more details.

10. Requirements and Strategies

When testing code changes to the alternate layout feature of the AppBuilder, be sure to include tests for both design-time and run-time behavior, as well as for the process of opening a file containing alternate layouts in the AppBuilder.

11. Supplementary Information

Not Applicable

12. Related Documentation

The following documents provide additional information about alternate layouts: