CREATE SCREEN

From Recital Documentation Wiki
Jump to: navigation, search

Purpose

Activate the Forms Designer


Syntax

CREATE SCREEN <filename> | (<expC>)


See Also

@...GET, @...GET - Check Boxes, @...GET - Radio Buttons, @...MENU, @...SAY, @...TO, APPEND, CHANGE, DEFINE TABLE, DISPLAY MEMORY, DISPLAY STATUS, DISPLAY STRUCTURE, EDIT, FMT(), Function Keys, INSERT, MODIFY SCREEN, QUERY, SET COLOR, SET COLOR OF, SET DESCRIPTIONS, SET FORMAT, SET POSTMENU, SET POSTFORM, SET POSTRECORD, SET PREMENU, SET PREFORM, SET PRERECORD


Description

The WYSIWYG Forms Designer is used to design the layout of forms, allowing you to create custom forms which can be used instead of the default forms with the following Recital/4GL screen form commands:

  • APPEND
  • EDIT
  • CHANGE
  • INSERT
  • QUERY

The file name can be substituted with any character expression, enclosed in round brackets, which returns a valid filename. If no file extension is specified, then '.scr' is used.

The Forms Designer work surface can be navigated with the cursor keys. It also has a full menu driven interface, allowing the following objects to be added to the form and configured. Each object has a corresponding Recital/4GL command that will be generated automatically by the Forms Designer when the screen form is saved.


Object Description
Text Simply type the text onto the work surface where you would like the text to appear. Text can be inserted before other text or overwrite existing text. Cut and paste facilities are also available.

The corresponding command is @...SAY.

Lines and boxes Lines (horizontal and vertical) and boxes can be added to the form using the <OPTIONS> menu item. A plus character marks the start and end of the object coordinates. Lines and boxes may be expanded and moved.

The corresponding command is @...TO.

Fields The <SELECT> and <MODIFY> menu items allow fields from multiple tables to be loaded onto the work surface. Each field inherits the attributes from the Application Data Dictionary.

The corresponding command is @…GET.

Memory Variables Memory variables can be added using the <MODIFY> menu item. The memory variables must be declared and initialized before the form is activated.

The corresponding command is @...GET.

Menus The <MODIFY> menu item provides facilities for placing menu options on the work surface and defining the commands to execute when they are selected. Pull down menus can be attached to a menu option.

The corresponding command is @...MENU.

Table fields The <TABLES> menu item is used to define multiple record child table fields. Before using this option, relevant tables, indexes, and relations must be created. The <MODIFY> menu is used to specify the source of fields contained in the Table Field.

The corresponding commands are DEFINE TABLE and @...GET.

Check boxes Check boxes are used for logical fields or memory variables. Each check box can be checked (true) or not (false). There is no interdependency between individual check boxes. In the Forms Designer, Check Boxes are defined using the <MODIFY> menu item.

The corresponding command is @...GET...BUTTON

Radio buttons Radio buttons form groups. Only one radio button can be selected from the group at a time and this selected button contains the value of a character field or memory variable. In the Forms Designer, Radio Buttons are defined using the <MODIFY> menu item.

The corresponding command is @...GET...BUTTON...GROUP


The menu bar for the Forms Designer worksurface can be activated by pressing the [MENUBAR] key. When the command MCONFIRM is set ON, the Forms Designer menu bar operates as pulldown menus. There are eight options available in the menu bar: <SETUP>, <MODIFY>, <OPTIONS>, <TRIGGERS>, <COLORS>, <TABLES>, <DICTIONARY> and <HELP>.

SETUP

The <SETUP> menu bar option displays a pop-up menu containing the following options:


Option Description
Select table Select a table for further use. Tables can be selected from the dialog menu box displayed to the right of the <Select table...> menu.
Create table Allows you to create a new table while in the Forms Designer.
Load fields Select fields to load onto the form. Fields can be selected from the dialog menu box displayed to the right of the <Load fields...> menu. The cursor keys, [PAGE UP] and [PAGE DOWN] are used to highlight each field in turn, the [RETURN] key to select the highlighted field and the [EXIT/SAVE] key to save the selections. The selected fields will be displayed on the form on consecutive rows starting at the current row/column position. The <Aspect is horizontal/vertical> menu option on the <Options> menu will change the way fields are loaded onto the form. The field name or description (SET DESCRIPTIONS ON) is displayed, and an edit region the length of the field is displayed in reverse video, one space to the right.
Quick form Select all the fields from the current table and place them onto the form.
Select next Selects the next workarea.
Current workarea Displays the name of the table open in the current workarea.
Select previous Selects the previous workarea.


MODIFY

The <MODIFY> option of the menu bar is used to add or change any of the following:-

  • Constant SAY text on the form.
  • GET fields on the form.
  • MENU options on the form.
  • Validations and triggers for GET fields on the form.
  • Check boxes and radio buttons.

When selected, <MODIFY> displays a menu. The menu items displayed depend on the current cursor position. If the cursor is currently positioned at the start of a field edit region, the menu will contain a list of field validation criteria and 'triggers'. If the cursor is positioned on a menu option, then the menu contains a list of attributes for the menu option. Otherwise, <MODIFY> displays a blank menu for a GET action. The action can also be changed to SAY, MENU, or BUTTON. You need only enter the first character to display the appropriate menu (G, S, M, or B).

The validation and triggers that can be specified for a GET action are as follows:-


Item Description
Action: Get (can be Get/Say/Menu/Button)
Source: Table alias name (or 'm' for memory variables). If an existing <source> table is not currently open, it will be opened automatically.
Content: Name of field or memory variable. Fields will be searched for in the currently selected table, and if found, the 'Type' and 'Width' fields will be filled in automatically.
Type: Data type
Width: Width of field
Decimal: Number of decimal places
Picture: Picture validation string. If @s <expN> is specified for a character field, then the field will be scrollable. The <expN> specifies the display width. The field will be scrollable up to the field width.
Range: For numeric and date fields, a range in the form <low>,<high>. This item may also be used to specify a pop-up choicelist for a character field by preceding the choicelist definition with an "@" character. Use two "@" characters to specify a "dynamic" browse menu. To specify a UDF to return a value to place in a field, precede the UDF name with an "@" character and a question mark: @?UDF()
Help: Help message to be displayed when the field has focus.
Relation: Defines this field as a key field for a related table. The alias name is specified to indicate the target of the relation. Changing the field value causes the pointer in the related table to move to that value.
Lookup: Defines a validity check using a cross-table lookup. The alias name of the lookup table must be specified. Changing the field value causes the lookup table to be scanned for the new value. If the value does not exist in the lookup table, a validation failed error message is displayed.
Validation: Any of the following validation clauses can be specified: an input validation procedure name, an @ sign followed by a boolean condition, or a validation string prefixed with a '$'.
Error: The error message to be displayed if validation fails..
Calculated: An expression that will be evaluated to provide the field's value. The field will be read only.
Recalculate: Sets a flag so that if the field value changes, all CALCULATED expressions will be reevaluated and the form will be refreshed.
Must enter: Force data to be input in this field.
Read when: Specify a boolean condition. The field will be read only unless the condition evaluates to true (.T.).
PreTrigger: Specify a procedure name for the PreField trigger. The PreField trigger procedure is called as the field is entered. Once a procedure name has been entered, pressing the [HELP] key with the cursor on the procedure name pops up a notepad to allow the procedure to be edited.
PostTrigger: Specify a procedure name for the PostField trigger. The PostField trigger procedure is called as the field is exited. Once a procedure name has been entered, pressing the [HELP] key with the cursor on the procedure name pops up a notepad to allow the procedure to be edited.


If the <Action> item is an @…SAY, this field will not be refreshed as you page up and down through the form. The command SET PCSAYS must be set ON for @...SAY to be refreshed.

When in the <MODIFY> menu, you can move between the fields on the form using the [PAGE DOWN] and the [PAGE UP] keys. When you have completed the field definition, you should commit the changes to the form by exiting from the modify menu using the [EXIT/SAVE] key. Pressing the [ABANDON] key discards the changes made to the definition, and exits the menu.

When you specify a MENU <Action>, then the following menu items will be displayed.


Item Description
Action: Menu
Item: The menu option to be displayed on the form.
Command: A list of commands to be executed when the menu is selected. Multiple commands can be specified, by separating each command with a semicolon.
Help: A help message to be displayed in the message line when the cursor is positioned on the menu option
Pulldown: A pulldown menu definition which consists of a list of pulldown options separated by commas, or @<procedure-name>. See @…MENU for details


When you specify a BUTTON <Action>, the following menu items will be requested:


Item Description
Source Table name (or 'm' for memory variables)
Content Name of field or memory variable
Name The name of the button which will be passed to the User Defined Function (UDF).
Label Enter a descriptive label for button. This will be displayed next to the button when SET DESCRIPTIONS is ON.
Group If you are creating a radio button, enter a group name. Each radio button in a list of choices must be given the same group name.
Help A help message to be displayed in the message line when the cursor moves on to this button.
Trigger The name of a trigger procedure to execute when this button is selected.


Check boxes and radio buttons are selection objects that can help end users enter data quickly and without error. Selected with the [SPACEBAR] key, check boxes and radio buttons display an asterisk (*) in their entry fields when selected. Check boxes are represented by square brackets: []. Radio buttons are represented by round brackets (). Check boxes are used when you have a list of choices from which any combination of those choices can be selected. The user can select one, all or none of these options depending on their selection needs. Each check box corresponds to an individual logical field or memory variable. Radio buttons are used when only one choice out of a group of choices may be selected at a time. Each radio button corresponds to a possible value for the same character field or memory variable.

OPTIONS

The <OPTIONS> menu contains items to add lines and boxes to the form, create or edit triggers and programs, change current settings for the Forms Designer, and access table, environment, and memory variable information.


Item Description
Box/Line Boxes and lines can be added to the form using this option. Select the option, then position the cursor to the top left corner and press [RETURN], finally, position the cursor to the lower right corner and press [RETURN] again.
Program The <Program...> menu item allows you to create or modify program files. It prompts for a filename then calls the default editor.
Descriptions are ON/OFF The <Descriptions are ON/OFF> menu item allows you to toggle between names and descriptions as your field labels. When you select this item, the setting will change from ON to OFF or vice versa.
Labels are ON/OFF Toggle field labels display on or off. Labels must be off for table fields.
Aspect is vertical/horizontal Toggle between and vertical or horizontal field loading. Horizontal field loading is required for table fields
Mconfirm is ON/OFF OFF command. When MCONFIRM is OFF, the menu bar operates as pulldown menus. When MCONFIRM is ON, menus must be selected with the [RETURN] key.
Display database structure Displays a screen containing information on the currently active table. (DISPLAY STRUCTURE)
Print database structure Prints the above information.
Display Environment Status Displays information regarding the environment. (DISPLAY STATUS).
Print environment status Prints the above information.
Display memory variables Displays a screen containing information on current memory variables. (DISPLAY MEMORY)
Print memory variables Prints the above information.


TRIGGERS

The <TRIGGERS> option allows you to specify or remove triggers for your form. Selecting the <TRIGGERS> option displays a pulldown menu of the following triggers:


Trigger Description
Preform Execute a procedure before the form is displayed
Postform Execute a procedure as the format file is exited
Prerecord Execute a procedure prior to the first @…GET
Postrecord Execute a procedure as a record is updated
PreMenu Execute a procedure before a menu is entered.
PostMenu Execute a procedure after a menu is exited.


If the [HELP] key is pressed when on a name of trigger program, the program can be edited in a popup notepad. For more information on triggers see the SET PREFORM, SET POSTFORM, SET PRERECORD, SET POSTCORD, SET PREMENU and SET POSTMENU commands.

COLORS

The <COLORS> option displays a menu for setting colors on individual @...GET, @...MENU and @...SAY objects. If the cursor is currently positioned at the start of a field edit region or menu item, then this object will be displayed, otherwise the first object from position 0,0 will be displayed. If there are no objects on the Forms Designer., the <COLORS> menu will not display. The [PAGEUP] and [PAGE DOWN] keys are used to move between all the objects on the work surface. Both the foreground and background colors can be set from this menu. The following colors may be defined:-


Color Attribute Code
BLACK N or blank
BLUE B
GREEN G
CYAN BG
BLANK X
GREY N+
RED R
MAGENTA RB
BROWN GR
YELLOW GR+
WHITE W


If the [HELP] key is pressed, then a pop-up choice list of available colors will be displayed.

TABLES

The <TABLES> option is for defining a table field. Table fields are used for browsing and updating multiple 'child' records related to a 'parent' table. Before using this option, the relevant tables, indexes and relations should be set up. The number of table fields you may define for one form is limited only by the number of available workareas and the screen space. After the <TABLES> menu option is selected, a form appears prompting for the following information:


Item Description
Table name: Enter in a unique name for the table. Names must start with a letter (a-z) or underscore and can include letters, digits and underscores. Names must be a maximum of ten characters long.
Database: Enter the alias name of the source database table. Pressing the [HELP] key will display a choice list of database tables in the current directory.
#of rows: Enter the number of rows the table will occupy.
Related field: Enter the key field for records in the child table. The table must be indexed on this field and this must be the master index order.
Related by: Enter the key expression from the parent table including the alias name and alias pointer, e.g. parent->linkfield or parent.linkfield.
Column titles: Enter in a title for each column in the table. Individual titles should be comma separated. This is optional and if used, a box will be drawn around the table.
Foreground: Used to specify the foreground color for the table. Pressing the [HELP] key will display a choice list of colors. If a color is not specified, the foreground color of FIELDS will be used.
Background: Used to specify the background color for the table. Pressing the [HELP] key will display a choice list of colors. If a color is not specified, the background color of FIELDS will be used
BoxForeground: Used to specify the foreground color of the box. Pressing the [HELP] key will display a choice list of colors. If a color is not specified, the foreground color of BOX will be used. Column titles must be specified for the box to be drawn.
BoxBackground: Used to specify the background color of the box. Pressing the [HELP] key will display a choice list of colors. If a color is not specified, the background color of BOX will be used. Column titles must be specified for the box to be drawn.
Shadow: If titles have been specified you may give the box a shadow on the right hand side and the bottom edge by specifying "Yes".
PreTrigger: Used to specify the name of a trigger procedure that will execute as the cursor enters the table field.
PostTrigger: Used to specify the name of a trigger procedure that will execute as the cursor exits the table field.


The [EXIT/SAVE] key should be used to exit the <TABLES> menu and save the definition. Pressing the [ABANDON] key will discard the definition. To define a second or further table field, press the [PAGE DOWN] key and this will redisplay a blank form.

The <Aspect is horizontal> and <Labels are OFF> options should be selected before loading fields to go into the table field, so that the fields form a horizontal row with a space between each edit region. The <source> of the @...GET fields that belong to the table field must be updated. To do this, move the cursor to the first field edit region that belongs to the table field and choose the <MODIFY> option from the menu. The alias name for each @...GET is displayed in the <Source> field. Prefix the alias name for each @...GET in the table field with the table name followed by a "!". This identifies the @...GETS as belonging to the specified table.

For example, if the table name for the table field is HW and the alias name of HARDWARE, the SOURCE field for each @...GET should read HW!HARDWARE.

Child tables that relate to a parent record on the same form must be positioned below the first accessible parent record field.

DICTIONARY

The <DICTIONARY> menu contains two options: <Display> and <Print>. The <Display> option displays the Application Data Dictionary for the currently active database in read-only mode. If there is no dictionary for the currently active, there will be no display. You may scroll through the fields by pressing the [PAGE DOWN] and [PAGE UP] keys. The data values for each field are displayed beneath the field values. The <Print> option prints the currently active Application Data Dictionary.

HELP

The <HELP> menu contains two options: <Help...> and <Keys help...>. The <Help...> option accesses the on-line Help system. The <Key help...> option displays the Function key usage chart.

The following keys are active in CREATE SCREEN:


Key Action
EXIT SAVE Save the changes and exit the Forms Designer
ABANDON Abandon changes and exit the Forms Designer
CURSOR UP Move up one line
CURSOR DOWN Move down one line
CURSOR LEFT Move one column to the left
CURSOR RIGHT Move one column to the right
HELP Display a popup key usage help page
RETURN When the cursor is positioned on the start of a field, allows repositioning of the field on the form; when positioned on a menu option, allows repositioning on the menu option; when positioning on a box or line, allows them to be dragged
DELETE CHAR Delete the character under the cursor
BACKSPACE Delete the character before the cursor
MENUBAR Activate the menu bar
^Z Move to the start of the line
^B Move to the end of the line
^T Delete from the cursor to the next word
^Y Delete the current line
^U If the cursor is positioned on an object - field, menu option, box or table field – the object will be removed from the form
^N Insert a blank line
^V Toggle between insert and overwrite mode
^K Insert a blank column from the current cursor position to the end of the form
^L Delete the column from the current cursor position to the end of the form


When the [EXIT/SAVE] key is pressed, the following three operations are performed:

The screen image is saved in a file with a ".scr" extension A screen format is generated to a file with a ".fmt" extension. The Forms Designer is exited.

The screen format file can be viewed or edited using a text editor. Care must be taken, however if changes are made to the format file. These changes will not be reflected in the <.scr filename> and any subsequent use of the MODIFY SCREEN command will use the original '.scr' file not the updated '.fmt' file.


Example

create screen myform


Products

Recital