		FED]
	DIGITAL ,
RESEARCH

GEMTM
Programmer's Guide
Volume 2: AES
COPYRIGHT

Copyright @ 1985 Digital Research Inc. All rights reserved. No
part of this publication may be reproduced, transmitted,
transcribed, stored in a retrieval system, or translated into any
language or computer language, in any form or by any means,
electronic, mechanical, magnetic, optical, chemical, manual or
otherwise, without the prior written permission of Digital Research
Inc., 60 Garden Court, P.O. Box DRI, Monterey, California 93942.

DISCLAIMER

DIGITAL RESEARCH INC. MAKES NO REPRESENTATIONS OR WARRANTIES WITH
RESPECT TO THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY
IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR
PURPOSE. Further, Digital Research Inc. reserves the ri,ght to
revise this publication and to make changes from time to time in the
content hereof without obligation of Digital Research Inc. to notify
any person of such revision or changes.

NOTICE TO USER

From time to time changes are made in the filenames and in the files
actually included on the distribution disk. This manual should not
be construed as a reoresentation or warranty that such files or
facilities exist on the distribution disk or as part of the
inaterials and programs distributed. Most distribution disks include
a "README.DCC" file. This file explains variations from the manual
which do constitute modification of the manual and the items
included therewith. Be sure to read this file before using the
software.

TRADEMARKS

Digital Research and its logo are registered trademarks of Digital
Research Inc. Concurrent, GEM, GEM Desktop, GEM Draw, GEM
Programmer's Toolkit, and Graphics Environment Manager are
trademarks of Digital Research Inc. We Make Computers Work is a
service mark of Digital Research Inc. UNIX is a trademark of Bell
Laboratories. IBM is a registered trademark of International
Business Machines. WordStar is a registered trademark of MicroPro
International. MS is a trademark of Microsoft Corporation.

GEM- Programmer's Gui,3e, Volume 2: AES was printed in the United
States of America.

First Edition: April 1985
Table of Contents

I		Introduction to GEM AES

1.1		Purpose of This Programmer's Guide . . . . . . . . 	1-1

1.1.1		Abbreviations of Names . . . . . . . . . . . 	1-1

1.2		Before Programming to GEM AES . . . . . . . . . . . 	1-1

1.3		Structure of This Programmer's Guide . . . . . . . 	1-2

1.3.1		Contents of the Introduction . . . . . . . . 	1-2
1.3.2		Sample GEM AES Calling Sequence . . . . . . 1-2
1.3.3		Subroutine Libraries . . . . . . . . . . . . 1-2

1.3.3.1		Naming Convention . . . . . . . . . 	1-3

1.4		GEM AES's Position in Memory . . . . . . . . . . . 	1-3

1.5		GEM AES Components . . . . . . . . . . . . . . . . 	1-4

1.5.1		Subroutine Libraries . . . . . . . . . . . . 	1-5
1.5.2		Limited Multitasking Kernel . . . . . . . . 	1-5

1.5.2.1 Desk Accessories . . . . . . . . . . 1-5
1.5.2.2 Screen Manager . . . . . . . . . . . 1-6
1.5.2.3 Dispatcher . . . . . . . . . . . . . 1-6

1.5.3		The Shell . . . . . . . . . . . . . . . . . 	1-8
1.5.4 Desk Accessory Buffer . . . . . . . . . . . 1-9
1.5.5 Menu/Alert Buffer . . . . . . . . . . . . . 1-9
1.5.6 X- and Y-Coordinates . . . . . . . . . . . . 1-9

2		Typical GEM AES Calling Routines

2.1		Introduction . . . . . . .

2.2		Initializing an Application

2.3		Finding Screen Resolution

2.4		Loading the Resource File

2-5		Getting Resource Addresses

iii
Table of Contents
(continued)

2.6		Dis-~Iav'.ng :.he Menu Bar . . . . . . . . . . . . . .	2-3
2.7		Displaying icons in the Desk.top W,. n d ow . . . . . .	2-4
2.8		Waiting for a User Event . . . . . . . . . . . . .	2-4
2.9		Menu Selection . . . . . . . . . . . . . . . . . .	2-5

2.10		Displaying a Dialog . . . . . . . . . . . . . . . .	2-6
2.111		Kevstroke Menu Selection . . . . . . . . . . . . .	2-8
2.12		Selecting an Icon . . . . . . . . . . . . . . . .	2-8
2.13		Creating a Window . . . . . . . . . . . . . . . . .	2-9

2.14 Calculating Work Area or Outer Dimensions . . . . . 2-10

2.15 Opening a Window . . . . .	2-11

2.16		Slider Size and Location .

2.17		Sizing a Win3ow . . . . . .

2.18		Rectangle List . . . . .

2.19		Before Updating a Window

2.20		Redrawing the Work Area

2.21		Making a Window Active

2.22		Closing and Deleting a Window . . . . . . . . . . .

Application Library

	3.1		Introduction . . 	. . . . . . . . . . . . .

3.2		Using the Application Library . .

	3.3		Global Array . . 	. . . . .	. . . . . . . . . . .	3-2

3.4		Application Library Routines . . . . . . . . . . .	3-3

3.4.1		APPL_INIT ., . . . . . . . . . . . . . . . .	3-5
3.4.2		APPL_READ . . . . . . . . . . . . . . . . .	3-6
3.4.3		APPL WRITE . . . . . . . . . . . . . . . . .	3-7
3.4.4		APPL FIND . . . . . . . . . . . . . . . . .	3-3

iv
Table of Contents
	(continued)

3.4.5		APPI, TPLAY . . . . . . . . . . . . . . . . .	3-9
3.4.6		APPI, TRECORD . . . . . . . . . . . . . . . .	3-10
3.4.7		APPL-EXIT . . . . . . . . . . . . . . . . . 	3-12

4		Event Library

4.1		Introduction . . . . . . . . . . . . . . . . . . . 	4-1

4.2		Using the Event Library . . . . . . . . . . . . . . 	4-1

4.2.1		Waiting for Multiple Events . . . . . . . . 	4-2
4.2.2		Keyboard Event . . . . . . . . . . . . . . .	4-2
4.2.3		Mouse Button Event . . . . . . . . . . . . .	4-2
4.2.4		Mouse Event . . . . . . . . . . . . . . . .	4-3
4.2.5		Message Event . . . . . . . . . . . . . . .	4-4

4.2.5.1		Predefined GEM AES Messages . . . .	4-4
4.2.5.2		MN SELECTED . . . . . . . . . . . .	4-5
4.2.5.3		V914-REDRAW . . . . . . . . . . . . .	4-5
4.2.5.4		WM TOPPED . . . . . . . . . . . . .	4-5
4.2.5.5		WM CLOSED . . . . . . . . . . . . .	4-6
4.2.5.6		WM FULLED . . . . . . . . . . . . .	4-6
4.2.5.7		WM ARROWED . . . . . . . . . . . .	4-6
4.2.5.8		WM HSLID . . . . . . . . . . . . .	4-6
4.2.5.9		WM VSLID . . . . . . . . . . . . .	4-7
4.2.5.10		WM SIZED . . . . . . . . . . . . .	4-7
4.2.5.11		WM MOVED . . . . . . . . . . . . .	4-7
4.2.5.12		AC OPEN . . . . . . . . . . . . . .	4-8
4.2.5.13		AC-CLOSE . . . . . . . . . . . . .	4-8

4.2.6		Timer Event . . . . . . . . . . . . . . . .	4-8

4.3		Event Library Routines . . . . . . . . . . . . . . 	4-9

4.3.1		EVNT KEYBD . . . . . . . . . . . . . . . . . 4-11
4.3.2 EVNT BUTTON . . . . . . . . . . . . . . . . 4-12
4.3.3 EVNT MOUSE . . . . . . . . . . . . . . . . . 4-14
4.3.4 EVNT MESAG . . . . . . . . . . . . . . . . . 4-16
4.3.5		EVNT TIMER . . . . . . . . . . . . . . . . . 4-17
4.3.6		EVNT MULTI . . . . . . . . . . . . . . . . . 4-18
4.3.7		EVNT-DCLICK . . . . . . . . . . . . . . . .4-20

v
Table of Contents
	(continued)

5		Menu Library

5.1		Introduction . . . . . . . . . .

5.2		Using the Menu Library . . . . . . . . . . . . . . 	5-4

5.3		Menu Library Routines . . . . . . . . . . . . . . . 	5-5

5.3.1		MENU BAR . . . . . .
5.3.2 MENU ICHECK . . . .
5.3.3 MENU IENABLE . . . .
5.3.4 MENU TNORMAL . . . .
5.3.5		MENU TEXT . . . . .
5.3.6		MENU-REGISTER . . . . . . . . . . . . . .

6		object Library

6.1		Introduction

6.2		Using the Object Library

6.3		Object Library Data Structures . . . . . . . . . . 	6-3

6.3.1		OBJECT Structure . . . . . . . . . . . . . . 6-4
6.3.2		TEDINFO Structure . . . . . . . . . . . . . 6-5
6.3.3		ICONBLK Structure . . . . . . . . . . . . . 6-3
6.3.4		BITBLK Structure . . . . . . . . . . . . . . 6-9
6.3.5		APPLBLK Structure . . . . . . . . . . . . . 6-10
6.3.6		PARMBLK Structure . . . . . . . . . . . . . 6-10
6.3.7		Predefined Values . . . . . . . . . . . . . 6-12
	6.3.7.1 Object Types . . . . . . . . . . . 6-12
	6.3.7.2 Object Flags . . . . . . . . . . . 6-14
	6.3.7.3 Object States . . . . . . . . . . . 6-i5
	6.3.7.4 Object Colors . . . . . . . . . . . 6-116

6.4		Object Library Routines . . . . . . . . . . . . . . 6-17

	6.4.1		OBJC ADD . 	. . . . . . . . . . . . . . . .	6-19
	6.4.2		OBJC DELETE	. . . . . . . . . . . . . . . .	6-20
	6.4.3		OBJC DRAW 	. . . . . . . . . . . . . . . .	6-21
	6.4.4		OBJC FIND 	. . . . . . . . . . . . . . . .	6-23
	6.4.5		OBJC OFFSET	. . . . . . . . . . . . . . . .	6-25
	6.4.6		OBJC ORDER 	. . . . . . . . . . . . . . . .	6-26
	6.4.7		OBJC EDIT ~ .	. . . . . . . . . . . . . . . .	G-27
	6.4.8		OBJC-CFANGE	. . . . . . . . . . . . . . . .	6-29
			vi
Table of Contents
	(continued)

7		Form Library

7.1		Introduction . . . . . . . . . . . . . . . . . . .	7-1

7.1.1		Forms: A Model . . . . . . . .
7.1.2		GEM AES Forms: The User's View
7.1.3		Dialog Boxes . . . . . . . . .

7.1.3.1		Editable Text Fields

7.1.4		Alerts . . . . . . .

7.1.4.1		Error Boxes . . . . . . . . . . . .	7-6

7.1.5		GEM AES Forms: The Programmer's View . . . . 	7-7

7.2		Using the Form Library . . . . . . . . . . . . . . 	7-9
7.3		Form Library Routines . . . . . . . . . . . . . . . 7-11

7.3.1		FORM DO . . . . . . . . . . . . . . . . . .	7-13
7.3.2		FORM-DIAL . . . . . . . . . . . . . . . . .	7-14
7.3.3		FORM ALERT . . . . . . . . . . . . . . . . .	7-16
7.3.4		FORM ERROR . . . . . . . . . . . . . . . . .	7-17
7.3.5		FORM-CENTER . . . . . . . . . . . . . . . .	7-18

8		Graphics Library

8.1		Introduction . . . . . . . . . . . . . . . . . . .	8-1

8.2		Using the Graphics Library . . . . . . . . . . . . 	8-1

8.3		Graphics Library Routines . . . . . . . . . . . . . 	8-1

8.3.1			GRAF RUBBERBOX . . . . . . . . . . . . . . .	8-4
8.3.2			GRAF DRAGBOX . . . . . . . . . . . . . . . .	8-6
8.3.3			GRAF MOVEBOX . . . . . . . . . . . . . . . .	8-8
8.3.4			GRAF-GROWBOX . . . . . . . . . . . . . . . .	8-9
8.3.5			GRAF SHRINKBOX . . . . . . . . . . . . . . .	8-11
8.3.6			GRAF WATCHBOX . . . . . . . . . . . . . . .	8-13
8.3.7			GRAF SLIDEBOX . . . . . . . . . . . . . . .	8-15
8.3.8			GRAF HANDLE	. . . . . . . . . . . . . . . .	8-17
8.3.9			GRAF MOUSE .	. . . . . . . . . . . . . . . .	8-18
8.3.10			GRAF MKSTATE . . . . . . . . . . . . . . . .	8-20

vii
Table of Contents
	(continued)

9		Scrap Library

9.1			Introduction . . . . . . . . . . . . . . . . . . .	9-1
9.2			Using the Scrap Library . . . . . . . . . . . . . .	9-1
9.3			Scrap Library Routines . . . . . . . . . . . . . .	9-2
	9.3.1		SCRPREAD . . . . . . . . . . . . . . . . .	9-4
	9.3.2		SCRP-WRITE . . . . . . . . . . . . . . . . .	9-5

10		File Selector Library

10.1 Introduction . . . . . . . . . . . . . . . . . . . 10-1

10.2 Using the File Selector Library . . . . . . . . . . 10-2

10.3 File Selector Library Routine . . . . . . . . . . . 10-3

	10.3.1 FSFL-INPUT 		. . . . . . . . . . . . . . . .	10-5

11		Window Library

11.1 Introduction . . . . . . . . . . . . . . . . . . .

11.2 Using the Window Library . . . . . . . . . . . . . 11-2

11.2.1 Comoonents of the Border Area . . . . . . .11-3
11.2.2 Division of Labor . . . . . . . . . . . . .11-6
11.2.3 Window Management Calls . . . . . . . . . .. 11-6
11.2.4 Support of Cverlapping Windows . . . . . . . li-8
11.2.5 R.---drawing ani Upfiating . . . . . . . . . . .		11-9
11.3 Window Library RO-Itines . . . . . . . . . . . . . .		11-11
11.3.1 WIND CREATE . . . . . . . . . . . . . . . .		11-13
11 .3. 2 WIND 0 P,,, N . . . . . . . . . . . . . . . . . li-i5
11.3.3 WIND CLOSE . . . . . . . . . . . . . . . . . 11-16
11.3.4 WIND DELETE . . . . . . . . . . . . . . . . !I-L7
11.3.5 WIND GET . . . . . . . . . . . . . . . . . . 11-13
11.3.6 WIND SET . . . . . . . . . . . . . . . . . . 11-21
11.3-'7 WIND FIND . . . . . . . . . . . . . . . . . ti-2-)
11.3.8 WIND UPDATE . . . . . . . . . . . . . . . . 11-24
11.3.9 WIND-CALC . . . . . . . . . . . . . . . . . il-25

viii
Table of Contents
	(continued)

12 Resource Library

12.1 Introduction . . . . . .

12.2 Using the Resource Library . . . . . . . . . . . . 12-1

12.3 Resource Library Routines . . . . . . . . . . . . . 12-2

12.3.1		RSRC LOAD . . . . . . . . . . . . . . . . .	12-4
12.3.2		RSRC FREE . . . . . . . . . . . . . . . . .	12-5
12.3.3		RSRC GADDR. . . . . . . . . . . . . . . . . .	12-6
12.3.4		RSRC SADDR . . . . . . . . . . . . . . . . .	12-8
12.3.5		RSRC-OBFIX . . . . . . . . . . . . . . . . .	12-9

13 Shell Library

13.1 Introduction

13.2 Using the Shell Library . . . . . . . . . . . . . . 13-1

13.3 Shell Library Routines . . . . . . . . . . . . . . 13-2

13.3.1 SHEL READ		. . . . . . . . . . . . . . . . . 13-4
13.3.2 SHEL WRITE		. . . . . . . . . . . . . . . . . 13-5
13.3.3 SHEL FIND		. . . . . . . . . . . . . . . . .13-7
13.3.4 SHEL-ENVRN . . . . . . . . . . . . . . . . .13-8
Figures

5-1.		Typical Menu . . . . . . . . . . . . . . . . . . .

6-1. Object Tree . . . . . . . . . . . . . . . . . . . 6-1
6-2. on-screen Display . . . . . . . . . . . . . . . . 6-2
6-3. OBJECT Structure . . . . . . . . . . . . . . . . . 6-4
6-4. TEDINFO Structure . . . . . . . . . . . . . . . . 6-6
6-5. ICONBLK Structure . . . . . . . . . . . . . . . . 6-8
6-6. BITELK Structure . . . . . . . . . . . . . . . . . 6-9
6-7. APPLBLK Structure . . . . . . . . . . . . . . . . -_10
6-8. PARMBLK Structure . . . . . . . . . . . . . . . . 6-11
6-9. Object Color WORD . . . . . . . . . . . . . . . . 6-16

7-1. Typical Product Survey Form . . . . . . . . . . . 7-2
7-2. Sample GEM AES Alert . . . . . . . . . . . . . . . 7-6
7-3. OBJECT Structure Elements . . . . . . . . . . . . 7-7
7-4. TEDINFO Structure Elements . . . . . . . . . . . . 7-8

10-1.		File Selector Dialog Box . . . . . . . . . . . . . 10-2

11-1.		Components of a Typical Window . . . . . . . . . . 11-2

x
	Section I
Introduction to GEM AES

1.1		Purpose of This Programmer's Guide

This		programmer's guide has three major purposes:

		Introduce a programmer to the concepts and structures underlying
GEM" Application Environment Services.

		Prepare the programmer to write a GEM application.

		Serve as a reference guide for the programmer writing a GEM
application.

1.1.1		Abbreviations of Names

The		following abbreviations appear throughout this programmer's
guide:

*		GEM - Graphics Environment Manager"

*		GEM AES - GEM Application Environment Services

9		GEM VDI - GEM Virtual Device Interface. The GEM VDI is described
in detail in the GEM Programmer's Guide, Volume 1: VDI.

o		DOS - MS`-DOS or PC DOS (version 2.0 or higher) or Concurrent" DOS
version 3.3 in DOS mode

1.2		Before Programming to GEM ARS

Before starting to write a GEM application, and even before reading
further in this programmer's guide, a programmer should do the
following:

e Read the GEM Programmer's Guide, Volume 1: VDI.

Because GEM AES uses GEM VDI function calls extensively, an
understanding of GEM VDT is essential to writing a successful GEM
application.

e Use the GEM Desktop-.

Familiarity with GEM AES's user interface--the GEM Desktop, icons,
drop-down menus, and windows--is also essential to writing a
successful GEM application.
GEM AES Programmer's Guide			1.3	Structure of Programmer's Guide

1.3 Structure of this Procrammer's Guide
.1

This proqrammer's guide contains three major divisions;

I .		This introduction, which includes descript-~ons of the maJor
components of GEM AES.

2.		'he description of a sample calling sequence for a typical GEM
application.

3.		Descriptions of the GEM AES subroutine libraries.

1.3.1		Contents of the Introduction

The remainder of this introduction describes the relationshin of GEM
AES to operating system files, GEM VDI, and applications, and
describes how GEM AES shares space in memory wi-.h each of the ~hree.

This section a'-so describes the architecture of GEM AES itself, as
well as its components and their relation-ship to each other.

1.3.2		Sample GEM AES Calling Sequence

Section 2 describes a typical sequence of calls from a GEM
application to GEM AES.

The calling sequence does not try to describe a specific application,
but instead tries to give a general overview of GEM AiS- function
calls. However, where specific examples are needed, the GEM Des'r:too
application serves as a typical case.

1.3.3		Subroutine Libraries

The remaining sections of this programmer's guide describe GEM A--,S's
subroutine libraries. Each section has the following basic
structure:

		an introduction to the library

		a section describing how an application uses the library

		descriptions of the library's data structures (if applicable)

		descriptions of each of the library's routines, including all Of
the routine's parameters and a sample C language binding
GEM AES Programmer's Guide			1.3	Structure of Programmer's Guide

1.3.3.1		Naming Convention

The parameter name for a routine does the following:

e It identifies the parameter.
o It identifies the subroutine library the routine belongs to.
o It identifies the routine to which the parameter belongs.

The part of the parameter name preceding the underbar is a code for
the subroutine library to which the routine belongs. The following
list gives several partial parameter names and the names of the
subroutine libraries to which they belong.

aP-...		Application Library
ev_...		Event Library
ob ...		Object Library
gr-...		Graphics Library
wi-...		Window Library

The first letter (or, in cases where there would be duplication, two
letters) following the underbar identifies the specific routine to
which the parameter belongs. The following list gives several
partial parameter names from the Graphics Library and the names of
the routines to which they belong.

gr_r ...		GRAF - RUBBERBOX
gr_m ...		GRAF - MOVEBOX
gr_s ...		GRAF - SHRINKBOX
gr_sl ...		GRAF - SLIDEBOX
gr_a ... 		GRAF-APPLMOUSE

Note that a second letter was required to distinguish GRAF-SLIDEBOX
from GRAF-SHRINKBOX.

1.4		GEN AES's Position in Nemory

GEM AES shares memory space with the following:

o DOS
* GEM VDI
o an application

When a user starts GEM AES, the system has already loaded DOS into
memory, followed by GEM VDI. The application takes as much of the
remaining memory space as it requires.

1-3
EM AES Programmer's Guide			1.4	GEM AES's Position in Memory

The application can be any of the following:

		the GEM Desktop
		a GEM application
		a DOS application

The GEM Desktop application is in fact a GEM application; it uses no
soecial function calls and does nothing that another GEM application
cannot do.

The user can start an application (GEM or DOS) from the GEM Desktop.
When the current application terminates, GEM AES automatically
invokes and runs the GEM Desktop unless the user has already invoked
another application. For example, the user can invoke the GEM Output
application from within another GEM application.

Note: The user can also start any GEM application from the DOS
prompt.

An application can use any of three sets of calls, each with a
specific purpose:

		DOS calls are responsible for managing the file system. The
programmer should t~e familiar with the material contained in the
DOS manual.

Because GEM AES requires DOS version 2.0 or higher, the programmer
should use the UNIX--type file system calls that are not available
in DOS version 1.1.

		GEM VDI calls manage graphics output to the screen or other
peripheral devices. The programmer should be familiar with the
material in the GEM Programmer's Guide, Volume 1: VDI.

		GEM AES calls manage graphics input. They make possible a variety
of high-level user interface graphics primitives that are used for
icons, drop-down menus, dialog boxes, alert messages, and windows.

1.5		GEM AES Components

The following GEM AES components occupy space in memory:

e subroutine libraries
9 a limited multitasking kernel and dispatcher
& the shell
o a desk accessory buffer
o a menu/alert buffer
GEM AES Programmer's Guide	1.5		GEM AES Components

1.5.1		Subroutine Libraries

GEM AES's subroutine libraries provide routines for a wide variety of
tasks, including windowing, monitoring the mouse's movement,
.0~		displaying system messages and error messages, and drawing objects on
the screen.

The code for the subroutine libraries is resident in memory, and it
remains in memory until the user exits GEM AES.

1.5.2		Limited Hultitasking Kernel

The limited multitasking kernel supports the following:

o		up to three desk accessory programs (see Section 1.5.2.1) or
background tasks/processes

o		one primary application, GEM or DOS, such as the GEM Desktop
application or WordstarlD

o		the GEM AES Screen Manager

The function of the limited multitasking kernel is to divide CPU time
between the primary application, background processes, and the Screen
Manager in such a way that the user does not see any degradation in
the performance of the primary application.

1.5.2.1		Desk Accessories

A desk accessory is an application that does not take over the entire
display screen. It runs in a specially designed window on top of the
GEM Desktop application or any other GEM application. The calculator
is a typical desk accessory.

The limited multitasking kernel supports as many as six desk
accessories in three desk accessory programs, called DESK1.ACC,
DESK2.ACC, and DESK3.ACC. Each desk accessory program can contain
more than one desk accessory. For example, in the GEM Desktop
application, the program DESK1.ACC contains both the clock and the
calculator.

The desk accessory programs are loaded into memory using the Overlay
option of the DOS EXEC function call (documented in the DOS manual).
They remain in memory until the user exits GEM AES.

A desk accessory program is loaded only if, after loading it and the
rest of the GEM software, 128 kilobytes of memory remain available
for the primary application.

1-5
GEM AES Programmer's Guide	1.5		GEM AES Components

If a desk accessory registers with GEM AES (see Section 5.3.6, the
MENU REGISTER call), it appears in the Desk Menu. The user starts
the ~iesk accessory by choosing it from the menu.

1.5.2.2		Screen Manager

The Screen Manager is a special process that monitors the actions of
the mouse when it is outside the work area of the top (active)
window. The work area is the part of the window exclusive of the
title bar, information line (if any), and border area.

The Screen Manager monitors the user's interaction with the
following:

		the border area of the top window

		the menu bar and drop-down menus

		any other part of the screen, except for the work area of the top
window

The Screen Manager sends the results of all these user interactions
to the application that is currently running.

When necessary, the Screen Manager is responsible for converting the
mouse form to an arrow (pointer).

1.5.2.3		Dispatcher

The dispatcher is the part of the multitasking kernel that makes sure
that no process dominates CPU time to the exclusion of the other
processes.

The kernel divides CPU time between the primary application,
background processes, and the Screen Mznager by assigning each task
to one of two lists: the Ready List and the Not-Ready List.

The Not-Ready List contains all processes that are waiting for one of
the following events:

 a keystroke
 a mouse button press
 mouse movement
 a message
*passage of a time interval

1-6
GEM AES Programmer's Guide		1.5	GEM AES Components

The Ready List contains all processes that are ready to run. A
process is ready to run when it is not waiting for one of the events
listed above.

The process at the head of the Ready List is the one that is
currently running. Any others on the list are waiting to run. The
multitasking kernel uses "round-robin scheduling" to run the
processes on the Ready List in the order in which they appear on the
list.

To prevent a single process from dominating CPU time, the
multitasking kernel dispatches at intervals. Dispatching involves
two steps:

1.		Moving processes from the Not-Ready List to the Ready List, if
they now qualify.

2.		Moving the currently running process to the end of the Ready List,
to give the next process on the list a chance to run.

GEM AES dispatches nonpre-emptively, which means that a process
periodically gives up its claim to CPU time and lets the next process
run. Dispatching takes place each time the running process makes a
GEM AES call.

If a process does not make any other kind of GEM AES call in the
course of its normal activity, it should periodically make an
EVNT TIMER call, specifying an interval of 0 (zero) milliseconds.
(See the description of the EVNT-TIMER routine, Section 4.3.5.)

At dispatch time, GEM AES's dispatcher first moves any processes that
have become ready to run from the Not-Ready List to the end of the
Ready List. GEM AES next stops the currently running process and
looks to see if any other processes are on the Ready List. If so,
the dispatcher moves the current process to the end of the Ready List
and starts the next process. If there are no other processes on the
Ready List, the current process begins to run again.

This dispatching procedure is repeated with each GEM AES call.

Dispatching also occurs when the running process "blocks, " which
means the process goes from a ready state to a not-ready state (for
example, when it needs to look for mouse movement before continuing).

If no processes are on the Ready List, the multitasking kernel
continually checks all processes to see if any can be moved over to
the Ready List.

1-7
GEM AES Programmer's Guide	1.5		GEM AES Components

1.5.3		The Shell

The Shell is in fact one of the GEM AES subroutine libraries, but
functionally it runs on top of the limited multitasking kernel. The
Shell invokes GEM AES and DOS applications, causing the primary
application to run.

The		following examples illustrate how the Shell starts GEM
applications.

		When the user enters the command "GEM", GEM AES is loaded into
memory, and the primary application is the GEM Desktop. The user
can start other applications, GEM or DOS, from the GEM Desktop.
After quitting the GEM Desktop, the user returns to the DOS
environment.

		When the user enters the command "GEM DRAW", GEM AES is loaded into
memory, and the primary application is GE24 Draw'. After quitting
GEM Draw, the user returns to the DOS environment.

		When the user enters the command "GEM DRAW /D", GEM AES is loaded
into memory, and the primary application is again GEM Draw.
However, the "/D" part of the command tail causes the user to
return to the GE24 Desktop after quitting GEM Draw.

If the user invokes another application from the GEM Desktop, the GE21
Desktop passes to the Shell the following information about the new
application:

*whether it is graphic or character-based
* whether it is a GEM application or a DOS application
e the name of the directory containing the application

(Most GEM applications are graphic, and most DOS applications are
charac ter -based, but the GEM Desktop needs to pass the information as
separate parameters of the SHEL - WRITE call for those cases where this
correlation does not hold.)

The GF24 Desktop then terminates.

Mien any application terminates, control returns to the process that
invoked it. In this case, control returns to the Shell.

The Shell determines if it was instructed to start a new application.
If it was not, it starts the GE~M Desktop again.

If the Shell was instructed to start a character-based application,
it converts the screen to character mode and makes a GEM VDI Close
Workstation call.

If the Shell was instructed to start a GEM application, no GE24 VDI
call or conversion is required.

1-8
GEM AES Programmer's Guide		1.5 GEM AES Components

When this application terminates, the Shell starts the next
application, either a user-requested application or (if none was
requested) the GEM Desktop.

To go from a character-based application to a GEM application or to
the GEM Desktop, the Shell must make a GEM VDI Open Workstation call
and convert the screen to graphics mode.

1.5.4 Desk Accessory Buffer

The desk accessory buffer contains the ACC files for the GEM AES
desk accessories.

As noted above, the multitasking kernel supports as many as three
desk accessory programs. The desk accessories remain in memory until
the user exits GEM AES.

1.5.5 Menu/Alert Buffer

Drop-down menus and alert boxes (the latter are a special form of
dialog box) appear at different times in a GEM application. They
always appear layered on top of any windows, icons, or dialogs
located in the same area.

When the menu or alert is no longer being displayed, GEM AES redraws
the screen from a buffer in which it stores the parts of the screen
that were displaced by the menu or alert. The application does not
redraw the screen.

This buffer can hold data equal to one-fourth the size of the screen
area. Consequently, no single menu or alert can be larger than one
fourth the size of the screen.

GEM AES uses the menu/alert buffer because an application redraw is
typically slower than a redraw from the buffer.

1.5.6 X- and Y-Coordinates

Several GEM AES subroutine libraries define objects by their X- and
Y-coordinates and their width and height. These X- and Y-coordinates
always refer to the upper left corner of the object.

End of Section 1

1-9
	Section 2
Typical GEM AES Calling Routines

2.1		Introduction

This section describes a hypothetical sequence of GEM AES and GEM
VDI calls that might be made by a GEM application. Where needed,
the GEM Desktop application serves as an example of a typical GEM
application.

These calling routines do the following:

9		initialize the application

9		determine the system's screen resolution

9		load the application's resource file

*		get the addresses of the application's resources

o		display the aPplication's menu bar

o		display icons on the desktop

o		let the application await user action

o		let the user select from a menu

o		display a dialog as the result of selecting from a menu

o		let the user make a menu selection by pressing a specially
designated key or combination of keys

o		let the user select an icon

o		let the user interact with windows

2.2		Initializing an Application

Application initialization consists of three steps:

1. Freeing unneeded memory.

When an application is first loaded into memory, it should make a
DOS call to modify the applination's memory allocation. By
freeing memory from the end of the application to the top of
memory, this call makes space available for the application's
resource file.

2-1
GEM AES Programmer's Guide			2.2	Initializing an App"ication

If the application does not make this call, the operatina system
will return an error message when the RSRC - LOAD call (describe6
in Section 2.4) makes its DOS memory allocation request.

2.		Initializing internal data structures and setting up GEM AES
arrays.

The application initializes its internal data structures and sets
up t~e following GEM AES arrays:

- GEM AES Parameter Block
- Control Array
- Global Array
- Integer Input (int_in) Array
- Integer Output (int out) Array
- Address Input (addr in) Array
- Address Output (addr-out) Array

The application allocates space for these arrays and establishes
bindings in its code so that parameters go to the right arrays.
Examples of these bindings are the sample language bindings in
this guide and the GEM Programmer's Toolkit'".

3.		The APPL-INIT call.

APPL-INIT, the application's first GEM AES call, sets up any
application-specific data structures and returns a system-wide
application identifier (ap_id). GEM AES places aD id in the
Global Array so it can identify the application throughout its
calling sequence.

2.3		Finding Screen Resolution

All of an application's textual or graphic data that is either
device- or language-specific (spoken/written language, not
programming language) is contained in the application's resource
file. These materials include the following:

text
icons
menus
dialogs
forms

All resource files have a RSC filetype.

Applications usually have at least two resource files, one for a
low-resolution screen (640x2OO pixels) and another for a hialh
resolution screen (640x4OO, 640x350, or 720x350 pixels).

2-2
GEM AES Programmer's Guide			2.3	Finding Screen Resolution

Before it can load the correct resource file, the application needs
to know the system's screen resolution. Two steps are required to
get this information:

1.		The application calls the GRAF - HANDLE routine. This call returns
	the GEM VDI handle for the screen.

2.		The application makes a GEM VDI Open Virtual Workstation call,
which provides the same information as an Open Workstation call.
This call returns the system's screen resolution.

For a description of the GEM VDI Open Virtual Workstation call,
see the GEM Programmer's Guide, Volume 1: VDI.

2.4		Loading the Resource File

when the application makes its RSRC LOAD call, the Resource Library
allocates memory for the resource file, loads it into memory, and
sets the pointer references in the file.

The RSRC-LOAD call also transforms special X, Y, width, and height
screen position information that allows the application to address
any pixel on the screen. This coordinate system assumes a standard
screen of 80 columns and 25 lines and uses a bit offset method of
locating screen positions. For example, on a given line, GEM AES
can address two points that are three pixels apart by identifying
their positions as (column 46 + 2 pixels) and (column 46 + 5
pixels).

2.5		Getting Resource Addresses

To get the address of any object contained in its resource file, the
application makes a RSRC - GADDR call. The application can make
RSRC-GADDR calls at either of the following times:

 immediately after making the RSRC LOAD call
 each time it needs a particular resource

In the first case, the application makes a series of anticipatory
RSRC-GADDR calls, getting and storing the address of each resource
it expects to need in the course of the current session.

2.6		Displaying the Menu Bar

The application's menu bar is a resource. To display the menu bar,
the application makes two calls:

1.		The application calls RSRC - GADDR (if it has not already done so),
	passing in the menu bar's data structure type and the index to
	the menu bar.

2-3
GtM AE6 Vrogrammer's Uuiae		2 . b	u1sp-Laying tne menu tsar

RSRC - GADDR returns the LONG ADDRESS of the root of the dbjecr
tree that draws the menu bar.

2.		The application calls MENU BAR, passing in the menu bar's address
and an me-bshow value of T (display the menu bar).

The Menu Library then displays the menu bar across the top of ~~he
screen.

2.7		Displaying Icons in the Desktop Window

To display icons in the desktop window, the application must first
know the size and location of the desktop window's available work
area. The work area includes everything but the menu bar and border
area (if any).

To get this information the application makes a WIND-GET call,
passing in values that do the following:

		identify the window as the desktop window (wi_uhandle = 0)

		ask for the window's X, Y, width, and height values (wi_gfield
4)

The call returns the work area's X, Y, width, and height values.

The application then makes an OBJC DRAW call to draw the icons in
the work area. The values co~-tained in ib - xicon, ib_vicon,
ib - wicon, and ib-hicon in each icon's ICO.NBLK structure determine
where the icon appears.

Note: Most applications will use the desktop window only as a
backdrop to their own application windows. The GEM Desktop
application, however, does display icons (disks and the trash can)
in the desktop window.

2.8 Waiting for a User Event

At this point the application has displayed its menu bar and desktop
icons, and it is now ready for user interaction.

The Event Library defines five user interaction events:

		keystroke
 pressing a mouse button
9 mouse movement
e message from a GEM AES process
*passage of a specified period of time
GEM AES Programmer's Guide			2.8	Waiting for a User Event

Although an application can wait for one event at a time, most
commonly it will make an EVNT-MULTI call to wait for some
combination of events.

When one of the awaited events occurs, GEM AES's dispatcher moves
the application from the Not-Ready List to the Ready List. When the
application reaches the head of the Ready List, it responds to the
user event and then returns to the Not-Ready List to await the next
event in the EVNT-MULTI sequence.

Note: It is suggested that GEM applications only accept input from
a single mouse button. If a mouse has more than one button, a GEM
application should look for input from the button on the left. DOS
applications can accept input from more than one mouse button.

2.9 Menu Selection

An application's menu bar is controlled by the GEM AES Screen
Manager; the application is not responsible for user interaction
with the menu bar.

The following sequence describes what happens when a user selects
Desktop Info..., one of the Desk Menu commands in the GEM Desktop
application. (Menu selection for any GEM application should follow
the same basic sequence.)

1.		The GEM Desktop application makes an EVNT-MULTI call that
includes a message as one of the awaited events.

2.		The user moves the mouse into the menu bar, touching the Desk
Menu's title.

3.		Receiving notification that the mouse has entered the menu bar,
the Screen Manager is dispatched to the Ready List. it
determines which menu title the pointer is touching, saves the
part of the screen under the menu, and displays the menu. The
Screen Manager highlights menu items as the user moves the mouse
pointer through the menu.

The GEM Desktop application is still on the Not-Ready List at
this time.

4.		The user clicks the mouse button on Desktop Info....

5.		The Screen Manager notifies the primary application of the user's
	selection by writing a message to the GEM Desktop application's
	message buffer. The ev - mmgpbuff parameter of the EVNT-MULTI call
	contains the buffer's address.
Ut;M Ahb 11rogrammer's UuIcie	Z.~ 		Menu belectlOn

The message ( the predefined GEM AES message MIN - SELECTED,
described in Section 4.2.5.2) contains object tree inaexes tor
the selected menu title and item.

6.		When the Screen Manager writes the message, the Dispatche_- checks
the Not-Ready List for the process that was waiting for the
message. It finds the GEM Desktop application and moves it over
to the Ready List.

The EVNT-MULTI call returns an ev-mwhich value to the GEM Desr.top
application. The bit setting in ev-mwhich indicates that a
message has been received.

The GEM Desktop application reads and interprets the message from
its buffer and displays the DESKTOP INFORMATION ~Iialog.
Displaying a dialog is described in Section 2.10.

The menu title remains highlighted until the requested action is
complete. In the case of displaying the DESKTOP INFORMATION
dialog, the menu title is highlighted until after the final
FORM-DIAL call.

When the action is complete, the application makes a MENU - TNORMAL
call with an me nnormal value of 1. This call changes ;-he men,
title from its7~ighlighted state to its normal state.

2.10		Displaying a Dialog

To display a dialog, the GEM Desktop application makes the following
sequence of calls:

1.		The application calls RSRC-GADDR to get the address of the
dialog's object tree.

(As noted in Section 2.5, the application can make this call at
any time between its RSRC - LOAD call and the beginning of the
dialog display sequence.)

2.		The application calls the FORM DIAL routine, passing in an
fo-diflag value of 0 (zero), an IPMD-START call.

This call reserves screen space for the dialog.

3.		The application can make a second FORM DIAL call, this time
passing in an fo-diflag value of 1, an FRD_GR9vJ call.

'niis call draws an expanding rectangle out to the position where
the dialog's borders will be.

This call is optional. Its primary purpose is to produce a
pleasing visual effect.

2-6
GEM AES Programmer's Guide		2.10	Displaying a Dialog

4.		The application calls the OBJC - DRAW routine to draw the dialog,
	whose root object is usually a G-BOX object type.

One of the OBJC DRAW call's input parameters is the address of
the dialog's object tree.

5.		The application calls FORM-DO, to monitor the user's interaction
with the dialog.

6.		When one of the dialog's exit conditions is met, the application
compares the dialog's initial values--set up in the RSRC-LOAD
call or in the application's code--with the values the dialog now
contains. The application notes any changes and acts
accordingly.

7.		In many cases the application makes a series of OBJC - CHANGE calls
	to reset the dialog objects to their initial values.

For example, after the user exits the DESKTOP INFORMATION dialog,
the GEM Desktop application changes the OK exit button's ob - state
from SELECTED to NORMAL so that the next time the user selects
Desktop Info..., the dialog does not appear with its OK button
already highlighted.

In some cases, the user can overwrite text strings that have been
set to initial values. The user backspaces over the string and
types a new string. After comparing values and acting
accordingly, the application might reset the string to its
initial value.

Note, however, that the user might want to save some changes made
to dialogs. One example is the DOCUMENT INFORMATION dialog, in
which the user will want to save both the document's name and its
Read/Write or Read-Only status.

8.		The application can call FORM - DIAL again, passing in an fo-diflag
	value of 2, an FMD-SHRINK cz~ll.

This call draws a shrinking box from the dialog's borders. Like
the call that draws the expanding box, this call is optional.

9.		The application calls FORM DIAL the last time, this time passing
in an fo-diflag value of _Y, an FMD-FINISH call.

This call removes the dialog from the screen and frees the screen
space that had been reserved by the dialog. The call also causes
the Screen Manager to send a message to the application to redraw
the screen.

The application can redraw the screen with an O&JC-DRAW call or
with several GEM VDI calls.

To be able to respond to such a redraw message at any time, the
application should be in an EVNT-MULTI wait.

2-7
GEM AES Programmer's Guide			2.11	Keystroke Menu SE'lection

2.11		Keystroke Menu Selection

GEM AES supports letting the user select some menu items b%, rressina
a specially designated key or combination of keys ins--ead oi- usiriq a
Menu. To enable this feature, the application should specify a
keyboard event as one of the awaited events in the EVNT-MULTI call.

When		the user presses one of the menu item selection keys,the
	application makes a MENU - TNORMAL call with an me nnormal vaiue of 0
(zero) to hiahlight the menu title.	The user does not see the menu,
	but the highiighted menu title serves as notice that the application
is acting on the user's request.

When the requested action has taken place, the application makes a
MENU TNORMAL call with an me-nnormal value of 1, to return t'he menu
titl7e to its normal state.

2.12		Selecting an Icon

To select an icon, the user clicks the mouse button once on the
icon.

The following sequence describes icon selection:

1.		The application sets the bit for a button event (..h1U_BUT1TON) 'In
the EVNT_MULTI call.

Input parameters for this call include the awaited mouse bu--ton
state (up or down) and the nurrber of times the ar-D1,1--ation wants
the button to enter that state within the presel. time Interval

2.		Wrien ~he user clicks on an icon, the EVNIT MULTI call returns an
ev-mwhich value with the bit set for a mouse button event.

3.		The application makes a GRAF MKSTATE call to get the mouse
pointer's X- and Y-coordinates.

4.		The application makes an OBJC - FIND call, passing in the Mouse
	pointer's X- and Y-coordinates from the r)revious call. The
	application also passes in the address of the obiect tree that
	draws the icons on the desktop ( if the pointer was in the desk top
	window) or in the application's window.

5.		If the OBJC - FIND call reports that the mouse pointer was over an
icon, the application makes an OBJC CHANGE call to change the
icon's ob-state from NORMAL to SELE~_TED.

If the mouse pointer was not over an icon, the application assumes
that the user intends to select a group of icons by dragging -an
expanding (or "rubber") rectangle around their.. In that event, the
aoDlication makes the following sequence of calls:

2-8
GEM AES Programmer's Guide		2.12	Selecting an Icon

1.		The application makes a GRAF-MKSTATE call to see if the button is
still down.

2.		If so, the application makes a GRAF RUBBERBOX call to draw the
rubber rectangle that will surround ~-he icons the user wishes to
select.

The call's input X and Y values are the X and Y values from the
GRAF-MKSTATE call.

The GRAF - RUBBERBOX call's output width and height values
(gr_rlastwidth and gr_rlastheight) define the size of the rubber
rectangle at the time the user released the mouse button.

3.		The application looks for icons inside the rectangle.

4.		The application makes an OBJC - CHANGE call for each icon, changing
	its ob--state from NORMAL to SELECTED.

Selecting an icon can change the appearance of menu items. For
example, when a folder, document, application, or disk icon is
selected, the File Menu item Open should change state from disabled
to enabled. The same icon selection can change other menu items
from enabled to disabled.

A disabled menu item appears in dimmed characters, which indicates
to the user that the item cannot be selected. An enabled item
appears in characters of normal brightness.

When the user selects an icon, the application's code determines
which menu items need to change state. The application then makes a
MENU - IENABLE (item enable) call for each of these items, passing in
me-eenable values of 0 (zero) to disable an item or I to enable it.

2.13		Creating a Window

When a GEM application is running, GEM AES and the application share
responsibility for drawing and managing windows. GEM AES is
responsible for all user interactions with any components present in
the window's border area. These components include the following:

 title bar
 move bar
o size box
* full box
o close box
o arrows, scroll bars, and sliders

The application is responsible for drawing and managing everything
that appears inside the window's work area.

2-9
GEM AES Programmer's Guide	2.13		Creating a Window

Making a window appear on the screen actually consists of twc3 steos:
creating the window and opening il:. 1-reatinc the window defines
what components will be present in the window; opening makes the
created window appear.

When the application makes		a WIND -- CREATE call,	it passes in a bit
vector with a bit set for each	border area component t- ' ne win6ow will
have. The application also		passes	in the size and location of the
window's greatest possible 		size.

The GEM Desktop application and the calculator desk accessory
illustrate how the WIND CREATE call works. (The calculator actually
appears in a window, although from the user's viewpoint, the
calculator and its window are indistinguishable.)

When the GEM Desktop makes a WIND - CREATE call, the bit is on for
(among others) the size box. This means the size box appears in the
GEM Desktop window's border area, and the user can chanqe the
window's size. In addition, the WIND_CREATE call defines the
window's largest size as the size of the GEM Desktop work area (all
of the screen below the menu ba--).

When the calculator desk accessory rakes a WIND-CREATE call, the bit
is off for the size box. No size box appears in the window's border
area, and the user cannot change the size of the window. The
WIND-CREATE call defines the window's greatest possible size (its
only size, because there is no size box) as nineteen characters wide
by thirteen characters high.

When an application makes a WIND - CREATE call, GEM AES returns a
window handle, a numeric identifier the application uses for all
future GEM AES calls.

2.14		Calculating Work Area or Outer Dimensions

Before issuing the WIND_OPEN call to open the window, the
application might need to make a WTND-CALC call to perform the
following calculation.

		Using the size and location of the window's outer dimensions
(including the border area) as input parameters, WIND-CALC returns
the size and location of the window's work area.

		Using the size and location of the window's work area as input
parameters, WIND - CALC returns the size and location of the
window's outer dimensions (including the border area).

In either case, WIND - CALC uses the same bit vector that WIND-CRFATE
used to identify the components of the window's border.

2-10
GEM AES Programmer's Guide		2.15	Opening a Window

2.15		Opening a Window

The WIND-OPEN call causes the window to appear on the screen.

In making the call, the application passes in the window handle from
WIND-CREATE and the initial size and location in which the window
will open.

The application determines the initial size and location. The
application can be written to remember a window's previous size and
location, or the application can specify that a window always open
in the same size and location.

When the application makes the WIND OPEN call, the GEM AES Screen
Manager draws the window's border area and then sends a message to
the application to draw the window's work area.

2.16		Slider Size and Location

If the work area of the window contains only part of the directory
or document ( if only a portion of the virtual amount of data is
visible in the physical window), the application makes a WIND SET
call to set the size and location of the vertical and/or horizo-ntal
sliders. A separate call is required for the size and location of
each slider.

The application makes similar WIND SET calls each time the size and
location of the sliders change.

2.17		Sizing a Window

When the user drags the window's size box, GEM AES is responsible
for displaying the rubber box that shows the user a preview of the
window's new size.

When the user releases the mouse button, GEM AES sends the
application a message containing the dimensions of the window the
user is requesting. The application must decide if the requested
size is valid.

If the requested size is valid, the application issues a WIND - SET
call to change the size of the window. If the new window is smafler
than the current window, the application does not have to redraw the
window's work area. If the new window is larger than the current
window, GEM AES sends the application a WM - REDRAW message requesting
that it redraw the contents of the window's work area.

If the requested size is not valid, the application must decide how
it responds to such a request. It can do any of the following:

2-11
GEM AES Programmer's Guide	~e.ll		Sizing a Window

 ignore the request

 automatically size the window to the nearest valid size

 display a dialog that informs the user the reajest is not. valid

if an application does not support a particular window function
(like sizing), it should not in its WIND CREATE call recuest the
'Sox) that supports this
window control point flike the size
function.

2.18		Rectangle List

An application is only responsible for redrawing and updating the
visiole portion of its windows. To keep track of the area for which
it is responsible, the application divides the visible por:1on of
each window's wDrk area into the fewest possible number of non
overlapping rectangles. For example, if the entire window is
visible, there is only one rectangle, the work area itself.

The application keeps a list of these rectangles by making a series
of WIND - GET calls, the first with an input value of WF FIRSTXYWH,
and the subsequent calls witri values of WF NEXT7YWH. The
aDolication continues making these calls until the rezurned width
an~ height values for the rectanqle are 0 (zero).

2.19		Before Updating a window

Before it uodates a window, an application must notifv GEM AES and
any other processes that an update is about to take place.

The application makes a WIND UPDATE call with a wi ubegend value of
1, which indicates the begiEnning of a window up3'atle. This call
freezes the rectangle lists of all windows except the one about to
be updated. The call also prevents menus and alerts from appearing
during window update.

When the update is complete, the application makes a WIND UPDATE
call with a wi ubegend value of 0 (zero) , which indicates the end of
a window upCate. This call frees the frozen rectangle lists,
allowing the other windows to change as required.

2.20		Redrawing the Work Area

when it redraws its window's work area, an application makes a
WIND-GET call to get the first rectangle in the rectangle list.

2-12
GEM AES Programmer's Guide			2.20	Redrawing the Work Area

The application then looks to see if the first rectangle has any
area in common with the "update rectangle," the part of the work
area that is to be redrawn. If so, the application redraws that
common area. If not, the application makes another WIND - GET call,
to get the next rectangle in the list. The application compares the
next rectangle with the update rectangle and again redraws any area
common to both rectangles.

The application continues this sequence of WIND GET calls,
comparisons, and redraws until it has gone through all the
rectangles in the rectangle list.

2.21		Making a Window Active

When the user presses the mouse button over a window, the
application--if it has made an EVNT MULTI call that includes a mouse
button event--receives a message i-rom the Screen Manager that the
button has been pressed.

The application then needs to find out where the button was pressed.
It makes a WIND FIND call, passing in the mouse's X- and Y
coordinates, whic-h were returned by the EVNT MULTI call. The
WIND-FIND call returns the window handle of the window tinder the
mouse pointer's position.

If the window handle is 0 (zero), the mouse pointer is on the GEM
Desktop, and the application is not responsible for the mouse button
event. The Screen Manager, assuming that the user intends to select
desktop icons, draws a rubber box on the GEM Desktop.

If the window handle identifies a inactive		window (including a desk
accessory window), the Screen Manager		sends a message to	the
application that owns the window. The		Screen Manager uses	the
predefined message WM - TOPPED, which tells		the application that	the
user has requested tl~at its window be brought to the top.

To bring the window to the top (make it "active"), the application
makes a WIND SET call with input values including the window's
handle and a c;de indicating that the window is to be brought to the
top.

2.22		Closing and Deleting a Window

When the user closes a window, either by interaction with the
window's border area or by choosing a command from a menu, the
Screen Manager sends a message to the application to close the
window. The application makes a WIND-CLOSE call, passing in the
handle of the window to be closed.

2-13
GEM AES Programmer's Guide			2.22	Closing and Deleting a Window

When the window is closed, its handle is still allocated to the
application. The application does not free the handle until it
makes a WIND-DELETE call.

The user cannot detect WIND_CREATE or WIND - DELETE; the user can onlv
detect WIND OPEN and WIND CLOSE. In most cases, an application will
make the cr7eate and open calls one immediately after the other, and
it will do the same with the close and delete calls. However, this
is optional.

Section 11, "Window Library," contains more details on specific
windowing techniques, as well as descriptions of the individual
Window Library calls.

End of Section 2

2-14
	Section 3
Application Library

3.1		Introduction

With a full multitasking operating system like Concurrent DOS, GEM
AES provides a desktop-style user interface that can have several
applications running at the same time. The applications appear in
windows that resemble overlapping sheets of paper. Whenever multiple
applications are running in a system simultaneously, the system
needs to be able to coordinate them. The Application Library's
routines make this kind of coordination possible.

GEM AES can extend a single-tasking operating system like PC DOS and
MS-DOS (version 2.0 and higher) to a limited multitasking form that
can simultaneously run a single foreground application and several
background applications. The foreground application can be one of
the following:

 a primary application like a word processing or drawing program
 a desk accessory like a clock/calendar or calculator

Background applications include print spoolers, network
communications drivers, and the GEM AES Screen Manager. The GEM AES
Screen Manager monitors the activities of the mouse when it is
outside the work area of the topmost window. The Screen Manager's
responsibilities include the following:

* drop-down menu interaction
* window border manipulation

In the limited multitasking environment, an internal GEM AES
dispatcher switches CPU time between the foreground application and
the background tasks, while the user switches CPU time between the
primary application and the desk accessories.

In both full and limited multitasking systems, an application must
first register with the Application Library before it can use the
other GEM subroutine libraries. The following sections describe the
routines that an application uses to interact with the Application
Library.

3-1
GEM AES Programmer's Guide			3.2	Using the Application ZAbrary

3.2		Using the Application Library

The Application Library controls access to the other GEM AES
subroutine libraries. Because multiple applications use these
subroutine libraries at the same time, eac~ subroutine must know
which application is requesting a service. The steos in the
following sequence illustrate the Application Library's role:

1.		An application is loaded into memory and starts executing.

2.		The application reserves the required space for the Global Array
(described in the next section) and makes a call 'to tell GEM AES
to initialize the space.

3.		The application enters its main body of code and runs until the
user reauests that it terminate.

4.		The application exits the Application Library.

5.		The application terminates.

The application should never tamper with the space it allocates for
GEM AES. The space contains global data structures that are vital
to the successful use of all GEM AES subroutines.

In addition to initialization, Application Library routines are also
responsible for message pipes (APPL - READ, APPL - WRITE, and
APPL-FIND). Section 4 contains a detailid description of message
pipes and other miscellaneous function calls.

3.3		Global Array

All of GEM AES's subroutines use the Global Array as a parameter.
The Global Array is 30 bytes long and contains the following
information:

global(O)			=	ap_version
global(l)			=	ap_count
global(2)			=	ap_id
global(3,4)			=	ap_.private
global(5,6)			=	ap_ptree
global(7,8)			=	ap_lresv
global(9,10)			=	ap_2resv
global(11,12)			=	ap-3resv
global(13,14)			= 	ap,_4resv

In the parameter definitions below, the code (G) indicates that GEM
AES supplies the value at the time of the APPL INIT call. The code
(A) indicates that the application supplies tFe value prior to the
APPL-INIT call.

3-2
GEM AES Programmer's Guide	3.3		Global Array

o		ap-version - (G) A WORD of data identifying the version of GE24 AES
being used.

o		ap-count - (G) A WORD of data specifying the maximum number of
applications this version of GEM AES supports concurrently.

o		ap_id - (G) A WORD of data containing a unique application
identifier that is in effect as long as the application remains in
the GEM AES application environment.

o		ap_private - (A) A LONG data value that is private to the
application and can hold any kind of information the application
requires.

a		ap_ptree - (A) A LONG address that points to the array of tree
	addresses initialized by the RSRC - LOAD call. This value should
	initially be zeroed by the application.

o		ap_lresv - (A) A LONG value that is reserved for future use and
should initially be zeroed by the application.

o		ap_2resv - (A) A LONG value that is reserved for future use and
should initially be zeroed by the application.

*		ap_3resv - (A) A LONG value that is reserved for future use and
should initially be zeroed by the application.

o		ap_4resv - (A) A LONG value that is reserved for future use and
should initially be zeroed by the application.

3.4 Application Library Routines

The Application Library provides the following routines:

o APPL-INIT		initializes a session with the Application Library

o			APPL READ	lets an application read a specified number of bytes
	from a message pipe

o		APPL WRITE - lets an application write a specified number of bytes
to a message pipe

o		APPL-FIND - finds the application identifier of another
application in the system

o		APPI, TPLAY - plays a piece of a GEM AES recording of the user's
actions

o		APPL TRECORD - records a set of the user's interactions with GEM
AES

o		APPL-EXIT - exits a session with the Application Library

3-3
GEN AES Programmer's Guide			3.4	Appilcation LIbrary xoutines

The following sections describe these routines.

In addition to the Global Array described in Section 3.3, each
Application Library routine has a GEM AES Parameter Block and a
Control Array that contain the following information:

GEM AES Parameter Block
	params(O)				=	long	address	(32	bits)	of	control array
	params(l)				=	long	address	(32	bits)	of	global array
	params(2)				=	long	address	(32	bits)	of	int in array
	params(3)				=	long	address	(32	bits)	of	int out array
	params(4)				=	long	address	(32	bits)	of	addr_in array
	params(5)				=	long	address	(32	bits)	of	addr-out array

	Control Array
	control(O)			=	op_code
	control(l)			=	size in WORDS of int_in array
	control(2)			=	size in WORDS of int out array
	control(3)			=	size in LONGS of addr - in array
	control(4)			=	size 'in LONGS of addr-out array

In addition, each routine contains some or all of the following
arrays:

		Integer Input ( int in) - Unless otherwise noted, each parameter in
this array is a W5-RD.

		Integer Output ( int_out) - Unless otherwise noted, each parameter
in this array is a WORD.

		Address Input (addr - in) - Unless otherwise noted, each parameter
in this array is a POINTER.

		Address Output (addr out) - Unless otherwise noted, each parameter
in this array is a -90INTER.

3-4
GEM AES Programmer's Guide		3.4 Application Library Routines

3.4.1		APPL-INIT

Purpose:

Initializes the application and establishes a number of internal
GEM AES data structures prior to calls to other Application
Library subroutines.

Parameters:

control(O)			=	10
control(l)			=	0
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int-out(O)			= 	ap-id

o		ap_id - If APPL - INIT was successful, ap - id is zero or a positive
number. GEM AES places this number in 'Ehe Global Array, and the
application uses it with future calls to Application Library
routines.

If APPL-INIT was not successful, the value of ap_id is -1. The
application should make no further Application Library calls.

Sample call to C language binding:

ap-id = appl_inito;

3-5
GEM AES Programmer's Guide			3.4	Application Library Routines

3.4.2		APPL-READ

Purpose:

Reads a specified number of bytes from a message pipe.

Parameters:

control(O)			=	11
control(l)			=	2
control(2)			=	1
controlM			=	1
control(4)			= 	0

int - in(O)			=	ap_rid
int-in(l)			= 	ap_rlength

int-out(O)			= 	ap_rreturn

addr-in(O)			= 	ap-rpbuff

e		ap_rid - the ap_id of the process whose message pipe the
application is reading (usually its own)

ap_rlength - the number of bytes to read from the message pipe

ap_rreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

ap_rpbuff - address of the buffer that will hold the bytes the
application is reading

Sample call to C language binding:

ap-rreturn = appl_read(ap_rid, ap_rlength, ap_rt)buff);

3-6
GEM AES Programmer's Guide			3.4	Application Library Routines

3.4.3		APPI, WRITE

Purpose:

Writes a specified number of bytes to a message pipe.

Parameters:

control(O)			=	12
control(l)			=	2
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int - in(O)			=	ap_yid
int-in(l)			= 	ap__ylength

int-out(O)			= 	ap_wreturn

addr-in(O)			= 	ap_wpbuff

		ap_wid - the ap - id of the process to which the application is
writing (usually not itself)

		ap_ylength - the number of bytes to write to the message pipe

		ap_wreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

		ap_wpbuff - address of the buffer holding the bytes that will be
written

Sample call to C language binding:

ap._yreturn = appl-write(ap__wid, ap_wlength, ap_wpbuff);

3-7
GEM AES Programmer's Guide			3.4	Application Library Routines

3.4.4 APPL-FIND

Purpose:

Finds the ap_id of another application in the system.

The application must know the ap_id before it can establish
communications with the other application.

Parameters:

control(O)			=	13
control(l)			=	0
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-out(O)			= 	ap_fid

addr-in(O)			= 	ap_fpname

e		ap_fid - The ap_id of the application for which the current
application is searching.

-1 - GEM AES could not find the application

e		ap_fpname - Address of a null-terminated string containing the
filename of the application for which the current application is
searching.

The string must be 8 characters long. If the filename has fewer
than 8 characters, the programmer must fill out the rest of the
string with blank spaces.

Sample call to C language binding:

ap_fid = appl_find(ap_fpname);

3-8
GEM AES Programmer's Guide			3.4	Application Library Routines

3.4.5		APPL-TPLAY

Purpose:

Plays a piece of a GEM AES recording of the user's actions.

Parameters:

control(O)			=	14
control(l)			=	2
control(2)			=	I
control(3)			=	1
control(4)			= 	0

int - in(O)			=	ap-tpnum
int-in(l)			= 	ap-tpscale

int-out(O)			= 	ap_tpreturn

addr-in(O)			= 	ap-tpmem

		ap_tpnum - the number of user actions to play back

		ap_tpscale - a sliding scale (from 1 to 10,000) determining the
speed at which GEM AES plays back the user's actions, for example:

	50 = half speed
100 = full speed
200 = twice speed

		ap_tpreturn - always equals 1 (one)

		ap_~tpmem - the address of the area in memory holding the recording
of user events that GEM AES will play back

Sample call to C language binding:

ap-tpreturn = appl_tplay(ap_tpmem, ap-tpnum, ap_tpscale);

3-9
GEM NES Programmer's Guide			3.4	Application Library Routines

3.4.6		APPL-TRECORD

Purpose:

Records a set of the user's interactions with GEM AES.

Each user event uses six bytes in memory, divided into a WORD and
* 'ONG value as follows:

*		The WORD contains a code for the event (as defined by "be Event
Library) that occurred.

0 = timer event
I = button event
2 = mouse event
3 = keyboard event

*		The LONG value's meaning depends on the type of event that was
recorded.

-		timer event: The number of milliseconds elapsed.

-		1~utton event: The LOW WORD is the button state (0 = button ur,1
	1 = button down). The HIGH WORD is the number of clicks.

-		mouse event: The LOW and HIGH WORD are the mouse's X- and Y
coordinates in pixels, respectively.

-		keyboard event: The LOW WORD contains tie character r-be user
typed. The HIGH WORD contains the keyboard state.

Parameters:

control(O)			=	15
control(l)			=	1
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-in(0)			= 	ap_trcount

int-out(O)			= 	ap-trreturn

addr-in(O)			= 	ap_trmem

3-10
GEM AES Programmer's Guide		3.4 Application Library Routines

o		ap_trcount - The number of user events that the application can
store. This number equals the available storage space (in bytes)
divided by the 6 bytes used by each event.

o		apL_trreturn - The number of user events the application recorded.

o		ap_trmem - The address of an area in memory where the recorded
user events will be stored.

Sample call to C language binding:

ap-trreturn = appl_trecord(ap_trmem, ap_trcount);

3-11
GEM AES Programmer's Guide			3.4	Application Library Routines

3.4.7		APPL-EXIT

Purpose:

Lets the Application Library clean up its environment when an
application is done making Application Library calls.

Parameters:

control(O)			=	19
control(l)			=	0
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int-out(O)			= 	ap_xreturn

e ap_xreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

Sample		call to C language binding:

ap_xreturn = appl_exito;

End of Section 3

3-12
	Section 4
Event Library

4.1		Introduction

An interactive application must be able to respond quickly to
several types of user input, including the following:

		typing on a keyboard

		clicking a mouse button

		moving a mouse

		choosing a menu command

		manipulating a control point on the border of a window

		doing nothing when something is expected (that is, the lack of
input)

GEM AES refers to these types of user input as "events" and provides
application writers with an Event Library, consisting of routines
that monitor events. These routines can significantly increase the
speed and efficiency of the application.

4.2		Using the Event Library

The Event Library lets an application get input from the keyboard
and mouse, other programs in the system, and the system itself. In
most programming interfaces available for developing desktop-style
applications, the programmer must write an application that spins in
a tight loop polling the keyboard, mouse, message pipe (described in
Section 4.2.5), and clock. This type of polling will exhaust the
resources of a multitasking system.

The Event Library avoids this problem by letting the application
tell the operating system what types of events to wait for. The
operating system can let other programs run, and it need only
activate the application when one or more of the desired events has
occurred.

The Event Library lets an application wait for any of the following
events:

o keyboard event - The user presses a key.

o mouse button event - The user presses or releases a mouse button.
-- -- riogrammer s uulae		4.Z	Using the Event Library

		mouse event - The user moves the mouse into or out of a specified
rectangle.

		message event - An application receives a message from another
process.

timer event - The preset timer amount expires.

multiple event - Any combination of the other events.

4.2.1		Waiting for Multiple Events

If an application were to wait only for a single type of event, it
would not respond to events of any other type. An application needs
to be able to wait for one or more of a specified set of events.
The Event Library makes this possible.

When any or all of the events in the set occur, the Event Library
notifies the application and returns a value that identifies the
events that have occurred. The application uses this value to
determine how it should process the events.

After processing the event or events, the application typically
specifies another set of events, calls the Event Library, and then
awaits notification that one of the new set of events has raken
place. While the application is awaiting notification, the svstem
can share CPU time with other processes that are ready to rin.

4.2.2		Keyboard Event

GEM AES recognizes a standard keyboard. The definition of this
keyboard is the same as the hardware standard implied in the IBM,!, PC
ROM BIOS documented in the GEM Programmer's Guide, Volume 1: VD1.

These keyboard events are encoded in a 16-bit form of console input.
The state of the Ctrl, Shift, and Alt keys is also available by
making the GEM A-ES GRAF-MKSTATE function call.

4.2.3		House Button Event

GEM AES lets an application wait for a specified mouse button or set
of buttons to enter a specified state (down or up).

A mask word performs a logical AND operat'~on on the bits
representing the mouse buttons the application wants to ignore. For
example, on a three-button mouse, a mask word value of 001 indicates
that the application only cares about input from the button on the
left. (The left button is represented by the Least Significant
Bit.)
GEM AES Programmer's Guide			4.2	Using the Event Library

State words indicate the state of the mouse buttons, both current
and desired. For example, a current state word value of 001
indicates that the user has pressed the left button.

A mouse button event takes place when the following equation is
true:

(current-state AND mask) = desired-state

For example, if the user presses the left button and that is what
the application is waiting for, a mouse button event takes place.
In that case the equation reads:

(001 AND 001) = 001

The application can also wait for the mouse button to enter the
desired state a specified number of times in a set interval. One
occurrence in the interval is referred to as a "click"; two
occurrences are called a "double-click."

The Event Library returns to the application the number of times the
mouse button entered the desired state in the interval. The number
returned is always at least 1 (one) and never more than the number
desired by the application.

4.2.4		House Event

Several kinds of mouse movement can cause an application to change
the appearance of the screen, including the following:

 dragging an icon over the desktop
 drawing a rubberband line or rectangle
 moving the mouse form into a sensitive region

 Mouse Event occurs when the mouse is either inside or outside a
pixel-aligned rectangle. For example, using a Mouse Event, an
application can change the mouse form from an arrow to a cross hair
whenever the mouse is inside a certain area of the screen. The
application waits for the Mouse Event that indicates that the mouse
is inside a certain rectangle on the screen. When the mouse enters
the rectangle, GEM AES notifies the application. The application
makes a GRAF MOUSE call to change the mouse form to a cross hair,
and then disengages to wait for the mouse to exit the rectangle.

As long as the mouse remains in the rectangle, the application is
inactive. As soon as the mouse exits, GEM AES reactivates the
application so it can change the mouse form back to an arrow.

The size of this critical rectangle depends on the resolution that
is required for the mouse response. For example, dragging objects
that can be placed on arbitrary pixel boundaries requires a
rectangle that is one pixel high and one pixel wide. However, most
applications, including graphics applications that use a grid for
aligning elements, do not always require such fine resolution. For

4-3
GEM AES Programmer's Guide		4.2	Using the Even" Library

exanple, inverting the items in a menu requires a resolution equal
to the size of the menu item in which the mouse form is located.

Systems can achieve significant improvements in overall throughput
if the amount of mouse motion significant for each action determines
the size of each of the application's mouse event rectangles.

4.2.5		Message Event

The GEM AES programming environment provides a user interface in
which applications use separate overlapping windows. The windows
reside on the physical screen, which looks like a gray desktop with
a menu bar running across the top. The window that is on top and
has control of the keyboard is called the "active window."

The application that owns the active window provides GEM, AES with
the following:

		a set of menus that appears in the menu bar

		the title that GEM AES places in the top border of the
application's window

		the kinds of window control points including the close box, full
box, and size box to which the application will respond

To ensure a consistent user interface and increase programmer
productivity, GEM AES manages all interactions with the user during
menu selection and window border manipulation. -However,
applications need to know the results of these external user
interactions. To provide this information, GE24 AES uses Message
Events.

To receive notification of external events, applications use a
standard message pipe. A Message Event occurs when an application
receives a message in its message pipe.

Messages come in a standard format defined by the GELM AES Message
Protocol and are placed in an application's message pipe in First
In-First-Out (FIFO) order. Each time an application reads a message
in its message pipe, GEM AES removes the~ message from the pipe.

4.2-5.1		Predefined GEM AES Messages

GEN AES provides several predefined message types. Each type has a
maximum length of 16 bytes. All the predefined message types define
the first three words in the same way:

4-4
GEM AES Programmer's Guide			4.2	Using the Event Library

		word 0 - A number identifying the message type.

		word 1 - The ap_id of the application that sent the message.

		word 2 - The length of the message, not counting the predefined 16
bytes. If the value of word 2 is not 0 (in other words, if the
message is longer than 16 bytes), the application should use an
APPL-READ call for the remainder of the message.

4.2.5.2		MN-SELECTED

GEM AES uses this message to notify an application that a user has
selected a menu item.

 word 0 = 10
 word 3 = the object index of the menu title selected
 word 4 = the object index of the menu item selected

4.2.5.3		WK-REDRAW

GEM AES uses this message to tell an application that a user has
taken an action that requires redrawing part of the work area of its
window. The work area is the part of the window exclusive of the
title bar, information line (if any), and border area.

 word 0 = 20

 word 3 = the handle of the window to redraw

 word 4 =		X-coordinate of the portion of the redraw area to redraw
(in screen coordinates)

 word 5 =		Y-coordinate of the portion of the redraw area to redraw
(in screen coordinates)

 word 6 =		width of the portion of the redraw area to redraw (in
screen coordinates)

 word 7 =		height of the portion of the redraw area to redraw (in
screen coordinates)

4.2.5.4		WM-TOPPED

GEM AES uses this message to tell the application that the user has
requested its window or another application's window be moved to the
top (made active).

o word 0 = 21
o word 3 = the handle of the window

4-5
GEM AES Programmer's Guide		4.2	Using the Event Library

4.2.5.5		WM-CLOSED

GEM AES uses this message to tell an application that the user has
requested that its window be closed.

word 0 = 22
word 3 = the handle of the window

4.2.5.6		WM-FUTJ-3?

GEM AES uses this message to tell an application that the user has
clicked the mouse button in the window's full box, either to enlarge
the window to its fullest possible size or, if the window is alrea3y
full, to return it to its previous size.

word 0 = 23
word 3 = the handle of the window

4.2-5.7		WM-ARROWED

GEM AES uses this message to tell an application that the user has
clicked in the arrows or scroll bars in the window's border area.

word 0 = 24
word 3 = the handle of the window
9 word 4 = the action requested by the user as follows:

0		page up
1		page down
2		row up
3		row down
4		page left
5 =		page right
6 =		column left
7 =		column right

The user invokes the page actions by clicking on the scroll bars.
The row and column actions are invoked when the user clicks on the
arrows. Section 11 .2 .1, "Components of the Border Area, " describes
scrolling in detail.

4.2-5.8 WM-HSLID

GEM AES uses this message to tell an application the new position
the user has requested for the horizontal slider.

word 0 = 25
word 3 = the handle of the application's window

4-6
GEM AES Programmer's Guide			4.2	Using the Event Library

word 4 =		a number from 0 to 1000, indicating the requested slider
position

0 = leftmost position
1000 = rightmost position

4.2.5.9 WM_VSLID

GEM AES uses this message to tell an application the new position
that the user has requested for the vertical slider.

 word 0 = 26

 word 3 = the handle of the application's window

 word 4 =		a number from 0 to 1000, indicating the requested slider
position

0 = top position
1000 = bottom position

4.2.5.10		MM-SIZED

GEM AES uses this message to give an application its window's new
coordinates when the user@,requests a change in the window's size.
The coordinates include the window's title bar, information line ( if
any), and borders.

o word 0 = 27
e word 3 = the handle of the window

o word 4 =		the requested X-coordinate (should remain the same as the
window's current X-coordinate)

e word 5 =		the requested Y-coordinate (should remain the same as the
window's current Y-coordinate)

e word 6 = the requested width

* word 7 = the requested height

4-2-5-11		WM-MOVED

GEM AESPuses this message to give an application its window's new
coordinates when the user requests a change in the window's
position. The coordinates include the window's title -bar,
information line (if any), and borders.
GEM AES Programmer's Guide		4.2	Using the Event Library

word 0 = 28
word 3 = the handle of the window
word 4 = the requested X-coordinate
word 5 = the requested Y-coordinate

9 word 6 =		the requested width (should remain the same as the
window's current width)

o word 7 =		the requested height (should remain the same as the
window's current height)

4.2.5.12		AC-OPEN

GEM AES sends this message to a desk accessory when the user selects
it from the Desk Menu.

word 0 = 30

word 3 =		me rmenuid: the desk accessory menu item identifier
returned by the MENU-REGISTER call

4.2.5.13		AC-CLOSE

GEM AES sends this message to a desk accessory when the following
set of conditions exists:

o		The current application has just terminated.
The screen is about to be cleared.
Window Library data structures are about to be reinitialized.

The desk accessory should zero any window handle it currently owns.

word 0 = 31

word 3 =		me - rmenuid: the desk accessory menu item identifier
returned by the MENU-REGISTER call

4.2.6		Timer Event

An application sometimes needs to wait a certain amount of time
before proceeding. For example, the application might be displaying
a message that must remain on the screen for a maximum of three
seconds. To gauge the time, the application can poll the system
clock or do a large number of difficult, hardware-specific
calculations. However, both of these methods are inefficient in a
multitasking system in which processes can make good use of each
other's delay time.

4-8
GEM AES Programmer's Guide			4.2	Using the Event Library

By using Timer EventSr GEM AES provides a more efficient method. A
Timer Event occurs when a programmer-specified number of
milliseconds has passed since the Timer Event was started.

4.3		Event Library Routines

The Event Library provides the following routines:

 EVNT KEYBD - waits for a keyboard event
 EVNT BUTTON - waits for a mouse button event
 EVNT MOUSE - waits for a mouse event
 EVNT MESAG - waits for a message event
 EVNT TIMER - waits for a timer event
 EVNT - MULTI		- waits for multiple events
 EVNT-DCLICK - sets and gets the speed required for double-clicking

The following sections describe these routines.

Each Event Library routine has a GEM AES Parameter Block, Control
Array, and Global Array that contain the following information:

GEM AES Parameter Block
	params(O)					=	long	address	(32	bits)	of	control array
	params(l)					=	long	address	(32	bits)	of	global array
	params(2)					=	long	address	(32	bits)	of	int in array
	params(3)					=	long	address	(32	bits)	of	int out array
	params(4)					=	long	address	(32	bits)	of	addr in array
	params(5)					=	long	address	(32	bits)	of	addr-out array

	Control Array
	control(O)			=	op_code
	control(l)			=	size in WORDS of int in array
	control(2)			=	size in WORDS of int out array
	control(3)			=	size in LONGS of addr in array
	control(4)			=	size in LONGS of addr-out array

4-9
	k~mm i-ma rruqLammer-s uulae		4	j zvent LijDrarY Routines

Global Array
	global(O)			=	ap version
	global(l)			=	ap-count
	global(2)			=	ap-id
	global(3,4)			=	ap private
	global(5,6)			=	ap-ptree
	global(7,8)			=	ap_lresv
	global(9,10)			=	ap_2resv
	global(11,12)			=	ap 3resv
	global(13,14)			= 	ap-4resv

Global Array parameters are described in Section 3.

Each routine also contains some or all of the following arrays:

Integer Input (int in) - Unless otherwise noted, each parameter in
this array is a W(5RD.

Integer Output (int I out) - Unless otherwise noted, each parameter
in this array is a WORD.

Address Input (addr - in) - Unless otherwise noted, each parameter
in this array is a POINTER.

Address Output (addr ' out) - Unless otherwise noted, each parameter
in this array is a :~OINTER.

4-10
GEM AES Programmer's Guide			4.3	Event Library Routines

4.3.1 EVNT-KEYBD

Purpose:

Notifies GEM AES that the application is waiting for any kind of
keyboard input.

Parameters:

control(O)			=	20
control(l)			=	0
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int-out(O)			= 	ev-kreturn

e		ev kreturn - the standard keyboard code for the values returned in
AfFand AL, as defined by the IBM PC DOS ROM BIOS

Sample call to C language binding:

ev-kreturn = evnt-keybdo;
GEM AES Programmer's Guide		4.3	Event Library Routines

4.3.2		EVNT-BUTTON

Purpose:

Notifies GEM AES that the application is waiting for a particular
mouse button state.

Parameters:

control(O)			=	21
control(l)			=	3
control(2)			=	5
control'(3)			=	0
control(4)			= 	0

int in(O)			=	ev bclicks
int in(l)			=	ev bmask
int-in(2)			= 	ev-bstate

int out(O)			=	ev breturn
int out(l)			=	ev bmx
int out(2)			=	ev-bmy
int out(3)			=	ev bbutton
int-out(4)			= 	ev-bkstate

		ev bclicks the number of times the application is waiting for
the mouse button to enter a particular state (ev-bstate) within a
preset time

		ev-bmask - the mouse buttons the application is waiting for

GEM AES can theoretically support 16 mouse buttons.

in ev - bmask, ev - bstate, and ev-bbutton, the following bits
represent the buttons:

OxOO01 - button on left
OxOO02 - second button from left
DxOO04 - third button from left, etc.

These parameters use the following bit settings:

0 - button up
1 - button down

ev-bstate - The button state for which the application is waiting.

ev breturn - The number of times the button actually entered the
desired state within the preset time. This number is never less
than 1 or greater than the number contained in ev-bclicks.

ev bmx - The X-coordinate of th'~ mouse oointer when the user event
occurred.

4-12
GEM AES Programmer's Guide			4.3	Event Library Routines

		ev - bmy - the Y-coordinate of the mouse pointer when the user event
	occurred.

		ev-bbutton The mouse button state when the user event occurred.

		ev bkstate The state of the keyboard's right-Shift, left-Shift,
Ctrlr and Alt keys when the user event occurred.

The following bits represent the keys:

OxOO01 - right-Shift
OxOO02 - left-Shift
OxOO04 - Ctrl
OxOO08 - Alt

This parameter uses the following bit settings:

0 - key up
1 - key down

Sample call to C language binding:

ev-breturn = evnt-button(ev-bclicks, ev-bmask,
ev - bstate, &ev - bmx, &ev-bmy,
&ev_bbutton, &ev-bkstate);

4-13
GEM AES Programmer's Guide		4.3	Event Library Routines

4.3.3		EVNT-MOUSE

Purpose:

Notifies GEM AES that the application is waiting for the mouse to
enter or leave a specified rectangle.

Parameters:

control(O)			=	22
control(l)			=	5
control(2)			=	5
control(3)			=	0
control(4)			= 	0

int in(O)			=	ev moflags
int in(l)			=	ev mox
int in(2)			=	ev-moy
int in(3)			=	ev mowidth
int-in(4)			= 	ev-moheight

int - out(O)			=	ev-moresvd
int - out(l)			=	ev_momx
int - out(2)			=	ev_momy
int out(3)			=	ev mobutton
,nt-out(4)			= 	ev-mokstate

 ev_moflags		flags for the call

OxOOOO - return on entry
OxOO01 - return on exit

		ev-mox - The X-coordinate of the mouse rectangle in pixel-based
screen coordinates.

		ev_moy - The Y-coordinate of the mouse rectangle in pixel-based
screen coordinates.

		ev-mowidth - The width of the mouse rectangle in Dixel-based
screen coordinates.

		ev_moheight - The height of the mouse rectangle in pixel-based
screen coordinates.

ev-moresvd - RESERVED; value always equals 1 (one).

ev-momx - The X-coordinate of the mouse ;Dointer when the user
event occurred.

ev_momy - The Y-coordinate of the mouse pointer when the user
event occurred.

ev-mobutton - The mouse button state when the user event occurred.

4-14
GEM AES Programmer's Guide			4.3	Event Library Routines

The following bits represent the buttons:

OxOO01 - button on left
OxOO02 - second button from left
OxOO04 - third button from left, etc.

This parameter uses the following bit settings:

0 - button up
1 - button down

ev mokstate - The state of the keyboard's right-Shif t, lef t-Shif t,
Ct-rl, and Alt keys when the user event occurred.

The following bits represent the keys:

OxOO01 - right-Shift
OxOO02 - left-Shift
OxOO04 - Ctrl
OxOO08 - Alt

This parameter uses the following bit settings:

0 - key up
1 - key down

Sample call to C language binding:

ev-moresvd = evnt-mouse(ev-moflags, ex_mox, ev_moy,
ev mowidth, ev moheight,
&ev_momx, &ev-momy,
&ev-mobutton, &ev-mokstate);

4-15
GEM AES Programmer's Guide		4.3	Event Library Rautlnes

4.3.4		EVNT-MESAG

Purpose:

Notifies GEM AES that the application is waiting for a standard
16-byte message in the message pipe.

Using message pipes to communicate between processes in the system
is very flexible and makes possible many different types of
messages in the 16-byte messag; buffer. For these messages to be
meaningful to the receiving application, a well-defined set of
message protocols must exist. GEM AES provides several pre6efined
messages, which are described in Section 4.2.5.

Parameters:

control(O)			=	23
control(l)			=	0
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-out(O)			= 	ev-mgresvd

addr-in(O)			= 	ev-mgpbuff

ev_mgresvd - RESERVED; value alwavs equals 1 (one).

ev mgpbuff - Address of the buffer where the message -will ne
placed. its size must be 16 bytes.

Sample		call to C language binding:

ev-mgresvd = evnt-mesag(ev-mgpbuff);

4-16
GEM AES Programmer's Guide			4.3	Event Library Routines

4.3.5		E"T-TIMER

Purpose:

Notifies GEM AES that the application is waiting for a specified
amount of time to pass.

Parameters:

control(O)			=	24
control(l)			=	2
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int in(O)			=	ev tlocount
int-in(l)			= 	ev-thicount

int-out(O)			= 	ev-tresvd

 ev-tlocount - LOW WORD of a LONG value.

 ev-thicount - HIGH WORD of a LONG value.

Combined, ev - tlocount and ev-thicount are the length of the time
interval in milliseconds.

 ev-tresvd - RESERVED; value always equals 1 (one).

Sample		call to C language binding:

ev-tresvd = evnt-timer(ev-tlocount, ev-thicount);

4-17
GEM AES Programmer's Guide		4.3	Event Library Routines

4.3.6		EVNT-?4ULTI

Purpose:

Notifies GEM AES that the application is waiting for one or more
events at the same time.

Parameters:

control(O)			=	25
control(l)			=	16
control(2)			=	7
control(3)			=	1
control(4)			= 	0

int in(O)			=	ev mflags
int in(l)			=	ev mbclicks
int in(2)			=	ev mbmaSK
int in(3)			=	ev mbstate
int in(4)			=	ev mmlflags
int in(5)			=	ev mmlx
int in(6)			=	ev mmly
int in(7)			=	ev mmlwidth
int in(8)			=	ev mmlheight
int in(9)			=	ev_mm,2flags
int--4n(10)			=	ev-mm2x
int in(ll)			=	ev mm2y
int in(12)			=	ev mm2width
int in(13)			=	ev mm2height
int in(14)			=	ev_mtlocount
int-in(15)			= 	ev-mthicount

int out(O)			=	ev mwhich
int-out(l)			=	ev-mmox
int out(2)			=	ev_mmoy
int out(3)			=	ev mmobutton
int out(4)			=	ev mmokstate
int out(5)			=	ev mkreturn
int-out(6)			= 	ev-mbreturn

addr-in(C)			= 	ev_mmgpbuff

Many of the EVNT MULTI parameters are defined under the other
Event Library rou7~ines. For example, the parameter ev mbclicks
corresponds to "he parameter ev bclicks, defined undE-r the
EVNT-BUTTON routine. Unique paramJters are defined below.

The two sets of mouse event parameters, ev mml ... and ev rr~m2...,
describe two distinct mouse rectangles. These parameters
correspond to the X, Y, width, and height parameters (ev-mox,
etc.) described under the EVNT-MOUSE routine.
GEM AES Programmer's Guide			4.3	Event Library Routines

 ev-mf lags - the type of event for which the application is waiting

This call uses the following bit settings:

OxOO01 - MU KEYBD
OxOO02 - MU BUTTON
OxOO04 - MU Ml
OxOO08 - MU M2
OxOO10 - MU MESAG
OxOO20 - MU-TIMER

 ev-mwhich - the event(s) in ev-mflags that actually occurred

This call uses the following bit settings:

OxOO01 - MU KEYBD
OxOO02 - MU BUTTON
OxOO04 - MU Ml
OxOO08 - MU M2
OX0010 - MU MESAG
OxOO20 - MU-TIMER

Sample call to C language binding:

ev-mwhich = evnt-multi(ev-mflags, ev-mbclicks, ev-mbmask,
	ev mbstate, ev mmlflags,
	ev__mmlx, ev_mmly, ev-mmlwidth,
	ev-mmlheight, ev-mm2flags,
	ev - mm2x, ev_=2y, ev-mm2width,
	ev - mm2height, ev-mmgpbuff,
	ev - mtlocount, ev-mthicount,
	&ev_mmox, &ev - mmoy,
	&ev - mmobutton, &ev-mmokstate,
	&ev_mkreturn, &ev-mbreturn);

4-19
L;Epl A.LA6 Pluylaltuuel S GUIULS		4 . J LVL311L LiULALY AUULiHRS

4.3.7		EVNT-DCLICK

Purpose:

Gets the current setting of the mouse button's double-click speed
or sets a new double-click speed for the mouse button.

Parameters:

control(O)			=	26
control(l)			=	2
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int in(O)			=	ev dnew
int-in(l)			=	ev-dgetset

int-out(O)			= 	ev-dspeed

		ev-dnew - the new double-click speed the user has selected

This parameter has integer values from 0 ~zero) to 4 that
correspond to the SLOW-2-3-4-FAST settings of the selection
buttons in the GEM Desktop's SET PREFERENCES dialog.

		ev_dgetset - the purpose of the call

1 = set a new double-click speed
0 = get the current double-click speed

If the value of ev - dgetset is 0, EVNT-DCLICK disregards the
ev-dnew value in the call.

		ev_dspeed - the double-click speed, either newly set (ev-dgetset
1) or already existing (ev_dgetset = 0)

This parameter uses the same integer values as ev-dnew.

Sample call to C language binding:

ev_dspeed = evnt-dclick(ev-dnew, ev_dgetset);

End of Sectinn 4

4-20
	Section 5
Menu Library

5.1		Introduction

Menus represent groups of options a user can choose within an
application. Menus commonly appear as some form of text list.

Each GEM application defines its own menus. When an application is
active (controls the keyboard and mouse), GEM AES displays the
titles of its menus in a menu bar at the top of the screen.

To select a menu, the user places the mouse form over the menu's
title in the menu bar. This causes the menu to drop down. The menu
appears in a rectangle below the menu bar and remains visible until
the user clicks the mouse button.

Figure 5-1 illustrates a typical menu.

M View Options

.. ... .... . I . .... ... ...
New Folder ...
Close
Close Window
. ... .... ... . .... ... .... ... .... ...

To Output
Quit

Figure 5-1. Typical Menu

5-1
ULM AES Programmer's Guide	S.1 		Introduction

The standard menu item is a text string that names the menu command.
In addition, a menu item can contain either of the following:

		A space for a check mark to the left of the menu item.

A check mark indicates that a certain condition is in eff-'ect. For
example, in a menu of text fonts, a check mark next to the name of
a font indicates that user-entered text will appear in that font.

		A character identifying a key that produces the same result as
choosing the menu item.

The user can press the key instead of displaying the menu and
choosing an item. The character appears on the menu to identify
this shortcut.

Depending on the current state of the application, menu items can
appear in either of two states: enabled (car be chosen) or d~sabled
(cannot be chosen). Menu items are enabled only when choosing them
is meaningful to the application. For example, the File Menu
command Open is enabled if the user has selected an icon and is
disabled if the user has not selected an icon.

The Menu Library displays enabled items in standard character
brightness; it displays disabled items in dimmed characters.

Responsibility for the user's interaction with menus is shared by
the Screen Manager and the Menu Library.

The application uses a Menu Library call to display its menu bar,
and it uses Menu Library calls to enable or disable menu 'items and
to display check marks in a menu.

After making a RSRC LOAD call to bring menu data into memory, and a
MENU - BAR call to i-isplay the menu, the application waits for a
message from its message pipe. If the user touches a menu title
with the mouse form, the Screen Manager does the following:

		It highlights the menu title in reverse video.

		It displays the menu items in a rectangle that appears below the
title.

As the user moves the mouse form up and down the menu, t:ne Screen
Manager uses reverse video to highlight eatch enabled item as the
mouse form touches it. The item remains highlighted as long as the
mouse form is in contact with it.

5-2
GEM AES Programmer's Guide	5.1 		Introduction

To choose a menu item, the user clicks the mouse button while the
mouse form is over an enabled item. The Screen Manager removes the
drop-down portion of the menu from the screen and writes a message
to the pipe. The application reads the message and acts
accordingly.

When the chosen action has been performed, the calling application
makes a Menu Library call to change the menu title back to its
normal state.

If the user chooses a menu item by using the keyboard shortcut
described previously, the application makes a Menu Library call both
to highlight the menu title and to return it to its normal state.
Section 2.11 describes keyboard menu selection in greater detail.

A		menu remains visible until the user clicks the mouse button.

If the user moves the mouse form outside the menu rectangle, the
Screen Manager dehighlights the currently highlighted item ( if any).
If the user moves the mouse form back into the rectangle, the Screen
Manager again highlights enabled items as the mouse form touches
them.

If the user clicks the mouse button outside the rectangle, the
Screen Manager removes the drop-down portion of the menu from the
screen. No item is chosen, and no message is written to the pipe.
To redisplay the menu, the user must move the mouse form back to the
menu bar and select the menu title.

The Menu Library has two additional special functions. First, it
supports context-sensitive text in menus. An application can change
the wording of its menu items depending on the application's current
state. Second, desk accessories use a Menu Library call to make
their names appear on the Desk Menu, which is where the user starts
them.

The Menu Library offers distinct advantages to both programmer and
user:

		The programmer can create menus that meet the unique requirements
of individual applications.

		The programmer does not have to be concerned with manipulating the
interaction between menu and mouse.

		The programmer can modify menus and/or menu items in an efficient
and timely manner.

		The user can expect all GEM AES application menus to be familiar,
both in appearance and function.

5-3
Ut;M AEb Programmer's Guide		5.2	Using the Menu Library

5.2		Using the Menu Libraxy

The Menu Library is intended to relieve the application of the
overhead of handling the interaction between mouse and menu. The
Menu Library has the following responsibilities:

displaying the appropriate menu bar for each active application
enabling and disabling menu items
displaying check marks in menus
returning a highlighted menu title to its normal state
displaying context-sensitive menu text
o displaying a desk accessory's name on the Desk Menu

The application need only do the following:

1.		Create a menu object tree. (The data for each menu is contained
in an object structure, described in Section 6.3.1. The current
state of the application determines whether a check mark appears
in the menu and whether an item is enabled.)

2.		Add the menu object tree to a resource file.

3.		Load the menu ob~ect tree into memory, using the Resource
Library's RSRC-LOAI; call.

4.		Call the MENU-BAR routine to have the Menu Library display the
menu titles across the top of the desktop.

After the application has completed the above steps, the menu titles
are visible in the menu bar, and the individual menus are ready for
user interaction.

The application's major task is to establish the menu resource file.
The information in the resource file determines the menu title's
location on the menu bar and the location of the menu rectangle
below the menu title.

When the user chooses an item, the Screen Manager writes a m,~ssage
to the pipe. Control then returns to the application, which must
read the pipe.

The pipe message contains the following:

a code indicating that it is a menu message
the object index of the menu title selected
the object index of the menu item chosen

(If the user does not choose an item, the Screen Manager does not
write a message to the pipe.)

5-4
GEM AES Programmer's Guide	5.2		Using the Menu Library

After processing the chosen item, the application makes a Menu
Library call to dehighlight the menu title and waits for the next
message to come through the message pipe.

oo--
5.3 Menu Library Routines

The Menu Library uses the following routines:

		MENU-BAR - displays or erases the menu bar

		MENU-ICHECK displays or erases check mark next to a menu item

		MENU IENABLE displays an enabled item in normal brightness and a
dis~bled item in dimmed characters

		MENU-TNORMAL - displays menu title in normal or reverse video

		MENU-TEXT - changes the text of a menu item

		MENU REGISTER - lets a desk accessory set a text string on the
Desk Menu and obtain a desk accessory identifier

The following sections describe these routines.

Each Menu Library routine has a GEM AES Parameter Block, Control
Array, and Global Array that contain the following information:

GEM AES Parameter Block
	params(O)			=	long	address	(32	bits)	of	control array
	params(l)			=	long	address	(32	bits)	of	global array
	params(2)			=	long	address	(32	bits)	of	int in array
	params(3)			=	long	address	(32	bits)	of	int out array
	params(4)			=	long	address	(32	bits)	of	addr - in array
	params(5)			=	long	address	(32	bits)	of	addr-out array

	Control Array
	control(O)			=	op_code
	control(l)			=	size in WORDS of int in array
	control(2)			=	size in WORDS of int out array
	control(3)			=	size in LONGS of addr - in array
	control(4)			=	size in LONGS of addr-out array

5-5
GEM AFS Programmer's Guide		5.3	Menu Library Routines

Global Array
	global(O)			=	ap_version
	global(l)			=	ap__count
	global(2)			=	ap id
	global(3,4)			=	aj~:private
	global(5,6)			=	ap_ptree
	global(7,8)			=	ap~_lresv
	global(9,10)			=	ap_2resv
	global(11,12)			=	ap__3resv
	global(13,14)			= 	ap_4resv

Global Array parameters are described in Section 3.

Each routine also contains some or all of the following arrays~

		Integer Input ( int_in) - Unless otherwise noted, each parameter in
this array is a WORD.

		Integer Output ( int - out) - Unless otherwise noted, each parameter
	in this array is a WORD.

		Address Input (addr_in) - Unless otherwise noted, each parameter
in this array is a POINTER.

		Address Output (addr out) - Unless otherwise noted, each parameter
in this array is a TOINTER.

5-6
GEM AES Programmer's Guide			5.3	Menu Library Routines

5.3.1		MENU-BAR

Purpose:

Displays or erases the application's menu bar.

The application should always call MENU-BAR to erase the menu
prior to its APPL-EXIT call.

Parameters:

control(O)			=	30
control(l)			=	1
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-in(O)			= 	me-bshow

int-out(O)			= 	me-breturn

addr-in(O)			= 	me-btree

		me bshow - a code for whether the application displays the menu
baT

0 - erase the menu bar
1 - display the menu bar

		me-breturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

e		me-btree - the address of the object tree that forms this menu

Sample call to C language binding:

mebreturn = menu-bar(me-btree, me-bshow);

5-7
ut~m Fr~b erogrammer's Guide		5.3	Menu Library Routilnes

5.3.2		MENU-ICHECK

Purpose:

Displays or erases a check mark next to a menu item.

Parameters:

control(O)			=	31
control(l)			=	2
control(2)			=	1
controlM			=	1
control(4)			= 	0

int in(O)			=	me citem
int-in(l)			= 	me-ccheck

int-out(O)			= 	me-creturn

addr-in(O)			= 	me-ctree

me-citem		a number that uniquely identifies this menu item

me - ccheck		a code for whether the application displays a check
marK next to the menu item identified by me_citem

0 -		do not display a check mark, or if a check mark is visible,
	erase it
I -		display a check mark

 me-creturn - a coded return messaae

0 - an error exists
n (positive integer) - no error exists

 me-ctree		the address of the object tree that forms this menu

Sample call to C language binding:

me-creturn		menu-icheck(me-ctree, me-citem, me-ccbeck)

5-8
GEM AES Programmer's Guide			5.3	Menu Library Routines

5.3.3 MENU-IENABLE

Purpose:

Enables or disables a menu item.

Parameters:

control(O)			=	32
control(l)			=	2
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int in(O)			=	me eitem
int-in(l)			= 	me-eenable

int-out(O)			= 	me__ereturn

addr-in(O)			= 	me_etree

 me-eitem - a number that uniquely identifies this menu item

 me-eenable - a code for how the application displays menu item

0 - disabled (dimmed characters)
1 - enabled (normal brightness)

 me-ereturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

 me-etree		the address of the object tree that forms this menu

Sample call to C language binding:

me-ereturn		menu_ienable(me-etree, me-eitem, me-eenable);

5-9
UIU-I AL~a eiuylalfuller g UUIZILS		5.3	Menu Library Routines

5.3.4		MENU-TBORMAL

Purpose:

Displays a menu title in normal or reverse video.

Parameters:

control(O)			=	33
control(l)			=	2
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int in(O)			=	me ntitle
int-in(l)			= 	me-nnormal

int-out(O)			= 	me-nreturn

addr-in(O)			= 	me_ntree

	 me T ntitle		a number unique to this application that identifies
	this menu

			me - nnormal	a code for whether the application displays the menu
	title in normal or reverse video

0 - reverse video
1 - normal video

 me-nreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

 me-ntree		the address of the object tree that forms this menu

Sample call to C language binding:

me-nreturn		menu-tnormal(me-ntree, me-ntitle,
		me-nnor ma 1) ;

5-10
GEM AES Programmer's Guide			5.3	Menu Library Routines

5.3.5		MENU-TEXT

Purpose:

Changes the text of a menu item.

This routine lets GEM AES support context-sensitive menus. For
example, a word processing application that lets the user turn the
character insert on and off can have a menu item reading "Insert
On" or "Insert Off", depending on the current state of the insert.

Parameters:

control(O)			=	34
control(l)			=	1
control(2)			=	1
control(3)			=	2
control(4)			= 	0

int-in(o)			= 	me-titem

int-out(O)			= 	me_treturn

addr - in(O) = me-ttree
addr-in(l) = me_ttext

		me-titem - A number that uniquely identifies this menu item.

		me-treturn - A coded return message.

0 - an error exists
n (positive integer) - no error exists

		me I ttext - The address of the new text string for this menu item.
This text string should be no longer than the one it is replacing
in the menu object tree structure.

 me-ttree		The address of the object tree that forms this menu.

Sample call to C language binding:

me-treturn		menu-text(me-ttree, me-titem, me-ttext);

5-11
L-&-I AL5		Gulde	5.3	Menu LI-brary Routines

5.3.6 MF.UU-REGISTER

Purpose:

Places a desk accessory's menu item string on the Desk Menu and
returns the accessory's menu item identifier.

The Desk Menu can list no more than six desk accessories.

Parameters:

control(O)			=	35
control(l)			=	1
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-in(O)			= 	me_rapid

int-out(O)			= 	me-rmenuid

addr-in(O)			= 	me_rpstring

		me rapid - the desk accessory's process ident4 fier

This value is the ap -id returned by the desk accessory's APPL-INIT
call.

		me-rmenuid - the desk accessory's menu item identifier, a value
ranging from 0 (zero) to 5

-1 - no room on the Desk Menu for this item

		me_rpstring - the address of the desk accessory's Desk Menu text
string

Sample call to C language binding:

me-rmenuid = menu_register(me_rapid, me_rpstring);

End of Section 5

5-12
	Section 6
Object Library

6.1		Introduction

An object is a collection of data describing something that appears
on the screen. For example, GEM AES objects include boxes,
characters, and icons. GEM AES defines several standard objects,
and the Object Library provides routines to handle them.

An application uses the Object Library to set up and manipulate a
tree structure of objects. Figure 6-1 shows a typical object tree.

root --------

child -------		child - -------

child ---- child ---- child		child ---- child

,, head
	...........		tail
-------- next

Figure 6-1. Object Tree

An object tree is an array of objects. Starting with a root object,
the tree consists of linked lists in which each child points to its
next sibling and to its children, if either exists. In addition,
the last child at each level points back to its parent.

6-1
GEM AES Programmer's Guide		6.2	Using the Object Library

6.2		Using the Object Library

Figure 6-2 illustrates how the Object Library works. It shows a
simple on-screen display: a box containing two boxes, one with text
inside.

----------------------

----------------

---------------

----------------

TEXT

----------------

----------------------

Figure 6-2. On-screen Display

The object tree that defines this display contains three obJects:

The root: the outer box. Its object type is G-BOX. Data for this
object include the following:

- X- and Y-coordinates of the upper left corner
- width and height
- thickness of the border
- foreground and background colors

The first child: the empty inner box. Its object type is also
G-BOX. Data for this object include the following:

-		X- and Y-coordinates of the upper left corner, relative to the
parent

-		width and height

-		thickness of the border

-		foreground and background colors
G04 AES Programmer's Guide			6.2	Using the Object Library

The second child: the box with TEXT. Its object type is
G-BOXTEXT. Data for this object include the following:

-		X- and Y-coordinates of the upper left corner, relative to the
parent

-		width and height

-		thickness of the border

-		foreground and background colors

An application can create an object tree by making separate calls to
the OBJC ADD routine for each of the root's children. The
application then calls the OBJC DRAW routine. Using the tree
structure created by the OBJC ADD7calls and the data contained in
the objects themselves, the Object Library draws the on-screen
image.

An application can also load one or more complete object trees with
the RSRC LOAD call. In that case, all parent-child relationships
have already been established.

Note that the parent object (in Figure 6-1, the root is the parent)
always occupies screen space greater than or equal to that occupied
by its children. In other words, the parent must contain its
children.

6.3 Object Library Data Structures

The Object Library uses the following data structures:

e OBJECT structure
o TEDINFO structure
e ICONBLK structure
& BITBLK structure
o APPLBLK structure
o PAFMBLK structure

If an element of one of these data structures has a value of -1, it
is either a nil index or a nil pointer.

The following sections describe these data structures.

6-3
ULM AL.5 PIUYLdIIUIIk--L b UUIUk-			U-3	UUJL-UL J-IULdly 1.~dLd 3LIULLULUb

6.3.1 OBJECT Structure

The OBJECT structure contains values that describe the object, its
relationship to the other objects in the tree, and its location
relative to its parent or (in the case of the root object) the
screen. There is an OBJECT structure for each object in a tree.

-------------------------------------
	ob next				ob head
-------------------------------------
I		ob - tail	I	ob-type	I
-------------------------------------
ob flags		ob state
----------------- ~: ----------
ob_spec 		i
-------------------------------------
I		ob-x		I	ob :: y	I
---------------------------- --------
I		ob - width	I	ob_height	I
-------------------------------------

Figure 6-3. OBJECT Structure

ob-next		a WORD containing the index of the object's next sibling
in the object tree array

ob head - a WORD containing the index of the first child: the head
of the list of the object's children in the object tree array

ob tail - a WORD containing the index of the last child: the tail
of the list of the object's children in the object tree array

ob type - a WORD containing the object type (defined in Section
6.-~.7.1). GEM AES ignores the high byte of this WORD.

ob	- flags - a WORD containing the object flags (defined in Section
6.3.7.2)

ob	- state - a WORD containing the object state (defined in Section
6.3.7.3)

ob_spec - a LONG value containing object-specific data. A
detailed description of ob_spec appears at the end of this
parameter list-

ob-x - a WORD containing the X-coordinate of the object relative
to its parent or (for the root object) the screen

ob-y - a WORD containing the Y-coordinate of the object relative
to its parent or (for the root object) the screen

6-4
GEM AES Programmer's Guide			6.3	Object Library Data Structures

		ob-width - a WORD that contains the width of the object in
pixels

		ob-height - a WORD that contains the height of the object in
pixels

Depending on the object's type, ob spec can be a POINTER or any
combination of WORD and/or BYTE vi-lues that add up to 32 bits.
object types are described in Section 6.3.7.1.

For object types G-BOX, G_IBOX, and G-BOXCHAR, the LONG value of
ob-spec is broken into a LOW WORD and a HIGH WORD. The LOW WORD is
the object color, as defined in Section 6.3.7.4.

The HIGH WORD is broken into two bytes. For the object type
G BOXCHAR, the HIGH BYTE of the HIGH WORD is a character. For all
o7ther object types, the HIGH BYTE equals zero.

The LOW BYTE of the HIGH WORD is the thickness of the border of the
object. This byte can have the following values:

00		no thickness

1			128	(positive values)	inside thickness: inward from the
object's edge

-1 - (-'127) (negative values)		outside thickness: outward from the
object's edge

6.3.2		TEDINFO Structure

The TEDINFO structure lets a user edit formatted text. The object
types G - TEXT, G-BOXTEXT, G FTEXT, and G FBOXTEXT use their ob-spec
pointers to point to TEDII~FO structures-.

I-

6-5
ULM AL5 FLUYLdIMIL-L .1, UUIUt!			U . j	Ul)je~.L LIULUL] L)LLLU OLLUI-LULUJ

te_ptext
------------------------------------
I		te_ptmplt
-------------------------------------
	te pvalid
-------------------------------------
I		te-font	I	te "Z resvdl 	I
------------------------- -----------
I				te-just	I	te color	I
-------------------------- 7 ---------
I			te_resvd2	I te	thickness 	I
----------------------- z -------------
1		te_txtien	I	te_tmplen	I
-------------------------------------

Figure 6-4. TEDINFO Structure

te_ptext		A POINTER to the actual text.

If the first text character is "@", the field is blank, and the
application can use any characters for the remaining character
positions in the field. For example, a te_ptext string "@xyzpdq"
is seven blank spaces.

te_ptmplt - A POINTER to a text string template for any further
data entry. The editable Portion of the field is represented by
underscores.

te_pvalid - A POINTER to a text string containing characters that
validate any entered text.

9				-	allow	only digits 0 - 9
A				-	allow	only uppercase A - Z, plus space
a				-	allow	upper- and lowercase A	Z, plus space
N				-	allow	0 - 9 and uppercase A	Z, plus space
n				-	allow	0 - 9 and upper- and lowercase A - Z, plus space
F				-	allow	all valid DOS filename characters, Plus ?
P				-	allow	all valid DOS Path name characters, plus	?
p				-	allow	all valid DOS path name characters, Plus
X				-	allow 	anything

te-font - A WORD identifying the font used to draw the text.

3 - system font: used in menus, dialogs, etc.
5 - small font: used in icons

te-resvdl - Reserved for future use.

6-6
GEM AES Programmer's Guide			6.3	Object Library Data Structures

te_just - A WORD identifying the type of text -justification
desired.

0 - left-justified
1 - right-justified
2 - centered

te-color - A WORD identifying the color and pattern of box-type
objects. See Section 6.3.7.4, "Object Colors."

te-resvd2 - Reserved for future use.

te thickness - A WORD containing the thickness in pixels of the
b6-rder of the text box. This WORD can have the following values:

00		no thickness

1		128 (positive values) = inside thickness: inward from the
object's edge

-1 - (-127) (negative values) = outside thickness: outward from
the object's edge

te	- txtlen - A WORD containing the length of the string pointed to
by te_ptext.

te tmplen - A WORD containing the length of the string pointed to
by te_ptmplt.

The following example illustrates how the TEDINFO structure works

te ptext is a string of raw data for a date. Its value is
"06'1384".

te-ptmplt, also a string, is a template that shows how to display
the data in te_ptext. Its value is "Enter Date: _. / - / - 11.

te-pvalid is a string of input validation characters. Its value
is "999999".

The editable text facility merges all the above data into one
string, "Enter Date: 06/13/84".

If the user types "1004", the string becomes "Enter Date:
10/04/84-.

If the user presses the Backspace key after typing "1004", the
string becomes "Enter Date: 10/0_/84".
GEM AES Programmer's Guide			6.3	Object Library Data structures

If te_ptext has no data or not enough data to fill out the
template, the unfilled parts of the template show underscores.
For example, if the user types "01" into an empty date field, it
then reads "Enter Date: 01/_/_".

6.3.3		ICONBLK Structure

The Object Library uses the ICONBLK structure to hold the data that
defines icons. The object type G_ICON points with its ob_spec
pointer to an ICONBLK structure.

-------------------------------------
I		ib pmask	I
---------------- --------------------
I		ib pdata	I
-------------------------------------
I		ib ptext	I
-------------------------------------
I		ib-char	I	ib - xchar 	I
-------------------------------------
I		ib_ychar	I	ib - xicon 	I
-------------------------------------
I		ib_yicon	I	ib - wicon 	I
-------------------------------------
I		ib_hicon	I	ib - xtext 	I
-------------------------------------
I		ib_ytext	I	ib - wtext 	I
-------------------------------------
I		ib_htext	1		0	1	0 	i
-------------------------------------

Figure 6-5. ICONBLK Structure

All X, Y, width, and height values for this structure are in pixels.

ib pmask - A POINTER to an array of WORDS representing the mask
bi -image of the icon.

ib_pdata - A POINTER to an array of WORDS representing the data
bit-image of the icon.

ib_ptext - A POINTER to the icon's text.

ib char - A WORD containing a character to be drawn in the icon
(for example, the letter "A" on a floppy disk icon).

ib-xchar - A WORD containing the X-coordinate of ib-char.

6-8
GEM AES Programmer's Guide			6.3	Object Library Data Structures

ib_ychar - A WORD containing the Y-coordinate of ib-char.

ib-xicon - A WORD containing the X-coordinate of the icon.

ib-yicon - A WORD containing the Y-coordinate of the icon.

ib - wicon - A WORD containing the width of the icon in pixels.
This value must be divisible by 16.

ib-hicon		A WORD containing the height of the icon in pixels.

ib-xtext		A WORD containing the X-coordinate of the icon's text.

ib_ytext		A WORD containing the Y-coordinate of the icon's text.

ib	- wtext A WORD containing the width of a rectangle in which the
iconts text will be centered.

ib-htext - A WORD containing the height of the icon's text in
pixels.

6.3.4		BITBLK Structure

The object type G IMAGE uses the BITBLK structure to draw bit images
like cursor forms or icons.

-------------------------------------
I		bi_pdata 	I

	bi wb			I	bi_hl	I
--------- T ---------------------------
bi - x			I	bi_y 	I
-------------------------------------
I			bi color	I 	I
------- -----------------------------

Figure 6-6. BITBLK Structure

*		bi_pdata - A POINTER to an array of WORDS containing the bit
image.

*		bi-wb - A WORD containing the width of the bi_pdata array in
bytes. Because the bi_pdata array is made of WORDS, this value
must be an even number.

*		bi hl - A WORD containing the height of the bit block in scan
lines (pixels).

6-9
GEM AES Programmer's Guide			6.3	Object Library Data Structures

		bi-x - A WORD containing the source X in bit form, relative to the
bi_pdata array.

		bi_y - A WORD containing the source Y in bit form, relative to the
bi_pdata array.

		bi-color - A WORD containing the color GEM AES uses when
displaying the bit-image. See Section 6.3.7.4 for the color
values.

6.3.5		APPLBLK Structure

The Object Library uses the APPLBLK structure to locate and call an
application-defined routine that will draw and/or change an object.
The object type G - PROGDEF points with its ob-spec pointer to an
APPLBLK structure.

-------------------------------------
I	ab code 	I
------------------ 1 -------------------
I	ab parm	I
----------------- :~ -------------------

Figure 6-7. APPLBLK Structure

		ab-code a POINTER to the routine for drawing and/or changing the
object

		ab-parm a LONG value (optionally provided by the application)
passed as a parameter when the Object Library calls the
application's object drawing/changing routine

6.3.6		PARMBLK Structure

The Object Library uses the PARMBLK structure to store information
relevant to the application's drawing or changing an object.

when it calls the application's object drawing/changing routine
(pointed to by ab-code), the Object Library provides a pointer to a
PARMBLK.

6-10
GEM AES Programmer's Guide			6.3	object Library Data Structures

I		pb_tree
--------------------------
pb_obj				I	pb_prevstate
	----------------------
	pb_currstate		pb_x
---------------
	pb_y		pb_w
		---------------------
	pb_h		pb_xc
--------------
	pb_yc		pb_wc
		---------------------
	pb_hc		Ipb_parm LOW WORD I
---------------
I pb_parm HI WORD

Figure 6-8. PARMBLIK Structure

pb_tree		A POINTER to the object tree that contains the
application-defined object.

pb_obj - A WORD containing the object index of the application
defined object.

pb_prevstate		A WORD containing the old state of an object to be
changed.

pb_currstate		A WORD containing the changed (new) state of an
object.

Note: If pb_prevstate and pb_currstate are the same, the
application is drawing the object, not changing it.

pb~_x - A WORD containing the X-coordinate of a rectangle defining
the location of the object on the physical screen.

pb_y - A WORD containing the Y-coordinate of a rectangle defining
the location of the object on the physical screen.

pb w - A WORD containing the width (in pixels) of a rectangle
deTining the size of the object on the physical screen.

pb_h - A WORn containing the height (in pixels) of a rectangle
defining the size of the object on the physical screen.

pb_xc - A WORD containing the X-coordinate of the current clip
rectangle on the physical screen.

pb_yc - A WORD containing the Y-coordinate of the current clip
rectangle on the physical screen.

6-11
ULM lkza erogrammer-S Uulue		V..3	J,~ULQLy "- ----

		pb_wc - A WORD containing the width (in pixels) of the current
clip rectangle on the physical screen.

		pb_hc - A WORD containing the height (in pixels) of the current
clip rectangle on the physical screen.

		pb_parm - A LONG value; identical to ab - parm in	the APPLBLK
	structure. The object Library passes this value		to the
	application when it is time for the application to draw or change
	the object.

6.3.7		Predefined Values

The Object Library routines use the following predefined values:

object types
object flags
object states
object colors

The following sections define these values.

6.3.7.1		Object Types

#define				G	BOX	20
#define				G	TEXT	21
#define				G	BOXTEXT	22
#define				G	IMAGE	23
#define				G	PROGDEF	24
#define				G __IBOX	25
#define				G	BUTTON	26
#define				G	BOXCHAR	27
#define				G	STRING	28
#define				G	FTEXT	29
#define G FBOXTEXT		30
#define G ICON		31
#define G-TITLE 		32

Object types are stored in the ob type section of the OBJECT
structure. All object types are gral5hic or bitmap object types.

		G_BQX - A graphi,; box; its ob-spec value contains the object's
color WORD and thickness.

		G TEXT - Graphic text; its ob spec value is a POINTER to a TEDINFO
slEructure in which the value ~~f te-ptext points to the actual text
string as displayed.

6-12
GEM AES Programmer's Guide			6.3	object Library Data Structures

G - BOXTEXT - A graphic box containing graphic text; its ob - spec
value is a POINTER to a TEDINFO structure in which the value of
te_ptext points to the actual text string as displayed.

G IMAGE - A graphic bit-image; its ob-spec value is a POINTER to a
BYTBLK structure.

G PROGDEF - A programmer-defined object; its ob-spec value is a
P_6INTER to an APPLBLK structure.

G IBOX - An		"invisible" graphic box; its	ob - spec value contains
tTe object's color WORD and thickness. It		has no fill pattern and
no internal		color. If its border has no	thickness, it is truly
invisible.		If its border has thickness,	it is an outline.

G		- BUTTON - A graphic text object centered in a box; its ob-spec
value is a POINTER to a null-terminated text string.

G __ BOXCHAR - A graphic box containing a single text character; its
6b 'd spec value contains the character, plus the object's color WORD
an thickness.

G		- STRING - A graphic text object; its ob-spec value is a POINTER
to a null-terminated text string.

G FTEXT - Formatted graphic text; its ob spec value is a POINTER
t7o a TEDINFO structure in which the value-of te_ptext points to a
text string. The text string is merged with the template pointed
to by te_ptmplt before it is displayed.

G FBOXTEXT - A graphic box containing formatted graphic text; its
o1b spec value is a POINTER to a TEDINFO structure in which the
value of te_ptext points to a text string. The text string is
merged with the template pointed to by te_ptmplt before it is
displayed.

G ICON - An object that describes an icon; its ob_SpeC value is a
P51NTER to an ICONBLK structure.

G-TITLE - A graphic text string used in menu titles; its ob-spec
value is a POINTER to a null-terminated text string.

6-13
GEM AES Programmer's Guide			6.3	Object Library Data Structures

6.3.7.2		object Flags

#define			NONE	OX0000
#define			SELECTABLE	OxOO01
#define			DEFAULT	OxOO02
#define			EXIT	OxOO04
#define			EDITABLE	OxOO08
#define			RBUTTON	OX0010
#define			LASTOB	OxOO20
#define			TOUCHEXIT	OxOO40
#define			HIDETREE	OxOO80
#define			INDIRECT 	OX0100

object flags are stored as a bit vector in the ob_flags portion of
the OBJECT structure. Each bit in the ob_flags WORD is significant.
Undefined bits should be set to zero.

		SELECTABLE - Indicates that the user can select the object.

		DEFAULT - Indicates that the Form Library will examine the object
if the user enters a carriage return. No more than one object in
a form can be flagged DEFAULT. This object is usually an exit
button, which lets the user enter a carriage return to exit the
form without using the mouse.

EXIT - Indicates that the Form Library will return control to the
caller after the exit condition is satisfied. The exit condition
is satisfied when the user selects the object by clicking on it

EDITABLE - Indicates that an object is editable by the user in
some way.

RBUTTON - An object called a radio button.

Radio buttons appear in groups of two or more, only one of which
may be selected at a given time. When the user selects a buttonr
the currently selected button is automatically de-selected.

All radio buttons in a group must have the same parent.

The "Floppy" and "Hard" buttons in the GEM Desktop application's
INSTALL DISK DRIVE dialog are examples of radio buttons.

LASTOB - Indicates that an object is the last object in the object
tree.

TOUCHEXIT - Indicates that the Form Library will return control to
the caller after the exit condition is satisfied. The exit
condition is satisfied when the user presses the mouse button
while the pointer is over ("touching") the object.

6-14
GEM AES Programmer's Guide			6.3	Object Library Data Structures

		HIDETREE - Makes a subtree invisible. When the application makes
an OBJC DRAW or OBJC FIND call, the Object Library will not draw
or finC the object o-r any of its children.

		INDIRECT - Indicates that the value in ob-spec is a pointer to the
actual value of ob-spec.

6.3.7.3 object States

#define NORMAL OX0000
#define SELECTED OxOO01
#define CROSSED OxOO02
#define CHECKED OxOO04
#define DISABLED OxOO08
#define OUTLINED OxOO10
#define SHADOWED OxOO20

object states determine how the OB DRAW routine draws objects.
Object states are stored as a bit vector in the ob-state portion of
the OBJECT structure.

		NORMAL - Indicates that the object is drawn in normal foreground
background colors.

		SELECTED - Indicates that the object is highlighted by being drawn
with its foreground and background colors reversed.

		CROSSED - Indicates that an "V is drawn in the object. The
object must be a box.

		CHECKED - Indicates that the object (typically one containing
text) is drawn with a check mark.

		DISABLED - Indicates that the object (typically one containing
text) is drawn faintly.

		OUTLINED - Indicates that an outline appears around a box object.
This state is used for dialog boxes.

		SHADOWED - Indicates that the object (usually a box) is drawn with
a drop shadow.

6-15
GEM AES Programmer's Guide			6.3	Object Library Data Structures

6.3.7.4		Object Colors

#define			WHITE	0
#define			BLACK	1
#define			RED	2
#define			GREEN	3
#define			BLUE	4
#define			CYAN	5
#define			YELLOW	6
#define			MAGENTA	7
#define			WHITE	8
fde*'ine			BLACK	9
#define			LRED	10
#define			LGREEN	11
#define			LBLUE	12
#define			LCYAN	13
#define			LYELLOW	14
#define			LMAGENTA 	15

object colors are stored as a WORD in the ob spec portion of the
OBJECT structure and the te_color portion of the TEDINFO structure.
An L preceding the name of the color (for example, "LGREEN")
indicates a light shade of the color.

Figure 6-9 shows the components of the object color WORD.

---------------------
I a I b Icl d I e I
----------------------

Figure 6-9. Object Color WORD

The high four bits ("a" in Figure 6-9) are the border color, with
values ranging from 0 to 15.

The next four bits ("b") are the text color, with values ranging
from 0 to 15.

The next bit ("c") indicates how text is written.

0 = transparent mode
1 = replace mode

(Transparent and replace mode are defined in the GEM Programmer's
Guide, Volume 1: VDI.)

6-16
GEM AES Programmer's Guide			6.3	Object Library Data Structures

The next three bits ("d") indicate the object's fill pattern, with
values ranging from 0 to 7.

0 = hollow fill
7 = solid fill
1 - 6 = dither patterns of increasing darkness

The low four bits ("e") are the object's inside color, with values
ranging from 0 to 15.

6.4 Object Library Routines

The Object Library uses the following routines:

 OBJC-ADD - adds an object to an object tree
 OBJC DELETE - deletes an object from an object tree
 OBJC DRAW - draws an object or object tree
 OBJC FIND - determines if the mouse is over an object
 OBJC-OFFSET computes an object's location relative to the screen
 OBJC ORDER changes the order of an object within its tree
 OBJC EDIT		lets a user edit text in an object
 OBJC-CHANGE - changes an object's state

The following sections describe these routines.

Note: A tree is an array of objects. In the Object Library routine
descriptions, references to an object refer to the array index of
the object in the tree.

Each Object Library routine has a GEM AES Parameter Block, Control
Array, and Global Array that contain the following information:

GEM AES Parameter Block
	params(O)					=	long	address	(32	bits)	of	control array
	params(l)					=	long	address	(32	bits)	of	global array
	params(2)					=	long	address	(32	bits)	of	int in array
	params(3)					=	long	address	(32	bits)	of	int out array
	params(4)					=	long	address	(32	bits)	of	addr - in array
	params(5)					=	long	address	(32	bits)	of	addr-out array

	Control Array
	control(O)			=	ol~__code
	control(l)			=	size in WORDS of int in array
	control(2)			=	size in WORDS of int out array
	control(3)			=	size in LONGS of addr in array
	control(4)			=	size in LONGS of addr-out array

6-17
GEM AES Programmer's Guide		6.4	object Library Routines

Global Array
	global(O)			=	ao version
	global(l)			=	a~-count
	global(2)			=	ap-id
	global(3,4)			=	ap_private
	global(5,6)			=	ap_ptree
	global(7,8)			=	ap_lresv
	global(9,10)			=	ap_2resv
	global(11,12)			=	ap_3resv
	global(13,14)			= 	ap_4resv

Global Array parameters are described in Section 3.

Each routine also contains some or all of the following arrays:

		Integer Input (int in) - Unless otherwise noted, each parameter in
this array is a W6RD.

		Integer Output (int_out) - Unless otherwise noted, each parameter
in this array is a WORD.

		Address Input (addr in) - Unless otherwise noted, each parameter
in this array is a POINTER.

		Address Output (addr out) - Unless otherwise noted, each parameter
in this array is a -OINTER.

6-18
GEM AES Programmer's Guide		6.4 Object Library Routines

6.4.1 0BJC-ADD

Purpose:

Adds an object to an object tree.

In creating an object tree, the application makes separate
OBJC ADD calls to establish the relationship of each child to its
parEFnt. For example, if the tree contains one parent with three
children and another parent with two children, the tree requires a
total of five OBJC-ADD calls.

Parameters:

control(O)			=	40
control(l)			=	2
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int in(O)		= ob aparent
int-in(l)		= ob-achild

int-out(O)		= ob-areturn

addr-in(O)		= ob-atree

		ob - aparent - the object to whose list of children the child will
	be added

		ob-achild - the object to add to parent's list of children

		ob-areturn - a coded return message

0 - an error exists
n (positive integer) - the object was successfully added

 ob I atree		the address of the object tree containing parent and
child

Sample call to C language binding:

ob-areturn		objc_add(ob-atree, ob-aparent, ob-achild);

6-19
GEM AES Programmer's Guide		6.4	object Library Routines

6.4.2 OBJC-DELETE

Purpose:

Deletes an object from an object tree by unlinking it from its
parent object.

Parameters:

control(O)			=	41
control(l)			=	1
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-in(O)			= 	ob_dlobject

int-out(O)			= 	ob-dlreturn

addr-in(O)			= 	ob-dltree

		ob_dlobject - the object to be deleted

		ob-dlreturn - a coded return message

0 - an error exists
n (positive integer) - the object was successfully deleted

		ob-dltree - the address of the object tree that contains the
object

Sample call to C language binding:

ob d1return = objc_delete(ob-dltree, ob_dlobJect);

6-20
GEM AES Programmer's Guide		6.4 Object Library Routines

6.4.3 OBJC-DRAW

Purpose:

Draws any object or objects in an object tree.

Each OBJC DRAW call defines a new clip rectangle, and the Object
Library d-raws only the parts of the object contained within the
clip rectangle for that call.

The clip rectangle is defined in the GEM Programmer's Guide,
Volume 1: VDI.

Parameters;

control(O)			=	42
control(l)			=	6
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int in(O)			=	ob drstartob
int in(l)			=	ob drdepth
int7in(2)			=	ob7drxclip
int in(3)			=	ob dryclip
int in(4)			=	ob-drwclip
int-in(5)			= 	ob-drhclip

int-out(O)		= ob-drreturn

addr-in(O)		= ob-drtree

		ob drstartob - the starting object on the tree indexed by
ob-drtree

		ob - drdepth - how many levels in the object tree to draw, starting
	from ob-drstartob

0 - starting object only
1 - first level children of starting object
2 - second level children of starting object [etc.)

ob-drxclip - the X-coordinate of the clip rectangle

ob-dryclip - the Y-coordinate of the clip rectangle

ob-drwclip - the width (in pixels) of the clip rectangle

ob-drhclip - the height (in pixels) of the clip rectangle
GEM AES Programmer's Guide		6.4	Object Library Routines

		ob-drreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

		ob-drtree - the address of the object tree that contains the
object

Sample call to C language binding:

ob-drreturn = objc_draw(ob-drtree, ob-drstartob,
ob_drdepth, ob-drxclio,
ob-dryclip, ob-drwclip,
ob-drhclip);

6-22
GEM AES Programmer's Guide			6.4	Object Library Routines

6.4.4 OBJC-FIND

Purpose:

Finds an object under the mouse form.

The application supplies the X- and Y-coordinates of the mouse's
position, as well as a parameter that tells OBJC-FIND how far down
the tree to search.

Parameters:

control(0)			=	43
control(l)			=	4
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int in(O)			=	ob fstartob
int in(l)			=	ob fdepth
int in(2)			=	ob fmx
int-in(3)			= 	ob-fmy

int-out.(O)			= 	ob-fobnum

addr-in(O)			= 	ob-ftree

*		ob-fstartob - the object at which to start the search

*		ob fdepth - how many levels in the object tree to search, starting
from ob-fstartob

0 - starting object only
1 - first-level children of starting object
2 - second-level children of starting object [etc.)

*		ob-fmx - the X-coordinate of the mouse's location

*		ob-fmy - the Y-coordinate of the mouse's location

e		ob - fobnum - the found object's number in the tree, ranging from 0
	(zero) to n

-1 - no object found

o		ob-ftree - the address of the object tree containing the object
identified by ob-fstartob

6-23
GEM AES Programmer's Guide		b.4	UD)ect LIDrary i-our-ines

Sample call to C language binding:

ob-fobnum = objc_find(ob-ftree, ob-fstartob, ob-fdepth,
ob-fmx, ob-fmy);

6-24
GEM AES Programmer's Guide			b.4	UDject Liorary xoutines

6.4.5 OBJC-OFFSET

Purpose:

Computes an object's X- and Y-coordinates relative to the screen.

Parameters:

control(O)			=	44
control(l)			=	1
control(2)			=	3
control(3)			=	1
control(4)			= 	0

int-in(O)			= 	ob-ofobject

int out(O) = ob ofreturn
int out(l) = ob ofxoff
int-out(2) = ob-ofyoff

addr-in(O)			= 	ob-oftree

		ob-ofobject - the object whose location is being computed

9		ob-ofreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

		ob-ofxoff - the X-coordinate of ob-ofobject relative to the screen

		ob-ofyoff - the Y-coordinate of ob-ofobject relative to the screen

		ob -- oftree - the address of the object tree containing the object
identified by ob-ofobject

Sample call to C language binding:

ob-ofreturn = objc-offset(ob-oftree, ob-ofobject,
&ob-ofxoff, &ob-ofyoff);

6-25
k.7ZI'I MJL~O r 1. U~J I CUILAM L 5 UUIUr-

6.4.6		OBJC-ORDER

Purpose:

moves an object to a new position in its parent's list of children
(for example, takes the third child and moves it to the second
child's place).

Parameters:

control(O)			=	45
control(l)			=	2
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int in(O)			=	ob - orobject
int-in(l)			=	ob-ornewpos

int-out(O)			= 	ob-orreturn

addr-in(O)			= 	ob-ortree

		ob-orobject - the object to be moved to a new position

		ob-ornewpos - the new position in which to put the object

	0 - on the bottom
	I - one from the bottom
	2 - two from the bottom [etc.)
-1 - on top

		ob-orreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

		ob-ortree - the address of the object tree that contains the
object identified by ob_orobject

Sample call to C language binding:

ob-orreturn = objc_order(ob-ortree, ob_orobject,
ob_ornewpos);

6-26
GEM AES Programmer's Guide		6.4 Object Library Routines

6.4.7 OBJC-EDXT

Purpose:

Lets the user edit text in an object.

The object must be of the type G-TEXT or G-BOXTEXT.

Parameters:

control(O)			=	46
control(l)			=	4
control(2)			=	2
control(3)			=	1
control(4)			= 	0

int in(O)			=	ob edobject
int in(l)			=	o6--edchar
inCin (2)			=	ob7edidx
int-in(3)			= 	oCedkind

int out(O) = ob edreturn
int-out(l) = ob-ednewidx

addr-in(O)		= ob-edtree

ob-edobject		- the object containing the text to be edited

ob-edchar		the character input by the user

ob - edidx		the index of the next character position in the raw
text string

ob-edkind - the OBJC-EDIT function to perform

0 - ED-START reserved for future use

1 -			ED-INIT	combine values in te_ptext and te-ptmplt into a
	formatted string; turn on text cursor

2 -		ED CHAR - validate typed characters against te_pvalid, update
te~-ptext, and display string

3 - ED-END - turn off text cursor

See		Section 6.3.2, "TEDINFO Structure."

ob-edreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists
GEM AES Programmer's Guide		6.4	Object Library Routines

		ob ednewidx - the index of the next character position in the raw
text string after the OBJC_EDIT operation is finished

		ob - edtree - the address of the object tree containing the object
	with the text to be edited

Sample call to C language binding:

ob-edreturn = objc_edit(ob-edtree, ob-edobject,
ob edchar, ob edidx,
ob-edkind, &o'S-ednewidx);

6-28
4.8		OBJC-CHANGE

Purpose:

Changes an object's ob-state value. Refer to Section 6.3.7.3,
"Object States."

Each OBJC-CHANGE call defines a new clip rectangle, and the Object
Library changes only the parts of the object contained within the
clip rectangle for that call.

Parameters:

control(O)			=	47
control(l)			=	8
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int in(O)			=	ob - cobject
int in(l)			=	ob cresvd
inCin (2)			=	ob7-cxclip
int in(3)			=	ob-cyclip
int in(4)			=	ob cwclip
int in(5)			=	ob chclip
int in(6)			=	ob-cnewstate
int-in(7)			=	ob credraw

int-out(O)			= 	ob-creturn

addr-in(O)			= 	ob-ctree

ob-cobject		The object to be changed.

ob-cresvd		Reserved; the value must be zero.

ob-cxclip		The X-coordinate of the clip rectangle.

ob-cyclip		The Y-coordinate of the clip rectangle.

ob-cwclip		The width (in pixels) of the clip rectangle.

ob-chclip		The height (in pixels) of the clip rectangle.

ob-cnewstate - The ob-state value of the object.

ob-credraw - A code for whether to redraw the object.

0 - do not redraw the object
1 - redraw the object

6-29
GEM AES Programmer's Guide		6.4	Object Library Routines

 ob-creturn - A coded return i-,tessage.

0 - an error exists
n (positive integer) - no error exists

 ob-ctree The address of the object tree containing the object.

Sample call to C language binding:

ob-creturn		objc_change(ob-ctree, ob-cobject, ob-cresvd,
ob cxclip, ob_cyclip,
ob cwclip, ob - chclip,
ob-cnewstate, ob-credraw);

End of Section 6

6-30
	Section 7
Form Library

7.1		Introduction

A form is a means of giving or gathering information. It can be a
set of questions, often in the form of a list, to which a user
responds by checking off boxes or writing text. A form can appear
on a piece of paper or on a computer screen.

GEM AES's Form Library displays forms almost exactly as they would
appear on paper. For example, an application can display a form and
then use the responses it receives to update an information
database. The Form Library collects the user's responses and stores
them in the object tree that describes the form.

In making this high-level interaction between application and user
possible, the Form Library offers several advantages, including the
following:

		The Form Library, and not the application, is responsible for the
user's interaction with the form.

		The application is idle until the user has completed the form.
When the user satisfies the form's exit condition, the application
regains control and acts on the user's responses.

		The Form Library greatly simplifies the programmer's task by
providing a consistent framework for interaction between the
application and the user.

7.1.1 Forms: A Model

A typical form is the product survey illustrated in Figure 7-1. This
kind of form, which might be included with a newly purchased
computer, contains several questions, to which the user responds by
putting an "X" in the appropriate boxes or by writing a response.

7-1
------------------------------------------------------------

i	I
1. Age (check one only):
10-29
30-49
50-69
over 70

2. Yearly Income (check one only):
less than $10,000
$10,000 - $29,999
$30,000 - $49,999
$50,000 - $69,999
over ~70,000

3. Activities You Enjoy (check all that apply):
Water Skiing
Hang Gliding
Backpacking
Bicycling
SCUBA Diving
Horseback Ridingl I

4. Computer Dealer's Name:

Address:

---------------------

Figure 7-1. Typical Product Survey Forn

The questions in this form require three different kinds of answer:

a check in a single box (questions I and 2)
a check in one or more boxes, or no check at all (question 3)
a written answer (question 4)

7.1.2		GEK AES Forms: The User's View

Forms in GEM AES are essentially the same as printed forms. For
example, GEM AES uses the same 'three types of response that appear
on the product survey. However, GEM AES uses its own terminology:

* radio buttons - The "check-one-only" type of response.

If a user selects one button, all other buttons are automatically
de-selected. Radio buttons are a "one of many" structure.

* check boxes - The "check-all-that-apply" type of response.

7-2
GEM AES 1JY69MM1fi6i!- Guide	).I 		Introduction

The user can select one or more of the options, or none at all.
Despite the name, a check mark does not necessarily appear in the
box when the user selects it. Check boxes are an "any of many"
structure.

e		editable text - For all responses requiring text entry.

GEM AES needs one piece of information that does not appear
explicitly on the product survey: notification that the user has
completed the form. To provide this information, the programmer
designates at least one box as an exit button and sets the object
flag to EXIT. When the user selects the box, the Form Library
completes its tasks and then passes control back to the application.

Many GEM AES forms have two exit buttons, one labeled "OK" and the
other labeled "Cancel". These buttons have the following functions:

		OK - Tells the Form Library that the form is complete. The
application can then act on the user's responses.

		Cancel - Tells the Form Library to ignore any responses and to
return control to the application. The environment remains the
same as it was before GEM AES displayed the form.

A form's exit buttons do not have to be labeled "OK" and "Cancel".
For example, a form can have an "OK" button alone, or it can have
buttons labeled "Excellent", "Very Good", "Good", "Fair I., "Poor".
The labels on the exit button or buttons depend entirely on the
application.

7.1.3		Dialog Boxes

A dialog, which is a special kind of form, provides a consistent
framework for interaction between an application and a user when
either of the following conditions exists:

		The application needs more information before it can carry out a
command.

		An error or some other condition occurs that requires that the
user be notified immediately.

Dialog boxes appear in the center of the screen. Each box contains
text and one or more exit buttons.

Dialogs are stored on disk as resources, which lets an application
programmer alter their content (for example, rewrite a message from
English to German) without having to make changes to the application
using them or the Form Library itself.

7-3
GEM AES Programmer's Guide	7.1 		Introduction

7.1.3.1		Editable Text Fields

Many dialogs have editable text fields. The user can move and edit
in these fields with the following keys:

*		left- and right-arrow - Move the text cursor left and right within
the field.

If the key is held down, the cursor moves continuously until it
reaches the beginning or end of the field.

9		down-arrow and Tab - Move the cursor to the next field.

If the key is held down, the cursor moves continuously from field
to field until it reaches the last field.

Note: The cursor goes to the beginning of the field only if the
field is empty. Otherwise, the cursor goes to the first open
character position following the field's data string.

*		up-arrow and Backtab - Move the cursor to the previous field.

To Backtab, the user presses the Tab and Shift keys at the same
time.

If the keys are held down, the cursor moves continuously from
field to field until it reaches the first field.

Note: The cursor goes to the beginning of the field only if the
field is empty. Otherwise, the cursor goes to the first open
character position following the field's data string.

*		Delete - Deletes the character following the cursor.

The cursor does not move.

If held down, the key deletes continuously until all characters
following the cursor have been deleted.

o		Backspace - Deletes the character to the left of the cursor.

The cursor and any following text move one character space to the
left.

If held down, the Backspace key moves the cursor and any following
text continuously to the left, deleting characters until the
cursor reaches the beginning of the field.

*		Return/Enter - Ends editing and terminates the dialog.

The Return/Enter key works this way only if one object in the form
has been flagged as a DEFAULT object (see Section 6.3 .7.2, "Object
Flags"). If no object has been flagged as a DEFAULT object, the
Form Library ignores any Return/Enter keystrokes.

7-4
GEM AES Programmer's Guide	7.1 		introduction

For example, in the dialog in Figure 7-2, the GEM Desktop
application has flagged the "Cancel" button as the DEFAULT object.
(The DEFAULT object is identified by its heavy border.) If the
user presses the Return/Enter key, intending to format a disk, the
keystroke instead cancels the format request. The DEFAULT flag
acts as an extra safety device, forcing the user to click the
mouse pointer on "OK".

Escape - Clears all characters from the field.

The user can also move through a field by typing a delimiter
character that appears to the right of the cursor. This delimiter
character must be a character that is not allowed by the validation
string te_pvalid (see Section 6.3.2, "TEDINFO Structure").

For example, the user might be entering a filename in the following
field:

The validation string for this field is "FFFFFFFFFFF"--all valid DOS
filename characters, plus ?, *, and :. The period is not a valid
character. If the user types "file.", the Form Library looks for a
period in the field to the right of the cursor's position. Finding
one, it moves the cursor one position past the period, filling all
spaces between the text and the delimiter with blanks. The user now
sees the following field:

f i 1 e 		-1 -

Similarly, the user can type "9/30/55" into the following date
field:

The		following field results:

9		/ 3 0 / 5 5

7.1.4 Alerts

An alert is a special kind of dialog box that notifies the user a
condition has arisen that requires immediate attention and, usually,
action by the user. Alerts are GEM AES's and GEM AES-based
applications' means of handling error conditions.

Figure 7-2 shows a sample alert.

7-5
Ctm ARS Programmer's Culde	/.i introaucrion

Formatting will ERASE all
information on the disk in drive
STOP		B:. Click on OK only if you don't	M. 7. .71
	mind losing this information.

Figure 7-2. Sample GEM AES Alert

The alert is contained in a text string. In the examples that
follow, the first is the actual alert string. The second describes
the components of the string. The string uses square brackets to
separate the components.

[3][Formatting will ERASE all1information on
the disk in drivejA:. Click on OK only if you
don't1mind losing this information.lCancellRetryl

[<icon#>1[<message text>][<exit buttons>]

The components of the string are the following:

		<icon#> - A single character that identifies an icon (if any) that
appears at the left side of the alert.

0 - no icon
1 - NOTE icon
2 - WAIT icon
3 - STOP icon

		<message text> - A maximum of 200 ASCII characters for text.

The alert can have five text lines, with no more than 40
characters on each line. In the string, the lines are separated
by the logical OR symbol [1].

		<exit buttons> - One, two, or three exit buttons, each containing
no more than 20 text characters.

In the string, the exit button text is separated by the logical OR
symbol.

7.1.4.1		Error Boxes

An error box is a special kind of alert that reports DOS errors like
"File Not Found." DOS error codes are defined in the PC DOS version
2.1 Technical Reference Manual.

7-6
uEm Aisb vrogrammer - s Uuiae	/.I 		Introduction

Unlike the text string for other alerts, the text string for an
error box is generated by the Form Library instead of the
application.

7.1.5		GEN ARS Forms: The Programmer's View

Structurally, a GEM AES form is an object tree, as described in
Section 6. In the alert in Figure 7-2, the root of the object tree
is the box that gives the form its structure. The root has three
children-objects, the text and two exit buttons. The three children
have no children-objects of their own.

Figures 7-3 and 7-4 show the OBJECT structure and TEDINFO structure
elements for each part of the form's object tree.

------------------------------------------------------------
	OBJECT
	structure
	element			root	text	OK 	CANCEL
------------------------------------------------------------
I			next 1	-1	1	2	1	3	1	0	1
------------------------------------------------------------
I			head 1	1	1	-1	1	-1	1	-1	1
------------------------------------------------------------
I			tail 1	3	1	-1	1	-1	1	-1 	1
--------------------------- ---------------------------------
I			type I	G-BOX	G-TEXT I G-BOXTEXT I G-BOXTEXT I

	flags						NONE		NONE	see below
------------------------------------------------------------
I				state I	NORMAL	I NORMAL I	NORMAL I	NORMAL I
------------------------------------------------------------
I		spec I OxOO020007L I	OxOL	I	OxOL	I	OxOL	I
------------------------------------------------------------
I			X 1		96		1	80	1	368	1	368	1
------------------------------------------------------------
I			Y 1		152	1		16	1	16	1	48	1
------------------------------------------------------------
I			width 1	448	1 272	1	64	1	64 	1
------------------------------------------------------------
I			height 1	96	1		64	1	16	1	16	1
------------------------------------------------------------

Figure 7-3. OBJECT Structure Elements

7-7
GEM AES Programmer's Guide	7.1 		Introduction

Valid flags for "OK" are the Boolean OR of SELECTABLE and EXIT.

Valid flags for "Cancel" are the Boolean OR of SELECTABLE, EXIT,
DEFAULT, and LASTOB.

The X- and Y-coordinates of the root are relative to the phy sical
screen. The X- and Y-coordinates of any children are relative to
their parents-in this case, the root.

------------------------------------------------------------
	TEDINFO
	structure
	element		root	text	OK	CANCEL

------------ ------
	ptext	!see below			OK	"Cancel"
	-----------------------------------------------------------
ptmplt I - I NULLPTR I NULLPTR I 		NULLPTR I

I		pvalid I		-	I NULLPTR I NULLPTR I NULLPTR I
------------------------------------------------------------
I		font I		-	I	IBM		I	IBM	i	IBM	I
------------------------------------------------------------
I		resvdl I		-	1	0	1	0	1	0	1
------------------------------------------------------------
I		just I		-	I TE - LEFT I TE - C-NTR I TE CNTR 1	--l
------------------------------------------------------------
I		color I		-	I		SYS FG	I	SYS FG	I	SYS FG	I
--------------------------------- Z ---------------------------
I		resvd2 I		-	1	0	1	0	1	0	1
------------------------------------------------------------
I thickness I			-	1	0	1	-2	1	-2	1
------------------------------------------------------------
I		txtlen I		-	1	0	1	0	1	0	1
------------------------------------------------------------
tmplen	0		0		1	0

ptext: "Formatting will ERASE all information on the disk in
drive A:. Click on OK only if you don't mind losing
this information."

Figure 7-4. TEDINFO Structure Elements

To display the whole form, the Form Library follows the structure of
the object tree from root to children, displaying each object in the
tree according to the information contained in the object. For a
more detailed discussion of displaying object trees, see Section 6.

7-8
GEM AES Programmer's Guide			7.2	Using the Form Library

7.2		Using the Form Library

To display a form, the application calls OBJC - DRAW, passing an index
to the object tree for the form. The Object Library displays the
form in the application's window. The application then makes a call
to the FORM - DO routine, and the Form Library monitors the user's
interaction with the form.

When the user selects an exit button, the Form Library returns
control to the application. In general, the application identifies
the object(.s). that cause the Form Library to relinquish control.
After regaining control, the application must look at the form,
determine if any changes took place, and decide on appropriate
action.

By contrast with an app li cat ion-de fined form, which appears inside a
window, a dialog sits on top of windows and desk accessories and
does not have to be within a window's boundaries.

To		display a dialog, the application takes the following steps:

1.		It calls the RSRC GADDR routine to get the address of the object
tree that draws 1~he dialog. This call is described in Section
12.3.

2.		It calls the FORM CENTER routine to center the dialog on the
screen. (This cafl is optional.)

3.		It calls the FORM DIAL routine to reserve the part of the
physical screen in which the dialog will appear. Nothing else
can occupy the reserved part of the screen.

4.		It calls the FORM DIAL routine again to draw an expanding box in
which the dialog will appear. (This call is optional.)

5.		It calls the OBJC DRAW routine to display the dialog. This call
is described in gection 6.4.

6.		It calls the FORM-DO routine to let the user interact with the
dialog.

7.		Men the user satisfies the dialog's exit condition, by clicking
	on an exit button or pressing the Enter key, the application
	calls the FORM - DIAL routine, to draw a shrinking box. (This call
	is optional.)

S.		It calls the FORM DIAL routine again, to free the reserved soreen
space and to red7raw the screen.

7-9
GEM AES Programmer's Guide		7.2	Using the Form im5rary

To display an alert, the application calls the FORM ALERT routine.
The FORM-ALERT routine contains the following internal steps:

1.		It constructs the object tree of the alert, based on the input
string whose address is contained in FORM-ALERT.

2.		It saves to the menu/alert buffer the screen space that will be
taken over by the alert.

3.		It calls the OBJC-DRAW routine, to display the alert.

4.		It calls the FORM-DO routine, to let the user respond to the
alert.

5.		After the user selects an exit button, it redraws the screen from
the menu/alert buffer.

6.		It reports the user's exit button selection to the application

To display an error box, the application calls the FORM - ERROR
routine. The input parameter for FORM ERROR is a DOS error code,
and its output parameter is a code th9t tells the application to
retry or abandon the requested action. Otherwise, FORM-ERROR uses
the same internal sequence as FORM-ALERT.

7-10
GEM AES Programmer's Guide			7.3	Form Library Routines

7.3		Form Library Routines

The Form Library uses the following routines:

FORM - DO - Causes the Form Library to monitor the user's
interaction with a form.

FORM-DIAL - Reserves or frees the portion of the screen used for
dialog boxes; draws an expanding or shrinking box.

FORM-ALERT - Displays an alert box.

FORM-ERROR - Displays an error box.

FORM-CENTER - Centers a dialog box on the screen.

Each Form Library routine has a GEM AES Parameter Block, Control
Array, and Global Array that contain the following information:

GEM AES Parameter Block
	params(O)					=	long	address	(32	bits)	of	control array
	params(l)					=	long	address	(32	bits)	of	global array
	params(2)					=	long	address	(32	bits)	of	int in array
	params(3)					=	long	address	(32	bits)	of	int out array
	params(4)					=	long	address	(32	bits)	of	addr - in array
	params(5)					=	long	address	(32	bits)	of	addr-out array

	Control Array
	control(O)			=	op-code
	control(l)			=	size in WORDS of int in array
	control(2)			=	size in WORDS of int out array
	control(3)			=	size in LONGS of addr in array
	control(4)			=	size in LONGS of addr-out array

Global Array
	global(O)			=	ap_version
	global(l)			=	ap~_count
	global(2)			=	ap_id
	global(3,4)			=	ap__private
	global(5,6)			=	ap_ptree
	global(7,B)			=	ap~_lresv
	global(9,10)			=	ap_2resv
	global(11,12)			=	ap__3resv
	global(13,14)			= 	ap_4resv

Global Array parameters are described in Section 3.

7-11
GEM AES Programmer's Guide		7.3	Form Library Routines

Each routine also contains some or all of the following arrays:

&		Integer Input ( int in) - Unless otherwise noted, each parameter in
this array is a Wd-RD.

e		Integer Output (int - out) - Unless otherwise noted, each parameter
	in this array is a WORD.

*		Address Input (addr - in) - Unless otherwise noted, each parameter
	in this array is a POINTER.

o		Address Output (addr out) - Unless otherwise noted, each parameter
in this array is a TOINTER.

7-12
GEM AES Programmer's Guide		7.3	Form Library Routines

7.3.1 FORK-DO

Purpose:

Causes the Form Library to monitor the user's interaction with a
form.

Parameters:

control(O)			=	50
control(l)			=	1
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-in(O)			= 	fo-dostartob

int-out(O)			= 	fo-doreturn

addr-in(O)			= 	fo-dotree

		fo dostartob - The number of an object (which must be an editable
text field) that the application wants active when the form is
displayed. The application can pass in a value of -1 if the form
does not contain editable text fields.

		fo doreturn - The number of the object that caused the exit from
th-e user's interaction with the form.

		fo - dotree - The address of the object tree that draws this
form.

Sample call to C language binding:

fo-doreturn = form-do(fo-dotree, fo-dostartob);
GEM AES Programmer's Guide		7.3	Form Library Routines

7-3.2		FORM-DIAL

Purpose:

Depending on the value in fo-diflag, does one of the following:

		reserves a portion of the physical screen for a dialog box

		draws an expanding box in which the dialog will appear

		draws a shrinking box when the user has completed interacting with
the dialog

		frees the reserved portion of the screen and redraws the screen

Parameters:

control(O)			=	51
control(l)			=	9
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int in(O)			=	fo-diflag
int in(l)			=	fo-dilittlx
int in(2)			=	fo-dilittly
int in(3)			=	fo-dilittlw
int in(4)			=	fo-dilittlh
int in(5)			=	fo-dibigx
int in(6)			=	fo-dibigy
int in(7)			=	fo-dibigw
int-in(S)			= 	fo-dibigh

int-out(O)			= 	fo-direturn

fo_diflag - The FORM-DIAL action being invoked by the current
call.

0 - FMD-START		Reserves screen space for the dialog box.

1 -		FMD GROW Draws expanding box from small to large X, Y,
widEh, and height (see description of GRAF-GROWBOX routine in
Chapter 8).

2 -		FMD - SHRINK - Draws shrinking box from large to small X, Y,
wid~h, and height (see description of GRAF-SHRINKBOX in
Chapter 8).

3 -		FMD-FINISH - Frees screen space reserved by FMD_START; causes
application to redraw screen.
GEM AES Programmer's Guide			7.3	Form LibrarY Routines

		fo-dilittlx - The X-coordinate of the box's smallest size.

		fo-dilittly - The Y-coordinate of the box's smallest size.

		fo-dilittlw - The width (in pixels) of the box's smallest size.

		fo-dilittlh - The height (in pixels) of the box's smallest
size.

		fo-dibigx - The X-coordinate of the box's largest size.

		fo-dibigy - The Y-coordinate of the box's largest size.

		fo-dibigw - The width (in pixels) of the box's largest size.

		fo-dibigh - The height (in pixels) of the box's largest size.

		fo-direturn - A coded return message.

0 - an error exists
n (positive integer) - no error exists

Sample call to C language binding:

fo-direturn = form-dial(fo-diflag, fo_dix, fo-diy,
fo-diw, fo-dih);

,011

7-15
GEM AES Programmer's Guide		7.3	Form Library Routines

7.3.3 FORM-ALERT

Purpose:

Displays an alert.

Section 7.2 describes the complete sequence of calls internal to
FORM-ALERT.

Parameters:

control(O)			=	52
control(l)			=	1
control(2)			=	1
control(3)			=	1
control(4)			= 	o

int-in(O)			= 	fo-adefbttn

int-out(O)			= 	fo-aexbttn

addr-in(-)			= 	fo-astring

		fo-adefbttn - the form's DEFAULT exit button (see Section 7.1.3.1)

0 - no DEFAULT exit button
1 - first exit button
2 - second exit button
3 - third exit button

		fo aexbttn - a number that identifies the exit button selected by
the user

1 - first exit button in string
2 - second exit button in string
3 - third exit button in string

		fo-astring - the address of the string containing the alert

Sample call to C language binding:

fo-aexbttn = form-alert(fo-adefbttn, fo-astring);

7-16
GEM AES Programmer's Guide			7.3	Form Library Routines

7.3.4		FORK-ERROR

Purpose:

Displays an error box.

Parameters:

control(O)			=	53
control(l)			=	1
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int-in(O)			= 	fo-enum

int-out(O)			= 	fo-eexbttn

		fo-enum - the DOS error code

		fo eexbttn - a code that identifies the user's exit button
sefection

1 - first exit button in string
2 - second exit button in string
3 - third exit button in string

Sample call to C language binding:

fo-eexbttn = form-error(fo-enum);

7-17
GEM AES Programmer's Guide		7.3	Form LibrarY Routines

7.3-5 FORM-CENTER

Purpose:

Centers a dialog box on the screen.

Parameters:

control(O)			=	54
control(l)			=	0
control(2)			=	5
control(3)			=	1
control(4)			= 	0

int out(O)			=	fo-cresvd
int out(l)			=	fo cX
int out(2)			=	fo-cy
int out(3)			=	fo cw
int-out(4)			= 	fo-ch

addr-in(O)			= 	fo-ctree

		fo-cresvd - [RESERVED]; values equals 1 (one).

		fo-cx - The X-coordinate of the centered object tree containing
the dialog box.

		fo_cy - The Y-coordinate of the centered object tree containing
the dialog box.

		fo-cw - The width (in pixels) of the centered object tree
containing the dialog box.

		fo-ch - The height (in pixels) of the centered object tree
containing the dialog box.

		fo-ctree - The address of the object tree that describes the
dialog.

Sample call to C language binding:

fo-cresvd = form-center(fo ctree, &fo cx, &fo-cy, &fo-cw,
	~'fo-ch)

End of Section 7

7-18
	Section 8
Graphics Library

8.1		Introduction

In certain circumstances a graphics application might need to
manipulate a rectangular outline (a box drawn with lines) on the
screen. The Graphics Library provides a set of routines for these
manipulations. As a result, each application cammake calls to a
single library within GEM AES, without having to carry the routines
in its own code.

Graphics Library routines are based on GEM VDI routines that are
fully described in the GEM Programmer's Guide, Volume l.- VDI. GEM
AES runs on top of GEM VDI, and a graphics application should use
GEM VDI for its graphics output. However, all graphics input is
made directly through GEM AES.

Graphics Library routines also return the GEM VDI handle of the
current opened screen workstation, change the mouse form to one of a
predefined set or to a form defined by the application, and get
information on the mouse and keyboard.

8.2		Using the Graphics Library

The boxes manipulated by the Graphics Library routines can be used
for a variety of purposes. In the GEM Desktop application, for
example, the GRAF RUBBERBOX routine draws the box that appears when
a user drags wf-th the mouse to select a group of icons. The
GRAF GROWBOX routine draws the expanding box that appears when a
user opens an icon, and the GRAF SHRINKBOX routine draws the box
that appears when the user closes a window.

8.3		Graphics Library Routines

The Graphics Library uses the following routines:

		GRAF RUBBERBOX - draws a "rubber" box that expands and contracts
from a fixed point as the mouse moves

		GRAF-DRAGBOX - moves a box, keeping the mouse pointer in the same
position in the box

		GRAF-MOVEBOX - draws a moving box

		GRAF-GROWBOX - draws an expanding box outline

		GRAF-SHRINKBOX - draws a shrinking box outline

8-1
I
~141N "n Isrogrammeris dulae			9.5	Graphics Library Routines

		GRAF - WATCHBOX - watches a box to see if the mouse pointer (with
	button down) is inside

		GRAF-SLIDEBOX - keeps a sliding box inside its parent box

		GRAF HANDLE - returns a GEM VDI handle for the opened screen
work~_tation that the GEM AES libraries use

		GRAF-MOUSE - lets an application change the mouse form to one of a
predefined set or to an application-defined form

		GRAF MKSTATE - returns the current mouse location, mouse button
s~
tate, and keyboard state

The following sections describe these routines.

Each Graphics Library routine has a GEM AES Parameter Block, Control
Array, and Global Array that contain the following information:

GEM AES Parameter Block
	params(O)				=	long	address	(32	bits)	of	control array
	params(l)				=	long	address	(32	bits)	of	global array
	params(2)				=	long	address	(32	bits)	of	int - in array
	params(3)				=	long	address	(32	bits)	of	int out array
	params(4)				=	long	address	(32	bits)	of	add-f - in array
	params(5)				=	long	address	(32	bits)	of	addr-out array

control(O)			=	op-code
control(l)			=	size in WORDS of int in array
control(2)			=	size in WORDS of int out array
control(3)			=	size in LONGS of addr - in array
control(4)			=	size in LONGS of addr-out array

Global Array
	global(O)			=	ap_version
	global(l)			=	ap-count
	global(2)			=	ap_id
	global(3,4)			=	ap_private
	global(5,6)			=	ap_pname
	global(7,8)			=	ap_lresv
	global(9,10)			=	ap-2resv
	global(11,12)			=	ap-3resv
	global(13,14)			= 	ap-4resv

Global Array parameters are described in Section 3.

8-2
GEK AES Programmer's Guide			8.3	Graphics Library Routines

Each routine also contains some or all of the following arrays:

		Integer Input ( int in) - Unless otherwise noted, each parameter in
this array is a W6-RD.

		Integer Output ( int - out) - Unless otherwise noted, each parameter
	in this array is a WORD.

		Address Input (addr I in) - Unless otherwise noted, each parameter
	in this array is a POINTER.

		Address Output (addr out) - Unless otherwise noted, each parameter
in this array is a IFOINTER.

8-3
ULJI-I PLL.3 rIUY11111ullel 5 L3ulue			U J	UldiAlIUS LIULdLy AUULIIIL-S

8.3.1 GRAF-RUBBERBOX

Purpose:

Draws a "rubber box.-

The position of the box's upper left corner is fixed, but by
dragging the lower right corner with the mouse pointer, the user
can make the box larger or smaller. The call returns the rubber
box's new size when the user releases the mouse button.

Parameters:

control(O)			=	70
control(l)			=	4
control(2)			=	3
control(3)			=	0
control(4)			= 	0

int in(O)			=	gr rx
int in(l)			=	gr-ry
int in(2)			=	gr_rminwidth
int-in(3)			=	gr_rminheight

int out(O) = gr_rreturn
int out(l) = gr_rlastwidth
int-out(2) = gr-rlastheight

 gr_rx - the box's X-coordinate

 gr_ry - the box's Y-coordinate

 gr_rminwidth		the box's smallest possible width in pixels

 gr_rminheight		the box's smallest possible height in pixels

 gr_rreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

		gr_rlastwidth	the width of the box when the user released the
	mouse button
		gr_rlastheight	the height of the box when the user released the
	mouse button

8-4
GEM AES Programmer's Guide	8.3		Graphics Library Routines

Sample call to C language binding:

1~		gr-rreturn = graf-rubberbox(gr-rx, gr-ry,
gr-rminwidth, gr-rminheight,
&gr-rlastwidth,
&gr~_rlastheight);

8-5
8.3.2		GRAF-DRAGBOX

Purpose:

Lets a user drag a box within an appli cat ion-de fined boundary
rectangle.

When the user presses the mouse button to begin dragging, GEM AES
makes a GEM VDI call to get the mouse's location. As the user
drags, this call keeps the mouse pointer in a fixed position
relative to the box's upper left corner.

Parameters:

control(O)			=	71
control(l)			=	8
control(2)			=	3
control(3)			=	0
control(4)			= 	0

int - in(O)			= 	gr-dwidth
int in(l)			=	gr dheight
int-in(2)			=	gr-dstartx
int in(3)			=	gr dstarty
int in(4)			=	gr dboundx
int in(5)			=	gr - dboundy
int in(6)			=	gr dboundw
int-in(7)			= 	gr-dboundh

int out(O) = gr-dreturn
int out(l)			=	gr - dfinishx
int-out(2)			= 	gr-dfinishy

 gr-dwidth		the width in pixels of the box being dragged

 gr-dheight		the height in pixels of the box being dragged

 gr-dstartx		the box's starting X-coordinate

 gr-dstarty		the box's starting Y-coordinate

 gr-dboundx		the X-coordinate of the boundary rectangle

 gr_dboundy		the Y-coordinate of the boundary rectangle

 gr-dboundw - the width in pixels of the boundary rectangle

 gr-dboundh - the height in pixels of the boundary rectangle

8-6
GEM AES Programmer's Guide			8.3	Graphics Library Routines

		gr_dreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

		gr-dfinishx - the box's X-coordinate when the user released the
mouse button

		gr_dfinishy - the box's Y-coordinate when the user released the
mouse button

Sample call to C language binding:

gr_dreturn = graf-dragbox(gr_dwidth, gr_dheight,
gr - dstartx, gr-dstarty,
gr-dboundx, gr_dboundy,
gr_dboundw, gr - dboundh,
&gr-dfinishx, ~gr-dfinishy);

I-
UrA-I tua rivyZammer 5 %julue			CS . .3	t~rdpnics ijIDrdKy AUUr-IneS

8.3.3		GRAF-MOVEBOX

Purpose:

Draws a box moving from one position to another.

The box's size does not change.

Parameters:

control(O)			=	72
control(l)			=	6
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int in(O)			=	gr - mwidth
int in(l)			=	gr - mheight
int in(2)			=	gr-msourcex
int in(3)			=	gr - msourcey
int in(4)			=	gr - mdestx
int-in(5)			= 	gr-mdesty

int-out(O)			= 	gr-mreturn

 gr-mwidth		the box's width in pixels

 gr_mheight		the box's height in pixels

 gr-msourcex - the box's X-coordinate, in its initial position

 gr_msourcey - the box's Y-coordinate, in its initial position

 gr-mdestx - the box's X-coordinate, in its final position

 gr_mdesty - the box's Y-coordinate, in its final position

 gr-mreturn a coded return message

0 - an error exists
n (positive integer) - no error exists

Sample call to C language binding:

gr_mreturn = graf-movebox(gr-mwidth, gr_mheight,
gr-msourcex, gr-msourcey,
gr-mdestx, gr-mdesty);

8-8
GEM AES Programmer's Guide			8.3	Graphics Library Routines

8.3.4 GRAF-GROKWX

Purpose:

Draws an expanding box outline.

Parameters:

control(O)			=	73
control(l)			=	8
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int - in(O)			=	gr-gstx
int - in(l)			=	gr_gsty
int - in(2)			=	gr_gstwidth
int - in(3)			=	gr_gstheight
int - in(4)			=	gr_gfinx
int - in(5)			=	gr_gfiny
int - in(6)			=	gr_gfinwidth
int-in(7)			= 	gr_gfinheight

int-out(O)			= 	gr_greturn

9 gr_gstx - the box's X-coordinate, in its initial size

9 gr_gsty - the box's Y-coordinate, in its initial size

* gr_gstwidth		the box's initial width in pixels

9 gr_gstheight		the box's initial height in pixels

9 gr_gfinx - the box's X-coordinate, in its final size

* gr_gfiny - the box's Y-coordinate, in its final size

* gr_gfinwidth		the box's final width in pixels

9 gr_gfinheight		the box's final height in pixels

9 gr_greturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

B-9
ULM AES Piogrammer's rulde			8.3	araphics Library Aou~ines

Sample call to C language binding:

gr_greturn = graf_growbox(gr_gstx, gr_gsty, gr_gstwidth,
	gr_gstheight, gr_gfinx,
	gr_gfiny, gr - gfinwidth,
	gr_gfinheigl~t) ;

8-10
GEM AES Programmer-s Uuiae			O.j	(jrapnics LjlDrary r-UUL-Ineb

8.3.5 GRAF-SHRINKBOX

Purpose:

Draws a shrinking box outline.

Parameters:

control(O)			=	74
control(l)			=	8
control(2)			=	i
controlM			=	0
control(4)			= 	0

int in(O)			=	gr - sfinx
int in(l)			=	gr-sfiny
int in(2)			=	gr_sfinwidth
int in(3)			=	gr_sfinheight
int in(4)			=	gr_sstx
int in(5)			=	gr_ssty
int in(6)			=	gr_sstwidth
int-in(7)			= 	gr_sstheight

int-out(O)		= gr_sreturn

o gr_sfinx - the box's X-coordinate, in its final size

o gr_sfiny - the box's Y-coordinate, in its final size

o gr_sfinwidth		the box's final width in pixels

o gr_sfinheight		the box's final height in pixels

o gr_sstx - the box's X-coordinate, in its initial size

o gr_ssty - the box's Y-coordinate, in its initial size

o gr_sstwidth - the box's initial width in pixels

e gr_sstheight - the box's initial height in pixels

o gr_sreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

8-11
- - ~~UJLUUWL=,L		a UU.LUC		U.j	ULt2jjII.Lt-5 ".LLJ.LU.Ly 	L%LJUL..LIICS

Sample call to C language binding:

gr_sreturn = graf_shrinkbox(gr_sfinx, gr_sfiny,
gr_sfinwidth,
gr_sfinheight, gr sstx,
gr_ssty, gr_sstwidth,
gr_sstheight) ;

B-12
um Phs Frogrammer-s wice			6.j	urapnics imrary xoutines

8.3.6		GRAF WATCHBOX

Purpose:

Tracks the mouse pointer in and out of a predefined box.

The box's object state changes as the mouse pointer enters and
leaves the box. The application makes this call only when the
mouse button is being held down, and the routine returns a value
only when the user releases the mouse button.

The box is contained in an object tree. The input variables for
gr-winstate and gr-woutstate are defined in Section 6.3.7.3.

Parameters:

control(O)			=	75
control(l)			=	4
control(2)			=	I
control(3)			=	I
control(4)			= 	0

int in(O)			=	[reserved]
int in(l)			=	gr - wobject
int in(2)			=	gr - winstate
int-in(3)			= 	gr-woutstate

int-out(O)			= 	gr-wreturn

addr-in(O)			= 	gr-wptree

		gr-wobject - the index of the object in the tree

		gr winstate - the box's state when the mouse pointer (with button
down) is inside it

OxOOOO NORMAL
OxOO01 SELECTED
OxOO02 CROSSED
OxOO04 CHECKED
OxO008 DISABLED
OxOO10 OUTLINED
OxOO20 SHADOWED

8-13
GEM AES Programmer's Guide		8.3	Graphics Library Routines

e		gr - woutstate - the box's state when the mouse pointer (with button
	down) is outside it

OxOOOO NORMAL
OxOO01 SELECTED
OxOO02 CROSSED
0x0004 CHECKED
0x0008 DISABLED
OxOO10 OUTLINED
OxOO20 SHADOWED

*		gr_wreturn - the mouse pointer's position when the button was
released

0 - outside the box
1 - inside the box

e		gr_wptree - the address of the object tree containing the box

Sample call to C language binding:

gr_wreturn = graf_watchbox(gr_wptree, gr - wobject,
gr-winstate, gr-woutstate);

B-14
GEM AES Programmer's Guide			8.3	Graphics Library Routines

8.3.7		GRAF-SLIDEBOX

Purpose:

Tracks a sliding box inside a parent box.

Mouse movement causes the sliding box to move, and the parent box
defines the sliding box's range of motion.

An application makes this call only when the mouse button is being
held down, and the routine returns a value only when the user
releases the mouse button.

Both boxes (slider and parent) are contained in an object tree.
The return value is a number that indicates the slider's relative
position inside the parent box.

Parameters:

control(O)			=	76
control(l)			=	3
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int in(O) = gr s1parent
int-in(l) = gr_slobject
int-in(2) = gr-slvh

int-out(O)			= 	gr_slreturn

addr-in(O)			= 	gr_slptree

		gr_slparent - The index of the parent in the tree.

		gr_slobject - The index of the object (the slider) in the tree.

		gr_slvh - A code for the direction of the slider's movement.

0 - horizontal
1 - vertical

		gr~_slreturn The position of the center of the slider relative to
its parent. The value can range from 0 to 1000.

if gr slvh			0:	0 = left
1000 = right

if gr-slvh			1:	0 = top
1000 = bottom

		gr~_slptree The address of the object tree containing slider and
parent.

8-15
GEM ALS Programmer - s UU I ae			0 . .3	Ul CLPI L L ~- a -~mL -1

Sample call to C language binding:

gr_slreturn = graf_slidebox(gr_slptree, gr_slparent,
gr_slobject, gr-slvh);

8-16
GEM AES Programmer's Guide			8.3	Graphics Library Routines

8.3.8		GRAF-HANDLE

Purpose:

Gets the GEM VDI handle for the currently opened screen
workstation.

GEM AES and GEM applications share this handle whenever they make
GEM VDI calls.

Parameters:

control(O)			=	77
control(l)			=	0
control(2)			=	5
control(3)			=	0
control(4)			= 	0

int out(O)			=	gr-handle
int out(l)			=	gr - hwchar
int out(2)			=	gr-hhchar
int out(3)			=	gr hwbox
int-out(4)			= 	gr-hhbox

* gr-handle		the GEM VDI handle

o gr hwchar		the width (in pixels) of a character cell in the
	sys-tem font used in menus and dialogs

e		gr hhchar - the height (in pixels) of a character cell in the
syg-tem font used in menus and dialogs

*		gr I hwbox - the width (in pixels) of a square box large enough to
	hold a system font character

9		gr hhbox - the height (in pixels) of a square box large enough to
hold a system font character

Sample call to C language binding:

gr-handle = graf-handle(&gr-hwchar, &gr-hhchar,
&gr-hwbox, &gr-hhbox);

8-17
GEM AES Programmer's Guide			8.3	Graphics Library i~outines

8.3.9 GRAF-MOUSE

Purpose:

Changes the mouse form to one of a predefined set or to an
application-defined form.

Note: The application selects or defines the mouse form that
appears in the work area of its topmost (active) window. Outside
the work area of the active window, the mouse form must always be
an arrow or an hourglass.

If it uses a mouse form other than an arrow, an application must
make a GRAF MOUSE call each time the mouse form exits or enters
the active window's work area.

The GRAF MOUSE call upon exit converts the mouse form to an arrow.
The GRAF-MOUSE call upon entry converts the mouse form back to the
application's mouse form.

The application uses an EVNT-MULTI call, specifying a mouse
rectangle equal to the active window's work area, to detect mouse
form exit and entry.

Parameters:

control(O)			=	78
control(l)			=	1
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-in(O)			= 	gr-monumber

int-out(O)			= 	gr-moreturn

addr-in(O)			= 	gr_mofaddr

e gr-monumber - a code identifying a predefined mouse form

	0 - arrow
	1 - text cursor (vertical bar)
	2 - hourglass
	3 - hand with pointing finger
	4 - flat band, extended fingers
	5 - thin cross hair
	6 - thick cross hair
	7 - outline cross hair
255 - mouse form stored in gr_mofaddr
256 - hide mouse form
257 - show mouse form

B-18
GEN AES Programmer's Guide		8.3 Graphics Library Routines

		gr-moreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

		gr-mofaddr - the address of a 35-word buffer that fits the mouse
form definition block specified in the GEM Programmer's Guide,
Volume 1: VDI.

Sample call to C language binding:

gr-moreturn = graf-mouse(gr-monumber, gr-mofaddr);

8-19
GE24 AES Programmer's Guide			M	6raphics Library Routln6F,

8.3.10		GRAF-MKSTATE

Purpose:

Returns the current mouse location, mouse button state, and
keyboard state.

Parameters:

control(O)			=	79
control(l)			=	0
control(2)			=	5
control(3)			=	0
control(4)			= 	0

int out(O)			=	gr_mkresvd
int-out(O)			=	gr - mkmx
int out(O)			=	gr-mkmy
int out(O)			=	gr - mkmstate
int-out(O)			= 	gr-mkkstate

		gr-mkresvd - [RESERVED]; value always equals 1 (one).

		gr_mkmx - The X-coordinate of the mouse's current location.

		gr-mkmy - The Y-coordinate of the mouse's current location.

		gr_mkmstate - The current mouse button state.

The following bits represent the buttons:

OxOO01 - button on left OxOO02 - second button from left OxOO04
third button from left, etc.

This parameter uses the following bit settings:

0 - button up I - button down

		gr_mkkstate - The current state of the keyboard's right-Shift,
left-Shift, Ctrl, and Alt keys.

The following bits represent the keys:

OxOO01 - right-Shift
OxOO02 - left-Shift
OxOO04 - Ctrl
OxOO08 - Alt

B-20
tamm P-c-b L-rogrammer s tjuiae			O.J	tirapnics ijiDrary mouLines

This parameter uses the following bit settings:

0 - key up
1 - key down

Sample call to C language binding:

gr-mkresvd = graf-mkstate(&gr-mkmx, &gr-mkmy,
&gr - mkmstate,
&gr-mkkstate);

End of Section 8

8-21
....
	Section 9
Scrap Library

9.1		Introduction

GEM AES's Scrap Library provides a set of routines that increase the
usefulness of different applications by managing data interchange
between the applications.

A standard data interchange format offers several advantages,
including the following:

*		Users can assemble an integrated set of independently developed
applications.

o		An application can take advantage of functions and output provided
by other applications.

The Scrap Library's user interface lets the user cut or copy from
one application's data space and paste into another's. The
temporary holding place for these scraps of data is a clipboard,
which is the implied destination for all cuts and the implied source
for all pastes.

The user can place data on the clipboard in two ways:

		By cutting, the user deletes the data from the source
application's data space.

		By copying, the user leaves the original piece of data in the
source application's data space.

The clipboard is only one level deep; each new cut or copy over
writes the current contents of the clipboard.

A paste is in effect a copy from the clipboard to the target
application. The data remains on the clipboard, allowing the user
to paste the same piece of data repeatedly.

9.2		Using the Scrap Library

GEM AES's Scrap Library supports the following interactions:

 writing the name of a scrap directory to the clipboard
 reading the name of a scrap directory from the clipboard
 managing the use of the disk as an extensible scrap area
	Ur~Vl PLI:-O rLUYLIMILLUICL 5 UU~UC I . ~ -W .-~V .		j

GEM AES stores scrap on the disk. The filename for scrap data is
always SCRAP. The data's filetype identifies what kind of data it
is. For different applications to be integrated, GEM AES must
define standard data types in which scrap may be stored.

GEM AES supports the following standard data types.		Each is
identified by a filetype in parentheses.
	ASCII text strings (.TXT)
	spreadsheet data (.DIF)
	metafile - GEM VDI-type graphic images (.GEM)
	bit-images - GEM VDI standard forms (.IMG)

All GEM AES programs should at least be able to read and write ASCII
data. Metafiles are described in the GEM Programmer's Guide, Volume
1: VDI.

In addition to these standard data types, programmers can add their
own application-specific data types.

An application can find or establish the full path (for example,
A:\SCRAPDIR\SCRAP.*) by using the SCRAP-READ and SCRAP-WRITE
routines.

To be accessible to a variety of applications, a piece of scrap
might appear on the clipboard in several data types. The
application can find and/or manipulate the actual size, contents,
and existence of scrap by making the following DOS file system
calls:

search
create
open
read
write
close
delete
9 get filesize

9.3		Scrap Library Routines

The Scrap Library uses the following routines:

		SCRP_READ	reads the scrap directory currently stored on the
	clipboard

 SCRP-WRITE		writes the scrap directory to the clipboard

The following sections describe these routines.
GEM AES Programmer's Guide			9.3	Scrap Library Routines

Each Scrap Library routine has a GEM AES Parameter Block, Control
Array, and Global Array that contain the following information:

GEM AES Parameter Block
	params(O)					=	long	address	(32	bits)	of	control array
	params(l)					=	long	address	(32	bits)	of	global array
	params(2)					=	long	address	(32	bits)	of	int in array
	params(3)					=	long	address	(32	bits)	of	int-out array
	params(4)					=	long	address	(32	bits)	of	addr-in array

params(5)			=	long address (32 bits) of addr-out array

	Control Array
	control(O)			=	op-code
	control(l)			=	size in WORDS of int in array
	control(2)			=	size in WORDS of int-out array
	control(3)			=	size in LONGS of add-r-in array
	control(4)			=	size in LONGS of addr-out array

Global Array
	global(O)			=	ap_version
	global(l)			=	ap_~ount
	global(2)			=	ap_id
	global(3,4)			=	ap_private
	global(5,6)			=	ap_ptree
	global(7,8)			=	ap_lresv
	global(9,10)			=	ap_2resv
	global(11,12)			=	ap-3resv
	global(13,14)			= 	ap_4resv

Global Array parameters are described in Section 3.

Each routine also contains some or all of the following arrays:

e		Integer Input ( int in) - Unless otherwise noted, each parameter in
this array is a Wd-RD.

e		Integer Output ( int - out) - Unless otherwise noted, each parameter
	in this array is a WORD.

o		Address Input (addr - in) - Unless otherwise noted, each parameter
in this array is a POINTER.

o		Address Output (addr out) - Unless otherwise noted, each parameter
in this array is a TOINTER.

9-3
GEm AEs Programmer-s uuiue

9.3.1 SCRP-R&AD

Purpose:

Reads the current scrap directory on the clipboard.

Parameters:

control(O)			=	80
control(l)			=	0
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-out(O)			= 	sc_rreturn

addr-in(O)			= 	sc-rpscrap

		sc-rreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

		sc_rpscrap - the address of the buffer into which the scrap
directory will be copied

Sample call to C language binding:

sc-rreturn = scrp_read(sc_rpscrap);

9-4
GEM AES Programmer's Guide			9.3	Scrap Library Routines

9.3.2 SCRP WRITE

Purpose:

Writes a new scrap directory to the clipboard, as a result of a
CUT or COPY command from the user.

Parameters:

control(O)			=	81
control(l)			=	0
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-out(O)			= 	sc-wreturn

addr-in(O)			= 	sc_wpscrap

*		sc-wreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

*		sc-wpscrap - the address of the buffer from which the new scrap
directory will be copied to the clipboard

Sample call to C language binding:

sc-wreturn = scrp~_write(sc_wpscrap);

End of Section 9

9-5
	Section 10
File Selector Library

10.1		Introduction

Many applications require that the user provide a filename to create
a new file, recall an existing file, or use a file as input for a
function like PRINT. Programmers can design applications that
elicit the filename from the user in a variety of ways, three of
which are described below:

		The application does not display a directory of existing
filenames. To act on an existing file, the user must remember its
filename. To create a file, the user must provide a filename that
does not already exist in the directory.

		The application displays a directory, and the user types a new or
existing filename.

		The application displays a directory. To act on an existing file,
the user selects the filename directly from the directory. To
create a file, the user types a filename.

The last method, the easiest for the user, is the method used by GE24
AES's File Selector Library, which provides a consistent user
interface for filename entry and selection.

When an application requests the File Selector Library to prompt the
user for a filename, a special dialog box called the File Selector
(or "Item Selector") appears on the screen. See Figure 10-1.

k

10-1
GEM AES Programmer's Guide	LV..L 		IIIUL~uu~4-1

ITEM SELECTOR

Directory: B:\GEMDRAW\*.GEM .......................................

Selection:
t
BANK				GEM
FORX2			GEM
GEMFILE		GEM
MAP				GEM
MYLOGO		GEM
MYMAP			GEM
STOCK			GEM	7 Ox 7.
STOCX2		GEM
-------- --
	Figure 10-1. File Selector Dialog Box

The File Selector dialog box displays the name of the current
directory (including drive identifier), a selection field, and a
list of filenames contained in the directory. The scrolling area to
the right of the directory list contains up- and down-arrows, a
scroll bar, and a slider.

The next section describes how the user interacts with the File
Selector.

10.2 Using the File Selector Library

The File Selector Library provides the programmer with a consistent
method of prompting the user for a filename. After the user selects
a menu command that requires a filename as input, the following
events typically occur:

1.		The application calls the File Selector Library to display the
File Selector dialog box.

2.		Before selecting or entering a filename, the user can do the
following:

scroll through the list of files in the directory

The File Selector dialog box's scrolling area is functionally
the same as the vertical scrolling area of a window. For
details of the user's interaction with the scrolling area, see
the descriptions of the up-arrow, down-arrow, and the vertical
scroll bar and slider in Section 11.2.1.

10-2
GEM AES Programmer's Guide 10.2 Using the File Selector Library

e change the directory being displayed

To do so, the user clicks on "Directory:" and then types in a
new drive identifier, directory path name, and file
specification containing a wildcard in the filename or
filetype, as in the following example:

C:\receipts\*.bas

After changing the directory specification, the user clicks the
mouse pointer anywhere inside the window containing the list of
filenames. GEM AES updates the window, displaying a list of
filenames that fit the new specification.

3.		The user selects a filename from the directory in the File
Selector dialog box or enters a new filename.

To select an existing file, the user places the mouse pointer
over the filename and clicks. If the filename is not currently
visible in the list, the user can place the mouse pointer over
"Selection:", click, and then type the filename.

To create a new file, the user places the pointer over
"Selection:", clicks, and then types the filename.

4.		The user selects OK or Cancel.

5.		The File Selector Library returns the following information to
the application:

e		the filename that was selected or entered

e		the current directory and wildcard specification

a		the way in which the user exited the File Selector dialog box
(OK or Cancel)

6.		If the user selected OK, the application continues on with the
filename that was selected or entered.

10.3		File Selector Library Routine

The File Selector Library uses the following routine:

FSEL-INPUT - Displays the File Selector dialog box and lets the
user select a filename.

10-3
GEM AES Programmer's Guide			1U.3	t'lie beiector iiorazy nvu~-~iic

This File Selector Library routine has a GEM AES Parameter Block,
Control Array, and Global Array that contain the following
information:

GEM AES Parameter Block
	params(O)				=	long	address	(32	bits)	of	control array
	params(l)				=	long	address	(32	bits)	of	global array
	params(2)				=	long	address	(32	bits)	of	int - in array
	params(3)				=	long	address	(32	bits)	of	int-out array
	params(4)				=	long	address	(32	bits)	of	addr_in array
	params(S)				=	long	address	(32	bits)	of	addr-out array

	Control Array
	control(O)			=	op-code
	control(l)			=	size in WORDS of int in array
	control(2)			=	size in WORDS of int-out array
	control(3)			=	size in LONGS of add-r - in array
	control(4)			=	size in LONGS of addr-out array

Global Array
	global(O)			=	ap_version
	global(l)			=	ap_?ount
	global(2)			=	ap id
	global(3,4)			=	apD?rivate
	global(5,6)			=	ap ptree
	global(7,8)			=	ap-iresv
	global(9,10)			=	ap_2resv
	global(11,12 )			=	ap-3resv
	global(13,14)			= 	ap_4resv

Global Array parameters are described in Section 3.

This routine also contains some or all of the following arrays:

e		Integer Input ( int_in) - Unless otherwise noted, each parameter in
this array is a WORD.

*		Integer Output (int - out) - Unless otherwise noted, each parameter
	in this array is a WORD.

*		Address Input (addr_in) - Unless otherwise noted, each parameter
in this array is a POINTER.

o		Address Output (addr-out) - Unless otherwise noted, each parameter
in this array is a POINTER.

10-4
GEM AES Programmer's Guide			10.3	File Selector Library Routine

10.3.1 FSEL-INPUT

Purpose:

Displays the File Selector dialog box and monitors the user's
interaction with it.

The File Selector Library returns the results of this interaction
between the user and the dialog to the application.

Parameters:

control(O)			=	90
control(l)			=	0
control(2)			=	2
control(3)			=	2
control(4)			= 	0

int-out(O)		= fs ireturn
int-out(l)		= fs-iexbutton

addr - in(O) = fs_iinpath
addr-in(l) = fs-iinsel

e		fs-ireturn - A coded return message.

0 - an error exists
n (positive integer) - no error exists

e		fs-iexbutton A code identifying the exit button selected by the
user.

0 - Cancel
1 - OK

*		fs - iinpath The address of the buffer that holds the initial
directory specification displayed in the File Selector dialog box.
This buffer will also hold the directory specification that was in
the File Selector dialog box when the user selected OK or Cancel.

*		fs iinsel - The address of the buffer that holds the initial
selection displayed in the File Selector dialog box. This buffer
will also hold the selection that was in the File Selector dialog
box when the user selected OK or Cancel.

10-5
GEM AES Programmer's Guide			10.3	File Selector Library Routine

Sample call to C language binding:

fs-ireturn = fsel_input(fs_iinpath, fs-iinsel,
. &fs-iexbutton);

End of Section 10

10-6
	Section 11
Window Library

11.1		Introduction

A window is an area with clearly defined boundaries. GEM AES
supports two kinds of windows:

		the desktop window
		application windows

While the user is in the GEM AES environment, the desktop window is
always present on the screen. It contains the menu bar and the
desktop surface. The desktop window is owned by the primary
application and serves as the backdrop for the application's other
windows.

GEM applications use application windows whenever they need to
present data n the screen. In addition, GEM AES supports
overlapping windows to allow an application to display two pieces of
data at the same time. For example, a word processor that lets a
user work simultaneously on two files can show each file in a
separate window.

Additional features of application windows include the following:

		They let the user view help information and the application data
area at the same time.

		They let the user cut and paste data between applications.

		They make it possible to display status information from several
background activities--for example, compiling, sorting, and
transferring data.

GIN AES supports a maximum of eight (8) windows at a time. Of these
eight windows, the desktop window is always identified by a window
handle (identifier) of zero. A GEM application can use all eight
available windows, although this could result in no windows being
left available for desk accessories. An application can avoid this
problem in the manner adopted by the GEM Desktop application, which
sets a limit of four (4) windows for itself, leaving the remaining
four windows available for desk accessories.

11-1
GEM AES Programmer's Guide		11.2	Using the winaow iiuidLy

11.2		Using the Window Library

An application window is made up of two components: a rectangular
work area surrounded by a border area.

Figure 11-1 illustrates the components of a typical window.

C1030 bOX		title bar	information line 	full box

1111		7	C: ~SIILES\ EAST,
6144 bytes used in 48 items.
7-*,,		l,.*__up-arrow
L_~ 		i-scroll bar
N,		N,
BROWN82-INC BROWN8 4 ~ E XF BROWN84ANC				GOAL79.INC	GDALSO-I	LSIA
	71~j			; 7-4 1
	I I		r, I		L. 	L
GOAL~AAMC JONE570.EXP JONE-~_IW 00NtSSC.EXP		00NESSCANC JONESOI-EXP	*-slider

JONESSE-INC			OONES63AXP	JONE58~ INC	J NESSA.EXP	JONES84-INC 	REPL79ANC
	1 1			1 7__~ 	117,	11	11	r,-scroll bar
REALS2.INC			REALOSANC		REAL ~4_ INC SIITH79.EXP SM.TTH7Y.INC		SMITH8C.EXP	down-arrow
101		1
size box
					T
	scroll bar			slider	scroll bari~
left-arrow				WORK AREA 	right-arrow

Figure 11-1. Components of a Typical Window

The work area has the following characteristics:

*		It is the portion of the window's area that is available for use
by the application.

9		All user interactions inside the work area are managed by the
application.

e		What appears in the work area as a result of user interaction is
defined, displayed, and controlled by the applicatiun.

The border area has the following characteristics:

11-2
ULM ALO k'roqlam, L a ~.~

e		The border area can have several different components. An
application determines which components will appear in the border
area but does not control them.

o		GEM AES's Screen Manager displays the contents of each window's
border and manages all user interactions with the border area.

11.2.1		Components of the Border Area

A window's border area has some or all of the following:

e title bar

All windows have a title bar, which appears across the top of the
window. It can contain a maximum of 80 text characters. The
application provides this text as the name of the window.

information line

The application determines if its window has an information line.

The information line appears directly under the title bar and can
contain a maximum of 80 text characters. The application provides
this text to describe the contents of the window.

The remaining features of the border are known as "window control
areas" because user interaction with any of them causes some change
to take place, either in the work area or to the window as a whole.
The application determines which window control areas appear in the
window.

 close box

The close box is located at the left end of the title bar.

When the user clicks the mouse on the close box, GEM AES sends the
application a message that the user wants the window closed.

 full box

The full box is located at the right end of the title bar.

The full box acts as a toggle with which the user can change the
window from its current size and location on the desktop to its
greatest possible size, and back again. In their greatest
possible size, most windows fill all of the desktop but the menu
bar.

11-3
GEM AES Programmer's Guicie		il. Z	U5 Llltj L.11C

e move bar

The move bar, when present, occupies the same space as the title
bar . The move bar is invisible and to the user is
indistinguishable from the title bar.

When the user Dresses the mouse button on the move bar, GEM AES
displays an XOied outline of the window. The user can drag this
outline around the desktop as long as the button is held down.
When the user releases the button, the outline disappears, andGEM
AES sends the application a message that the user wants the window
moved to the location indicated by the outline's last position.

e size box

The size box is located in the lower right corner of the window

When the user presses the mouse button on the size box, GEM AES
displays an XORed outline of the window. The upper left corner of
the outline remains in a fixed position. The lower right corner
can be dragged around as long as the user continues to press the
button.

When the user releases the button, the outline disappears. GEM
AES sends the application a message that the user wants the
window's size changed to match the size of the outline when the
button was released.

e up-arrow

The up-arrow appears at the top of the right border.

When the user clicks on the up-arrow, GEM AES moves one line (or
an equivalent) toward the beginning of the directory or file.

* down-arrow

The down-arrow appears at the bottom of the right border, directly
above the size box.

When the user clicks on the down-arrow, GEM AES moves one line (or
an equivalent) toward the bottom of the directory or file.

* left-arrow

The left-arrow appears at the left end of the bottom border.

When the user clicks on the left-arrow, GEM AES moves the
equivalent of one line toward the left side of the directory or
file.

* right-arrow

The right-arrow appears in the bottom border immediately to the
left of the size box.

11-4
Utm Ats Programmer s uulae			11.Z	Uhilly L110 "Illuun __.Y

When the user clicks on the right-arrow, GEM AES moves the
equivalent of one line toward the right side of the directory or
file.

vertical scroll bar and slider

The vertical scroll bar is located between the up-arrow and down
arrow. The vertical slider moves up and down in the scroll bar

By clicking on the part of the scroll bar above the slider (when
visible), the user moves one page (or an equivalent) toward the
beginning of the directory or file.

By clicking on the part of the scroll bar below the slider (when
visible), the user moves one page (or an equivalent) toward the
end of the directory or file.

To move quickly to the top or bottom of the window's data or to
any point between, the user can drag the slider inside the scroll
bar.

The length of the scroll bar represents all the window's data,
from top to bottom. The position of the slider in the scroll bar
indicates which part of the data is currently visible in the
window. If the slider is at the top of the scroll bar, the top of
the window shows the top of the data. If the scroll bar is two
thirds of the way down the scroll bar, the top of the window shows
a point two-thirds of the way through the data.

The size of the slider indicates how much of the data is visible
in the window. For example, if the slider is half the size of the
scroll bar, half the window's data is visible.

horizontal scroll bar and slider

The horizontal scroll bar is located between the left-arrow and
the right-arrow. The horizontal slider moves back and forth in
the scroll bar.

By clicking on the part of the scroll bar to the left of the
slider (when visible), the user moves to the left by the
equivalent of one page.

By clicking on the part of the scroll bar to the right of the
slider (when visible), the user moves to the right by the
equivalent of one page.

To move quickly anywhere to the left or right, the user can drag
the slider inside the scroll bar.

Like the vertical slider, the horizontal slider also shows the
location of the top of the window relative to the window's data
and how much of the data is visible.

11-5
GEM AES Programmerls GuiAe		11.2 Usin4 tA& W1118?5W L113ldly

The following sections describe concepts and procedures that apply
in the GEM AES windowing environment.

11.2.2		Division of Labor

GEM AES and the application divide responsibility for window
management.

GEM AES handles all user-mouse interactions that occur outside the
window's work area, including the following:

clicking on the close box or full box

pressing the mouse button in the move bar to drag the window's
outline

9		pressing the mouse button in the size box to produce a larger or
smaller window outline

e		manipulating the scroll bars

GEM AES sends a message to the application that created the window
telling it the outcome of these interactions. When it receives one
of these messages from GEM AES, the application has two choices:

		Make a Window Library call that causes the requested change to
occur.

		Ignore the message.

This division of labor between GEM AES and the application has the
following advantages:

		The application is not responsible for user interactions outside
its window's work area.

		The application determines when and if user-requested window
changes take place.

		Because it chooses which window control areas appear in its
window's border area, the application also controls the kinds of
window changes a user can request.

11.2.3		Window Management Calls

An application usually follows some variation of the following steps
to fulfill its window management responsibilities:
GEM AES Programmer"s Guiae			11.Z	UbIKILJ L11e "4-~M ---j

1.		It calls WIND - GET with a value of WF-WORKXYWH for window 0 (the
	desktop window).

This call returns the window's X- and Y-coordinates, plus its
width and height in pixels. These values identify the part of the
screen below the menu bar that is available to the application

2.		It calls WIND - CALC with the width and height values from the
	previous call, plus a code identifying the border components it
	is requesting.

WIND CALC returns the size of the work area for this window in
its greatest possible size.

3.		It determines the size of the work area it requires.

This size must be less than or equal to the size returned by the
previous call.

4.		It calls WIND CALC with the desired work area size and the code
describing th~e window's border.

WIND CALC returns the size of the window including the border
area. This size is used in the WIND-CREATE, WIND-OPEN, and
WIND-SET calls.

5.		It calls WIND - CREATE with the size returned by WIND-CALC and the
	code describing the window's border.

The size given to WIND-CREATE determines the window's maximum
possible size.

GEM AES returns a window handle (numeric identifier) for use with
the other window calls.

6.		It calls WIND OPEN with the window's initial size and location on
the desktop.

The window appears after this call has been made.

7.		It uses the window to display information to the user.

The application uses an EVNT MULTI call to wait for messages from
GEM AES regarding user requests to close, full, size, scroll, or
top (activate) the window. To support the overlapping window
environment, GEM AES can also send a message requesting that part
of the window be redrawn. The redraw procedure is described in
Section 11.2.5.

8.		It makes a WIND CLOSE call when the application no longer wants
the window visi-ble on the screen.

The window disappears, but it is still allocated to the
application and may be reopened.

11-7
GEM AES Programmer's Guide		11.2	using the Window Libr&fy

9.		It makes a WIND DELETE call when the application no longer needs
the window at a-11.

This call frees the window handle for use by another application.
The application should always close a window before deleting it.

Managing multiple windows is an extension to the procedure described
above. When an application gets a message requesting a window
change, it uses the handle of the affected window in its Window
Library calls.

11.2.4		Support of Overlapping Windows

Application windows can overlap like sheets of paper on a desktop.
The topmost window is called the active window.

When the user clicks the mouse button outside the active window's
border area, GEM AES looks at what was under the tip of the mouse
pointer and acts as follows:

If the pointer was over the desktop, GEM AES does nothing.

If the pointer was over another window, GEM AES sends a message to
the application owning the current active window. The message
informs the application that the user wants the other window
brought to the top (activated) . The application should respond to
this message with a GEM AES call to bring the other window to the
top.

There are two instances when part of a window may not be visible:

when one window overlaps another

when the active window has been positioned so that part of it is
off the physical screen

When an application sends output to the work area of its window, it
draws that output only to the portion of the physical screen that is
visible to the user. This selective drawing is called "clipping."

(GEM AES is responsible for drawing the border, but clipping applies
here as well.)

GEM AES uses a list of rectangular regions to keep track of the
portion of the physical screen belonging to each window. This list
contains the least number of non-overlapping rectangles that define
the visible area of the window. For example, if the window is fully
visible, the list contains one rectangle.

11-8
GEM AES Programmer's Guide			11.2	using tne winaow i~iDrary

The application obtains the list by making a series of WIND - GET
calls. The application must only draw to the physical screen in the
area defined by the window's current rectangle list.

11.2.5		Redrawing and Updating

To use the windowing system most efficiently, an application should
be able to respond quickly to redraw requests from GEM AES.

There are three reasons why an application might need to update a
window's work area:

		to display new application-generated information to the user

		to respond to a message reporting a user request to scroll the
contents of the window

		to respond to a request from GEM AES to redraw a portion of the
window

In each case, some portion of the work area has to be updated. This
1. update rectangle" can range in size from a one-pixel square to the
entire work area. In the first two cases above, the application
defines the update rectangle. In the third case, GEM AES's redraw
message contains the X- and Y-coordinates of the update rectangle,
as well as its width and height.

Knowing the size and location of the update rectangle, the
application follows these steps:

1.		It calls WIND UPDATE with a value of 1, which indicates the
beginning of an update.

This call freezes the rectangle lists of all the windows on the
screen.

2.		It calls WIND GET with a value of WF FIRSTXYWH, which asks for
the location and size of the first rectangle in the window's
rectangle list.

3.		If the width and height values of this rectangle are not zero, it
continues to step 4. If the values are zero, it goes to step 8.

4.		It calculates a "result rectangle, " which is the intersection (if
any) of the rectangle obtained from the window's rectangle list
and the update rectangle.

11-9
GEM PG Vol. 2: AES	il.1		Using th6 WIMUUW wulaly

5.		If the result rectangle has width and height, the application
draws the portion of the window defined by the result rectangle.
To simplify the process of clipping the window contents to fit
the rectangle (which will probably be required) , GEM VDI provides
a "set clip rectangle" call.

If the result rectangle has zero width or height, the application
doesn't draw anything. It continues to the next step.

6.		It calls WIND GET with a value of WF-NEXTXYWH, which asks for the
next rectangfe from the window's rectangle list.

7.		It repeats steps 3, 4, 5, and 6.

8.		It calls WIND-UPDATE with a value of 0, which indicates the end
of an update.

This call allows the resumption of changes to the rectangle lists
of all the windows on the screen.

11-10

I
GEM AES Programmer's Guide			11.3	Window Library Routines

11.3 Window Library Routines

The Window Library provides the following routines:

*		WIND-CREATE - allocates the application's full-size window and
returns a handle

o WIND-OPEN		opens the created window to a specified size

e WIND-CLOSE		closes an open window

o WIND-DELETE		de-allocates the application's window and handle

o		WIND-GET - gets information on a particular window

o		WIND SET - sets new values for the fields that determine how a
windZ~w is displayed

o		WIND FIND - determines which window is under the mouse's X,Y
position

e		WIND-UPDATE - notifies GEM AES that the application is about to
update or has finished updating a window, or that the application
is about to take or relinquish control of all mouse functions

o		WIND-CALC - calculates the X- and Y-coordinates and the width and
height of a window's work area or border area

The following sections describe these routines.

Each Window Library routine has a GEM AES Parameter Block, Control
Array, and Global Array that contain the following information:

GEM AES Parameter Block
	params(O)					=	long	address	(32	bits)	of	control array
	params(l)					=	long	address	(32	bits)	of	global array
	params(2)					=	long	address	(32	bits)	of	int in array
	params(3)					=	long	address	(32	bits)	of	int-out array
	params(4)					=	long	address	(32	bits)	of	addr - in array
	params(5)					=	long	address	(32	bits)	of	addr-out array

	Control Array
	control(O)			=	op code
	control(l)			=	si-Ze in WORDS of int in array
	control(2)			=	size in WORDS of int out array
	control(3)			=	size in LONGS of addr_ln array
	control(4)			=	size in LONGS of addr-out array

11-11
GEM AES Programmer s tuiut:

Global Array
	global(O)			=	ap - version
	global(l)			=	ap-count
	global(2)			=	ap_id
	global(3,4)			=	ap_private
	global(5,6)			=	ap_ptree
	global(7,8)			=	ap~_lresv
	global(9,10)			=	ap-2resv
	global(11,12)			=	ap-3resv
	global(13,14)			= 	ap-4resv

Global Array parameters are described in Section 3.

Each routine also contains some or all of the following arrays:

		Integer Input ( int_in) - Unless otherwise noted, each parameter in
this array is a WORD.

		Integer Output (int out) - Unless otherwise noted, each parameter
in this array is a WORD.

		Address Input (addr_in) - Unless otherwise noted, each parameter
in this array is a POINTER.

		Address Output (addr out) - Unless otherwise noted, each parameter
in this array is a TOINTER.

11-12

1
GEM AES Programmer's Guide			I I . i	W1 naow, 1~1 Drd ry X%UU 1_.Ljjeb

11.3.1		WIND-CREATE

Purpose:

Allocates the application's full-size window and returns the
window's handle (numeric identifier).

This routine establishes the window's greatest possible size; the
WIND-OPEN routine determines the window's actual size when opened.

Parameters:

control(O)			=	100
control(l)			=	5
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int - in(O)			=	wi-crkind
int - in(l)			=	wi_crwx
int - in(2)			=	wi_crwy
int in(3)			=	wi crww
int-in(4)			= 	wi-crwh

int-out(O)			= 	wi-crreturn

e wi-crkind - the individual components present in the window

The following bits represent the components:

OxOO01 -			NAME	(title bar with name)
OxOO02				-	CLOSE	(close box)
OxOO04 -			FULL	(full box)
OxOO08 -			MOVE	(move box)
OxOO10 -			INFO	(information line)
OxOO20				-	SIZE	(size box)
OxOO40				-	UPARROW	(up-arrow)
0x0080				-	DNARROW	(down-arrow)
OxO100				-	VSLIDE	(vertical slider)
OxO2OO				-	LFARROW	(left-arrow)
OxO4OO				-	RTARROW	(right-arrow)
OxO8OO				-	HSLIDE	(horizontal slider)

This call uses the following bit settings for each component:

0 - does not have the component
1 - has the component

* wi-crwx - the X-coordinate of the full-size window

o wi-crwy - the Y-coordinate of the full-size window

11-13
GEM AES Programmer's Guide		I 1 ..3	MLIIU~W --.7 ---

e		wi-crww - the width (in pixels) of the full-size window

*		wi-crwh - the height (in pixels) of the full-size window

*		wi crreturn - the handle (numeric identifier) that will identify
tl~7is window in future calls. Values range from 0 to n. A
negative value indicates that GEM AES has no more windows
available.

Sample call to C language binding:

wi-crreturn = wind-create(wi-crkind, wi-crwx, wi_crwy,
wi-crww, wi-crwh);

11-14
GEM AES Programmer's Guide			11.3	Window Library Routines

11.3.2 WIND-OPEN

Purpose:

opens a window in its initial size (not necessarily its full size)
and location.

Parameters:

control(O)			=	101
control(l)			=	5
control(2)			=	1
controlM			=	0
control(4)			= 	0

int in(O)			=	wi ohandle
int in(l)			=	wi-owx
int in(2)			wi-owy
int in(3)			wi oww,
int-in(4) 			wi-owh

int-out(O) 		wi-oreturn

 wi-ohandle		the handle of the window to be opened

 wi-owx - the X-coordinate of the window in its initial size

* wi-owy - the Y-coordinate of the window in its initial size

o wi-oww - the width (in pixels) of the window in its initial size

o wi-owh - the height (in pixels) of the window in its initial size

* wi- return - a coded return message

0 - an error exists
n (positive integer) - no error exists

Sample call to C language binding:

wi-oreturn = wind_open(wi_ohandle, wi_owx, wi_owy, wi_oww,
	wi- wh),

11-15
GEM AES Programmerls duide		11.3	WIIIUUW IJIL)LULI lujuU21100

11.3.3		WIND-CLOSE

Purpose:

Closes an opened window.

Although closed, the window and its handle remain allocated. The
application can reopen the window by again calling the WIND-OPEN
routine.

Parameters:

control(O)			=	102
control(l)			=	1
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int-in(0)		= wi-clhandle

int-out(O)		= wi-clreturn

 wi-clhandle - the handle of the window to be closed

 wi-clreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

Sample call to C language binding:

wi-clreturn = wind-close(wi-clhandle);

11-16
OEM AES Programmer's Guld6			11.3	W111UUW JJILUMLY lujut-111ra

11.3.4		WIND-DELETE

Purpose.

Frees the space occupied by the window and its handle.

To open the window again, the application must first recreate it
by calling the WIND-CREATE routine before calling the WIND-OPEN
routine.

Parameters:

control(O)			=	103
control(l)			=	I
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int-in(O)			= 	wi-dhandle

int-out(O)			= 	wi-dreturn

& wi-dhandle - the handle of the window to be deleted

a wi-dreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

Sample call to C language binding:

wi-dreturn = wind-delete(wi-dhandle);

I- -~
GEM AES Programmer's Guide		11.3	Window Library RoUtines

11.3.5 WIND-GET

Purpose:

Depending on the information requested by the call, returns one of
the following:

		X- and Y-coordinates and width and height values for various
aspects of the current and previous windows

		slider location and size

		the handle of the active window

		X- and Y-coordinates, width, and height of the rectangles in the
window's rectangle list

Parameters:

control(O)			=	104
control(l)			=	2
control(2)			=	5
control(3)			=	0
control(4)			= 	0

int - in(O)			=	wi_ghandle
int-in(l)			= 	wi_gfield

int - out(O)			=	wi-greturn
int - out(l)			=	wi-gwl
int - out(2)			=	wi-gw2
int - out(3)			=	wi_gw3
int-out(4)			= 	wi_gw4

		wi_ghandle - The handle of the window about which the application
wants information.

		wi_gfield - A numerical value identifying the field about which
the application wants information. The value of wi_gfield
determines which of wi_gwl, wi_gw2, wi_gw3, and wi_gw4 is
returned.

I		- WF-RESVD1 - [RESERVED]

4		- WF WORKXYWH - the coordinates of the work ared of the window
	- re-turns wi_gwl (X-coordinate)
	- returns wi_gw2 (Y-coordinate)
	- returns wi-gw3 (width)
	- returns wi_gw4 (height)

11-18
GEM AES Programmer's Guide			11.3	Window Library Routines

5 -		WF CURRXYWH - the coordinates of the entire current window,
	including borders, title bar, and information line
	- returns wi_gwl (X-coordinate)
	- returns wi_gw2 (Y-coordinate)
	- returns wi_gw3 (width)
	- returns wi_gw4 (height)

6		WF PREVXYWH - the coordinates of the previous window,
	inFluding borders, title bar, and information line
	- returns wi_gwl (X-coordinate)
	- returns wi_gw2 (Y-coordinate)
	- returns wi gw3 (width)
	- returns wi-gw4 (height)

7		WF FULLXYWH - the coordinates of the window at its fullest
	possible size, including borders, title bar, and
	information line
	- returns wi gwl (X-coordinate)
	- returns wi-gw2 (Y-coordinate)
	- returns wi_gw3 (width)
	- returns wi-gw4 (height)

8 -		WF-HSLIDE - a number between 1 and 1000, giving the relative
	position of the horizontal slider
	(1 = leftmost position; 1000 = rightmost position)
	- returns wi_gwl

9 -		WF VSLIDE - a number between 1 and 1000, giving the relative
	position of the vertical slider
	(1 = top position; 1000 = bottom position)
	- returns wi-gwl

10 -		WF TOP - the window handle of the window that is on top
	(aFtive)
	- returns wi_.~gwl

11 -		WF - FIRSTXYWH - the coordinates of the first rectangle in the
	window's rectangle list
	- returns wi__~gwl (X-coordinate)
	- returns wi_gw2 (Y-coordinate)
	- returns wi gw3 (width)
	- returns wi-gw4 (height)

12 -		WF NEXTXYWH - the coordinates of the next rectangle in the
	window's rectangle list
	- returns wi_gwl (X-coordinate)
	- returns wi_gw2 (Y-coordinate)
	- returns wi_gw3 (width)
	- returns wi_gw4 (height)

13 - WF-RESVD2 - [RESERVED]
GEM AES Programmer's Guide		11.3	Window Library Routines

15 - WF-HSLSIZE - the size of the horizontal slider
	-1 = default minimum size (a square box)
1 - 1000 =		the slider's relative size compared to
the horizontal scroll bar
- returns wi_gwl

16 - WF-VSLSIZE - the size of the vertical slider
	-1 = default minimum size (a square box)
1 - 1000 =		the slider's relative size compared to
the vertical scroll bar
- returns wi_gwl

17 -		WF SCREEN - the address and length of the internal menu/alert
	buYfers
	- returns wi_gwl (low WORD of address)
	- returns wi gw2 (high WORD of address)
	- returns wi-gw3 (low WORD of length)
	- returns wi_gw4 (high WORD of length)

9 wi_greturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

wi_gwl - The value returned depends on the field named in
wi_gfield (see above).

wi_gw2 - The value returned depends on the field named in
wi-gfield (see above).

wi-gw3 - The value returned depends on the field named in
wi_gfield (see above).

wi-gw4 - The value returned depends on the field named in
wi_gfield (see above).

Sample call to C language bindingz

wi_greturn = wind_get(wi - ghandle, wi_gfield, &wi gwl,
~;wi-gw2, &wi_gw3, &wi_gwT);

11-20
GEM AES Programmer's Guide			11.3	Window Library Routines

11.3.6		WIND-SET

Purpose:

Changes the value in one of several fields that determine how a
window is displayed.

Parameters:

control(O)			=	105
control(l)			=	6
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int in(O)			=	wi shandle
int in(l)			=	wi sfield
int in(2)			=	wi swl
int in(3)			=	wi sw2
int in(4)			=	wi sw3
int-in(5)			= 	wi-sw4

int-out(O)			= 	wi-sreturn

*		wi shandle - The handle of the window whose fields the application
wishes to change.

e		wi-sfield - A numerical value identifying the field the
application wishes to change.

2 -		WF NAME - the address of the string containing the name of
	th~-e window
	- takes wi-swl and wi-sw2

3 -		WF-INFO - the address of the string containing the
	information line
	- takes wi-swl and wi-sw2

5 - WF-CURRXYWH - defined under WIND-GET

8 - WF-HSLIDE - defined under WIND-GET

9 - WF-VSLIDE - defined under WIND-GET

10 - WF-TOP - defined under WIND-GET
uLm AL5 Frogrammer s tuiue		L.L . J	n.LIIUUW ~UXLJIULr

14 -		WF NEWDESK - the address of a new default GEM Desktop for
	GER AES to draw
	- takes wi swl (object tree LOW WORD)
	- takes wi sw2 (object tree HIGH WORD)
	- takes wi-sw3 (starting object to draw in tree)
15 -		WF-HSLSIZE - defined under WIND-GET
16 -		WF-VSLSIZE - defined under WIND-GET

*		wi - swl - The value depends on the field named in wi-sfield (see
above).

e		wi - sw2 - The value depends on the field named in wi-sfield (see
above).

*		wi - sw3 - The value depends on the field named in wi-sfield (see
above).

*		wi - sw4 - The value depends on the field named in wi-sfield (see
	above).
e		wi-sreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

Sample call to C language binding:

wi-sreturn = wind-set(wi-shandle, wi-sfield, wi-swl,
wi-sw2, wi-sw3, wi-sw4);
GEM AES Programmer's Guide			11.3	Window Library Routines

11.3.7 WIND-FIND

Purpose:

Finds which window is under the mouse's X,Y position.

Parameters:

control(O)			=	106
control(l)			=	2
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int in(O)			=	wi fmx
int-in(l)			= 	wi-fmy

int-out(O)		= wi-freturn

		wi-fmy - the X-coordinate of the mouse's position

		wi-fmy - the Y-coordinate of the mouse's position

		wi freturn - the handle of the window under the mouse's X,Y
posi

Sample call to C language binding:

wi-freturn = wind-find(wi-fmx, wi_fmy);
L.IA ALS pimping? I unag		11.j masw LISP&PY pzuu.~k

11.3.8 WIND-UPDATE

Purpose:

Does one of the following:

9		Notifies GEM AES that the application is about to begin updating a
window or has finished updating a window.

During the update, GEM AES does not allow changes to take place in
the portion of the screen belonging to the window.

*		Notifies GEM AES that the application is taking control of all
mouse functions, regardless of the mouse's location on the screen,
or is returning to normal mouse function.

When the application has control of all mouse functions, the
Screen Manager no longer responds to mouse input, and menus and
window control points are not active.

Parameters:

control(O)			=	107
control(l)			=	1
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int-in(O)		=wi_ubegend

int-out(O)		= wi-ureturn

e wi_ubegend - a code for the call's function

0 - END UPDATE
1 - BEG UPDATE
2 - END MCTRL
3 - BEG-MCTRL

o wi-ureturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

Sample call to C language binding:

wi-ureturn = wind_update(wi_ubegend)

11-24
GEM AES Programmer's Guide			11.3	Window Library Routines

11.3.9 WIND-CALC

Purpose:

Calculates the X- and Y-coordinates and the width and height of a
window's border area or work area.

In calculating the border area's parameters, this routine uses the
corresponding parameters of the work area as input values. In
calculating the work area's parameters, this routine uses the
corresponding parameters of the border area as input values.

Parameters:

control(O)			=	108
control(l)			=	6
control(2)			=	5
control(3)			=	0
control(4)			= 	0

int in(O)			=	wi_ctype
int in(l)			=	wi-ckind
int in(2)			=	wi_cinx
int in(3)			=	wi_ciny
int in(4)			=	wi cinw
int-in(5)			= 	wi-cinh

int out(O)			=	wi-creturn
int out(l)			=	wi coutx
int out(2)			=	wi-couty
int out(3)			=	wi coutw
int-out(4)			= 	wi-couth

 wi-ctype - the type of calculation to perform

0 - return border area X, Y, width, and height
1 - return work area X, Y, width, and height

 wi-ckind - the individual components present in the window

The following bits represent the components:

OxOO01				-	NAME	(title bar with name)
OxOO02 -			CLOSE	(close box)
OxOO04				-	FULL	(full box)
OxOO08				-	MOVE	(move box)
OxOO10				-	INFO	(information line)
OxOO20				-	SIZE	(size box)

11-25
ur~m arob L-rogrammer-s uulae		11.13	winaaw, ilDrary xoutines

OxOO40 -			UPARROW	(up-arrow)
OxOO80				-	DNARRCYW	(down-arrow)
OxOlOO				-	VSLIDE	(vertical slider)
OxO2OO				-	LFARROW	(left-arrow)
OxO4OO				-	RTARROW	(right-arrow)
OxO8OO				-	HSLIDE	(horizontal slider)

This call uses the following bit settings for each component:

0 - does not have the component
1 - has the component

wi-cinx - the input X-coordinate of the work area (if wi-ctype =
0) or border area (if wi_ctype = 1)

wi_ciny - the input Y-coordinate of the work area (if wi-ctype =
0) or border area (if wi_ctype = 1)

wi - cinw - the input width value of the work area (if wi-ctype = 0)
or border area (if wi-ctype = 1)

wi - cinh - the input height value of the work area (if wi-ctype
0) or border area (if wi_ctype = 1)

wi-creturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

wi - coutx - the output X-coordinate of the work area	if wi-ctype
1) or border area (if wi_ctype = 0)

wi-couty - the output Y-coordinate of the work area if wi-ctype
1) or border area (if wi_ctype = 0)

wi coutw - the output width value of the work area (if wi-ctype
1) or border area (if wi_ctype = 0)

wi couth - the output height value of the work area if wi_ctype
1) or border area (if wi_ctype = 0)

Sample call to C language binding:

wi-creturn = wind-calc(wi_ctype, wi - ckind, wi-cinx,
	wi ciny, wi cinw, wi cinh,
&WT coutx, ~~wi cout -
Y,
&wi-coutw, &wi-couth);

End of Section 11

11-26
	Section 12
Resource Library

12.1		introduction

The Resource Library is the interface between an application and its
resources, the collection of data used by the application. Types of
resources include trees, objects, strings, icons, and pictures.

The purpose of a resource file is to isolate an application's
device-, user-, and country-specific data from its code. This
isolation provides the following advantages:

e machine-code portability

To port the application across different environments, the
programmer need only change the resource file data.

9 customization of appearance

A non-programmer can change the application's menu structure, the
layout of dialog boxes, and error message text. In most cases the
programmer need not be involved.

e internationalization of text messages

To change text messages from one language to another, one need
only change the text in the resource file.

* device-independent raster graphics

Because they are stored as resources, GEM AES's icons and other
bit-mapped images can be tailored to the resolution
characteristics of various displays.

In all these instances the application's code is unchanged.

Most applications have a single resource file that contains all
their resources. GEM AES follows the convention that all resource
files have the filetype RSC.

The programmer creates a resource file by using the GEM Resource
Construction Set.

12.2 Using the Resource Libraxy

When an application calls RSRC - LOAD with the name of a resource
file, the Resource Library does the following:

12-1
- -----			----	- - --, - - - --- ~ - - - - - ~.r

It searches for the file and finds its total size in bytes.

Using the DOS allocate call, it allocates enough memory space to
hold the resource file.

o		It opens the resource file, reads it into the allocated memory
space, and closes the file.

9		It makes any required updates to the file. These updates do the
following:

-		make the file device-specific to the screen's resolution

-		link up all the OBJECT pointers, TEDINFO pointers, ICONBLK
pointers, and BITBLK pointers

-		build the array of tree pointers

-		store the address of the tree array in the application's Global
Array

The application can now make calls to any routines that require a
tree index, including Object Library routines, FORM-DO, and
MENU-BAR.

To get or set any pointer in the OBJECT, TEDINFO, ICONBLK, or BITBLK
structures, the application calls RSRC-GADDR and RSRC-SADDR.

When the application is finished with the data from the resource
file, it calls RSRC - FREE to release the allocated memory and zero
out the address of Ehe tree array in the Global Array.

12.3		Resource Library Routines

The Resource Library uses the following routines:

RSRC-LOAD - loads an entire resource file into memory

RSRC-FREE - frees the memory allocated during RSRC-LOAD

RSRC-GADDR - gets the address of a data structure in memory

RSRC-SADDR - stores an index to a data structure

RSRC OBFIX - converts an object's X- and Y-coordinates, width, and
heigi;t from character coordinates to pixel coordinates

The following sections describe these routines.

12-2
OEM AES Programmer's Guide			12.3	Resource Library Routines

Each Resource Library routine has a GEM AES Parameter Block, Control
Array, and Global Array that contain the following information:

GEM AES Parameter Block
	params(O)					=	long	address	(32	bits)	of	control array
	params(l)					=	long	address	(32	bits)	of	global array
	params(2)					=	long	address	(32	bits)	of	int in array
	params(3)					=	long	address	(32	bits)	of	int out array
	params(4)					=	long	address	(32	bits)	of	addr in array
	params(5)					=	long	address	(32	bits)	of	addr-out array

	Control Array
	control(O)			=	op_code
	control(l)			=	size in WORDS of int in array
	control(2)			=	size in WORDS of int out array
	control(3)			=	size in LONGS of addr_in array
	control(4)			=	size in LONGS of addr-out array

Global Array
	global(O)			=	ap_version
	global(l)			=	ap_count
	global(2)			=	ap_id
	global(3,4)			=	ap_private
	global(5,6)			=	ap_ptree
	global(7,8)			=	ap_lresv
	global(9,10)			=	ap_2resv
	global(11,12)			=	ap_3resv
	global(13,14)			= 	ap-4resv

Global Array parameters are described in Section 3.

Each routine also contains some or all of the following arrays:

		Integer Input (int in) - Unless otherwise noted, each parameter in
this array is a Wd-RD.

		Integer Output (int-out) - Unless otherwise ncted, each parameter
in this array is a WORD.

		Address Input (addr in) - Unless otherwise noted, each parameter
in this array is a POINTER.

		Address Output (addr - out) - Unless otherwise noted, each parameter
in this array is a ]~OINTER.

12-3
12.3.1		RSRC-LOAD

Purpose:

Allocates memory and loads a resource file into memory.

Parameters:

control(O)			=	110
control(l)			=	0
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-out(O)			= 	re-lreturn

addr-in(O)			= 	re_lpfname

		re-lreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

		re_lpfname - the address of the ASCII string of the resource
filename

Sample call to C language binding:

re-lreturn = rsrc-load(re_lpfname);

12-4
UVA,l MLa FILXJIdMMUf H uuiae			12.3	Re5UfCL% L113rary R45UtlhLs

12.3.2 RSRC-PREE

Purpose:

Frees the memory space allocated in RSRC-LOAD.

Parameters:

control(O)			=	111
control(l)			=	0
control(2)			=	1
control(3)			=	0
control(4)			= 	0

int-out(O)			= 	re-freturn

re-freturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

Sample call to C language binding:

re-freturn = rsrc-freeo;

I-

12-5
I
GEM AES Programmer's Guide		12.1	Resource Lll~rary Aoutines

12.3.3 RSRC-GADDR

Purpose:

Gets the address of a data structure in memory.

Parameters:

control(O)			=	112
control(l)			=	2
control(2)			=	I
control(3)			=	0
control(4)			= 	I

int - in(O)			=	re_gtype
int-in(l)			= 	re_gindex

int-out(0)			= 	re-greturn

addr-out(O)		= re-gaddr

a re_.~gtype - the type of data structure

0 tree
I OBJECT
2 TEDINFO
3 ICONBLK
4 BITBLK
5 string
6 imagedata
7 obspec
	8			te_ptext	(see	Section	6.3.2)
	9			te_ptmplt	(see	Section	6.3.2)
	10			te_pvalid	(see	Section	6.3.2)
	11			ib_pmask	(see	Section	6.3.3)
	12			ib_pdata	(see	Section	6.3.3)
	13			ib-ptext	(see	Section	6.3.3)
	14			bi_pdata	(see	Section	6.3.4)
	15			ad-frstr - the	address	of a POINTER to a free string
	16			ad-frimg - the	address	of a POINTER to a free image

re_gindex		the index of the data structure

re_greturn		a coded return message

0 - an error exists
n (positive integer) - no error exists

re_gaddr - the address of the data structure specified by re_gtype
and re_gindex
GEM AES Programmer's Guide		12.3	Resource Library Routines

Sample call to C language binding:

1~
re_greturn = rsr(:_gaddr(re_gtype, re_gindex,
&re_gaddr);

11~

12-7
GEM AES Programmer's Guide		12.3	Resource Library Routines

12.3.4 RSRC-SADDR

Purpose:

Stores the address of a data structure in memory.

Parameters:

control(O)			=	113
control(l)			=	2
control(2)			=	I
controlM			=	1
control(4)			= 	0

int - in(O)			=	re_stype
int-in(l)			= 	re-sindex

int-out(O)			= 	re-sreturn

addr-in(O)			= 	re-saddr

		re_stype - the type of data structure

15 ad-frstr - defined under RSRC-GADDR
16 ad_frimg - defined under RSRC-GA-DDR

		re - sindex - the location in the data structure where re-saddr will
	be stored

		re-sreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

 re-saddr		the address of the data structure

Sample call to C language binding:

re-sreturn rsrc-saddr(re_stype, re-sindex,
re-saddr);

12-8
GEM AES Programmer's Guide			12.3	Resource Library Routines

12.3.5 RSRC-OBFIX

Purpose:

Converts an object's location and size from character coordinates
to pixel coordinates.

Character coordinates are defined as the object's X, Y, width, and
height values, where each WORD has the integral character position
in the Least Significant Byte and the positive or negative pixel
offset in the Most Significant Byte.

Parameters:

control(O)			=	114
control(l)			=	1
control(2)			=	1
control(3)			=	1
control(4)			= 	0

int-in(O)			= 	re_oobject

int-out(O)			= 	re-oresvd

addr-in(O)			= 	re_otree

o re_oobject The index of the object to be converted.

o re-oresvd		[RESERVED]; value always equals 1 (one).

o re-otree - The address of the tree that contains the object.

Sample call to C language binding:

re-oresvd = rsrc-obfix(re-otree, re_oobject);

End of Section 12

12-9
ld--%
	Section 13
Shell Library

13.1		Introduction

The Shell Library serves two major functions:

o		It lets an application keep track of the command and command tail
that invoked it.

e		It lets applications invoke other applications directly, without
first returning to the GEM Desktop application.

It allows a user to request an application ( for example, an output
application) from within a running application. The user can, if
the application supports this practice, string together several
applications in this manner.

The GEM Desktop application is itself an example of an application
that uses the second Shell function to invoke GEM and DOS
applications.

13.2		Using the Shell Library

Two Shell Library routines use a single buffer that contains the
following:

o		the command with which the Shell Library invoked the current
application or will invoke the next application

o		the command tail with which the Shell Library invoked the current
application or will invoke the next application

To learn the name of the command and command tail that invoked it,
an application calls the SHEL-READ routine, passing in the
following:

Pointers to the addresses of the application's buffers that will
hold the command information.

The Shell Library copies the data from its own buffer to the
application's buffer.

13-1
o A pointer to the application's home directory.

The home directory is where the system looks if it does not find
the application in the current directory.

To invoke an application, the current application (or the GEM
Desktop) follows these steps:

1.		It calls the SHEL WRITE routine and passes in the address of the
command, commarTd tail, and home directory for the next
application to run. It also indicates whether the requested
application is graphic or character-based and whether it is a GEM
or DOS application.

2.		When the current application terminates, the Shell Library starts
the application that was requested next.

To exit GEM AES, an application makes a SHEL-WRITE call, passing in
an sh-wdoex value of 0 (zero).

The other two Shell Library routines are SHEL-FIND and SHEL-ENVRN

SHEL FIND makes it possible for an application to locate a filename
by following the DOS search path.

SHEL ENVRN lets an application search the DOS environment for a
predefined environment parameter like "COMSPEC=" or "VERIFY=". The
routine returns the address of the byte immediately following the
parameter. This byte contains the value of the parameter, and its
address is stored in a LONG value pointed at by one of the input
parameters of SHEL-ENVRN.

13.3		Shell Library Routines

The Shell Library uses the following routines:

		SHEL-READ - lets an application determine how it was invoked

		SHEL WRITE - exits GEM AES or tells which application to run
next

		SHEL-FIND - locates a filename by following the DOS search path

		SHEL-ENVRN - searches the DOS environment for a parameter and
returus the address of its value

Each Shell Library routine has a GEM AES Parameter Block, Control
Array, and Global Array that contain the following information:

13-2
GEM AES Programmer's Guide			13.3	Shell Library Routines

GEM AES Parameter Block
	params(O)					=	long	address	(32	bits)	of	control array
	params(l)					=	long	address	(32	bits)	of	global array
	params(2)					=	long	address	(32	bits)	of	int in array
	params(3)					=	long	address	(32	bits)	of	int-out array
	params(4)					=	long	address	(32	bits)	of	add-r in array
	params(5)					=	long	address	(32	bits)	of	addr-out array

	Control Array
	control(O)			=	op-code
	control(l)			=	size in WORDS of int in array
	control(2)			=	size in WORDS of int-out array
	control(3)			=	size in LONGS of addr~_in array
	control(4)			=	size in LONGS of addr-out array

Global Array
	global(O)			=	ap_version
	global(l)			=	apL-count
	global(2)			=	ap_id
	global(3,4)			=	ap_private
	global(5,6)			=	ap_ptree
	global(7,S)			=	apL_lresv
	global(9,10)			=	ap_2resv
	global(11,12)			=	ap--3resv
	global(13,14)			= 	ap_4resv

Global Array parameters are described in Section 3.

Each routine also contains some or all of the following arrays:

*		Integer Input ( int in) - Unless otherwise noted, each parameter in
this array is a W5-RD.

*		Integer Output ( int - out) - Unless otherwise noted, each parameter
	in this array is a WORD.

9		Address Input (addr - in) - Unless otherwise noted, each parameter
in this array is a POINTER.

*		Address Output (addr out) - Unless otherwise noted, each parameter
in this array is a ]~OINTER.

13-3
GEM AES Programmer's Guide		13.3	Shell Library Routines

13.3.1		SHEL-READ

Purpose:

Lets an application identify the command that invoked it.

Note: The format of the information in the buffer referred to in
the addr-in parameter descriptions is consistent with the format
used by the Load/execute program function, as documented in the
DOS Technical Reference manual for PC DOS version 2.10 and higher.

Parameters:

control(O)			=	120
control(l)			=	0
control(2)			=	1
control(3)			=	2
control(4)			= 	0

int-out(O)			= 	sh-rreturn

addr - in(O) = sh-rpcmd
addr-in(l) = sh_rptail

		sh-rreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

		sh_rpcmd - the address of a buffer that will hold the command that
invoked the application

		sh_rptail - the address of a buffer that will hold the command
tail invoked with the command

Sample call to C language binding:

sh-rreturn = shel-read(sh-rpcmd, sh-rptail);

13-4
GEM AES Programmer's Guide			13.3	Shell Library Routines

13.3.2		SHEL-WRITE

Purpose:

Tells GEM AES whether to run another application and, if so, which
application to run.

Parameters:

control(O)		= 121
control(l)		= 3
control(2)		= 1

control(3)		= 2
control(4)		= 0

int in(O) = sh wdoex
int in(l) = sh wisgr
int-in(2) = sh-wiscr

int-out(O)			= 	sh-wreturn

addr in(O) = sh wpcmd
addr-in(l) = sh-wptail

o		sh wdoex - a coded instruction to exit the system or run another
application when the user exits the current application

0 - exit GEM AES and return to the operating syster prompt
1 - run another application

o		sh-wisgr - a code for whether the next application is a graphic
application

0 - not graphic application
1 - graphic application

o		sh-wiscr - a code for whether the next application is a GEM AES
application

0 - not GEM application
1 - GEM application

e		sh-wreturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

*		sh-wpcmd - the address of the new command file to execute

o		sh wptail - the address of the command tail for the next
program

13-5
- - ~LVLJLaMLUt!L 5 uulue		Ij.j	oneii iiorary vourines

Sample call to C language binding:

sh-wreturn = shel-write(sh-wdoex, sh-wisgr, sh-wiscr,
sh_~wpcmd, sh-wptail) ;

1-ft,

13-6
GEM AES Programmer's Guide			13.3	Shell Library Routines

13.3.3 SHEL-FIND

Purpose:

Searches for a filename in the current directory and in each
directory in the search path; when it finds the filename, returns
its full DOS file specification.

Parameters:

control(O)			=	124
control(l)			=	0
control(2)			=	1
controlM			=	1
control(4)			= 	0

int-out(O)			= 	sh-freturn

addr-in(O)			= 	sh_fpbuff

e		sh-freturn - a coded return message

0 - an error exists
n (positive integer) - no error exists

*		sh f pbuff - the address of a buffer with distinct input and
ou~Eput functions

input:		holds the filename the application is searching for
output:		holds the full DOS file specification of the filename's
	location in the search path

The buffer must be long enough to hold the full DOS file
specification (80 character minimum).

Sample call to C language binding:

sh-freturn = shel_get(sh_fpbuff);

13-7
UEM AES Programmer's C,uide		13.3	Shell Library Routines

13.3.4 SHEL-ENVRN
Purpose:
Searches in the DOS environment for the occurrence of an
environment parameter string; stores the address of the byte
immediately following the parameter string in a LONG value.

Parameters:

control(O)			=	125
control(l)			=	0
control(2)			=	1
control(3)			=	3
control(4)			= 	0

int-out(O)			= 	sh-eresvd

addr - in(O)			=	sh - epvalue
addr-in (1)			= 	sh-eparm

		sh-eresvd - [RESERVED]; value equals one (1)

		sh epvalue - the address of a LONG value in which this routine
wiTl store the address of the byte immediately following the
parameter string

		sh - eparm - the parameter string for which the application is
searching (includes the "=" sign)

Sample call to C language binding:

sh-eresvd = shel-envrn(sh-epvalue, sh-eparm);

End of Section 13

13-8
Index

A			C
AC - CLOSE, 4-8	calculating work area or
AC OPEN, 4-8			window's outer
ac-Eivating a window, 2-13				dimensions, 2-10
active window, 4-4, 11-8				changing the mouse form, 4-3
Address Input (addr-in)				character coordinate system,
	Array, 2-2				2-3
Address Output (addr-out)				check boxes, 7-2
	Array, 2-2		check mark, 5-2
Alert message text, 7-6				child, 6-2, 6-3
alerts, 1-9, 7-5			child object, 6-1
alert string, 7-6			choosing a menu item, 5-3
altering dialog, 7-3				click, 4-3
Alt key, 4-2	clipboard, 9-1
any of many structure, 7-3				clipping, 11-8
APPLBLK structure, 6-10				clip rectangle, 6-21, 6-29
APPL FIND, 3-2		close box, 11-3
application, 11-6			closing a window, 2-13
application identifier				Concurrent DOS, 1-1, 3-1
	(ap id), 2-2			context-sensitive text
applica-Eion windows, 11-1				in menus, 5-3
application's home				Control Array, 2-2
	directory, 13-2				converting screen to
APPL INIT, 2-2, 3-2				character/graphics mode,
APPL READ, 3-2, 4-5				1-8
APPL WRITE, 3-2		copying data, 9-1
ASCIY test strings, 9-2				creating
			new file, 10-3
B				window, 2-9
		Ctrl key, 4-2
background applications, 3-1				cursor forms, 6-9
Backspace, 7-4		customization of appearance,
Backtab, 7-4			12-1
BITBLK, 12-2	cutting and pasting data, 11-1
BITBLK structure, 6-9				cutting data, 9-1
bit-images, 9-2
bit offset, 2-3		D
blocking, 1-7
border area, 11-2			data interchange, 9-1
border color, 6-16			data structures
button event (MU-BUTTON),				initializing, 2-2
	2-8	DEFAULT object, 7-4, 7-5
button state, 4-2			Delete, 7-4

Index-1
delimiter character, 7-5		exit button, 7-3, 7-6, 7-9
desk accessories, 1-5, 3-1,			exit condition, 7-9
		5-3, 11-1
	closing, 4-8
	opening, 4-8
desk accessory buffer, 1-9			filename entry and
desk accessory programs, 1-5			selection, 10-1
Desk Menu, 1-6, 5-3	filename for scrap data, 9-2
desktop window, 2-4, 11-1			File Selector, 10-1
device-independent raster				changing directory, 10-3
		graphics, 12-1		scrolling, 10-2
dialog, 7-3	File Selector dialog box,
	altering, 7-3			10-2
	displaying, 2-6	fill pattern, 6-16
	exit conditions, 2-7		foreground application, 3-1
	resetting objects to		form, 7-1
		initial values, 2-7		FORM ALERT, 7-10
disabled, 5-2	form-atted text, 6-5
disabled menu item, 2-9		FORM CENTER, 7-9
dispatcher, 1-6	FORM-CO, 12-2
dispatching	FORM-DIAL, 2-6, 2-7, 7-9
	nonpre-emptive, 1-7	FORM-DO, 2-7, 7-9, 7-10
displaying	FORM7ERROR, 7-10
	alert, 7-10	Form-Library
	dialog, 7-9		responsibilities, 7-1
	error box, 7-10	full box, 4-6, 11-3
	form, 7-9	full multitasking operating
DOS, 1-1, 1-3			system, 3-1
DOS		allocate call, 12-2	functions, 13-1
DOS		application, 1-4
DOS		calls, 1-4	G
DOS		environment, 13-2
DOS		error codes, 7-6, 7-10	G BOX, 6-2
DOS EXEC function call		G-BOXTEXT,6-3, 6-5, 6-27
Overlay option, 1-5	G-EMAES, 1-1
DOS file system calls, 9-2			GEM	AES calls, 1-4
DOS memory allocation	GEM		AES Message Protocol,
	request, 2-2		4-4
DOS search path, 13-2	GEM		AES Parameter Block,
double-click, 4-3		2-2
down-arrow, 7-4, 11-4	GEM		AES' windows
			responsibilities, 11-6
		GEM		application, 1-4
		GEM		Desktop, 1-1, 1-4, 11-1
editable text, 7-3	GEM		Programmer's Toolkit,
editable text fields, 7-4			2-2
enabled, 5-2	GEM		Resource Construction
enabled menu item, 2-9			Set, 12-1
error box, 7-6	GEM		VDI, 1-1, 1-3, 8-1
error conditions, 7-5	GEM		VDI calls, 1-4
Escape, 7-5	GEM		VDI Close Workstation
events, 4-1		call, 1-8
EVNT MULTI, 2-5, 2-6,	GEM		VDI handle, 2-3
	7-13, 8-18, 11-7	GEM		VDI Open Virtual
EVNT-TIMER, 1-7		Workstation call, 2-3

Index-2
GEM		VDI Open Workstation	M
	call, 1-9
G FBOXTEXT, 6-5		machine-code portability,
G FTEXT, 6-5		12-1
G-ICON, 6-8	making a window active, 2-13
G IMAGE, 6-9	managing multiple windows,
Global Array, 2-2, 3-2, 12-2			11-8
G PROGDEF, 6-10		mask word, 4-2
GRAF GROWBOX, 8-1		maximum of eight (8)
GRAF HANDLE, 2-3			windows, 11-1
GRAF MKSTATE, 2-8, 2-9, 4-2			me bshow, 2-4
GRAF MOUSE call, 4-3				memory, 1-3
GRAF RUBBERBOX, 2-9, 8-1				freeing, 2-1
GRAF-SHRINKBOX, 8-1				"required for desk
G-TERT, 6-5, 6-27				accessories", 1-5
	menu, 1-9, 5-1
H		making disappear, 5-3
		moving mouse out of, 5-3
horizontal scroll bar, 11-5		menu/alert buffer, 1-9, 7-10
horizontal slider, 4-6, 11-5			menu bar, 2-4, 2-5, 5-1, 5-4
		displaying, 2-3
I	MENU		BAR, 5-2, 5-4, 12-2
	MENU		IENABLE, 2-9
ICONBLK, 12-2	menu Library
ICONBLK structure, 2-4, 6-8				responsibilities, 5-4
IBM PC ROM BIOS, 4-2				menu object tree, 5-4
icons, 6-9	MENU - REGISTER, 1-6, 4-8
inactive window, 2-13				menu resource file, 5-4
information line, 11-3				menu selection, 2-5
initializing an application,				menu title
	2-1		highlighting with keystroke,
inside color, 6-17				2-8
Integer Input (int-in)				MENU-TNORMAL, 2-6, 2-8
	Array, 2-2		message, 2-5
Integer Output (int-out)				message buffer, 2-5
	Array, 2-2		message event, 4-2, 4-4
internationalization of text				message pipe, 3-2, 4-4, 5-2
	messages, 12-1				metafile, 9-2
item Selector, 10-1				MN - SELECTED, 2-6, 4-5
		mouse button, 2-5
K			mouse button event, 4-1, 4-2
		mouse button state, 2-8
keyboard event, 4-1, 4-2		mouse event, 4-2, 4-3
keystroke menu selection,		mouse form, 8-18
	2-8, 5-2, 5-3		move bar, 11-4
		MS-DOS, 1-1, 3-1
L			multiple event, 4-2
left-arrow, 11-4		N
limited multitasking
	environment, 3-1		naming convention, 1-3
limited multitasking kernel,		nil index, 6-3
	1-5	nil pointer, 6-3

Index-3
Not-Ready List, 1-6, 2-5,		R.
	2-6
NOTE icon, 7-6	radio buttons, 7-2
	Ready List, 1-6, 2-5, 2-6
0	rectangle lists, 2-12, 11-9
	redrawing and updating, 11-9
OB DRAW, 6-15	redrawing screen, 2-7
ob-flags, 6-14	redrawing work area, 2-12
OBJC ADD, 6-3, 6-19	replace mode, 6-16
OBJC CHANGE, 2-7 - 2-9		resolution required for
OBJC DRAW, 2-4, 2-7, 6-3,	mouse response, 4-3
	7-9, 7-10	resource addresses, 2-3
OBJC FIND, 2-8	resource file, 2-3, 12-1
object	resources, 12-1
	child, 6-1	result rectangle, 11-9
	root, 6-1	Return/Enter, 7-4
	sibling, 6-1	right-arrow, 7-4, 11-4
X- and Y-coordinates, 1-9		root, 6-2
OBJECT, 12-2	root object, 6-1
object colors, 6-16	round-robin scheduling, 1-7
object color WORD, 6-16		RSRC FREE, 12-2
object flags, 6-14	RSRC GADDR, 2-3, 7-9, 12-2
object states, 6-15	RSRC LOAD, 2-2, 2-3, 5-2,
OBJECT structure, 6-4, 6-12,			_~-4, 6-3, 12-1
	6-14, 6-15, 6-16, 7-7		RSRC SADDR, 12-2
object tree, 6-1, 7-7, 7-8		rubber rectangle, 2-8, 2-9
object type, 6-3, 6-12
object type G BOX, 6-2		S
ob spec, 6-16
ob spec pointer, 6-5, 6-8, 6-10		SCRAP READ, 9-2
ob-state, 6-15, 6-29	SCRAP-WRITE, 9-2
ob-type, 6-12	Scree-n Manager, 1-6, 2-5,
one of many structure, 7-2				2-11, 2-13, 3-1, 5-2,
opened screen workstation				5-3, 5-4, 11-3
	8-1, 8-17	screen positions
opening a window, 2-11			locating, 2-3
overlapping windows, 11-1, 11-8			screen resolution, 2-2
		selecting
P				filename, 10-3
			icon, 2-8
parent-child relationships,			menu, 5-1
	6-3, 6-19	set clip rectangle, 11-10
parent object, 6-3	SHEL - ENVRN, 13-2
PARMBLK structure, 6-10		SHEL FIND, 13-2
pasting data, 9-1	Shell, 1-8
PC DOS, 1-1, 3-1	Shell Library, 13-1
predefined environment		SHEL - READ, 13-1
	parameter, 13-2	SHEL WRITE, 1-8, 13-2
predefined message types,		Shif-E, 4-2
	4-4	sibling object, 6-1
predefined values, 6-12		single-tasking operating
primary application, 1-5,			system, 3-1
	3-1	size box, 2-11, 11-4

Index-4
sizing a window, 2-11				window
slider size and location,				activating, 4-5
	2-11		application responsibilities,
spreadsheet data, 9-2				2-9
standard data types, 9-2				closing, 4-6
state words, 4-3			fulled, 4-6
STOP icon, 7-6		GEM AES responsibilities,
subroutine libraries, 1-5				2-9
			greatest possible size, 2-10
T				initial size and location,
				2-11
Tab, 7-4		making active, 4-5
te color, 6-16		moving, 4-7
TEBINFO, 12-2		redrawing, 4-5
TEDINFO structure, 6-5,				sizing, 4-7
6-16, 7-7	window control areas, 11-3
how it works, 6-7		window handle, 2-10, 2-13,
text color, 6-16			11-7
text string for error box,			window management
	7-7		responsibilities, 11-6
timer event, 4-2, 4-8			WIND_SET, 2-11, 2-13
title bar, 11-3		WIND_UPDATE, 2-12, 11-9, 11-10
transparent mode, 6-16		WM ARROWED, 4-6
	WM CLOSED, 4-6
U	WM FULLED, 4-6
	WM HSLID, 4-6
up-arrow, 7-4, 11-4		WM MOVED, 4-7
update rectangle, 2-13, 11-9		WM REDRAW, 4-5
updating a window, 2-12		WM_REDRAW message, 2-11
user events, 2-4		WM SIZED, 4-7
	WM TOPPED, 2-13, 4-5
V	WM VSLID, 4-7
	work area, 11-2
validation string to-pvalid,
	7-5	X
validation string values,
	6-6	X- and Y-coordinates, 1-9
vertical scroll bar, 11-5
vertical slider, 4-7, 11-5

W
WAIT icon, 7-6
WIND CALC, 2-10, 11-7
WIND CLOSE, 2-13, 11-7
WIND CREATE, 2-10, 2-14, 11-7
WIND DELETE, 11-8
	free the handle, 2-14
WIND FIND, 2-13
WIND GET, 2-4, 2-12r 11-7,
	11-9, 11-10
	WIND-OPEN, 2-11, 2-14, 11-7

Index-5
NOTES

-1w..
