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 [1[][] The components of the string are the following: • - 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 • - 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]. • - 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 Re§5UfCL% 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..