app builder object speak

8/14/2019 App Builder Object Speak

1/166

BluePhoenix AppBuilder 2.1 .0.

ObjectSpeak Reference Guide
http://www.bluephoenixsolutions.com/


2/166

BluePhoenix AppBuilder 2.1.0.ObjectSpeak Reference GuideApril, 2003

Corporate HeadquartersBluePhoenix Solutions

Vlierwerf 7B4704 SB RoosendaalThe Netherlands+31 (0) 165 399 401+31 (0) 165 396 308 fax

USA HeadquartersBluePhoenix Solutions USA, Inc.8000 Regency ParkwayCary, NC 27511United States+1 919.380.5100+1 919.380.5111 fax

www.bluephoenixsolutions.com

1992-2003 BluePhoenix Solutions

All rights reserved.

BluePhoenix is a trademark of BluePhoenix Solutions. All other product and company namesmentioned herein are for identification purposes only and are the property of, and may be trademarksof, their respective owners.

Portions of this product may be covered by U.S. Patent Numbers 5,495,222 and 5,495,610 and various

other non-U.S. patents.

The software supplied with this document is the property of BluePhoenix Solutions, and is furnishedunder a license agreement. Neither the software nor this document may be copied or transferred by anymeans, electronic or mechanical, except as provided in the licensing agreement.

BluePhoenix Solutions has made every effort to ensure that the information contained in this documentis accurate; however, there are no representations or warranties regarding this information, includingwarranties of merchantability or fitness for a particular purpose. BluePhoenix Solutions assumes noresponsibi li ty for errors or omissions that may occur in this document. The information in thisdocument is subject to change without prior notice and does not represent a commitment byBluePhoenix Solutions or its representatives.
http://www.bluephoenixsolutions.com/http://www.bluephoenixsolutions.com/


3/166

AppBuilder 2.1.0 ObjectSpeak Reference Guide i

TABLE OF

CONTENTS

Table of Contents

AppBuilder 2.1.0 ObjectSpeak Reference Guide

1 ObjectSpeak Int roduct ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Managing Objects with ObjectSpeak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Understanding Dot Notation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Accessing Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Using Pre-Defined Objects versus Dynamic Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Calling Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Responding to Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

2 Java User-Interface Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Comprehensive List of Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Abstract Class Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2GuiObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10Basic Control Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13

CheckBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15ComboBox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17EditField. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21Ellipse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24GroupBox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26ListBox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30MenuBar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31

MenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32MultiLineEdit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-34FileEditor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-36PasswordField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37PushButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37RadioButton. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-40Rectangle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-42Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-42


4/166

ii Table of Contents AppBuilder 2.1.0 ObjectSpeak Reference Guide

Smooth Scrolling in a Table Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-47

Incremental Smooth Scrolling with setMoreRows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-48

Incremental Smooth Scroll ing with Dynamic Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-54

Dynamic-Only Control Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-58MessageBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-58

PopupMenu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-61Timer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-63

Supporting Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-65Accelerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-66Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-67Constants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-68Dimension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-71Font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-72Formats (Derived) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-73GlobalEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-74Locale. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-75Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-76

SetItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-78Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-79

3 Java User-Interface Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

User Interface Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Activate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2CellFocusGained. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2CellFocusLost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3ChildRuleEnd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6CommError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Converse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8DataRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9DoubleClick. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12EnterKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13FieldError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13FieldValidation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14FocusGained. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16FocusLost. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16HeaderClick. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17MessageBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18ParentRuleEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18Post. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19

RowFocusGained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20RowFocusLost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20RuleEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22Terminate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22SQLError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22Timer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23WindowError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23


5/166

Table of Contents iii

Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24Terminate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25WindowValidation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25

Data Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26Field-level Validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26Window-level Validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29

4 Java User-Interface Propert ies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

User-Interface Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Valid Edit Mask Characters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13

A Summary of Java Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1

Java Support for Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1

Java Support for Propert ies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-2

Java Support for Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-5

B Supported Methods for Java Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-1

Suppor ted Java Classes and Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-1

C Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .C-1

Check Box Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .C-1

Index


6/166

iv Table of Contents AppBuilder 2.1.0 ObjectSpeak Reference Guide


7/166

AppBuilder 2.1.0 ObjectSpeak Reference Guide 1-1

CHAPTER

1

OBJECTSPEAK INTRODUCTION


AppBuilder provides a way to interact with properties of objects and methods at execution time usingextensions to the Rules Language and the application run-time system collectively called ObjectSpeak.ObjectSpeak uses an object-based Rules Language syntax to manage entities that appear within the run-time windows as objects. Rules coding for applications is simplified using ObjectSpeak becauseObjectSpeak does not require component calls or changes to the hierarchy.

M anaging Objects w ith ObjectSpeak

ObjectSpeak functions use more compact Rules Language syntax and minimize overall impact on thesize and complexity of the application hierarchy. With ObjectSpeak, Rules Language takes a modern,object-based approach to window objects, such as edit fields, push buttons, and check boxes.

Features of ObjectSpeak include:

Prerequisites

General Syntax

Object properties can be set during the design phase in Window Painter using the information in theRules Language Reference Gui deand theDevelopment Tools Reference Guide. Understanding objectpropert ies helps you to manipulate these properties at execution t ime using ObjectSpeak. After you haveunderstood the prerequisites and reviewed the syntax, you can review detailed information about theevents that are triggered by the objects and how to respond to them in the following sections:

Java User-Interface Objects

Java User-Interface Events

Java User-Interface Properties

Prerequisites

This guide assumes familiari ty with developing applications using AppBuilder and installation of theAppBuilder product using the Installati on Guide for Windows. Prerequisites include basic application

Note Portions of ObjectSpeak functionality are also available using standard system components provided byAppBuilder to perform standard functions. For more information, refer to the System Components

Reference Guide.


8/166

1-2 ObjectSpeak Introduction

General Syntax

development experience and familiarity with Microsoft Windows NT/2000 operating system andgeneral familiari ty with the concepts of distr ibuted applications.

This guide is a companion to the Rules Language Reference Guideand assumes that you have thatinformation available as it documents extensions for Java to the Rules Language for supportedObjectSpeak entities.

For more information about the concepts and overall process of developing applications, refer to thedocuments listed in Table1-1.

Terminology

ObjectSpeak uses some terminology that, though it differs from terms used in Window Painter, is morein keeping with current standard terminology. The fol lowing table explains the correspondence betweenthese terms.

General Syntax

Using the general syntax of ObjectSpeak involves:

Understanding Dot Notation

Accessing Properties

Using Pre-Defined Objects versus Dynamic Objects

Calling Methods

Responding to Events

Table 1-1 Documentation Set

Documentation Title Topics

Product Concepts Guide An overview of the AppBuilder features and implementation.

Developing Applications Guide Detailed information on using AppBuilder to create applications.

Deploying Applications Guide Detailed information on configuring and deploying applications.

Development Tools Reference GuideDetailed descriptions of the tools used in AppBuilder to create

applications.

Workgroup Repository Administration GuideOverview and specific details on configuring and managing

repository-based development.

Rules Language Reference Guide Detailed instructions for developing applications using RulesLanguage.

AppBui lder Ob jec tSpeak AppBui lder Window Painter

Enabled not Protected

Editable not Read-only

Label Static Text

ShortHelp Status Line Help

Table Multicolumn List Box (MCLB), Spreadsheet


9/166

General Syntax


Understanding Dot Notation

The general syntax of an ObjectSpeak expression is shown in the example:

myPushButton.Visible

The name of the object is followed by a period, which is followed by the name of the property. In this

example, the name of the object, a push button, is myPushButton. The property is Visible. By looking upthe property Visible in the Chapter 4, Java User-Interface Propert ies , we find that it is a Boolean,having a value of either True (for on or visible) or False (for off or hidden).

Accessing Propert ies

ObjectSpeak allows you to manipulate the properties of user interface objects during execution. Forexample, you may want to disable or enable a menu item dynamically in response to the current state ofthe program or protect an edit field by making it non-editable.

ObjectSpeak uses a dot notation to indicate that a property or method of an object is being accessed.

The standard syntax for accessing the properties and methods of an object is:

Use the name of the object (QueryButton), followed by a period, fol lowed by the name of the property(Text).

Using Get and Set Methods

For each property, ObjectSpeak uses two common methods: Get and Set.

Getretrieves the value of the objects property and assigns a variable. This can be done simply by usingthe dot notation:

map myPushButton.Enabled to saveValue

Setassigns a value for that property to the object, as shown in the following sample:

map False to myPushButton.Visible

Alternatively, you can use:

myPushButton.Visible(False)

Example - M odifying New and Existing Properties

The following ObjectSpeak sample changes the Textproperty of the push button calledQueryButtontoQuery:

map Query to QueryButton.Text

This example assigns a newvalue to a property. The following example demonstrates how to determinethe currentvalue of a property:

if QueryButton.Text = Query

USE rule QUERY_RULE

endif


10/166


General Syntax

In this example, the value of the Textproperty of theQueryButtonobject is not being changed; it issimply being referenced to see if it is equal to the string Query.

Using Pre-Def ined Objects versus Dynamic Objects

Some window objects are pre-defined and can be referred to in the Rules Language code using theirsystem identifier (HPSID). For example, an edit field defined in the window as myEdit, can be used asfollows, without a declaration:

myEdit.text = 'Hello World'

Objects can also be declared and created dynamically, and require a declaration:

dcl

myEdit as object type EditField

enddcl

map new EditField to myEdit

myEdit.text = 'Hello Again'

When declaring these dynamic objects, avoid using the pre-defined object types, such as EditField,PushButton, Checkbox, etc., that are defined as Types in AppBuilder. Code generation generatesambiguous reference errors when it encounters these object names. If you want to use these names, referto the Rules Language Reference Guidefor an explanation of how to use aliases to redefine object names.

Calling Methods

Methods are functions or procedures that can be called on an object that tell the object to perform aspecific task.

For each of the properties common to window objects you set the value of that property by using theSet prefix before the name of the property. For a list of common properties, refer to Chapter 4, JavaUser-Interface Propert ies.

Parameters in Methods

The general syntax for a Java object method is as follows:

Method parameters appear in parentheses fol lowing the method name. If there are no parameters,empty parentheses are shown.

Within the parentheses, the parameter name is given fi rst, followed by a colon, then the type.

Mul tiple parameters are separated by commas.

If a method has a return value, the closing parenthesis of the parameters is fol lowed by a colon,which is followed by the return value type.

Note For HTML, adding an object to the window dynamically is notsupported.


11/166

General Syntax


In most cases, to dynamically create an object, you usenew ObjectName. For such objects, themethod for creating the object is not shown.

Some objects (such as Color) require parameters to create a new instance. For these objects, themethod for creating the instance is shown. The method name is the same as the object name, andthe required parameters are indicated.

Examples - Show and Set M ethods

Using the Show M ethod

In this example, the Java client contains an object namedMessageBoxthat displays a message on thescreen. TheMessageBoxobject has a method named Showthat causes the message box to appear onthe screen.

dcl

MyMessageBox object type MessageBox;

enddcl

map new MessageBox to MyMessageBox

map 'Invalid Data' to MyMessageBox.Title

map 'The amount in the Interest field is too large'to MyMessageBox.Message

MyMessageBox.Show

This example:

1. Creates aMessageBoxobject and maps it to the local variable MyMessageBox.

2. Assigns the desired title and message str ings to theTitleandMessageproperties.

3. Calls theShowmethod to display the message box.

Using the Set MethodA Set method is used to assign values to properties. For example, consider the following codesamplesthat accomplish the same result:

This line assigns (maps) a value directly to theTextproperty of the push button.

map Query to QueryButton.Text

This line calls the setTextset method of the push but ton, passing the new text as a parameter. In thisexample,setText( )is the set method for the Textproperty.

QueryButton.SetText(Query)

Set methods take exactly one parameter, whose type is the same as that of the property. By convention,the name of a property set method is simply the property name prefixed by Set. For example, a stringproperty named Texthas a set method named setTextwhich takes a string parameter. Likewise, aBoolean property named AutoSelecthas a set method named setAutoSelect() which takesone boolean parameter, as the following code illustrates:

NameField.SetAutoSelect(True)

Although both methods (set property and map statement) can be used to change the value of aproperty, the set method provides a slightly more compact notation.

Note In an actual AppBuilder application, this code would be located in the body of a procedure.


12/166


General Syntax

Responding to Events

In AppBuilder, rules that display windows are completely event-driven. That is, by clicking the mousebutton or selecting a menu item a window is displayed. These events are sent to the rule, where they areoptionally handled by special procedures called event procedures. Event procedures are defined withinthe rule itself using a special syntax and contain the logic that is needed to respond to the event. Eventsand event procedures play a central role in event-driven programming. In fact, writing event-drivenprograms is largely a process of determining which events you need to respond to and writing eventprocedures that provide the appropriate responses.

The following are some of the actions that generate events:

Opening the window

Closing the window

Clicking a push button, radio button, or checkbox

Selecting a menu item

Shifting focus to a user interface object, such as an edit field

Shift ing focus away from a user interface object Double-clicking on an object with the mouse

Entering erroneous data into an error field

Trying to close the window when one or more fields contain erroneous data

It is not necessary to provide an event handler for every event that may be generated. If the program isrequired to respond to the event, an event procedure must be defined and the code that responds to theevent must be placed wi thin the procedure.

Example - Closing a Window Using an Event Procedure

If a window contains a push button named CloseButtonthat is used to close the window when

clicked, the required event procedure is:

proc for Click object CloseButton

( e object type ClickEvent )

MAIN_WINDOW.Terminate

endproc

This event procedure responds to the Clickevent by calling theTerminatemethod on the window,causing the window to close.


13/166


CHAPTER

2

JAVA USER-INTERFACE OBJECTS


User-interface objects are used to build windows for client applications on the Java platform. Thissection discusses all the available objects and the properties, methods, and events for ObjectSpeakobjects. For each object described in this section, an overview is provided followed by lists of theproperties, methods, and events for that object. Detailed information about the properties that arecommon to many of these objects is summarized in Appendix 4, Java User-Interface Properties.

The objects are organized into these categories:

Abstract Class Objects

Basic Control Objects

Dynamic-Only Control Objects

Support ing Objects

The first category includes the high-level user interface objects, including Rule and Window. The secondcategory includes the basic building blocks of any window user interface, from check box to edit field.The third category includes the functional objects that can only be generated dynamically, such as thepop-up menu. The fourth category consists of support objects, such as colors and fonts, that support theother user interface building blocks.

Comprehensive List of Objects

Table2-1lists the user interface objects available in ObjectSpeak.

Note For information on how to create these objects using the Window Painter, refer to the Window Painter tooltopic in the Development Tools Reference Guide.

Table 2-1 ObjectSpeak Objects

Accelerator Ellipse Locale PopupMenu

CheckBox Font Menu PushButton

Color Format MenuBar RadioButton

Column GlobalEvent MenuItem Rectangle

ComboBox GroupBox MessageBox Rule

Constants GuiObject MultiLineEdit Table

Dimension Label PasswordField Timer

EditField ListBox Point Supporting Objects


14/166

2-2 J ava User-Interface Objects


These are also categorized as:



Dynamic-Only Control Objects

Support ing Objects


The Abstract Class (high-level) user interface objects available in ObjectSpeak are:

Format

GuiObject

Rule

Window

Format

TheFormatobject specifies the information needed to format text for display in various types of fields.A Formatobject is used for edit fields, combo boxes, list boxes, and table columns, where it is specified.

When a GUI object, such as an edit field, is created during the design phase in Window Painter, itautomatically creates the Formatobject and generates the code to callsetFormat()on the GUIobject. The Formatobject used by a user interface object can be obtained by viewing its Formatproperty.

DisplayMaskspecifies the mask that is used when the field does not have focus. Focus indicates thatthe object is active. For backwards compatibility, the DisplayPictureproperty is also included; it isequivalent to DisplayMask. EditMaskspecifies the mask that is used to format the text when thefield has focus.

For detailed information on display and edit masks, refer to the Developing Applications Guide.


15/166



Properties and Methods

Table2-2lists the properties and methods for this object.

Example - M odifying the D isplay M ask

The following code sample shows how you can use ObjectSpeak in the rules code to modify the displaymask used by an edit field named BirthDateField:

map 'dd/mm/yyyy' to BirthDateField.Format.DisplayMask

The following example copies the format used by one field to another field:

map BirthDateField.Format to HireDateField.Format

GuiObject

A GuiObjectobject is a generic type used to display any interface object. Many events provide areference to the object that triggered the event. This reference is specified in theSource:GuiObjectproperty of the event, as illustrated in Example - GuiObject.The type of Source is GuiObject.

Being a generic type,GuiObjectprovides propert ies and methods common to many interface objectsbut does not contain all the propert ies and methods available for the objects. Some of the properties andmethods defined in GuiObjectare not implemented on the actual object represented byGuiObject. For example, when GuiObjectrepresents a menu item, calling the Size:Dimensionproperty has no effect, since you cannot specify the size of a menu item.

GuiObjectcannot be used to access object properties other than those listed in Table2-3. Thus, whilea GuiObject may refer to an object that is a push button, you cannot access properties of the push buttonother than those listed.

BecauseGuiObjectis a generic type that represents any GUI object, it can be used to disable an editfield or any other user interface object when it is clicked.


Table2-3lists the properties and methods for GuiObject:

Table 2-2 Format Object Properties and Methods

Property:Type (Get Method) Set Method

DisplayMask:String setDisplayMask(String)

DisplayPicture:String setDisplayPicture(String)

EditMask:String setEditMask(String)

Type:Integer

Addi tional Get Method Addi tional Set Method

getDisplayString(DataObject):String

getEditString(DataObject):String


16/166



Additional Action Methods

GuiObjectsupports methods related to focus. ThehasFocus()method is used to determine if theobject currently has focus. (It is recommended that you use the Focus property instead of hasFocus()method). ThesetFocus()method is used to request that focus be set to the object.

Example - GuiObject

In the following example, an application has a Query button and an editf ield in the window with hpsid,MyEdit must be disabled temporarily when it is pressed. Use the following event procedure:

proc QueryButtonClick for Click object QueryButton

( e object type ClickEvent )

// find the EditField MyEdit, and disable it(the findGuiObject

// function returns a GuiObject)

thisRule.findGuiObject("MyEdit").setEnabled(false)

endproc

Thin-Client Support

The following properties are notsupported in thin-client applications:

Font:Font

Location:Point

Size:Dimension

Focus

shortHelp

Table 2-3 GuiObject Object Properties and Methods


Background:Color setBackground(Color)

Enabled:Boolean setEnabled(Boolean)

Focus:Boolean setFocus()

Font:Font setFont(Font)

Foreground:Color setForeground(Color)

HpsID:String setHpsID(String)

Location:Point setLocation(Point)

ShortHelp:String setShortHelp(String)

Size:Dimension setSize(Dimension)

Type:Integer(Read only)a

a. New in Appbuilder 2.1.

Visible:Boolean setVisible(Boolean)


17/166



Rule

The Rule object plays a central role in the AppBuilder Java client since it provides an object interface toAppBuilder Rules Language rules. The Rule object has no properties but does define a number ofmethods to initiate actions, obtain information, and implement events.

Rule Methods

Table2-4lists the methods for the Rule object.

findGuiObject( SystemID:String ):GuiObject

ThefindGuiObject()method searches for an object with the given system identifier (HPSID) onthe active window. The active window is the non-detached window most recently opened by a rule or itsparents. The reference to the object is returned in the form of a GuiObject, so it can be directlymanipulated using the methods defined in GuiObject. If there is no active window, this methodreturns a null reference. In order to test for this returned "null reference, use the isClearfunction.

Table 2-4 Rule Object Methods

Methods

findGuiObject( SystemID:String ):GuiObject

findGuiObject( SystemID:String,type:Integer):GuiObject

getActiveWindow( ):Window

getInputView( ):View

getOutputView( ):View

getWindow( ):Window

postToChild(InstanceName:String, EventName:String):Boolean

postToChild(InstanceName:String, EventName:String, ViewName:View):Boolean

postToChild(InstanceName:String, EventName:String, ViewName:View, Parameter:String):Boolean

postToParent(EventName:String):Boolean

postToParent(EventName:String, ViewName:View):Boolean

postToParent(EventName:String, ViewName:View, Parameter:String):Boolean

postTo(aRule:rule, EventName:String)

postTo(aRule:rule, EventName:String, aView:View))

postTo(aRule:rule, EventName:String, aView:View, Parameter:String)

queryUserAuthentication( ):Boolean

setShortHelpFile(HelpFileName:String):Boolean

setUserAuthentication(userID:String, password:String)

showHelpTopic( HelpID:String):Boolean

terminate( )

trace(message:String)

For Thin Client Only:

addCookie( )

getCookie(name:string)

getCookie(aView:View)

setCookie( )


18/166



For example:

dcl

aEditField object type EditField;

enddcl

map thisrule.findGuiObject('OBJECT_HPSID') to aEditField

if isClear(aEditField)

*> error scenario


19/166



getWindow ( ):Window

ThegetWindow()method returns an object reference to the any window displayed by the rule. Thereference is returned in the form of a Windowobject. If the rule does not display a window, this methodreturns a null reference. In order to test for this returned null reference, use the isClearfunction.

postToChild(InstanceN ame:String, EventNam e:String):Boolean

postToChild(InstanceName:String, EventName:String,ViewName:View):Boolean

postToChild(InstanceName:String, EventName:String, ViewName:View,

Parameter:String):Boolean

postToParent(EventName:String):Boolean

postToParent(EventName:String, ViewName:View):Boolean

postToParent(EventName:String, ViewName:View, Parameter:String):Boolean

postTo(aRule:rule, EventNam e:String)

postTo(aRule:rule, EventName:String, aView:View)

postTo(aRule:rule, EventName:String, aView:View, Parameter:String)

These methods allow you to send a view to a given window. The postTo()method will send an event,event and view, or event, view and a parameter string to itself. (The first parameter of a Rule must be

thisRule or the longname of the rule posting event). The postToParent()method sends thespecified view to the parent window. The postToChild()method posts the specified view to thechild with the specified instance name.

queryUserAuthentication( ):Boolean

ThequeryAuthentication():Booleanmethod queries for the name of the user and verifiespermissions.

setShortHelpFile(HelpFileName:String):Boolean

ThesetHelpFile()method specifies the name of Java help file that contains the help informationfor this rules window. This help file also is used by windows displayed by all descendent rules of thisrule, unless those rules specify their own help files.

setUserAuthentication(userID:String, password:String)

ThesetUserAuthentication()method allows you to set the user credentials to authenticate theremote server rules. The same method gets invoked if QUERY_AUTHENTICATION_ON_STARTUP is

Note setHelpFile()is notsupported in thin-client.


20/166



enabled through the sett ing in the APPBUILDER.INI fi le. This information can be overr idden by theAppBuilder communication exits when a remote rule is invoked.

showHelpTopic( HelpID:String):Boolean

TheshowHelpTopic()method displays the help topic specified by the help ID from the windowshelp file. As noted above, if this window has not specified a help file, it uses the help file of its parent rule.For windows, the help ID must be the long name of the window. For user interface objects placed on thewindow, the ID must be the window long name, followed by a dot, followed by the system identifier(HPSID) of the object.

terminate( )

Theterminate()method stops the event.

trace(message:String)

Thetrace(message:String)method traces the message.

Cookies:Thin Client Only

TheRuleobject supports these additional methods for thin client only:

addCookie( )


setCookie( )


addCookie( )

TheaddCookie()method allows any valid cookie name as a name (as opposed to the old setCookiewhich allows only the system FIELD names as names of the cookie). With this method, you can have acookie like "Company.Dept.Developer" as a name with dots, etc., as part of the name. The value is anyvalid string value and the age is the expiry time of the cookie in milliseconds.


ThegetCookie(name:String)method returns the data associated with the given cookie name.

setCookie( )

ThesetCookie()can be used to create client-side HTTP cookie with the names of fields in the viewand values of the fields making up the name-value pair elements of the cookie. The age sets up the expirytime in seconds. As the HTTP cookie does not support hierarchical data structures, this method usesonly FIELDs directly under the given View; all nested views are ignored.


ThegetCookie(aView:View)retrieves cookie data sent to the web client and is saved on the webclient environment for the specified time until expir ing. Subsequent requests from this client

Note showHelpTopic() is notsupported in thin-client.


21/166



environment receive the cookie data and the AppBuilder rule invokesgetCookie(aView:View)toretr ieve the data. The cookie data with names matching the FIELD names of this view are read into theview. For example:

AB_WEBCLIENT_RULE.setCookie(AB_WEBCLIENT_VIEW, 3600 )

whereAB_WEBCLIENT_RULEis the name of the rule,AB_WEBCLIENT_VIEWis the view containing

the set of fields to be used as cookie names and values, and 3600is the expiry time of the cookies inseconds.

AB_WEBCLIENT_RULE.getCookie(AB_WEBCLIENT_VIEW )

where AB_WEBCLIENT_RULE is the name of the rule and AB_WEBCLIENT_VIEW is the viewcontaining the set of fields to be filled with data if the field names match the cookie names.

Events

The following events can be triggered using theRuleobject:

Activate

ChildRuleEnd

CommError

Converse

Initialize

ParentRuleEnd

Post

RuleEnd

Terminate

SQLError

TheChildRuleEndevent is triggered when a child rule of the current rule has terminated. TheRuleEndevent is triggered when another rule, for which the current rule has registered an eventprocedure, terminates.

The rule that ends must be a detached rule that was started using the command:

use rule detach

where is the name of the local variable (defined in the dclsection) whichreferences the rule.

TheConverseevent on the rule is the same as the Converseevent on the window; only one event

needs to be registered, either the rule's or the window's. TheInitializeandTerminateeventsare different events but are merged with the window'sInitializeandTerminateevents in futurereleases (but only one event needs to be registered either for rule or for window). The Postevent istriggered when the rule receives a view that was posted by another rule using one of the two Postmethods described in Rule Methods.


22/166



Window

TheWindowobject plays a central role in the Java client, since it provides an object interface towindows. The Windowobject has numerous properties, defines several methods to initiate actions orobtain information, and also implements several events.

Properties and M ethods

Table2-5describes the properties and methods for theWindowobject.

Note The window panel contains the position of the window at design time, which may differ from the resolution atexecution time resulting in the location being different.

Table 2-5 Window Object Properties and Methods


Altered:Boolean setAltered(Boolean)


DefaultButton:PushButton setDefaultButton(PushButton)


FocusedGuiObject:GuiObject (read only)

HpsID:String (read only)


MenuBar:MenuBar setMenuBar(aMenuBar:MenuBar)

PopupMenu:PopupMenu setPopupMenu(PopupMenu)

Resizable:Boolean setResizable(Boolean)


Text:Stringa

a. Tthe Text property can be used to get/set the Title of the window.

setText(String)

Type:Integer(Read only)


Addi tional Get Method Addi tional Set Method

clearSelection()

getHelpTopic():String

addChild (Object)b

b. Not supported for thin client (HTML). In thin-Client, GUI objects cannot be dynamically created and added using

addChild. Please refer to the SystemComponents Guide for a description on using HPS_SET_HTML_FILE and

HPS_SET_HTML_FRAGMENT.

clearAltered( )

clearWindowChanges( )

printFrame( )c

c. Not supported for thin-client(HTML).

ShowMessageBox(messageType:Integer,

message:String):Integer

ShowMessageBox(message:String, title:String,

buttonType:Integer, messageType:Integer):Integer

d

d. Not supported for thin-client(HTML).

terminate( )

updateDisplay( )e

e. Not supported for thin-client(HTML).


23/166



clearSelection()

Clears selected i tems of all listboxes and Tables(MCLB) in the window.

DefaultButton:PushButton

Specifies the default pushbutton for the window.

getHelpTopic():String

Returns HelpTopic name, if a Helpset is set.

Resizable:Boolean

TheResizeableproperty specifies whether the window can be resized by the user during execution.

In Java, if a window is resizable, the minimize and maximize buttons appear at the right of the title bar. Ifthe window is not resizable, these buttons are not available and the window cannot be minimized or

maximized.


TheaddChild()method adds a programmatically-created object to the window (either GUI Objectsor Java Beans).

Theterminate()method terminates the current window, allowing the owning rule to return.

TheupdateDisplay()method causes the visible window to immediately repaint itself. Thismethod is useful for replacing the converse nowait statement from the earl ier converse-driven versions of the product. If the window has not yet been displayed, call thesetVisible(True)method instead to display the window. The updateDisplay()method iscalled implicitly whenever theVisible:Booleanproperty is set to True.

TheshowMessageBox()method can be in either:

ShowMessageBox(message:String,title:String,buttonType:Integer,

messageType:Integer)

or

ShowMessageBox(messageType:Integer,message:String)

wheremessageis the message to show, titleis the title for the message box, buttonTypeis one ofthe following:

Constants.DEFAULT_BUTTONS

Constants.OK_BUTTON

Constants.OK_CANCEL

Constants.YES_NO

Constants.YES_NO_CANCEL

Note This property is notsupported for HTML client.


24/166



and messageTypeis one of the following:

Constants.ERROR

Constants.INFORMATION

Constants.WARNING

Constants.QUESTION

Constants.PLAIN

Events

The following events can be tr iggered by theWindowobject:

Close

Converse

EnterKey

Initialize

MessageBox*

Terminate

WindowError

WindowValidation

(*only supported by the thin-client)

The Closeevent is triggered when the user attempts to close the window using the system exit (theXinthe upper right corner of the window) or uses the system hot key (usually Alt+F4). The system doesnothing by default. If the system is to shut down, you must explicitly terminate the window. Refer to the

catalog of events (the Close Window with System Menu event, in particular) in the DevelopingApplications Guide. This event has no methods or properties.

The MessageBoxevent is triggered after the window is created but before it is shown. It is an ideal placeto initiali ze the program's data, as well as to make any needed adjustments to the visual objects on thewindow. The Terminateevent is called while the window is closing.

The WindowErrorand WindowValidationevents are called when the user attempts to close the windowwith a push button or menu item for which validation is enabled. Window validation is used to preventthe window from closing when editable fields contain invalid information, when mandatory fields areempty, and for any other condition which the application logic concludes is unacceptable.

In thin-client development, the following events arenotsupported:

Close

WindowError

WindowValidation

EnterKey

In thin-client, WindowError and WindowValidation can be done through Javascript using theextension.js, which can be customized to include any WindowError/Validation handling procedures.


25/166


26/166




Table2-7lists the properties and methods for the Checkboxobject:

DataLink:DataObject

The check box can be linked to a character field of length one (1) that contains an ' X' when the checkbox is selected, or to a Boolean field that contains True if the check box is selected.

The DataObject for a check box is Boolean or String.

Set the property as shown in the following example:

aCheckBox.setDataLink(field of View of View)


TheDataLinkobject has methods related to focus. The hasFocus()method is used to determine ifthe object currently has focus. The setFocus()method is used to request that focus be set to theobject.

Table 2-7 Checkbox Object Properties and Methods





DataLink:DataObject setDataLink(DataObject)





ImmediateReturn:Boolean setImmediateReturn(Boolean)


Mnemonic:Char setMnemonic(Char)

MnemonicKeycode:Integer setMnemonicKeycode(Integer)


Selected:Boolean setSelected(Boolean)



TabStop:Boolean setTabStop(Boolean)

Text:String setText(String)




27/166



Events

The fol lowing events can be triggered by theDataLinkobject:

Click

FocusGained

FocusLost

Click

TheDataLinkobject triggers the Clickevent when any of the following occur:

The user presses the primary mouse button when the mouse is on the object.

The Spacebar is pressed when the object has the focus.

The user presses the objects mnemonic key (Al t+mnemonic key).

TheSelected:Booleanproperty is changed.

A value is mapped into the field data-l inked to the object.

TheDataLinkobject triggers the FocusGainedevent when the following occurs:

The user tabs into the object or clicks on the object.

TheDataLinkobject triggers the FocusLostevent when the following occurs:

The user tabs out of the object or clicks on another object in the window or on the window itself.

Column

TheColumnobject plays a fundamental role in implementing tables in the Java client. In general, a

Tableobject owns one or moreColumnobjects. The Table object has a number of properties thateffect the table as a whole, while the Column object contains a number of properties that determine theappearance and behavior of individual columns. The properties of a column effect all cells within thatcolumn.

Depending on your needs, you may access propert ies or methods on the table or on individual columnsof the table. As with all other visual objects, the names of tables and columns are the same as their systemidentifier (HPSID).

The table is data-linked to an occurring view and each column in the table (other than the optional

numbering column) is associated with a field in the hierarchy beneath the occurring view. The completedata link consists of a data link from the table to the occurring view. For each column, data is linkedusing a specification of the path from the occurring view to the part icular field in the view to which thecolumn is linked. These data links are specified using Set methods with the following properties:

.FieldPath path from occurr ing view to field

.ViewLink link to the occurring view

The first is set with theTableobject. The second is set with Columnobject.

Note The Column object is not a stand-alone object you cannotplace a Column object in a window without aTableobject.


28/166




Table2-8lists the properties and methods for the Columnobject:

getHeader():String

Returns the header as a string.

getHeader(n:Integer)

Returns the "n"th line of header string for a multi-l ine header.

setFieldPath:String Array

This is the path from occurring view to f ield when l inked to an occurr ing view. This specifies the path inthe hierarchy from the view to a specific field.

Table 2-8 Column Object Properties and Methods

Property:Type (Get Method) Supported Set Method



Editable:Boolean setEditable(Boolean)

EditLimit:Integer setEditLimit(Integer)


Error:Boolean (read only)

Empty:Boolean (read only)

FieldPath:String setFieldPath(String)



Format:Format setFormat(Format)

HeaderLineCount:Integer (Read only)



Justification:Integer setJustification(Integer)

Mandatory:Boolean setMandatory(Boolean)


SetLink:Set setSetLink(Set)


Width:Integer setWidth(Integer)

Type:Integer(read-only)

Addi tional Get Method Addi tonal Set Method

getHeader():String

getHeader(n:Integer)

addHeader(String)

setFieldPath(String Array)


29/166



For example, if the table is linked to the occuring view MYTABLE_OCCand the column is linked to thefield MYTABLE_COLUMN1of MYTABLE_OCC,the the field path wil l be the dynamic array with thevalue 'MYTABLE_COLUMN1'.

dcl

Col1_FieldPath object array of varchar(20);

enddcl

Col1_FieldPath.append('MYTABLE_COLUMN1')COL1.setFieldPath(Col1_FieldPath)

FieldPath:String

This property uses String instead of String Array for FieldPath; the path is separated by dots('.').

In the following example, TABLE_OCC is an occurring view linked to a table, TABLE_VIEW1 is a childview of TABLE_OCC, and COL_FIELD1 is a Field of TABLE_VIEW1 and is linked to the column COL1.

COL1.setFieldPathString("TABLE_VIEW1.COL_FIELD1")

ViewLink:Array

This is the link for the list when linked to an occurring view. For a Column, this specifies the occurringview which contains the data to be displayed.

Width:Integer

This specifies the width of a table column.


Each column can have one or more rows of header text. Each row is added by calling theaddHeader()method, wi th the first call to that method specifying the first line of header text, thesecond call specifying the second line, and so on.

When the Column is enabled, thesetSetLink(Set)method creates a drop-down combo box editorfor the column wi th the values from the set. When the Column is disabled, it shows a protected edit fieldthat displays the domain value from the set.

ComboBox

TheComboBoxobject i s used to display the standard combo box object that combines an edit area anda drop-down list. The list contains choices that can be selected and that subsequently appear in the editarea.


30/166



Figure 2-2shows a sample combo box.

Figure 2-2 Sample Combo Box

If a combo box is painted as DropDown, it is an editable combo box. If a combo box is painted asDropDownList, i t is a non-editable combo box.

In a DropDown combo box, the contents of the edit area can be directly modified. In a DropDownListcombo box, the contents of the edit area can be modified only by selecting items in the list. Duringexecution, the combo box can be changed from editable to non-editable using the Editable property. To

make the combo box non-editable at execution time, set the Editable property toFalse

.

In an editable combo box, if text has been entered but not committed to the data link, it can be rolledback by pressing Escape (Esc). Pressing Enterwhile focus is on an edit area whose contents have beenmodified commits the changes to the data link. Moving focus away from the combo box also commitsthe changes.

Combo boxes can be linked to character fields, numeric fields (integer or decimal), date fields or timefields. Combo boxes can be more complex than other window objects because a combo box has twodata-links - one for the edit area and one for the list. Furthermore, the li st can be linked to either of twodata structures: an occurring view or a set. For a combo box linked to an occurring view, the data linkfor the list consists of two parts: the link to the occurring view and the path in the hierarchy from theoccurring view to the field itself.

Constructor and Parameters

The following is a sample declaration and construction:

dcl

aComboBox object type ComboBox;

enddcl

map NEW ComboBox() to aComboBox

There are no parameters for this object.


Table2-9lists the properties and methods for the ComboBoxobject:

Note Editable objects generated in the rule source code do not have a format object defined. A format objectneeds to be defined and passed to the listbox, if formatting is desired.


31/166



DataLink:DataObject

This is the link for the edit area of the combo box. It specifies the data field in the application hierarchyto which the edit field is linked.

The DataObject for a combo box is: Date, Decimal, Integer, ShortInteger, String, or Time.

setFieldPath:String Array

This is the path from occurr ing view to field when linked to occurring view. It specifies the path in thehierarchy from the view to a specific field.

Table 2-9 ComboBox Object Properties and Methods




AutoSelect:Boolean setAutoSelect(Boolean)



DomainType:Integer (read only)


EditLimit:Integer setEditLimit(Boolean)




















ViewLink:Array setViewLink(Array)


Note EditLimit, Empty, and Error are only valid for an editable combo box.


32/166



FieldPath:String

This is the path from occurr ing view to field when linked to occurring view. It specifies the path in thehierarchy from the view to a specific field.

SetLink:Set

This is the link for the list when linked to a set. For static combo boxes, it specifies the set from which thevalues displayed in the combo box are taken.

ViewLink:Array

This is the link for the list when linked to an occurring view. For dynamic combo boxes, it specifies theoccurring view from which the items in the drop down l ist are taken.


This object has methods related to focus. The hasFocus() method is used to determine if the objectcurrently has focus. The setFocus() method is used to request that focus be set to the object.

Events

The fol lowing events can be triggered by the ComboBox object:

Click

DoubleClick

FieldError

FieldValidation

FocusGained

FocusLost

TheComboBoxobject triggers the Clickevent when any of the following occur:

The user presses the mouse button while the mouse is on the object.

The Spacebar is pressed while the object has the focus.

The user presses the objects mnemonic key (Alt+mnemonic key).

TheSelected:Booleanproperty is changed.

A value is mapped into the field data-l inked to the object.

This object also triggers theDoubleClickevent.

TheComboBoxobject triggers the FocusGainedevent when the following occurs:


TheComboBoxobject triggers the FocusLostevent when the following occurs:

The user tabs out of the object or clicks on another object in the window or on the window itself.

Note These events are not supported for thin-client comboboxes.


33/166



Editable combo boxes provide for data validation using theFieldErrorand FieldValidationevents. Whenan attempt is made to commit data, either by moving focus or pressing Enter, and the data containserrors, the FieldErrorevent is triggered. If there are no errors, the FieldValidationevent is triggered,allowing the application to verify that the data is acceptable.

EditField

TheEditFieldobject displays a standard edit field object with a rectangular area into which a singleline of text can be entered. If the text is too long to be displayed within the rectangular area, horizontalscrolling is automatically enabled.

When text is entered but not committed to the data link, it can be rolled back by pressing Escape ( Esc).Pressing Enterwhen you focus on an edit field whose contents have been modified commits the changesto the data link. Moving focus away from an edit field also commits the changes.

Figure 2-3shows a sample dialog with three edit fields. Each field has static text added in front of it.

Figure 2-3 Ed it Field Dialog

The PasswordFieldobject is very similar but displays asterisks (*) instead of the value. For an edit fieldwith multiple lines, refer to the MultiLineEditobject.



dcl

aEditField object type EditField;

enddcl

map NEW EditField() to aEditField


Note Editable objects generated in the rule source code do not have a format object defined. A format objectneeds to be defined and passed to the listbox if formatting is desired.


34/166




Table 2-10lists the properties and methods for this object.

Focus:Boolean

This method has no parameters.

AutoTab:Boolean

In an edit field, this indicates whether an automatic tab event is generated at the input of the lastcharacter of the maximum allowed limit , depending on the edit limit value or the length of the dataobject l inked to the field. The default property isFalse which indicates the focus remains in the editfield at the input of the last allowable character and the user has to manually generate a shift of focus.This property is used only by Java run-time.

Table 2-10 EditField Object Properties and Methods





AutoTab:Boolean setAutoTab


Border:Boolean setBorder(Boolean)



EditLimit:Integer setEditLimit(Boolean)





















35/166



DataLink:DataObject

An edit field can be linked to a character field, a numeric field (integer or decimal), a date field, or a timefield. It is not necessary for an edit field to have a data link. I f it has a data link, the text in the edit fieldcan be accessed either through the Text property or using rules code to access the data-l inked field. If itdoes not have a data link, the only way to set or query the text in the edit field is with the Text property.The DataObject for an edit field is Date, Decimal, Integer, ShortInteger, String, or Time.


ThesetBorder()method is used to draw the border around the edit field that makes it appear eitheras a three-dimensional box or a two-dimensional box depending on the 3D property, or to have noborder. For example:

EditField.setBorder(flag:Boolean)

When the flag isTrue, it has a three-dimensional or two-dimensional border around the edit field.When the flag isFalse, no border is drawn around the edit field.

This object has methods related to focus. ThehasFocus() method determines if the object currentlyhas focus. ThesetFocus()method requests that focus be set to the object.

When the EditField is disabled, the setSetLink(Set)method displays the domain value from theset.

Events

This object can trigger the following events:

Click

DoubleClick

FieldError

FieldValidation

FocusGained

FocusLost

This object triggers the Clickevent when any of the following occur:


In addition, this object triggers the DoubleClickevent.

This object triggers the FocusGainedevent when the following event occurs:


This object triggers the FocusLostevent when the following event occurs:

The user tabs out of the object or clicks on another object in the window or the window itself.

EditFieldprovides for data validation using the FieldErrorand FieldValidationevents. When anattempt is made to commit the data either by moving focus or pressing Enter, and the data containserrors, the FieldErrorevent is triggered.


36/166



If there are no errors, theFieldValidationevent is triggered, allowing the application to veri fy thatthe data is acceptable.

Thin-Client Support

Click, DoubleClick, FocusGained, FocusLost events are not supported for thin-client EditField.

The FieldError and FieldValidation events are supported through client-side JavaScripts.

Ellipse

An Ellipseobject is used to display an ellipse or circle.

Thin-Client Support

This isnot

supported for thin (HTML) clients.



dcl

anEllipse object type Ellipse;

enddcl

map NEW Ellipse() to anEllipse



Table 2-11lists the properties and methods for this object:

Events

This object generates no events.

Table 2-11 Ellipse Object Properties and Methods










37/166



GroupBox

A GroupBoxobject is used to display a rectangle with an optional title in the upper left, that is used togroup together other objects, for example, radio buttons or check boxes.

Figure 2-4 GroupBox Objects with Two Radio Buttons



dcl

aGroupBox object type GroupBox;

enddcl

map NEW GroupBox() to aGroupBox


Properties and MethodsTable2-12lists the properties and methods for this object.

Events

This object generates no events.

Table 2-12 GroupBox Properties and Methods












38/166



Label

TheLabelobject is used to display both non-editable text and graphics in the window. Although theuser cannot edit the static text, the text can be modified with rules code. A Labelobject cannot bedisabled and it cannot receive focus.



dcl

aLabel object type Label;

enddcl

map NEW Label() to aLabel


Properties and M ethodsTable 2-13lists the properties and methods for this object:

For aLabel, the horizontal justification of the text within the label area is specified by the Justi ficationproperty, while the vertical justification isdetermined by the VerticalJustification property

Table 2-13 Label Object Properties and Methods





HorizontalTextPosition:Integer setHorizontalTextPosition(Integer)


Image:String setImage(String)










VerticalJustification:Integer setVerticalJustification(Integer)


VerticalTextPosition:Integer setVerticalTextPosition(Integer)


39/166



VerticalJustification:Integer

For Labelobjects, the VerticalJustification property specifies vertical justification. Valid valuesaredefined in the Constants class as:

TOP_JUSTIFY

CENTER_JUSTIFY

BOTTOM_JUSTIFY

The default vertical justification is CENTER_JUSTIFY.

Events

TheLabelobject triggers the following events:

Click

DoubleClick

This object triggers the Clickevent when any of the following occur:


The user presses the objects mnemonic key (that is, Alt+mnemonic key).

In addition, this object triggers the DoubleClickevent.

ListBox

TheListBoxobject is used to display standard l ist box functionali ty. It provides a list of items

displayed in a rectangular area. I f the vertical size of the area is not sufficient to show all the choices, thena vertical scroll bar automatically appears. Figure 2-5shows a sample List Box.

Figu re 2-5 Sam ple L is t Box

List boxes can be linked to character fields, numeric fields (integer or decimal), date fields, or time fields.The data link is specified by a combination of two properties. The FieldPath property specifies thelocation of the specific field that contains the items relative to the view. The ViewLink property specifiesoccurring view that holds the items to be displayed in the list box.

Note Not supported for thin-client.


40/166





dcl

aListBox object type ListBox;

enddcl

map NEW ListBox() to aListBox



Table 2-14lists the properties and methods for this object:

Note Editable objects generated in the rule source code do not have a format object defined. A format objectneeds to be defined and passed to the listbox if formatting is desired.

Table 2-14 ListBox Object Properties and Methods

Property:Type (Get Method) Set MethodFocus:Boolean setFocus()













SelectedIndex:Integer setSelectedIndex(Integer)

SelectionMode:Integer setSelectionMode(Integer)




Type:Integer(read-only)

ViewLink:Array setViewLink(Array)


Addi ti onal Get Method Addi tional Set Method

getNextSelectedIndex:Integer

clearSelection( )

getNextSelectedIndex(fromIndex:Integer):Integer

resetSelectedIndex(index:Integer):Boolean


41/166


42/166



Menu

TheMenuobject displays choices on a menu bar and within a drop-down or popup menu containingadditional selections. Figure 2-6shows a sample menu dialog.

Figur e 2-6 Sam ple Men u

Constructor and ParametersTo create a Menu with pull-down items:

1. Create a MenuBar and add it to the Window using thesetMenuBarmethod.

2. Create a Menu and add it to the MenuBar using theaddmethod.

3. Create each MenuItem and add each one to the Menu using theaddmethod.

For example:

dcl

aMenuBar object type MenuBar;

aMenu object type Menu;

aChild object type MenuItem;enddcl

proc InitProc for Initialize object TEST_WINDOW

(e object type InitializeEvent)

map new MenuBar to aMenuBar

map new Menu to aMenu

set aMenu.text := 'File'

aMenu.setMnemonic('F')

map new MenuItem to aChild

set aChild.text := 'Open'

aChild.setMnemonic('O')

TEST_WINDOW.setMenuBar(aMenuBar)

aMenuBar.add(aMenu) aMenu.add(aChild)

endproc


Menu


43/166




Table2-15lists the properties and methods for this object.


TheMenuobject has two additional methods. The add()method appends MenuItems to the menu.

TheaddSeparator()method appends separators.

Events

TheMenuobject does not trigger any events.

MenuBar

TheMenuBarobject displays a menubar as part of the Menuobject.MenuBaris not a GuiObject but acontainer for Menus and MenuItems.



dcl

aMenuBar object type MenuBar;

enddcl

map NEW MenuBar() to aMenuBar


Table 2-15 Menu Object Properties and Methods













Addi tional Act ion Method

add(Item:MenuItem)

addSeparator( )

add(Menu)

getItem(integer):guiObjecta

a. The returned guiObject item will be either a Menu or MenuItem only.

getItemCount()Integer


44/166



Methods

The following methods are supported for this object:

bar.Add(Menu)

map bar.getMenu(index) to aMenu

map bar.getMenuCount() to anInt

Events

This object does not trigger any events.

MenuItem

TheMenuItemobject i s used to display a menu choice as part of either theMenuobject or thePopupMenuobject. Menu items can be associated with a key combination that triggers the actionassociated with the menu item when pressed. The key combination is called an acceleratorand is

specified using the Accelerator property.



dcl

aMenuItem object type MenuItem;

enddcl

map NEW MenuItem() to aMenuItem



Table 2-16lists the properties and methods for this object.

Table 2-16 MenuItem Object Properties and Methods


Accelerator:Accelerator setAccelerator(Accelerator)


Checked:Boolean setChecked(Boolean)

CheckMandatoryFields:Boolean setCheckMandatoryFields(Boolean)





IgnoreValidation:Boolean setIgnoreValidation(Boolean)




45/166



Accelerator:Accelerator

This specifies a key combination that triggers a menu item's Clickevent without navigating the menuhierarchy, also referred to as hot keys. Valid values may be specified in the Constantsclass or theAcceleratorclass.

Checked:Boolean

This specifies whether a menu item is displayed with a check mark. This property is equivalent to theSelected:Booleanproperty. It is provided for backwards compatibil ity with previous versions of theproduct.

For backward compatibility, when a checked MenuItem is clicked it will not toggle the checkmark butfi res a cli ckevent (in Java, checked MenuItems will toggle when clicked). You must write code to uncheckthe MenuItem.

A new appbuilder.ini sett ing is added to support the java functionali ty under the section[CCOMPATIBILITY],

TOGGLE_CHECK_MENU_ONCLICK. The value for the ini key should be TRUE to suppor t javafunctionality.

Style:Integer

This is a read-only property.

Returns one of the following values:

Constants.PLAIN_MENUITEM

Constants.CHECKBOX_MENUITEM

Events

The following event is triggered by this object: Click

MenuItemtriggers the Clickevent when the user selects the menu item or when the user presses theaccelerator key combination associated with that menu item.

Selected:Boolean setSelected(Boolean)




Style:Integer(Read only)

Validation:Boolean setValidation(Boolean)


Table 2-16 MenuItem Object Properties and Methods (Continued)


46/166



MultiLineEdit

TheMultiLineEditobject displays the standard multi-line edit field object, a rectangular area intowhich multiple lines of text can be entered. If the text is too long to display within the rectangular area,horizontal scrolling is automatically enabled. For a single-l ine edit field, refer to the EditFieldobject.

When text is entered but not committed to the data link, it can be rolled back by pressing the Escape(Esc). Pressing Enterwhile focus is on an edit field with modified contents causes the changes to becommitted to the data link. Moving focus away from the field also causes the changes to be committed.

MultiLineEdithas two methods. The hasFocus()method is used to determine if the objectcurrently has focus. ThesetFocus()method is used to request that focus be set to the object.

Properties

app builder object speak

Documents