ESL Language Programmers Guide

ESL Programmers Guide

Creating & running ESL Applications

Configuration File

Runtime Memory Handling

Global Memory

Changing Program and Global Memory Allocations

Program Control of Memory

The freesize Function

The set low memory threshold Statement

The squeeze memory Statement

The response to low memory Response Statement

Handling Keyboard Characters

Pointing Devices

Mouse Pointer Appearance

Touchscreen Support

Using the Default Pointing Device

Using a Pointing Device

Controlling Input From a Pointing Device

Printing and Plotting

Using the plot Action Statement

OPTION_STRING Parameters

Error Messages

Fonts

Specifying a Font

Inheritance of Font Type

ESL Fonts

ESL Language Elements

The ESL Character Set

Blanks

Comments

Keywords and Identifiers

Values

Categories and Types of Values

Compile-time Values

Literals

Integer Literals

Floating Point Literals

Changing the Precision

String Literals

Using Escape Sequences in String Literals

Initializing Variables

Referencing Variables

Global, Application and Local Variables

Finding the Length of a String Variable

Assigning Values to Variables During Runtime

The copy Action Statement

The append Action Statement

The extract from Action Statement

Defining and Referencing Groups Arrays

Specifying Dimensions in an Array Definition

Specifying Elements in an Array Definition

Global Variable Arrays

Referencing Elements in Arrays

Resizing an Array

Using Structures

Creating a Structure

Defining a Structure Type

Arrays Within Structures

Nested Structures

Structure Nesting and Size

Declaring Structure Variables

Array of Structures

Referencing Fields

Passing a Structure to a Subroutine

Example

Built-in Functions

Object Inquiry Functions

Item Inquiry Functions

Action Inquiry Functions

Response Inquiry Functions

Special Inquiry Functions

Expressions, Operators, and Operands

Arithmetic Operators

Precedence in Arithmetic Operators

Relational Operators

Precedence in Relational Operators

Boolean Operators

Precedence in Boolean Operators

Type Conversions

String/Integer and String/Floating Point Conversions

Boolean/String Conversions

Boolean/Integer and Boolean/Float Conversions

Float/Integer Conversions

Integer/ Floating Point Conversions

String/Name Conversions

String/Name with Ancestry Conversions

Modules

ESL's Objects and Coordinate Systems

Types of Objects and Their Uses

The Components of an Object

Common Object Attributes

Standard ESL Color Set

Additional ESL Colors

color Keyword

Color in Regions

Specifying Color in Drawing Statements

Ancestry

Specifying Ancestry in Object References

Priority

Using Priority

Parameter

Font in Textual Regions

Coordinate Systems and Cursors

The Screen Coordinate System

Environment Declaration

Device Units

Dialog Units

Origin

The Object Coordinate System

Drawing in the Coordinate System of a Graphical Object

Drawing in the Coordinate System of a Textual Region

The Ancestor Coordinate System

The Screen as Ancestor

Windows and Viewports: The Coordinate Systems of Regions

Windows

Changing Window Position

Viewports

Effects of Ancestry in Windows and Viewports

Multiple Regions

The Graphics and Text Cursors

The Graphics Cursor

The Text Cursor

Text Cursor in Textual Regions

Redrawing an Object

Responses and Blocks, Object Action Statements, and Classes

About Responses

Overview of Responses and Their Uses

Responding to Program Startup

Responding to Objects

Response to Selection by User-Generated Input

Responses to Entry Field Validation

Responding to Action Bar Items

Using Response Inquiry Built-in Functions

Table of Response Inquiry Built-in Functions

xcoord and ycoord Functions

Leaving (Exiting) a Block

Explicitly Leaving a Block

Implicitly Leaving a Block

Responding to a Block Being Left Implicitly

Responding to Stimuli and Returning to a Specified Block

Disabling Responses Outside A Block

Responding to Specified Stimuli and Returning to a Block

Using the response to start Response Definition Within a Block

Using the response to char Response Definition in Blocks

About Action Statements

Overview of Actions and Their Uses

Specifying Action Statements

Creating, Changing, Clearing, and Deleting Objects

Creating a New Object

Adding to the Contents of an Object

Deleting the Contents and Children of an Object

Deleting the Contents of an Object Without Deleting Its Children

Replacing the Contents of an Object and Deleting Its Children

Replacing the Contents of an Object Without Deleting Its Children

Deleting an Object

Changing Attributes of Objects

Changing Selectability

Changing Visibility

Changing Color

Changing Border Attributes in Regions

Changing Ancestry

Changing Priority

Changing Parameter

Changing the Size and Position of an Object

Changing Size

Changing Position

Changing Ancestry in the change position to Statement

Using Classes of Objects

Overview

Defining a Class of Objects

Defining Responses for a Class of Objects

Specifying Actions for a Class of Objects

Adding an Object to a Class

Deleting an Object from a Class of Objects

Changing Class Membership

Using Built-in Functions with Classes

Using the object Function with a Class

Using the ancestry and object Functions Together

parameter Function

Using the parameter and object Functions Together

Using the members Function with a Class

Graphical Objects, Image Regions, and Sense Regions

Defining Graphical Objects

Defining Keys

Creating New Identifiers for Objects

Specifying Position in the Object Definition

Color in Keys

Defining a Graphical Region

Defining the Size and Position of a Graphical Region

Ancestry in Graphical Regions

Color in Graphical Regions

Drawing Statements for Graphical Objects

Overview

Placement of Drawing Statements

Colored and/or Solid Box

Colored and/or Solid Ellipse

Drawing a Wedge

Colored and/or Solid Wedge

Limitations in Drawing Wedges

Drawing Shapes

Boundaries in Shapes

Graphics Cursor in Shapes

Drawing an Arc of Specified Degrees

Drawing an Arc to a Specified Endpoint

Defining and Referencing Patterns

Referencing a Pattern

Reference Point of a Pattern

Coordinates of a Pattern

Accumulation of Scaled and Rotated Patterns

Displaying Text in Graphical Objects

Displaying Text in a Graphical Region

Centering Text

Font/Color of Text

Action Statements for Changing Windows and Viewports in Graphical Regions

Introduction

Changing the Viewport Size

Changing the Viewport Position

Changing the Window Size

Changing the Window Position

Using Built-in Functions with Graphical Objects

Introduction

Using Functions to Inquire about Size and Position

top of, bottom of, left of, and right of Functions

xmiddle of and ymiddle of Functions

xcursor of and ycursor of Functions

xposition and yposition Functions

xsize of and ysize of Functions

window xsize of and window ysize of Functions

window xposition of and window yposition of Functions

Using Functions to Inquire about Attributes

ancestry of Function

background of and foreground of Functions

border of Function

exists Function

handle of Function

parameter of Function

priority of Function

selectability of Function

visibility of Function

Image Regions

Supported Image File Formats

Vector vs. File Images

Foreground and Background Colors

Cache Specifications

Scaling

sample

preserve foreground / background

no scale

Specifying File Contents

Specifying an Image Map

Specifying Image Maps in Image Regions

Read Statements

Defining Sense Regions

Visibility Attribute

Priority Attribute

xcoord and ycoord Built-in Function

Windows Frame Attributes

Textual Regions

Defining and Using Textual Regions

Extra Action Statements

Defining the Size of the Window and Viewport

Defining and Using a Colored Textual Region

Drawing Statements for Textual Regions

Where to Place Textual Region Drawing Statements

Addressing a Character

Moving the Text Cursor

Defining Text Segments and Text Blocks

Defining a Text Segment

Defining a Text Block

Inserting Text

Inserting a Text String

Using Escape Sequences in Inserted Strings

Inserting a Text Segment

Inserting a Text Block

Inserting an ASCII Text File or Color-attributed File

Using the ioerror Function

Overwriting Text

Overwriting with Text Strings

Overwriting with Escape Sequences

Overwriting with Text Segments

Overwriting with Text Blocks

Overwriting Text Blocks with Blanks

Response Definitions for Textual Regions

Action Statements for Textual Regions

Adding Drawing Statements to a Textual Region

Removing Text

Controlling Text Emphasis

Changing the Visibility of the Text Cursor

Writing a Textual Region to a File

Using the ioerror Built-in Function

Creating a New File

Appending to a File

Replacing the Contents of a File

Writing to a Color-attributed File

Reading a File into a Textual Region

Using the ioerror Function

Reading an ASCII Text File into a Textual Region

Reading a Color-attributed File into a Textual Region

Using Escape Sequences in Files

Finding a String of Text in a Textual Region

Changing the Size and Position of a Textual Region's Window and Viewport

Changing the Viewport Size

Changing the Viewport Position

Changing the Window Size

Changing the Window Position

Using Built-in Functions with Textual Regions

Using the textual Object Inquiry Built-in Functions

textual line Function

textual segment Function

textual block Function

Extracting Text from a Textual Region

Using the column size of Object Inquiry Built-in Function

Using the line size of Object Inquiry

Using the foreground at and background at Object Inquiry Built-in Functions

Using the found Action Inquiry Built-in Function

Sample Programs Using Textual Regions

Sample 1

Sample 2

Working with Colored Textual Regions

Defining a Colored Textual Region

Ways to Color Text

Coloring Text that Already Exists in the Program

Specifying Colors for a Text Segment

Specifying Colors for a Text Block

Region Attributes and Action Bars

Region Attributes

Using the Border Attribute

Using the Title Bar Attribute

Using the Minimize Attribute

Using the Maximize Attribute

Using the System Menu Attribute

Using the Scroll Attributes

Using the No Scale Attribute

Using the Pointer Attribute

Using the Action Bar Attribute

Creating Action Bars

Defining an Action Bar Template

Defining Global Items

Accelerator Keys

Mnemonics

Item Parameters

An Example Action Bar Template

Manipulating Action Bars

Adding Action Bars at Runtime

Changing a Region's Action Bar

Deleting a Region's Action Bar

Manipulating Action Bar Items

Naming Items

Item Classes

Manipulating Item Classes

Checking and Unchecking Items

Enabling and Disabling Items

Changing the Text of an Item

Adding Item Templates at Runtime

Adding Items to Action Bars

Adding Items to Pull-downs

Deleting Items from Regions

Responding to Action Bar Items

Built-in Functions

Built-in Functions in Inquiries

Built-in Functions in Responses

Dialog Boxes, Dialog Regions, and Controls

Dialog Boxes

Actions for Dialog Boxes

Keyboard Use in Dialog Boxes

Example of a Dialog Box

Built-in Functions for Dialog Boxes and Controls

Dialog Regions

Actions for Dialog Regions

Built-in Functions for Dialog Regions

Dialog Control Objects

Groups

Mnemonics

Single-Line Entry Fields

Actions for Entry Fields

Entry Field Responses

Multi-line Entry Fields

Actions for Multi-line Entry Fields

Multi-line Entry Field Responses

List Boxes

Actions for List Boxes

Built-in Functions for List Boxes

List Box Responses

Combination Boxes

Actions for Combination Boxes

Built-in Functions for Combination Boxes

Drop-down Lists

Actions for Drop-down Lists

Built-in Functions for Drop-down Lists

Pushbuttons

Actions for Pushbuttons

Pushbutton Responses

Radio Buttons

Actions for Radio Buttons

Built-in Functions for Radio Buttons

Radio Button Responses

Check Boxes

Actions for Check Boxes

Built-in Function for Check Boxes

Check Box Responses

Static Text

Actions for Static Text Objects

Group Boxes

Actions for Group Boxes

Actions for Spin Buttons

Slider Responses

Sample Code

Program Flow and Performance

Controlling Program Flow

Declaring External Subroutines and Functions

ESL Action Routines and Internal Subroutines

Defining an Action Routine

Example

Special Characteristics of Action Routines

Declaring an ESL Subroutine

Defining an ESL Subroutine

Differences Between ESL Subroutines and Action Routines

The include Statement

Nested Include Files

Exiting the Program

Transferring to Another Program

Saving a Program in Progress

Global and Application Entities

Variables

Global Variables in Changed Programs

Global and Application Variables in Saved Programs

Applications

Devices

Memory

invoke Action Statement

Controlling Flow Within A Program

Referencing an Action Routine

Specifying a Conditional Action Statement

Nesting Conditional Action Statements

Specifying a call Action Statement

Specifying a for or while loop

Nested Loops

for each member loop Action Statement

Accessing the Current Class Element

for each child loop Action Statement

Accessing the Current Child Object

for each select line loop Action Statement

Accessing the Current Selected Line

for each select row/column loop Action Statement

Accessing the Current Selected Row or Column

Response Statements for Specified Time

Responding to Elapsed Time

Responding to Elapsed Time During Which no Stimulus is Received

Action Statements to Suspend Processing

Waiting for a Specified Number of Seconds

Using wait 0

Monitoring Program Execution

Using the Errorlog File

Action Statements and Environment Declarations for Debugging

Tracing Action Statements for Portions of an ESL Program

Sending Values to the Errorlog

Using Data in External Formats

Reading and Writing Fields

Passing Structures to External Routines

Converting External Data

Conversion Routines

Default Conversions for C Data

Specifying an External Conversion Routine

External Routines and Stimulus Libraries

Writing External Functions and Subroutines

Declaring Subroutines and Functions in ESL

Calling Conventions

Function Arguments and Return Values

Keyword reference

Keyword small

Subroutine Arguments and Return Values

Built-in Function errorlevel

Compiling and Linking C DLLs for ESL

Compiling and Linking for ESL

Exchanging Structures with External Routines

Manipulating Fields in an External Subroutine or Function

Strings

Pointers to Structures for Calling CICS

Writing Your Own Conversion Routines

Coding Suggestion

How a Conversion Routine is Called

C Conversion Routine Protocol

Unsuccessful Conversions

Sample External Conversion Routine in C

Stimulus Libraries

Declaring a Stimulus

Defining a Stimulus Response

EslEvent

Response Inquiry Functions

Copying the Window Handle

Writing a Stimulus Library for ESL for Windows

Using the Extended Call Interface

Debugging

Calls to the Windows operating system

Standard File Dialogs

Keyboard Modifier Key Queries

Mouse Queries

Entry Field Selections

Edit menu operations

Coordinate conversions

Miscellaneous OS functions

Library Subroutines and Functions

Overview

Library Subroutines

Library Functions

ESL Library Functions and Subroutines

Subroutines

Functions

The Date Library Functions

The Help Library Subroutines

The Math Library Functions and Subroutines

The File I/O Library Subroutines

Overview

The record Definition

Filler

Variable Name

Array Variable Reference

Record

Example 1

Example 2

OpenFile( ) and CloseFile( ) Subroutines

Parameter Adjustment Subroutines

Error Handling Subroutine

File Information Subroutine

The Message Library Functions

String Library Functions and Subroutines

Entering/Editing Cell Text

Mouse Operations

Creating and Manipulating Table Objects

Use of Table References

Response Inquiry Built-in Functions

Object Inquiry Built-in Functions

Adding Double-Click Behavior

Sequence of Events in a Drag Operation

Drag and Drop Support in ESL

Designing A Drag and Drop Interface

Source and Target Objects

Device Objects

Template Objects

Application Objects

Drag Types and Drag Data

Dragtype Strings

Dragdata Strings

Writing Drag and Drop Code

Source Object Responses

on drag Response

Target Object Responses

Dragging Between Two ESL Applications

Example

Appendix A ESL Business Graphics

Introduction

Creating a Graph

Required Procedures

Table A-1 Action Routines for Each Graph Type

Specifying Data Elements for a Graph

Elements in a Graph

Specifying the Decimal Point Character

Rules and Variables for Certain Graph Types

Width and Height of Region

Remarks for GxTitle and GyTitle

Axis Boundaries

Remarks for GAutoScaleX and GAutoScaleY

GTopY, GBottomY, GTopX, and GBottomX

Tick and Pie Wedge Labels

Remarks for GLabels

Remarks for GXTickIncrement and GYTickIncrement

Pie Wedge Starting Point

Remarks for GMarkerLineWidth

Example:

Superimposing Two Graphs

GMovables: Moving Text in a Graph

Sample Program Using the Graph Module

Summary of BGraph Module Variables

Public File of the BGraph Module

Appendix B Additional Modules

The CText Module

The Date Module

The Property Sheet Module

The Status Line Module

The Tool Bar Module

The Validate Module