Sie sind auf Seite 1von 202

Lahey/INTERACTER Starter Kit

Revision C P. O. Box 6091 Incline Village, NV 89450


Printed on 50% recycled paper

Copyright
Copyright 1995-1997 by Lahey Computer Systems, Inc. and Interactive Software Services, Ltd. All rights reserved worldwide. This manual is protected by federal copyright law. No part of this manual may be copied or distributed, transmitted, transcribed, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, manual, or otherwise, or disclosed to third parties.

Trademarks
Names of Lahey products are trademarks of Lahey Computer Systems, Inc. Other brand and product names are trademarks or registered trademarks of their respective holders.

Disclaimer
Lahey Computer Systems, Inc. reserves the right to revise its software and publications with no obligation of Lahey Computer Systems, Inc. to notify any person or any organization of such revision. In no event shall Lahey Computer Systems, Inc. be liable for any loss of profit or any other commercial damage, including but not limited to special, consequential, or other damages. While every effort is made to ensure the accuracy of the information in this User Guide, Interactive Software Services Ltd. and Lahey Computer Systems Inc. cannot be held responsible for any errors therein. The right is reserved to revise this document and the associated software without notice.

Conditions of Use
Use of the Lahey/INTERACTER Starter Kit package shall be in accordance with the Lahey/INTERACTER Starter Kit licence agreement.

License Agreement
Lahey Computer Systems Inc. and Interactive Software Services Ltd. ("The Licencors") hereby grant the user of this software ("The Licencee") a non-exclusive and non-transferable licence to use the Lahey/ INTERACTER Starter Kit ("The Software") including its associated utilities and documentation according to the following terms and conditions : 1) The Software may only be copied for back-up purposes, to support its use for software development purposes on one processor at any one time. 2) The object and executable code files supplied with The Software may not be modified in any manner whatsoever. The supplied source code example files may be modified for the purposes of training and product familiarisation.

3) The object filesand library files supplied with The Software may not be distributed to any third parties. 4) Application software in the form of bound executable programs which incorporate any part of The Software may be distributed to any third party. The Licencors do not claim any run-time licence or royalty fees on such software. The character set files supplied with the Software may also be distributed with such application programs to any third party, so long as they are required by those application programs and provided that such programs make substantial use of The Software. 5) Application programs developed using The Software should include a clear and prominent comment in the source code acknowledging use of The Software. Technical and User documentation for such software should also clearly and prominently acknowledge use of The Software. 6) The supplied copy of The Software may not be used on more than one processor at any one time. The Software may be transferred from one processor ("The Original") to another so long as all files supplied with The Software are removed from The Original processor. 7) LICENSORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) ALL IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE SOFTWARE AND USER PROGRAMS, IN NO EVENT SHALL LICENSORS BE LIABLE FOR ANY LOST OR ANTICIPATED PROFITS, OR ANY INDIRECT, INCIDENTAL, EXEMPLARY, SPECIAL, OR CONSEQUENTIAL DAMAGES, WHETHER OR NOT LICENSORS WERE ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Lahey Computer Systems, Inc. 865 Tahoe Boulevard P.O. Box 6091 Incline Village, NV 89450-6091 (702) 831-2500 Fax: (702) 831-8123 BBS: (702) 831-8023 Technical Support (702) 831-2500 support@lahey.com

Table of Contents
Introduction...........................................vii
Text Screen Output .......................................viii Input Handling ..............................................viii High Resolution Graphics .............................. ix General Functions............................................ x

Input Handling.......................................83
Group KM: Keyboard/Mouse Event Handling .. 83 Group IN: Fixed Field Input Handling...........92 Group MN: Menu Handling...........................97 Group IP: Input Control Parameter Selection .... 103 Group MC: Mouse Cursor Control ..............114

Supplied Files .........................................1 Configuration ..........................................3 Getting Started with INTERACTER .......5
Fundamentals................................................... 5 A Worked Example ......................................... 9

High Resolution Graphics..................117


Group GG: General Graphics.......................117 Group GS: Graphics Style Selection............123 Group GD: Graphics Drawing/Movement...133 Group GC: Graphics Character Output........136

Supported Hardware ............................19


Displays ......................................................... 20 Mice ............................................................... 24

General Functions ..............................147


Group SC: Screen Manipulation ..................147 Group IF: Information..................................158 Group OS: Operating System Interface .......175 Group HW: Hardware Identification ...........177 Group CH: Character Manipulation.............179

Initialization Data File Format..............27


Keyword Quick Reference Summary............ 28 Keywords in Detail ........................................ 28

Error Codes ...........................................35 Exit Codes .............................................37 Filename Specification.........................39 Keyboard Codes ...................................41
IBM PC (Standard Keyboard) ....................... 41 IBM PC (Enhanced Keyboard)...................... 45

Obsolete Routines ..............................187

Subroutine Summary ...........................49


Subroutine Groups ......................................... 49 Subroutine Summary ..................................... 50

Text Screen Output ..............................55


Group OU: Text Output................................. 55 Group CU: Cursor Control ............................ 57 Group CL: Clearing ....................................... 60 Group AT: Text Attributes ............................ 61 Group CG: Character Graphics ..................... 65 Group WN: Window Manager ...................... 72
Lahey/INTERACTER Starter Kit

Contents

vi

Lahey/INTERACTER Starter Kit

Introduction

Traditionally, platform-independent interactive Fortran software has been uncommon or has relied on a simple teletype style interface. Full screen interaction is more commonly achieved using software interfaces which tie a program to a particular platform. This dilutes one of Fortran's main assets, namely its portability. The INTERACTER user-interface and graphics library from ISS was designed to overcome this by providing a wide selection of portable screen output and user input handling facilities. The full version of INTERACTER runs on platforms as diverse as DOS, Windows, multi-user systems running serial terminals and Unix/VMS workstations running X Windows. The Lahey/INTERACTER Starter Kit (LISK) is derived from the full version of INTERACTER and is targetted at one specific platform, namely DOS running Lahey 32-bit Fortran compilers. A companion product, the Winteracter Starter Kit (WiSK) is provided for creating Windows programs with LF90. This replaces the Windows version of LISK shipped with previous versions of LF90. Both LF90 and Essential LF90 support a common version of the Lahey/INTERACTER Starter Kit. The Starter Kit will run on any PC compatible based on a 386 processor or above. The routines in the Lahey/INTERACTER Starter Kit are organized into four general categories: Text Screen Output Input Handling High Resolution Graphics General Functions

Each category is sub-divided into groups, which are identified in this manual by two-character codes, e.g., CU for cursor control, MN for menus and so on. The following sections provide a general summary of the types of facilities provided by each of these subroutine groups. Before starting to use INTERACTER it is recommended that you browse through the rest of this introduction to familiarize yourself with the range of features on offer and more importantly, where to find them. Note that the subroutine group summaries presented here follow the same order as the final chapters of this manual which describe each routine in detail.
Lahey/INTERACTER Starter Kit

vii

Introduction

Text Screen Output


Broadly, INTERACTER treats text and graphics output separately, though both can co-exist on the same screen. The subroutine groups in this category deal with various aspects of text screen output.

OU: Text Output


Text can simply be 'pushed' out at the current cursor position or can be placed at specific positions. Vertical output is also available.

CU: Cursor Control


The position and movement of the cursor can be controlled. The cursor can also be switched on and off on most displays.

CL: Clearing
Areas and the entire screen can be cleared.

AT: Text Attributes


Text attributes (or 'highlights') can be specified. Attributes available are color, bold, flashing, italics, reverse and underlining, depending on display.

CG: Character Graphics


A number of routines are provided to draw frames around text areas on both text and graphics screens, using either line-graphics characters or graphics primitives. For more powerful facilities see the high resolution graphics routines.

WN: Window Management System


The window system enables output to be restricted to specific areas of the screen. The very useful 'pop-up' feature allows windows to be overlaid so that the old screen contents are restored when they are closed.

Input Handling
This category provides a set of functions which handle various types of text and option input.

viii

Lahey/INTERACTER Starter Kit

KM: Keyboard/Mouse Event Handling

KM: Keyboard/Mouse Event Handling


This section of INTERACTER provides the most fundamental low level input functions which read single keystrokes and mouse button/movement events. Single key detection includes identification of non-printing (e.g., function) keys in a keyboard independent manner.

IN: Fixed Field Input Handling


Flexible string input routines are provided which replace Fortran READ statements. This group also features prompt/response boxes, with a pop-up option.

MN: Menu Handling


These menu routines make use of single-character input and mouse detection, to provide horizontal/vertical pointer/highlight menus, greatly simplifying option selection. A pop-up facility is also included.

IP: Input/Menu Handling Parameter Selection


The manner in which the input and menu handling routines behave can be modified. All input control keys can be redefined. Pop-up mode is selectable.

MC: Mouse Cursor Control


The mouse cursor can be enabled/disabled.

High Resolution Graphics


These routines provide high resolution graphics output facilities.

GG: General Graphics


A number of general facilities are grouped together under this heading, such as graphics initialization and area/co-ordinate system selection. A read-pixel routine is also provided.

GS: Graphics Style Selection


Control is provided over color, line-type and fill style.
Lahey/INTERACTER Starter Kit

ix

Introduction

GD: Graphics Drawing/Movement


These are the basic drawing primitives. In addition to simple move and draw functions, polygon and circle fill routines are provided.

GC: Graphics Character Output


Text output in graphics mode supports both hardware and software character sets. Various vector and outline software character sets are provided.

General Functions
The remaining routines provide a variety of functions which are likely to be required in interactive applications.

SC: Screen Manipulation


Of particular importance are the INTERACTER screen handling initialization and termination routines. Other facilities are mode selection and screen bell control.

IF: Information
A set of functions are provided which enable a program to interrogate the current state of the routines in the library and the hardware on which the program is currently running.

OS: Operating System


Environment variable access and termination with exit code routines are provided.

HW: Hardware Identification


Display and mouse identification routines are provided, though these will not normally need to be called directly.

CH: Character Manipulation


While not strictly screen input/output handling functions, these routines provide important string manipulation facilities which are of considerable value in interactive applications.

Lahey/INTERACTER Starter Kit

Supplied Files

This chapter describes the files which you receive with your Lahey/INTERACTER Starter Kit. These are installed as part of the compiler installation procedure. Refer to Configuration on page 3 for information on how to use and set up INTERACTER once it has been installed. The Lahey/INTERACTER Starter Kit library is installed into the lib directory:
lib\lisk.lib

Lahey/INTERACTER Starter Kit library

A VESA BIOS screen mode interrogation program is installed in the bin directory. This program can be used to determine what screen modes can be used with your graphics card:
bin\vesainfo.exe

VESA BIOS screen mode interrogation program

The following Starter Kit files are installed into a compiler sub-directory called LISK. The sub-directories within this directory contain:
charsets\standard.chr charsets\duplexr.chr charsets\triplexr.chr charsets\fixed.chr charsets\swiss.chr demos\*.f90 demos\interact.f90

Standard vector-based software character set Duplex Roman vector-based software character set Triplex Roman vector-based software character set Courier-like outline character set Helvetica-like outline character set Source for various demo programs
INTERACTER module (interface definitions and symbolic

names)
init\*.ini init\readme.txt

Sample initialization file entries for various displays Guide to selecting initialization file settings

Lahey/INTERACTER Starter Kit

Chapter 1

Supplied Files

Lahey/INTERACTER Starter Kit

Configuration

This chapter deals with how to configure the environment of INTERACTER based programs. Once the files described in chapter 1 have been installed, it is recommended that you set up an initialization file as documented in Initialization Data File Format on page 27. This is a file which can be used to tell INTERACTER exactly what sort of environment it is running in. In addition to the initialization file itself, you may also find it useful to set up the following operating system variables:
INTINIT: name of your initialization file INTCHDIR: name of the software character sets directory

The definitions for these variables should normally be added to AUTOEXEC.BAT. Typical definitions would be:
SET INTINIT=c:\[e]lf90\lisk\interact.ini SET INTCHDIR=c:\[e]lf90\lisk\charsets

(N.B. There must be no spaces before the '=' signs, since DOS will treat the trailing space as part of the variable name.) The two environment variable assignments above will also be required by your end-users when running INTERACTER-based programs. Two further operating system variables can also be defined, if required:
INTTERM : current display type (see chapter 4) INTCHAR : default character set file name

These are equivalent to the DISPLAY and CHARSET initialization file keywords (see Initialization Data File Format on page 27). To illustrate INTERACTER's features, various demonstrations are supplied, including a program called INPUT. Refer to the compilers user documentation for information on how to compile and link these programs with Lahey Fortran.
Lahey/INTERACTER Starter Kit

Chapter 2

Configuration

Lahey/INTERACTER Starter Kit

Getting Started with INTERACTER


This chapter aims to introduce you to writing software using INTERACTER. It assumes that you are already familiar with how to compile and link INTERACTER programs, as described in the LF90 Users Guide. The first section summarizes some basic rules which need to be observed along with some important basic concepts. Since INTERACTER has been designed to be as simple to use as possible, these are kept to a minimum. However, a few minutes effort to read and digest the next few pages will prove worthwhile. Later in this chapter you will find a worked example which provides a gentle introduction to writing an INTERACTER application.

Fundamentals
Certain basic principles apply regardless of which INTERACTER features you use.

Screen Control Codes and Fortran I/O


All screen I/O should be performed via INTERACTER. This means that screen control codes (such as ANSI escape codes) must not be used. These will almost certainly confuse INTERACTER and cause unintended effects. This cannot be stressed too strongly. This particularly applies to codes which may affect the cursor position or cause some effect other than simply placing text on screen. Similarly, Fortran READ's and WRITE's direct from/to the screen should be avoided, for a variety of reasons, most notably because: INTERACTER will not be aware of the text which your program has placed on the screen. Some run-time systems will not cope properly with terminal I/O, if you port LISK code to other platforms later using the full version of INTERACTER.
Lahey/INTERACTER Starter Kit

Chapter 3

Getting Started with INTERACTER


While you may find that WRITE(* or READ(* works in some cases under DOS, consistent behavior cannot be guaranteed. Consequently, you should always use INTERACTER subroutine calls to write to or read from the screen. The routines in the IN and OU subroutine groups can be viewed as functional replacements for Fortran READ and WRITE statements. Fortran I/O is freely available on all other channels.

Subroutine Arguments
Data Types All subroutine arguments of type CHARACTER may be of any length, since the passedlength character type CHARACTER*(*) is used in all cases, except where explictly stated otherwise. ALL subroutine arguments of type INTEGER are 4-byte integers, regardless of the compiler default. Similarly, all REAL arguments are single-precision 4-byte variables. Interface Definitions An interface definitions module is supplied in source form in the LISK\DEMOS directory in a file called INTERACT.F90. This file contains a module called INTERACTER which defines the type and intent of all LISK subroutine arguments and functions. Compile this module, then add the following statement at the beginning of every program unit that calls INTERACTER routines:
USE INTERACTER

This will cause the compiler to check the number and type of arguments in each INTERACTER call. All of the demos in the LISK\DEMOS directory USE this module, so be sure to compile it before building any demos. Use of this module is now required. Users upgrading from an earlier version of LISK who have not previously included a USE INTERACTER statement in their programs will need to add such statements before using the latest version. Certain subroutines now use assumed shape arrays (which require an interface definition) where previously they used assumed size (which did not). This change has allowed LISK to become compatible with both LF90 and Essential LF90. Note that the full version of INTERACTER still uses assumed shape arrays. Users planning to upgrade to the full version will not encounter problems however, because the INTERACTER module supplied with the full library declares the affected subroutine arguments differently. No code changes will therefore be required when upgrading.

Lahey/INTERACTER Starter Kit

Naming Conventions
Symbolic Names LISK programs can make extensive use of pre-defined symbolic names which are defined in the INTERACTER Fortran 90 module. These symbolic names can be used in place of numeric subroutine arguments/results and are designed to be meaningful, aiding program readability. Whilst use of these symbolic names is not obligatory, it is recommended. They are documented in this manual and therefore form part of the formal definition of LISK. The types of the symbolic names are all defined in the INTERACTER module, allowing them to be used in any program simply by inserting the appropriate USE INTERACTER statement in each program unit. Users upgrading from an earlier version of LISK will need to replace their INCLUDE statements with USE INTERACTER statements. The INTERACTER module now supercedes and replaces the previously supplied INCLUDE files. Note that the supplied version of the INTERACTER module is based on that provided with the full INTERACTER library and consequently contains a number of PARAMETER statements which are not directly applicable to the Lahey/INTERACTER Starter Kit.

Naming Conventions
All externally callable routines in INTERACTER start with the letter I. Various internal subroutines and COMMON blocks are used. All internal subroutines have names starting with the letters XX (e.g., XXOUTU). Internal COMMON blocks are named INTRnn where nn is a 2digit number (e.g., INTR01). Avoid using subroutines or COMMON blocks with similar names. A consequence of using I as the initial letter is that all real INTERACTER functions must be explicitly declared, even when using Fortran's implicit typing conventions.

Text and Graphics Screen Modes


In this manual a distinction is drawn between text and graphics screen modes (as selected by IScreenMode/IScreenModeN), and the routines which can be called in each. INTERACTER allows text screen handling routines to be called in both text and graphics screen modes, while graphics routines can only be called in graphics modes. Text handling routines are mainly those described in Text Screen Output on page 55 and Input Handling on page 83, while High Resolution Graphics on page 117 deals with the graphics handling routines. Text and graphics look best when integrated, which involves using INTERACTER in graphics screen mode. The following notes summarize some of the considerations when using text screen routines in graphics modes.
Lahey/INTERACTER Starter Kit

Chapter 3

Getting Started with INTERACTER


Issues to consider when generating text output in DOS graphics modes are: Text attribute support varies in graphics modes, depending on which screen mode is being used. Underlining and reverse video are available in all graphics modes. Bold text and background colors are available in color modes. Flashing text and italics are not supported. Text output in graphics modes is slower, due to the manner in which screen memory is organized, though still reasonably fast because INTERACTER writes text direct onto video memory rather than via the BIOS. Window/menu/input-box pop-ups behave differently in text and graphics modes. In text mode, pop-ups are very fast due to the relatively small amount of screen data which must be buffered. Significantly more data must be buffered in graphics modes and is consequently slower. Menus and text windows use 'graphical' frames in graphics mode, rather than boxdrawing characters. Operation in graphics mode within a DOS box inside Windows may present problems, resulting from poorly written Windows video drivers and/or the inability of Windows to window a particular type of graphics mode.

Error Reporting
All error reporting in INTERACTER is performed via a single function called InfoError, which is in the IF subroutine group. Whenever INTERACTER encounters an error, it sets a global error flag which can be interrogated using InfoError. This global error flag may be over-written by subsequent errors, but is never cleared until InfoError is called. It is the callers responsibility to decide when to interrogate and/or clear the error flag and issue any appropriate error messages. When INTERACTER encounters an error it will simply update the error flag and attempt to take suitable default action. INTERACTER will not report errors to the screen, since this may not be appropriate in many applications. If a routine sets the INTERACTER error flag, the values which it may set it to are documented with the description of the routine. A summary of all the INTERACTER error codes is also provided in Error Codes on page 35. Symbolic names for all the possible error codes are defined in the INTERACTER module.

Lahey/INTERACTER Starter Kit

Some Efficiency Considerations

Some Efficiency Considerations


While the performance of INTERACTER programs will depend heavily on the hardware being used and the nature of the application, here is a selection of simple ways to ensure that you get the best from the library: Monochrome graphics screen modes are faster than color ones. Similarly, there is a trade off between resolution and performance. The higher the graphics mode resolution, the slower your programs are likely to run. Due to differences in video memory organization, 256-color modes can actually be faster than 16-color modes, for some graphics operations. When using a software character set to annotate graphics, use a relatively simple font such as 'Standard'. When filling areas in graphics mode, solid fills are typically quicker than stippled/ dithered ones.

A Worked Example
The remainder of this chapter explains how to write a simple INTERACTER program which uses a typical selection of the facilities available, including both text and graphics handling routines. The short program is built up step by step, with newly introduced statements highlighted at each stage by an '*' in the right hand margin. The very first thing to do in any INTERACTER program is to initialize the screen handling system by calling IScreenOpen. This sets up various information required by INTERACTER, including the most important of all, the display hardware. In other words, INTERACTER needs to know what sort of display adapter or monitor it is running on, to ensure it behaves correctly and makes best use of the available hardware. There are two ways in which INTERACTER can determine the type of display being used: 1) It can read an initialization data file, describing your display type. This is a simple to create ASCII text file. The name of this file can be specified in a number of ways. See the documentation for IScreenOpen. The format of this file is described in Initialization Data File Format on page 27. 2) If no such file is found, INTERACTER automatically tries to identify the display hardware. In addition to calling IScreenOpen, the last INTERACTER subroutine to be called must be the termination routine IScreenClose, which terminates screen handling. A bare minimum INTERACTER program therefore looks like this:
Lahey/INTERACTER Starter Kit

Chapter 3

Getting Started with INTERACTER


PROGRAM LISK_EXAMPLE USE INTERACTER CALL IScreenOpen(' ','G',640,480,16) ! put your code in here CALL IScreenClose() STOP END PROGRAM LISK_EXAMPLE * * * * * * *

So far, all this program will do is either clear the screen. The 'G' argument tells IScreenOpen to select a graphics screen mode. Let's assume we want the program to read some data from a file and plot it in the form of a graph. The first thing we require is the name of the file. An INTERACTER 'fixed field input' routine can be used to obtain this from the user. This is rather like an enhanced Fortran READ statement which allows the size of the response to be restricted. There are several such routines but the one we will use is InStringXY ("Input a String at a specified X,Y position"):
PROGRAM LISK_EXAMPLE USE INTERACTER IMPLICIT NONE CHARACTER (LEN=40) :: FILENAME INTEGER :: IBOX,LENGTH,LASTY CALL IScreenOpen(' ','G',640,480,16) ! IBOX = 1 100 CALL ITextColourN(TextBlack,TextWhite) CALL InStringXY(2,2,'Filename : ',IBOX,FILENAME,LENGTH) IF (LENGTH.EQ.0) THEN LASTY = InfoScreen(3) CALL IOutStringXY(1,LASTY,'Please enter a filename') GO TO 100 END IF ! CALL IScreenClose() STOP END PROGRAM LISK_EXAMPLE

* * * * * * * * * * * *

Our program now displays a 'Filename : ' prompt at text co-ordinate (2,2) with a box drawn around the prompt and reply fields. The user will only be able to type up to 40 characters. If a blank string is entered the IOutStringXY routine displays a message on the bottom line of the screen and the user must re-enter the response. The input box and the message will both be displayed in black on a white background. Note the introduction of symbolic color names, defined in the INTERACTER module. But what if the user decides not to load a data file after all ? In the current example, the user is trapped in a loop until a name is entered. However, unlike a Fortran READ statement, it is possible to determine which key the user actually pressed to terminate input, i.e. was it Return, Escape, Tab, etc.?

10

Lahey/INTERACTER Starter Kit

A Worked Example
In INTERACTER these are referred to as 'exit' keys. After calling any input routines you can test which exit key was used by calling the InfoInput function with an argument of 55. In our example we will check for the 'quit' key (usually, but not necessarily the Escape key):
PROGRAM USE LISK_EXAMPLE INTERACTER :: FILENAME * * :: IBOX,LENGTH,LASTY,I,NVALUE

IMPLICIT NONE CHARACTER (LEN=40) INTEGER ! IBOX = 1 100 CALL ITextColourN(TextBlack,TextWhite) CALL InStringXY(2,2,'Filename : ',IBOX,FILENAME,LENGTH) IF (InfoInput(55).EQ.23) THEN GO TO 1000 ELSE IF (LENGTH.EQ.0) THEN LASTY = InfoScreen(3) CALL IOutStringXY(1,LASTY,'Please enter a filename') GO TO 100 END IF ! OPEN(20,FILE=FILENAME,STATUS='OLD') READ(20,*) CLOSE(20) ! 1000 CALL IScreenClose() STOP END PROGRAM LISK_EXAMPLE NVALUE READ(20,*) (VALUES(I),I=1,NVALUE) * * * * * * * * * REAL, DIMENSION(50) :: VALUES CALL IScreenOpen(' ','G',640,480,16)

The program now terminates if the user presses the quit key or reads some free format data from a file. (The data file handling is deliberately simplified for the sake of this example). Now let's extend the idea of using an exit key by adding a 'pop-up' help facility. The 'help' key is normally F1. When this is pressed we will make a window appear using IWinOpen which will automatically close when the user presses a key. We will also use a slightly different variant of the input routine, InStringXYDef, which displays a default value in the input field. This will enable a partly entered response to remain in the input field after the help window has been displayed:
Lahey/INTERACTER Starter Kit

11

Chapter 3

Getting Started with INTERACTER


PROGRAM LISK_EXAMPLE USE INTERACTER IMPLICIT NONE CHARACTER (LEN=40) :: FILENAME REAL, DIMENSION(50) :: VALUES INTEGER :: IBOX,LENGTH,LASTY,I,NVALUE CALL IScreenOpen(' ','G',640,480,16) ! IBOX = 1 FILENAME = 'MYDATA.DAT' 100 CALL ITextColourN(TextBlack,TextWhite) CALL InStringXYDef(2,2,'Filename: ',IBOX,FILENAME,LENGTH) IF (InfoInput(55).EQ.23) THEN GO TO 1000 ELSE IF (InfoInput(55).EQ.22) THEN CALL ITextColourN(TextBlack,TextWhiteBold) CALL IWinAction('CFP') CALL IWinOpen(3,3,30,5) CALL IWinOutString( & 'Enter the name of a file containing the ') CALL IWinOutString('data which you wish to plot.') CALL IWinOutStringXY(1,5,'Press any key') CALL InKeyEvent() CALL IWinClose(1) GO TO 100 ELSE IF (LENGTH.EQ.0) THEN LASTY = InfoScreen(3) CALL IOutStringXY(1,LASTY,'Please enter a filename') GO TO 100 END IF ! OPEN(20,FILE=FILENAME,STATUS='OLD') READ(20,*) NVALUE READ(20,*) (VALUES(I),I=1,NVALUE) CLOSE(20) ! 1000 CALL IScreenClose() STOP END PROGRAM LISK_EXAMPLE

* *

* * * * * * * * * * *

FILENAME now offers MYDATA.DAT by default. If the help key is pressed a bold white window with black text appears. The IWinAction routine controls the action taken by IWinOpen when it opens a window - in this case it specifies a Cleared Frame in Pop-up

mode. A 30 column by 5 row window is opened and some text is 'poured' into it. A prompt is then centred on the bottom window line. A single keyboard or mouse event is read from the input queue and the window is closed. Since 'pop-up' mode was selected, the window disappears from the screen.

12

Lahey/INTERACTER Starter Kit

A Worked Example
Now let's try plotting the data that has been loaded, in the form of a graph using a programsupplied routine called PLOT:
PROGRAM USE INTERFACE SUBROUTINE PLOT(VALUES,NVALUE) IMPLICIT NONE REAL , INTENT (IN), DIMENSION(:) :: VALUES :: NVALUE INTEGER, INTENT (IN) END SUBROUTINE PLOT END INTERFACE CHARACTER (LEN=40) INTEGER ! IBOX = 1 FILENAME = 'MYDATA.DAT' 100 CALL ITextColourN(TextBlack,TextWhite) CALL InStringXYDef(2,2,'Filename : ',IBOX,FILENAME,LENGTH) IF (InfoInput(55).EQ.23) THEN GO TO 1000 ELSE IF (InfoInput(55).EQ.22) THEN CALL ITextColourN(TextBlack,TextWhiteBold) CALL IWinAction('CFP') CALL IWinOpen(3,3,30,5) CALL IWinOutString( & 'Enter the name of a file containing the ') CALL IWinOutString('data which you wish to plot.') CALL IWinOutStringXY(1,5,'Press any key') CALL InKeyEvent() CALL IWinClose(1) GO TO 100 ELSE IF (LENGTH.EQ.0) THEN LASTY = InfoScreen(3) CALL IOutStringXY(1,LASTY,'Please enter a filename') GO TO 100 END IF :: FILENAME :: IBOX,LENGTH,LASTY,I,NVALUE REAL, DIMENSION(50) :: VALUES CALL IScreenOpen(' ','G',640,480,16) LISK_EXAMPLE INTERACTER * * * * * * *

IMPLICIT NONE

Lahey/INTERACTER Starter Kit

13

Chapter 3

Getting Started with INTERACTER


! OPEN(20,FILE=FILENAME,STATUS='OLD') READ(20,*) NVALUE READ(20,*) (VALUES(I),I=1,NVALUE) CLOSE(20) ! CALL IClearScreen() CALL PLOT(VALUES,NVALUE) ! 1000 CALL IScreenClose() STOP END PROGRAM LISK_EXAMPLE ! SUBROUTINE PLOT(YVALUE,NVALUE) USE INTERACTER ! REAL, INTENT (IN) , DIMENSION(:) :: YVALUE INTEGER, INTENT (IN) :: NVALUE CALL IGrPause('A') RETURN END SUBROUTINE PLOT

* * *

* * * * * * * * *

So far, PLOT does nothing. IGrPause waits for the user to press Return/Enter and clears the screen. A simple graph can now be constructed using a series of low level move and draw commands:

14

Lahey/INTERACTER Starter Kit

A Worked Example
SUBROUTINE PLOT(YVALUE,NVALUE) USE INTERACTER IMPLICIT NONE ! REAL, INTENT (IN) , DIMENSION(:) :: YVALUE INTEGER, INTENT (IN) :: NVALUE ! REAL :: XMIN,XMAX,YMIN,YMAX,XLEN,YLEN,XPOS INTEGER :: IX ! Calculate X and Y ranges XMIN = 1.0 XMAX = REAL(NVALUE) YMIN = 999999.0 YMAX = -999999.0 DO IX = 1,NVALUE YMAX = MAX(YMAX,YVALUE(IX)) YMIN = MIN(YMIN,YVALUE(IX)) END DO XLEN = XMAX - XMIN YLEN = YMAX - YMIN CALL IGrUnits(XMIN-0.1*XLEN,YMIN-0.1*YLEN, & XMAX+0.1*XLEN,YMAX+0.1*YLEN) ! Draw simple axes CALL IGrMoveTo(XMIN,YMAX) CALL IGrLineTo(XMIN,YMIN) CALL IGrLineTo(XMAX,YMIN) ! Draw line graph CALL IGrMoveTo(XMIN,YVALUE(1)) DO IX = 2,NVALUE XPOS = XMIN + XLEN*REAL(IX-1)/REAL(NVALUE-1) CALL IGrLineTo(XPOS,YVALUE(IX)) END DO CALL IGrPause('A') RETURN END SUBROUTINE PLOT

* * * * * * * * * * * * * * * * * * * * * * * * * *

Minimum X and Y values are assigned. IGrUnits is then used to define a co-ordinate system which leaves a border around the area in which the graph will be plotted. A simple L-shaped axis is plotted, followed by the data itself. IGrLineTo is effectively a Pen-Down and draw operation, so the DO loop creates a connected line graph. And finally, to add some annotation to the X axis:
Lahey/INTERACTER Starter Kit

15

Chapter 3

Getting Started with INTERACTER


SUBROUTINE PLOT(YVALUE,NVALUE) USE INTERACTER IMPLICIT NONE ! REAL, INTENT (IN) , DIMENSION(:) :: YVALUE INTEGER, INTENT (IN) :: NVALUE ! CHARACTER (LEN=3) :: STR REAL :: XMIN,XMAX,YMIN,YMAX,XLEN,YLEN,XPOS INTEGER :: IX,ISTART ! Calculate X and Y ranges XMIN = 1.0 XMAX = REAL(NVALUE) YMIN = 999999.0 YMAX = -999999.0 DO IX = 1,NVALUE YMAX = MAX(YMAX,YVALUE(IX)) YMIN = MIN(YMIN,YVALUE(IX)) END DO XLEN = XMAX - XMIN YLEN = YMAX - YMIN CALL IGrUnits(XMIN-0.1*XLEN,YMIN-0.1*YLEN, & XMAX+0.1*XLEN,YMAX+0.1*YLEN) ! Draw simple axes CALL IGrMoveTo(XMIN,YMAX) CALL IGrLineTo(XMIN,YMIN) CALL IGrLineTo(XMAX,YMIN) ! Draw line graph CALL IGrMoveTo(XMIN,YVALUE(1)) DO IX = 2,NVALUE XPOS = XMIN + XLEN*REAL(IX-1)/REAL(NVALUE-1) CALL IGrLineTo(XPOS,YVALUE(IX)) END DO ! Add annotation to X axis CALL IGrCharJustify('C') DO IX = 5,NVALUE,5 CALL IGrMoveTo(REAL(IX),YMIN) CALL IGrLineTo(REAL(IX),YMIN-YLEN*0.025) CALL IntegerToString(IX,STR,'(I3)') ISTART = ILocateChar(STR) CALL IGrCharOut(REAL(IX),YMIN-YLEN*0.06,STR(ISTART:)) END DO CALL IGrPause('A') RETURN END SUBROUTINE PLOT

* *

* * * * * * * * *

16

Lahey/INTERACTER Starter Kit

A Worked Example
Labels and tick marks are added to the X axis using centre justified text. For more examples of how to use INTERACTER see the various demonstration programs supplied in LISK\DEMOS.

Lahey/INTERACTER Starter Kit

17

Chapter 3

Getting Started with INTERACTER

18

Lahey/INTERACTER Starter Kit

Supported Hardware

The tables on the following pages list the display and mouse hardware supported by INTERACTER. Each hardware item is allocated a reference number which can either be specified in the INTERACTER initialization file (using the DISPLAY or MOUSE keywords) or in direct calls to the hardware identification routines (IDisplay/IMouse). The former method is recommended, since this allows programs to remain hardware independent.

Lahey/INTERACTER Starter Kit

19

Chapter 4

Supported Hardware

Displays
Table 1: DOS Display Types
Display Number 1 2 3 4 5 6 7 8 9 10 11 12 13 Notes: Display Type

MDA with direct drive monochrome monitor CGA with composite monochrome monitor CGA with RGB color monitor EGA with direct drive monochrome monitor EGA with RGB color monitor EGA with Enhanced color Display MCGA with analog monochrome monitor MCGA with analog color monitor VGA/SVGA with analog monochrome monitor VGA/SVGA with analog color monitor HGC with direct drive monochrome monitor CGA with b & w monitor (no gray scaling) VESA compatible SVGA

MDA = Monochrome Display Adapter CGA = Color Graphics Adapter EGA = Enhanced Graphics Adapter MCGA = Multi-color Graphics Array VGA = Video Graphics Array SVGA = Super VGA HGC = Hercules Graphics Card VESA = Video Electronics Standards Association Effectively, there are two things to establish under DOS. Which video adapter is in the PC and what sort of monitor is it connected to? If no display number is specified, INTERACTER identifies the hardware in use for itself. SVGA, VGA, MCGA, EGA, MDA and Hercules screens can be identified automatically. By process of elimination this means that an unidentified screen is probably a CGA, though the precise monitor type will not be known. In this situation INTERACTER assumes a CGA with RGB monitor (display type 3).

20

Lahey/INTERACTER Starter Kit

Displays
The following adapter-specific notes may be useful.
MDA

The old Monochrome Display Adapter (MDA) supplied with the original IBM PC supports a single text mode and no graphics. This is the only INTERACTER PC display option which does not support graphics.
Hercules Graphics Card

The Hercules (HGC) is a direct descendent of the MDA. It supports the same text mode and adds a single monochrome graphics mode. Despite its age it has been a widely used standard due to its low cost and relatively good graphics resolution (720x348).
CGA

INTERACTER effectively supports two screen modes on the CGA: 80x25 16-color text mode and 640x200 monochrome graphics. When selecting a CGA display, it is important to differentiate between a composite monochrome monitor (type 2) and a black and white display (type 12). The former can perform gray scaling in color text mode whereas the latter cannot. If text colors on a monochrome CGA are indistinguishable, use display number 12. Note also that direct drive mono monitors (display types 1, 4, and 11) are completely different to other monochrome monitors. Some CGA-standard displays add support for non-standard graphics modes. The most common is the monochrome 640x400 'AT&T/Olivetti' mode. Various Toshiba laptops and Olivetti PC's implement this mode. See the MODE9 initialization file keyword inInitialization Data File Format on page 27 for more details.
EGA

The Enhanced Graphics Adapter (EGA) was the first halfway decent color graphics standard for the PC. INTERACTER expects an EGA to be fitted with a full 256k of video memory, when operating in color graphics modes. Three different monitor types are supported, namely direct drive mono, RGB or ECD. On a mono display one text mode and one graphics mode are supported (functionally, this is quite similar to the Hercules Graphics card). An EGA card with an RGB display is very similar to a CGA except that 16 colors can be displayed in 640x200 graphics mode. The Enhanced color Display provides the best output quality on an EGA with support for a 640x350 16-color mode. Certain non-IBM EGA's also support a 132 column text mode. Where available this can be activated via the MODE10 initialization file keyword. See Initialization Data File Format on page 27 for details.
MCGA

The MCGA is an offbeat hybrid of the CGA and VGA which was only implemented on certain bottom of the range PS/2 systems. It adds 640x480 monochrome and 320x200 256-color graphics modes to those available on the CGA.
VGA/SVGA

VGA is now effectively the universal standard display type on PC compatibles. The more general term 'Super VGA' describes the multitude of non-IBM VGA adapters which extend the VGA standard. A VGA/SVGA is identified automatically by INTERACTER as one of display types 9/10 or 13:
Lahey/INTERACTER Starter Kit

21

Chapter 4

Supported Hardware
Standard VGA or non-VESA SVGA (9/10)

If a display adapter is identified as a VGA (or non-VESA compatible SVGA), the display type will be set to 9 or 10. This provides access to the standard IBM VGA modes, giving a maximum graphics resolution of 640x480 in 16 colors, plus support for non-standard 28/43/ 50-line 80 column text modes. If the display adapter supports SVGA modes, but is not VESA compatible, initialization file entries can be specified which identify the availability of additional manufacturer-specific modes. See below.
VESA Display type (13)

Most newer SVGA's are VESA compatible. That is, they include a BIOS (either in hardware or in a TSR on the utilities disk) which implements standard functions defined by the Video Electronics Standards Association. Such a BIOS is intended to allow SVGA screen modes to be selected and controlled in a manufacturer-independent manner. INTERACTER will automatically identify the presence of such a video BIOS and select display type 13. It will interrogate the BIOS to identify the available VESA compatible screen modes (numbers 256268/284) and make these available to the calling program. To check for VESA compatibility, run the supplied VESAINFO utility (in the LISK\INIT directory). This is a freely distributable program, which developers are encouraged to pass on with their INTERACTER-based applications. Simply run VESAINFO from the DOS prompt with no arguments. If a VESA BIOS is installed, it will list all the available VESA screen modes which are supported by INTERACTER on the current display. For completeness, it also lists the MODEnn keywords which can be used with the alternative SVGA mode selection mechanism described later. There should normally be no need to use these MODEnn keywords, but they may prove useful in the unlikely event that auto-selection of VESA modes gives problems. In this situation, set the display type to 10 and add selected VESA MODEnn keywords, as reported by VESAINFO, to the initialization file. Note that InfoHardware(32) can be used to test from within a program for the presence of a VESA video BIOS. The returned value also identifies which VESA modes are available.
Initialization File MODEnn Keywords:

On a non-VESA compatible SVGA, an alternative mechanism for identifying and selecting SVGA modes involves the use of MODE10/MODE11/MODE12 initialization file keywords. These can be used to configure INTERACTER to use up to three additional screen modes, which have been assigned mode numbers of 10/11/12: Table 2: MODEnn Keywords
nn
10 11 12 Screen Mode

Extended 16-color text mode (up to 132x66 ) 16-color SVGA graphics mode (up to 1600x1200) 256 color SVGA graphics mode (up to 1600x1200)

22

Lahey/INTERACTER Starter Kit

Displays
Each type of SVGA card requires different settings to select these modes. There are several possible reasons for choosing to use these adapter-specific modes in preference to the general purpose "VESA compatible SVGA" option (display type 13): Some SVGA's are not VESA-compatible and a VESA TSR may not be immediately available. A few (not many) VESA BIOS's report modes as being available when they are not. If this happens, set the display type to 10 and use MODEnn keywords. Chipset-specific settings specified via the MODEnn keywords can give marginally better performance in bank-switched graphics modes. The exact speed gain is hard to predict and may not be noticeable in many cases. Some SVGA cards support extra non-VESA modes, which can then be identified alongside the VESA modes, by setting the display type to 13 and specifying MODEnn keywords in the initialization file. e.g., Tseng Labs boards support 100x40x16 text and 640x350x256 graphics modes which can only be identified via MODE10 and MODE12 keywords. Some VESA-compatible BIOS replacement TSR's only report the availability of graphics modes, even though VESA compatible text modes are also available. The MODE10 keyword will provide the only method of selecting extended text modes in this case. In the rare event that a MOUSE.COM driver functions correctly in SVGA mode, this may give slightly cleaner mouse cursor handling, than the INTERACTER maintained cursor. To use the MOUSE.COM cursor, a MODEnn keyword is required without a trailing C argument.

If the MODEnn mode selection mechanism is used, for one of the above reasons, refer to the descriptions of the MODE10, MODE11 and MODE12 initialization file keywords in Initialization Data File Format on page 27. Also, numerous examples are provided in the INIT subdirectory. In general, it is necessary to identify the type of chipset which a particular SVGA is based on before selecting the settings to use in the initialization file (e.g., is it based on Tseng Labs, Trident, Cirrus, etc.?). There are various ways to identify the SVGA type: The file LISK\INIT\READ.ME includes a list of chipsets used by various 'brandname' SVGA's. DOS 6.x and Windows 3.1/95 include the Microsoft Diagnostics program MSD. This includes a 'Video' option which attempts to identify the SVGA type. while not entirely reliable it may give a clue in the 'Manufacturer' or 'OEM Name' fields. Two recommended Public Domain/Freeware SVGA identification programs are available:
Lahey/INTERACTER Starter Kit

23

Chapter 4

Supported Hardware
TEST16/TEST256 (part of the Super VGA Test Library) WHATVGA (part of Finn Thogersen's VGADOC)

Check the copyright notices in the SVGA handbook, if available. Dump the copyright message in the first bytes of the video BIOS, using DEBUG (this may not work, depending on how your video BIOS is configured):
debug -d c000:0

Once the SVGA type has been identified, copy the appropriate MODEnn settings from the corresponding .ini examples file in the INIT directory. If the SVGA type cannot be identified there are VESA BIOS versions of each of the possible MODEnn keywords. These are reported by the VESAINFO utility described earlier. All of the files in the INIT directory can be freely distributed with your INTERACTER-based applications, including the READ.ME file and VESAINFO.EXE program (see earlier notes). It may also prove useful to distribute a compiled/linked copy of the WHATMODE test program, as supplied in the DEMOS directory. This provides a quick and simple method of testing whether the currently identified graphics modes are working on the current display.

Mice
Table 3: Mouse Types
Mouse Number 1 2 3 Mouse Type

No mouse fitted/don't use mouse 2-button mouse 3-button mouse

Under DOS, a Microsoft (2-button) or Mouse Systems (3-button) compatible mouse is required. MOUSE.COM or the equivalent driver must be installed before running programs which use the mouse. INTERACTER will check to see whether the driver is loaded and will also attempt to determine whether a 2- or 3-button mouse is attached. Where fitted, the mouse is available for use in menus, input fields, etc. A genuine Microsoft driver is recommended (v6.1 or later), since INTERACTER expects the driver to conform to the specification published by Microsoft. Third party 'Microsoft compatible' drivers are a common source of incompatibility. Non-mouse pointing devices such as digitizing tablets or trackerballs can also be used as a mouse with INTERACTER provided a suitable MOUSE.COM equivalent is loaded.

24

Lahey/INTERACTER Starter Kit

Mice
Virtually all available mouse drivers (including Microsoft's) fail to work correctly in AT&T and Super VGA modes (INTERACTER modes 9-12). Typical problems include a missing or incorrectly displayed mouse cursor and erratic cursor movement. In this situation add a 'C' at the very end of the MODEnn record in your initialization file to inform INTERACTER that it must provide its own mouse cursor in these modes. This will also cause mouse movement to be identified in a different way thereby also curing the erratic cursor movement problem. In VESA modes 256+ (available when display type 13 has been selected) INTERACTER automatically activates these fixes, so no user action is required. See Initialization Data File Format on page 27 for more information on initialization file keywords.

Lahey/INTERACTER Starter Kit

25

Chapter 4

Supported Hardware

26

Lahey/INTERACTER Starter Kit

Initialization Data File Format


The INTERACTER initialization file is an ordinary text file which can be prepared with any text editor. The name of the file can be specified in one of three ways: By assigning a name to an environment variable called INTINIT. This is the recommended method, since it allows you to create a single initialization file and access it from any program regardless of which directory that program is invoked from. A name can be specified when calling IScreenOpen at program start up. If neither of the above methods are used, INTERACTER will attempt to open a file called INTERACT.INI.

The use of an initialization file is optional, but recommended. Its purpose is to define various information to INTERACTER, including: The type of display you are using The names of various default input files, e.g., a software character set. The control keys to be used by the input handling routines. Logical file numbers to be used for certain I/O operations.

Each record in your initialization file describes one of the above, by means of a keyword, an equals sign and a value. Keywords can be in upper or lower case. The format of these records is quite flexible and comments are allowed for. Records of up to 90 characters can be processed allowing filenames of up to 80 characters to be specified. Only that information which you wish to define need be included and it can be in any order.

Lahey/INTERACTER Starter Kit

27

Chapter 5

Initialization Data File Format

Keyword Quick Reference Summary


The following initialization file keywords are recognized. See Initialization Data File Format on page 27 for full details of these keywords. Table 4: INTERACTER Keywords
Keyword CHARDIR = CHARSET = DISPLAY = KEYnn = MODE9 = MODE10 = MODE11 = MODE12 = MOUSE = REVERSE = VER = Meaning

Directory containing INTERACTER character sets Default character set file name Display type Control keys (i.e., KEY1->KEY50) AT&T 640x400 mono graphics mode availability Extended EGA/VGA/SVGA text mode availability 16-color SVGA graphics mode availability 256-color SVGA graphics mode availability Mouse type Reverse foreground/background on mono displays Show version number

Keywords in Detail
The following keywords can be set to the indicated types of values:
CHARDIR = string The name of the directory containing the INTERACTER software graphics character sets. Alternatively, this value is definable via the INTCHDIR environment variable. If neither is defined, the current directory at run-time is assumed. CHARSET = string The default software graphics character set filename, as used by IGrCharSet. Alternatively, the name of this file can be set up in an environment variable called INTCHAR.

28

Lahey/INTERACTER Starter Kit

Keywords in Detail
DISPLAY = numeric-value

The display type number, as can be specified to IDisplay. Display numbers are listed in Supported Hardware on page 19. Alternatively, the display number can be set up in an operating system variable called INTTERM. The selected display type is accessible in your programs via InfoHardware(10).
KEYnn = numeric value The ASCII code or special INTERACTER code (see InKeyEvent) of the specified input control key. The full list of input control keys is defined under the InControlKey routine. Note that nn is a 1- or 2-digit number, so KEYnn actually means anything from KEY1 for control key number 1 (cursor up) to KEY70 for key number 70 ('spare exit' key). Control key assignments can be interrogated in your programs via InfoInput(1-50/151-170). MODE9 = ax bx cx dx [C] The register values to be used to switch into INTERACTER screen mode 9 (mono AT&T 640x400 graphics) on the PC. This keyword can be used to activate this screen mode on certain sub-VGA PC screens. Up to 4 decimal numeric values should be supplied, identifying the AX/BX/CX/DX register values to be specified in a call to the INT 10h BIOS interrupt which selects this screen mode. Any trailing values which are omitted are treated as zero. Commonly, all that will need to be specified is the screen mode number allocated by a particular manufacturer to this non-standard graphics mode. Refer to the documentation supplied with your PC display adapter for details of appropriate values or see the sample initialization file entries in the INTERACTER INIT sub-directory.

If the record containing the MODE9 keyword ends with a space delimited 'C', INTERACTER will maintain its own mouse cursor in this mode. Note this must be the very last character on the line, if specified. Most Microsoft compatible mouse drivers do not support a mouse cursor in non-standard PC graphics modes, so a trailing 'C' will normally be required if a mouse is to be used.
MODE10 = ax bx cx dx chipset width height [C]

The register values to be used to switch into INTERACTER screen mode 10 (Extended EGA/ VGA/SVGA 16-color text) on the PC. The first 4 arguments, ax/bx/cx/dx, are the INT 10h mode selection register values as described under the MODE11 keyword. The next three arguments are numeric values:
chipset = not used width = screen mode width in columns (default = 132) height = screen mode height in rows (default = 25)

Any trailing values which are omitted take the default values shown. The [C] option has the same effect as for the MODE9 keyword, i.e., it causes INTERACTER to maintain its own mouse cursor in this screen mode. It must be the very last character on the line, if specified.
Lahey/INTERACTER Starter Kit

29

Chapter 5

Initialization Data File Format


The chipset argument is not used when selecting mode 10 but must be included as a placeholder, if the mode width and height are specified, to ensure consistency with the MODE11 and MODE12 keyword. Refer to the documentation supplied with your PC display adapter for details of appropriate values. Here are some examples (many more are included in the LISK\INIT sub-directory): Table 5: MODE10 Argument Examples
Argument Argument Adaptor

MODE10 = 35 C

MODE10 = 48 0 0 0 1 80 60 C

VGA based on Tseng Labs ET4000 chipset VGA based on Paradise (Western Digital) chipset VGA based on Video 7 chipset

MODE10 = 85 C

MODE10 = 84 0 0 0 2 132 43 C

MODE10 = 28421 65 C

MODE10 = 28421 69 0 0 3 132 28 C

MODE11 = ax bx cx dx chipset width height [C] The register values to be used to switch into INTERACTER screen mode 11 (16 color SVGA graphics) on the PC. See IScreenModeN.

The first 4 arguments, ax/bx/cx/dx, are the register values for the BIOS screen mode selection interrupt (invoked via INT 10h). The values of cx and dx are normally zero. On most SVGA chipsets ax is a manufacturer-specific screen mode number, e.g., the Paradise 800x600 16-color mode number is 88, hence AX is 88 and BX is zero. However, some chipsets require a fixed value for AX (e.g., 20226 for a VESA BIOS or 28421 for a Video 7 card) in which case the mode number must be specified in the BX value. Mode numbers are often listed in a table in the back of the VGA manual, where supplied. VGA manuals aften quote mode numbers as hex values (e.g., 58h instead of 88). The values in a MODE11 record must be expressed in decimal.

30

Lahey/INTERACTER Starter Kit

Keywords in Detail
The next three arguments are numeric values:
chipset = VGA chipset number width = screen mode width in pixels (default = 800) height = screen mode height in pixels (default = 600)

Table 6: Chipset = Argument Values


Value 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 Chipset

Tseng Labs ET3000 (default) Tseng Labs ET4000 Paradise (Western Digital) Video 7 Everex ATI x8800 Trident Chips & Technologies 82c452/82c453 Ahead B Oak Technologies OTI-037C/067/077 Genoa 6x00 GVGA NCR 77C20/21/22E S3 86C911/924 Cirrus 540x-5424/62xx Primus 2000 AcuMos AVGA RealTek 3106 Ahead A VESA BIOS Oak Technologies OTI-087 Cirrus 64xx

Lahey/INTERACTER Starter Kit

31

Chapter 5

Initialization Data File Format


Table 6: Chipset = Argument Values
Value 21 22 23 24 25 26 Chipset

Avance Logic ALG2xxx UMC 85c408 MXIC MX860x0 Weitek W5x86 Hualon HM86304 Cirrus 5426-545x

Any trailing values which are omitted take the default values shown. If the mode width and height are omitted, the chipset can also be omitted since 800x600 mode is not bank-switched (and is therefore not chipset dependent). See Supported Hardware on page 19 for information regarding chipset identification. Supported 16-color mode width and height values are 800x600, 1024x768, 1280x1024 and 1600x1200. The [C] option has the same effect as for the MODE9 keyword, i.e., it causes INTERACTER to maintain its own mouse cursor in this screen mode. It must be the very last character on the line, if specified. Here are some examples (many more are included in the LISK\INIT sub-directory): Table 7: MODE11 Argument Examples
Argument Argument Adaptor

MODE11 = 55 0 0 0 1 1024 768 C

MODE11 = 61 0 0 0 1 1280 1024 C

VGA based on Tseng Labs ET4000 chipset VGA based on Paradise (Western Digital) chipset VGA based on Video 7 chipset

MODE11 = 88 C

MODE11 = 100 0 0 0 2 1280 1024

MODE11 = 28421 98 C

MODE11 = 28421 101 0 0 3 1024 768 C

32

Lahey/INTERACTER Starter Kit

Keywords in Detail
Alternatively, many (but not all) SVGA adapters support a 'generic' 800x600x16 mode, number 106 (6A hex). Where available, this can be enabled using the following:
MODE11 = 106 C MODE12 = ax bx cx dx chipset width height [C]

The register values to be used to switch into INTERACTER screen mode 12 (256 color SVGA graphics) on the PC. See IScreenModeN Subroutine on page 150. The first 4 arguments, ax/bx/cx/dx, are the INT 10h mode selection register values as described under the MODE11 keyword. The next three arguments are numeric values:
chipset = VGA chipset number (see MODE11 keyword) width = screen mode width in pixels (default = 640) height = screen mode height in pixels (default = 480)

Any trailing values which are omitted take the default values shown. Unlike the MODE11 keyword, the chipset is required in all modes. See Supported Hardware on page 19 for information regarding chipset identification. The largest supported 256-color mode is 1600x1200. The [C] option has the same effect as for the MODE9 keyword, i.e., it causes INTERACTER to maintain its own mouse cursor in this screen mode. It must be the very last character on the line, if specified. Here are some examples (many more are included in the LISK\INIT sub-directory): Table 8: MODE12 Argument Examples
Argument Argument Adaptor

MODE12 = 46 0 0 0 1 C

MODE12 = 56 0 0 0 1 1024 768 C

VGA based on Tseng Labs ET4000 chipset VGA based on Paradise (Western Digital) chipset VGA based on Video 7 chipset

MODE12 = 94 0 0 0 2 640 400 C

MODE12 = 95 0 0 0 2 C

MODE12 = 28421 103 0 0 3 C

MODE12 = 28421 105 0 0 3 800 600 C

MOUSE = numeric-value

The mouse type number as can be specified to IMouse. Mouse numbers are listed in Supported Hardware on page 19. The selected mouse type is accessible in your programs via InfoHardware(13).
Lahey/INTERACTER Starter Kit

33

Chapter 5

Initialization Data File Format


REVERSE = string

Foreground/background colors can be reveresed on monochrome displays by specifying


REVERSE=YES on monochrome sub-VGA PC screens (i.e., display types 1, 4, 11 and 12). VER =

A record of this type will cause the INTERACTER version number to be displayed at startup. There should normally be no need to use this feature, but the number should be quoted when reporting problems. Note that the equals sign (=) is required as usual, but there is no following value.
Example PC Initialization File REM This is a typical DOS INTERACTER initialization file DISPLAY = 10 (VGA with color monitor) CHARSET = DUPLEXR.CHR REM Define some input control keys KEY13 = 179 (clear to start becomes F9 ) KEY14 = 180 (clear to end becomes F10) REM Note that comments are allowed in MODE commands but before REM 'C' MODE11 = 55 (800x600x16 Tseng Labs mode) C

34

Lahey/INTERACTER Starter Kit

Error Codes

The following error values are set by various INTERACTER routines and are returned by the error information function InfoError. The listed symbolic names are all defined in the INTPARAM module. Table 9: INTERACTER Error Codes
Name ErrFileOpen ErrFileIO ErrFileClose ErrLargeNum ErrMaxWindow ErrWinBuffer ErrWinCoOrds ErrNoSubstring ErrBadChar ErrBadClear ErrBadUnits No. 1 2 3 4 7 8 9 10 12 14 16 Description

Error opening a file. Error reading from a file. Error closing a file or device. Number too large in string-to-numeric conversion. Max number of windows exceeded. Window buffer space exceeded. Invalid window co-ordinates. No substring found. Invalid character detected. Invalid text co-ordinates for clear operation.
X or Y graphics unit range is invalid. Default of 0-1 used.

ErrNumToStr ErrMenuOpt

18 19

Numeric to string conversion error. String filled with *'s. All options start with '-' in a menu.

Lahey/INTERACTER Starter Kit

35

Chapter 6

Error Codes
Table 9: INTERACTER Error Codes
Name ErrBadRadius ErrBadMode No. 20 41 Description

Radius of a circle is <= zero. Unknown or unsupported screen mode requested in call to IScreenModeN Unknown color number specified to IGrColourN. Current color remains unchanged. Invalid X and/or Y range specified to IGrArea. reset to 0-1. Fill too complex in IGrPolygonComplex. Unable to find software font file in IGrCharOut to substitute for unavailable hardware font Range

ErrBadColour

42

ErrBadArea ErrFillComplex

44 49

ErrNoSoftFont

53

36

Lahey/INTERACTER Starter Kit

Exit Codes

In the event of INTERACTER detecting an unrecoverable error, it calls the IOsExitProgram routine and passes an exit code to the operating system. The following is a list of the exit codes, which routines generate them and the likely cause. Codes 1 to 20 are reserved for use by INTERACTER. Table 10: INTERACTER Exit Codes
Exit Code Generated By Cause

IScreenModeN

A screen mode which INTERACTER expected to be able to select was not actually selected. This is usually due to incorrectly identifying the display type to INTERACTER. An attempt has been made to select a graphics screen mode when the currently identified display type does not support graphics. Check the selected INTERACTER display type.

13

IScreenMode IGrInit IScreenOpen

Lahey/INTERACTER Starter Kit

37

Chapter 7

Exit Codes

38

Lahey/INTERACTER Starter Kit

Filename Specification
Several INTERACTER routines take an optional filename as an argument, including IScreenOpen, and IGrCharSet. In all cases, if a non-blank filename is supplied, this takes priority. The format of the filename will normally be system specific, having been obtained from an operating system variable (using IOsVariable) or from the screen (using InString/InStringDef/etc.). In general, hard coding filenames is not recommended for portability reasons. To simplify programming, blank filenames can be supplied, in which case INTERACTER has clear rules to determine the name of the file or device which it will attempt to open: Non-blank filename supplied -> Yes -> Open specified file | no | Default name specified -> Yes -> Open file named in initialization file in initialization file? | no | Environment variable set? -> Yes -> Open file named in environment variable | no | Use a system-specific default filename When a blank filename is supplied, the name supplied in the initialization file is used. If no such name was specified, the contents of an environment variable are used. If the environment variable has not been set up either, INTERACTER finally uses a system specific default
Lahey/INTERACTER Starter Kit

39

Chapter 8 Filename Specification


(e.g., interact.ini). The only exception to these rules is IScreenOpen which obviously omits the second test. The initialization file keywords, operating system variable names and typical system specific default filenames are listed below: Table 11: Filename Specification
Routine IScreenOpen IGrCharSet Initialization File Keyword CHARSET Environment Variable INTINIT INTCHAR Typical Default Filename INTERACT.INI STANDARD.CHR

40

Lahey/INTERACTER Starter Kit

Keyboard Codes

The availability of non-ASCII keys, such as function keys, varies considerably on the displays supported by INTERACTER. To overcome this, InKeyEvent returns a set of standardized key codes which correspond to an 'ideal' keyboard. The definition of these 'ideal' key codes appears under the InKeyEvent routine. This chapter lists the actual keys which are available on various types of keyboard, in terms of the key codes returned by InKeyEvent (and InKeyEventImm). On some keyboards, a separately detectable keypad is available i.e., the keys on the keypad can be identified separately from keys with the same keytop legend on the main keyboard. For these keyboards, two key code tables are listed, one for keypad mode 2 and the other for keypad mode 3. These keypad modes are controlled by the InKeypad routine in the IP group. Essentially, in keypad mode 2, keypad keys are treated as cursor or editing keys. In mode 3 they return their uniquely assigned codes. Refer to the documentation for the InKeypad routine for more details. Also listed are the default control key assignments used by INTERACTER's input routines. These default assignments can be overridden if required using the KEYnn initialization file keywords (seeInitialization Data File Format on page 27) or the InControlKey routine (see Input Handling on page 83).

IBM PC (Standard Keyboard)


The 'standard' PC keyboard normally has 83 keys, with the keypad doubling up for cursor and editing keys. Keypad mode 2 is therefore the default on the PC to enable the cursor keys etc. to be detected. On a standard PC keyboard InfoInput(56) will return a value of 0. The Alt/keypad technique for generating specific ASCII codes is fully supported. Where the generated code is greater than 127 it will be returned with 256 added. For example, Alt/ 128 returns an InKeyEvent code of 128+256=384. Similarly, all other Alt/key combinations are supported (Alt/A-Alt/Z, Alt/0-Alt/9, etc) in which case 512 is added to the InKeyEvent code, e.g., Alt/A returns 512 + 65 = 577.
Lahey/INTERACTER Starter Kit

41

Chapter 9

Keyboard Codes

Table 12: Key Codes on a Standard 83-key PC Keyboard under DOS in keypad mode 2
Code 9 13 27 32126 127 128 129 Key Tab Return Escape ASCII chars Ctrl/Backspace Keypad 8 Keypad 2 Code 140 141 142 143 Key Keypad 7 Keypad 1 Keypad 0 Keypad . Code 162 163 164 165 Keypad * Key Keypad +

144 150 151

Shift/Tab

166 170 171180 191200 211220 231240 F1F10 Shift/F1Shift/F10 Ctrl/F1Ctrl/F10 Alt/F1Alt/F10 Alt/Keypad 8-bit char Alt/Backspace Alt/Tab Alt/Return Alt/Escape Alt/0Alt/9 Alt/A-Alt/Z

130

Keypad 6

152

131

Keypad 4

153

132

Keypad 9

154

133 134 135 136 137 138

Keypad 3 Ctrl/Keypad 6 Ctrl/Keypad 4 Ctrl/Keypad 9 Ctrl/Keypad 3 Ctrl/Keypad 1

155 156 157 158 159 160

Keypad 5

384511 520 521 525 539

Keypad -

560569 577602

139

Ctrl/Keypad 7

161

42

Lahey/INTERACTER Starter Kit

IBM PC (Standard Keyboard)

Table 13: Key Codes on a Standard 83-key PC Keyboard under DOS in keypad mode 3
Code 9 13 27 32126 127 128 129 Key Tab Return Escape ASCII chars Ctrl/Backspace Code 140 141 142 143 Key Code 162 163 164 165 Keypad * Key Keypad +

144 150 151

Shift/Tab Keypad 0 Keypad 1

166 170 171180 191200 211220 231240 384511 520 521 525 539 560569 577602 F1F10 Shift/F1Shift/F10 Ctrl/F1Ctrl/F10 Alt/F1Alt/F10 Alt/Keypad 8-bit char Alt/Backspace Alt/Tab Alt/Return Alt/Escape Alt/0Alt/9 Alt/A-Alt/Z

130

152

Keypad 2

131

153

Keypad 3

132

154

Keypad 4

133 134 135 136 137 138 Ctrl/Keypad 6 Ctrl/Keypad 4 Ctrl/Keypad 9 Ctrl/Keypad 3 Ctrl/Keypad 1

155 156 157 158 159 160

Keypad 5 Keypad 6 Keypad 7 Keypad 8 Keypad 9 Keypad -

139

Ctrl/Keypad 7

161

Keypad .

Lahey/INTERACTER Starter Kit

43

Chapter 9

Keyboard Codes

Table 14: DOS - Default Control Key Assignments


Control Key Number 1 2 3 4 5 6 Contol Key Function cursor up cursor down cursor right cursor left extended cur/up extended cur/down extended cur/ right extended cur/left extreme cur/up extreme cur/down extreme cur/right extreme cur/left clear to start clear to end move to start move to end toggle insert mode backspace/delete 1 backspace/delete 2 InKeyEvent Code 128 129 130 131 132 133 Actual Key(s) Keypad 8/Cursor Up Keypad 2/Cursor Down Keypad 6/Cursor Right Keypad 4/Cursor Left Keypad 9/ Page Up Keypad 3/ Page Dn

134

Ctrl/Keypad 6 Ctrl/Keypad 4

8 9 10 11 12 13 14 15 16 17 18

135 136 137 138 139 173 174 140 141 142 8

Ctrl/Keypad 9 Ctrl/Keypad 3 Ctrl/Keypad 1

Ctrl/Keypad 7 F3 F4 Keypad 7/Home Keypad 1/End Keypad 0/Insert Backspace

19

127

Ctrl/Backspace

44

Lahey/INTERACTER Starter Kit

IBM PC (Enhanced Keyboard)


Table 14: DOS - Default Control Key Assignments
Control Key Number 20 21 22 23 24 25 26-30 35 36-70 Contol Key Function delete under cursor confirm input help quit tab back-tab spare exit keys next item spare exit keys InKeyEvent Code 143 13 171 27 9 144 0 32 0 Actual Key(s)

Keypad . / Delete Return F1 Escape Tab Shift/Tab undefined Space Bar undefined

IBM PC (Enhanced Keyboard)


The newer 'enhanced' PC keyboard has 101/102 keys and has largely come to replace the original 'standard' keyboard. The enhanced keyboard has separate cursor/editing keys and two extra function keys. There is less need to use keypad mode 2, but this is the default on all PC's to ensure consistent behavior on systems with either keyboard type. On an enhanced keyboard InfoInput(56) will return 1. The Alt/Keypad technique for generating specific ASCII codes is fully supported. Where the generated code is greater than 127 it will be returned with 256 added. For example, Alt/ 128 returns an InKeyEvent code of 128+256=384. Similarly, all other Alt/key combinations are supported (Alt/A-Alt/Z, Alt/0-Alt/9, etc) in which case 512 is added to the InKeyEvent code, e.g., Alt/A returns 512 + 65 = 577. The default IBM PC control key assignments on an enhanced keyboard, are as listed under the Standard Keyboard.

Lahey/INTERACTER Starter Kit

45

Chapter 9

Keyboard Codes

Table 15: Key Codes on Enhanced PC Keyboard under DOS in keypad mode 2
Code 9 13 27 32126 127 128 129 Key Tab Return Escape ASCII chars Ctrl/Backspace Cursor Up Cursor Down Code 140 141 142 143 Key Home End Insert Delete Code 162 163 164 165 Key Keypad + Keypad / Keypad *

144 150 151

Shift/Tab

166 170 171182 191202 211222 231242

Keypad Enter

F1F12 Shift/F1Shift/F12 Ctrl/F1Ctrl/F12 Alt/F1Alt/F12 Alt/Keypad 8-bit char Alt/Backspace Alt/Tab Alt/Return

130

Cursor Right

152

131

Cursor Left

153

132

Page Up

154

133 134 135 136

Page Down Ctrl/Keypad 6 Ctrl/Keypad 4 Ctrl/Cursor Up Ctrl/Cursor Down Ctrl/Cursor Right Ctrl/Cursor Left

155 156 157 158

Keypad 5

384511 520 521 525

137

159

539 560569 577602

Alt/Escape Alt/0Alt/9 Alt/A-Alt/Z

138

160

Keypad -

139

161

46

Lahey/INTERACTER Starter Kit

IBM PC (Enhanced Keyboard)

Table 16: Key Codes on Enhanced PC Keyboard under DOS in keypad mode 3
Code 9 13 27 32126 127 128 129 Key Tab Return Escape ASCII chars Ctrl/Backspace Cursor Up Cursor Down Code 140 141 142 143 Key Home End Insert Delete Code 162 163 164 165 Key Keypad + Keypad / Keypad *

144 150 151

Shift/Tab Keypad 0 Keypad 1

166 170 171182 191202 211222 231242 384511 520 521 525

Keypad Enter

F1F12 Shift/F1Shift/F12 Ctrl/F1Ctrl/F12 Alt/F1Alt/F12 Alt/Keypad 8-bit char Alt/Backspace Alt/Tab Alt/Return

130

Cursor Right

152

Keypad 2

131

Cursor Left

153

Keypad 3

132

Page Up

154

Keypad 4

133 134 135 136

Page Down Ctrl/Keypad 6 Ctrl/Keypad 4 Ctrl/Cursor Up Ctrl/Cursor Down Ctrl/Cursor Right Ctrl/Cursor Left

155 156 157 158

Keypad 5 Keypad 6 Keypad 7 Keypad 8

137

159

Keypad 9

539 560569 577602

Alt/Escape Alt/0Alt/9 Alt/A-Alt/Z

138

160

Keypad -

139

161

Keypad .

Lahey/INTERACTER Starter Kit

47

Chapter 9

Keyboard Codes

48

Lahey/INTERACTER Starter Kit

10 Subroutine Summary

Subroutine Groups
Text Screen Output
Group OU: Group CU: Group CL: Group AT: Group CG: Group WN: Text Output Cursor Control Clearing Text Attributes Character Graphics Window Manager

Input Handling
Group KM: Group IN: Group MN: Group IP: Group MC: Keyboard/Mouse Event Handling Fixed Field Input Handling Menu Handling Input Control Parameter Selection Mouse Cursor Control

High Resolution Graphics


Group GG: Group GS: Group GD: Group GC: General Graphics Graphics Style Selection Graphics Drawing/Movement Graphics Character Output
Lahey/INTERACTER Starter Kit

49

Chapter 10

Subroutine Summary

General Functions
Group SC: Group IF: Group OS: Group HW: Group CH: Screen Manipulation Information Operating System Interface Hardware Identification Character Manipulation

Subroutine Summary
Group OU: Text Output Routines
IOutString IOutStringXY IOutVertical IOutVerticalXY

Output string at current cursor pos Output string at a specific (x,y) pos Output string vertically from current cursor pos Output string vertically at a specific (x,y) pos

Group CU: Cursor Control Routines


ICursor ICursorLeft ICursorRight ICursorXY

Enable/disable cursor Move cursor left N columns & wrap at edge of screen Move cursor right N columns & wrap at edge of screen Move cursor to a specific (x,y) position

Group CL: Clearing Routines


IClearArea IClearScreen

Clear a screen area Clear the whole screen

Group AT: Text Attribute Routines


ITextAttribute ITextColourN

Set bold/flash/italic/reverse/underline combination Select foreground/background text colors by number

Group CG: Character Graphics Routines


IFrame IFrameOptions IFrameTitle IFrameTitleBox IFrameType ISplitFrameH

Print a frame round a screen area Specify frame options (colors, etc.) Print a frame, with a title within top of frame Print a frame, with a title in a box at top of frame Select frame type Split up a frame horizontally

50

Lahey/INTERACTER Starter Kit

Group WN: Window Management Routines

Group WN: Window Management Routines


IWinAction IWinClear IWinClearArea IWinClose IWinCursorXY IWinOpen IWinOpenTitle IWinOutString IWinOutStringXY IWinSelect

Define action to be taken when opening a window Clear the whole of the currently selected window Clear an area of the currently selected window Close top window & optionally restore screen Position cursor within current window Open a new window Open a new window with a title Output string at current window cursor position Output string at a specific window position Select current window by number

Group KM: Keyboard/Mouse Event Handling Routines


InCharacter InEventSelect InKeyEvent InKeyEventCursor InKeyEventImm

Get single character from keyboard (wait for key press) Select events to be reported via InKeyEvent/InKeyEventImm Get single key/mouse event, inc. function/keypad/cursor keys As InKeyEvent but also simulate a text cursor As InKeyEvent but immediate return if no event waiting

Group IN: Fixed Field Input Handling Routines


InString InStringDef InStringXY InStringXYDef

Get fixed length string (no default offered) Get fixed length string, offering a default Get string at an (x,y) position (no default offered) Get string at an (x,y) position, offering a default

Group MN: Menu Handling Routines


IMenuHoriz IMenuVertic

Horizontal pointer/highlight menu Vertical pointer/highlight menu

Group IP: Fixed-field/Menu Input Parameter Selection Routines


InControlKey InHighlight InKeypad InMouseOptions InPopup

Define control keys for all input handling routines Select highlight for menu & input-at-(x,y) routines Select keypad detection/interpretation mode Specify mouse options for fixed field/menu input Select pop-up mode for menu & input-at-(x,y) routines
Lahey/INTERACTER Starter Kit

51

Chapter 10

Subroutine Summary

Group MC: Mouse Cursor Control


IMouseCursorHide IMouseCursorShow

Hide mouse cursor Show mouse cursor

Group GG: General Graphics Routines


IGrArea IGrAreaClear IGrGetPixelRGB IGrInit IGrPause IGrQuit IGrUnits

Define size of graphics area Clear the current graphics screen area Get the a screen pixel value as an (r,g,b) triplet Start graphics output Pause before clearing screen to start a new picture End graphics output Define plotting units to be used

Group GS: Graphics Style Selection


IGrcolorN IGrFillPattern IGrLineType IGrPaletteRGB

Select graphics color using a color number Define fill pattern (solid/stippled/hatched) Select line type (solid, dots, dashes or dot/dash) Redefine color palette using RGB color scheme

Group GD: Graphics Drawing Primitives


IGrCircle IGrLineTo IGrMoveTo IGrPoint IGrPolygonComplex

Draw/fill circle at an absolute position Draw line to a new absolute position Move current plotting position to a new absolute position Draw a single point at new absolute position Draw/fill a complex (possibly intersecting) polygon

Group GC: Graphics Character Output Routines


IGrCharJustify IGrCharLength IGrCharOut IGrCharSet IGrCharSize IGrCharSpacing

Select graphics text justification Return relative length of string allowing for prop spacing Output character string at an absolute (x,y) position Select graphics character set to use for text output Select graphics text/symbol size Select fixed or proportional spacing

52

Lahey/INTERACTER Starter Kit

Group SC: Screen Manipulation Routines

Group SC: Screen Manipulation Routines


IScreenBell IScreenClose IScreenMode IScreenModeN IScreenModeOptions IScreenOpen

Enable/disable/ring the bell Terminate INTERACTER screen handling Select screen mode by resolution & colors Select screen mode by number Specify screen mode selection options Initialize INTERACTER screen handling

Group IF: Information Routines


InfoAttribute InfoError InfoGraphics InfoGrScreen InfoHardware InfoInput InfoScreen InfoScreenMode InfoWindow

Return text attributes information Return error information Return real graphics mode information Return graphics facilities information (screen) Return hardware information Return keyboard input facilities information Return screen mode information (current mode) Return screen mode information (any mode) Return window management system information

Group OS: Operating System Interface


IOsExitProgram IOsVariable

Abort program with an error message & error code Return the value of an operating system (environment) variable

Group HW: Hardware Identification Routines


IDisplay IMouse

Select display type Select mouse type

Group CH: Character Manipulation Routines


IActualLength IFillString IJustifyString ILocateChar ILocateString ILowerCase IntegerToString IStringToInteger IUpperCase

Return actual length of string excluding trailing blanks Fill a character string with a given character Justify a string within a character variable Locate position of first non blank character Locate position of first non blank sub-string Convert a string to lower case Convert an integer value to a string Convert a string to an integer value Convert a string to upper case
Lahey/INTERACTER Starter Kit

53

Chapter 10

Subroutine Summary

54

Lahey/INTERACTER Starter Kit

11 Text Screen Output

Group OU: Text Output


These routines provide the most fundamental text screen output facilities at the heart of INTERACTER. IOutString is a central 'workhorse' routine which simply pushes out a string at the current cursor position, leaving the cursor at the end of the string which has been written. IOutStringXY performs the same task, but at a specified column/row. IOutVertical and IOutVerticalXY provide equivalent functions for outputting text vertically. Cursor position specification follows the same conventions as described in the CU group, i.e., the top left corner is (1,1).

IOutString Subroutine
Description
Output string at current cursor position.

Syntax
IOutString(string)

Arguments
CHARACTER string = String to output

Effect
Outputs string, at the current cursor position, in the current text style. The cursor is left at the end of the string. Text which would extend beyond the end of the current screen line is truncated. Text can safely be written to the bottom right hand corner of the screen, since scrolling is suppressed.
Lahey/INTERACTER Starter Kit

55

Chapter 11 Text Screen Output


Example
CHARACTER (LEN=10) :: STR1 CALL IOutString(STR1) CALL ICursorXY(1,5) CALL IOutString('Leave the cursor on this line > ')

IOutStringXY Subroutine
Description
Output string at a specific (x,y) position.

Syntax
IOutStringXY(ix,iy,string)

Arguments
INTEGER ix = Column INTEGER iy = Row CHARACTER string = String to write out

Effect
Outputs a string at the specified screen position, in the same way as IOutString.

Example
CALL ICursorXY(IX,IY) CALL IOutString('Enter name: ') ! this is simpler ... CALL IOutStringXY(IX,IY,'Enter name: ')

IOutVertical Subroutine
Description
Output string vertically from current cursor position.

Syntax
IOutVertical(string)

Arguments
CHARACTER string = String to output

56

Lahey/INTERACTER Starter Kit

IOutVerticalXY Subroutine
Effect
Outputs string, vertically (downwards) from the current cursor position. Text which would extend beyond the bottom line of the screen is truncated in a similar manner to text which is output horizontally using IOutString. (If a string is to be written in the extreme right column of the screen, use IOutVerticalXY to output your string, instead of IOutVertical.)

Example
CALL ICursorXY(2,1) CALL IOutVertical('1 2 3 4 5 6 7 8 9 A B')

IOutVerticalXY Subroutine
Description
Output string vertically at a specific (x,y) position.

Syntax
IOutVerticalXY(ix,iy,string)

Arguments
INTEGER ix = Column INTEGER iy = Row CHARACTER string = String to write out

Effect
Outputs a string vertically from the specified screen position, in the same way as IOutVertical.

Example
CALL ICursorXY(IX,1) CALL IOutVertical('Vertical !') ! this is simpler ... CALL IOutVerticalXY(IX,1,'Vertical !')

Group CU: Cursor Control


The cursor control routines use text screen co-ordinates which assume that (1,1) is the top left corner of the screen. The size of screen depends on the mode selected using IScreenMode or IScreenModeN, which are available in the SC group.
Lahey/INTERACTER Starter Kit

57

Chapter 11 Text Screen Output


CU routines allow the cursor position to be set absolutely (ICursorXY), or by a distance relative to the current position (ICursorLeft, ICursorRight). The on-screen cursor can be enabled or disabled (ICursor).

ICursor Subroutine
Description
Enable/disable cursor.

Syntax
ICursor(onoff)

Arguments
CHARACTER onoff = 'ON': switch the cursor on (upper or lower case) = any other value to switch cursor off

Effect
Enables or disables the cursor. Certain INTERACTER routines automatically set the state of the hardware cursor. The menu handling routines disable it and the fixed field input routines enable it. In all cases these routines will restore the state set by ICursor on exit. The default state of the cursor on mode selection (as performed by IScreenOpen, IGrInit, IScreenMode or IScreenModeN) is enabled in text mode and disabled in graphics mode.

Portability notes
There is no hardware cursor in graphics screen modes.

Example
CALL CALL CALL CALL CALL ICursor('OFF') IOutStringXY(10,2,'The cursor should now be off ...') InKeyEvent(IKEY) ICursor('ON') IOutStringXY(10,4,'And now it should be back on ...')

ICursorLeft Subroutine
Description
Move cursor left N columns & wrap at edge of screen.

58

Lahey/INTERACTER Starter Kit

ICursorRight Subroutine
Syntax
ICursorLeft(ncols)

Arguments
INTEGER ncols = Number of columns by which to move left

Effect
Moves the cursor left by the specified number of columns. If the cursor would move beyond the edge of the screen it is wrapped onto the previous line, at the other side of the screen.

Example
CALL ICursorLeft(10)

ICursorRight Subroutine
Description
Move cursor right N columns & wrap at edge of screen.

Syntax
ICursorRight(ncols)

Arguments
INTEGER ncols = Number of columns by which to move right

Effect
Moves the cursor right by the specified number of columns. If the cursor would move beyond the edge of the screen it is wrapped onto the next line, at the other side of the screen.

Example
CALL ICursorRight(5)

ICursorXY Subroutine
Description
Move cursor to a specific (x,y) position.

Syntax
ICursorXY(ix,iy)
Lahey/INTERACTER Starter Kit

59

Chapter 11 Text Screen Output


Arguments
INTEGER ix = Column INTEGER iy = Row

Effect
Moves the cursor to a specific position, assuming that the top left 'home' position is (1,1). Attempts to position the cursor 'off-screen' will have no effect.

Example
CALL ICursorXY(10,5) CALL IOutString('This is 10 columns across & 5 lines down')

Group CL: Clearing


These routines allow all or part of the screen to be cleared. They always clear to the currently selected background text attribute as set by the ITextColourN or ITextAttribute routines in the AT group.

IClearArea Subroutine
Description
Clear a screen area.

Syntax
IClearArea(ixtopl,iytopl,ixbotr,iybotr)

Arguments
INTEGER ixtopl = Top left column of area INTEGER iytopl = Top left row of area INTEGER ixbotr = Bottom right column of area INTEGER iybotr = Bottom right row of area

Effect
Clears an area, defined by the top left and bottom right co-ordinates (IXTOPL,IYTOPL) and (IXBOTR,IYBOTR), leaving the cursor at (IXTOPL,IYTOPL). The routine does nothing if the left X value is greater than the right X value, or if the top Y value is greater than the bottom Y value.

60

Lahey/INTERACTER Starter Kit

IClearScreen Subroutine
If the specified area extends beyond the current screen limits, the area co-ordinates are adjusted accordingly.

Errors
ErrBadClear (14): Invalid text co-ordinates. For example, IXTOPL is greater than IXBOTR or IYTOPL is greater than IYBOTR.

Example
DO IY=1,20 CALL IOutStringXY(1,IY,'*********************************') END DO CALL IClearArea(5,5,20,15)

IClearScreen Subroutine
Description
Clears the whole screen.

Syntax
IClearScreen()

Effect
Clears the screen, leaving the cursor at position (1,1).

Example
CALL IOutStringXY(1,20,'Press a key to continue') CALL InKeyEvent(KEY) CALL IClearScreen

Group AT: Text Attributes


Displayed text can be greatly enhanced using these text attribute control routines. These allow colors to be selected (where available) as well as supporting highlights such as underlining, bold text and so on. Both routines simply select the attribute to be used by any further text output. They have no immediate on-screen effect until other routines are called which display text. Non-color attributes are selected in combination by calling ITextAttribute. Foreground/ background color are set via ITextColourN.
IScreenOpen initializes all attributes to 'off' and text colors to white on black.

Lahey/INTERACTER Starter Kit

61

Chapter 11 Text Screen Output


Since the availability of text attributes varies from one type of display or screen mode to another, the InfoAttribute function is provided to identify which are supported. See the documentation under Group IF.

ITextAttribute Subroutine
Description
Set bold/flash/italics/reverse/underline combination.

Syntax
ITextAttribute(bfiru)

Arguments
CHARACTER bfiru upper or lower case: = A string containing any or none of the following characters in
B: F: I: R: U:

Select bold text Select flashing text Select italics Select reverse video Select underlining

Effect
Selects a combination of text attributes. Only those attributes indicated in the argument string will be enabled and the others will be disabled. All attributes are off at start-up. To disable all text attributes, call ITextAttribute with a blank argument. Text attribute support is display dependent. InfoAttribute reports the availability of each attribute. Selecting an unavailable attribute will have no effect.

Portability notes
Bold is supported on the PC in all modes except mono graphics modes. Enabling bold causes text to be displayed in a higher intensity. Thus if foreground and background text colors are the same and bold is enabled, text is still readable. On a color screen, the same effect can be achieved by specifying a bold color number to ITextColourN. Flashing text is only supported in monochrome text screen modes. Italics are not supported. Reverse video is supported in all modes. Underlining is supported in mono text screen mode 7 (available on the MDA, Hercules, EGA and VGA adapters) and in all graphics modes. On true monochrome displays (i.e., not gray scaled CGA or VGA mono screens) the foreground/background 'colors' can be exchanged by using the REVERSE initialization file keyword.

62

Lahey/INTERACTER Starter Kit

ITextColourN Subroutine
Example
CALL CALL CALL CALL ITextAttribute('BF') IOutStringXY(1,2,'Flashing/Bold') ITextAttribute(' ') IOutStringXY(1,4,'This is normal text')

ITextColourN Subroutine
Description
Select foreground/background text colors by number.

Syntax
ITextColourN(nfcolr,nbcolr)

Arguments
INTEGER nfcolr = Foreground text color number (see below) INTEGER nbcolr = Background text color number (see below)

Effect
Selects foreground and background text colors, by number. The color numbering scheme follows the same general order as graphics colors selected by IGrColourN. If only one color needs to be specified, the other color number should be set to -1. Colors 0-7 are 'normal intensity'. Colors 8-15 select equivalent bold/bright shades.

Lahey/INTERACTER Starter Kit

63

Chapter 11 Text Screen Output


Invalid color numbers are ignored, as are calls made in monochrome screen modes. Table 17: Text Colors
Name TextBlack TextRed TextYellow TextGreen TextCyan TextBlue TextMagenta TextWhite No. 0 1 2 3 4 5 6 7 Color Name TextBlackBold TextRedBold TextYellowBold TextGreenBold TextCyanBold TextBlueBold TextMagentaBold TextWhiteBold No. 8 9 10 11 12 13 14 15 Color

Black Red Yellow Green Cyan Blue Magenta Off-white

Dark gray Bold Red Bold Yellow Bold Green Bold Cyan Bold Blue Bold Magenta Bold White

In a graphics mode, the text palette is the same as the 16-color palette described under IGrColourN. Redefining the following graphics color numbers will therefore typically also redefine the corresponding text colors: Table 18: Redefining Graphcis and Text Colors
Color Black Red Yellow Green Cyan Blue Magenta Off-white Text Color # 0 1 2 3 4 5 6 7 Graphics Color # 0 47 79 111 143 175 207 239 Color Dark gray Bold Red Bold Yellow Bold Green Bold Cyan Bold Blue Bold Magenta Bold White Text Color # 8 9 10 11 12 13 14 15 Graphics Color # 240 31 63 95 127 159 191 223

64

Lahey/INTERACTER Starter Kit

Group CG: Character Graphics


Portability notes
A color screen adapter (CGA/MCGA/EGA/VGA) is required. Both foreground and background colors are selectable in all color screen modes. All 16 colors are available by default. If IScreenModeOptions(8,1) has been called (to enable flashing text), only 8 background colors are available in 16-color text modes on MCGA/EGA/VGA screens. The latter is also true of background colors on a CGA screen regardless of the state of screen mode option 8. Specifying a normal intensity color in combination with the 'bold' attribute (as set by ITextAttribute) has the same effect as specify a bold color directly.

Example
CALL CALL CALL CALL ITextColourN(5,7) IOutStringXY(1,3,' Blue text on a white background ') ITextColourN(1,-1) IOutStringXY(1,5,' Now red text, & & still on a white background') CALL ITextColourN(0,2) CALL IFrameTitleBox(8,8,73,20,'C', & 'Black frame/Yellow background')

Group CG: Character Graphics


The routines in this group are used by the fixed-field-input (IN), menu (MN) and text window (WN) routines, to draw frames around text areas. Unlike the high- resolution graphics facilities described in High Resolution Graphics on page 117, these routines are available in both text and graphics modes. Character graphics frames are drawn in one of two ways, depending on screen mode: 1) Box-character frames: Simple line drawing characters are used in text mode. 2) Graphical frames: In graphics mode, frames are drawn using graphics primitives, providing a more pleasing effect and a wider choice of frame types. Logically, these modes of operation are the same. In both cases, the height or width of a frame is considered to be equivalent to that of one text character. This is obviously true for boxdrawing characters, but graphical frames are designed to always lie within the same single character cell width/height. This ensures a consistent calling interface, regardless of the current frame drawing method.

IFrame Subroutine
Description
Print a frame round a screen area.
Lahey/INTERACTER Starter Kit

65

Chapter 11 Text Screen Output


Syntax
IFrame(ixleft,iytop,ixrght,iybot,action)

Arguments
INTEGER ixleft = Left column of box INTEGER iytop = Top row of box INTEGER ixrght = Right column of box INTEGER iybot = Bottom row of box CHARACTER action = String describing required action: = ' ' : leave frame contents unchanged = 'C' : clear frame contents (upper or lower case)

Effect
Draws a frame around an area of the screen defined by (IXLEFT,IYTOP) and (IXRGHT,IYBOT). The frame itself lies within the text columns/rows specified by the subroutine arguments. If action contains the letter C, the area inside the frame will be cleared, otherwise it will remain unchanged.
IFrame always draws a complete frame. If any of the arguments lie off-screen, he invalid corner co-ordinates of the frame are adjusted to fit within the screen area.

Example
CALL IFrame(10,10,40,12,'C') CALL ICursorXY(12,11) CALL IOutString('This is inside the frame')

IFrameOptions Subroutine
Description
Specify frame options (colors, etc.).

Syntax
IFrameOptions(noptn,ivalue)

Arguments
INTEGER noptn = Option number (see below) INTEGER ivalue = Option value (see below)

66

Lahey/INTERACTER Starter Kit

IFrameOptions Subroutine
Effect
Defines options to be applied when drawing text frames. Table 19: IFrameOptions Arguments
Symbolic Name

noptn

ivalue

Default

TitlePos

Frame title position (0=as IFrame, i.e., none 1=as IFrameTitle 2=as IFrameTitleBox) Title foreground color (see below) Title background color (see below) Primary border color (see below) Secondary border color

Varies

TitleForeCol TitleBackCol BorderCol BorderCol2

4 5 6 7

Bold white Blue -1 -1

Option 3 is updated automatically by IFrame, IFrameTitle and IFrameTitleBox to indicate the title position within the most recently drawn frame. This information is used by ISplitFrameV to determine the top of its vertical line when graphical frames are in use. If ISplitFrameV must be called for a frame which was called earlier with a different title position, option 3 allows this to be identified. Options 4/5 allow frame title colors to be controlled independently of the currently selected colors as set by ITextColourN. Color numbers are as for ITextColourN, i.e. 0-15 or -1 to use the current color. Titles are bold white on blue (15/4) by default. Options 6/7 control both box-character and graphical frames, on all color displays. They set the border colors independently of the currently selected colors as set by ITextColourN. Color numbers are as for ITextColourN, i.e. 0-15 or -1 to use the current color. The latter is the default, so frames use the colors most recently selected by ITextColourN. The 'primary' and 'secondary' border colors represent the foreground and background text colors when using box-character frames. In 3D graphical frames they control the color pairs used to create the 3D effect.

Example
CALL IFrameOption(4,9) CALL IFrameOption(5,0) CALL IFrameOption(6,10) CALL ITextColour('W','BLUE') CALL IWinOpenTitle(0,0,50,10,'Bold Red Title on Black b/g')

Lahey/INTERACTER Starter Kit

67

Chapter 11 Text Screen Output

IFrameTitle Subroutine
Description
Print a frame, with a title within top of frame.

Syntax
IFrameTitle(ixleft,iytop,ixrght,iybot,action,title)

Arguments
INTEGER ixleft = Left column of box INTEGER iytop = Top row of box INTEGER ixrght = Right column of box INTEGER iybot = Bottom row of box CHARACTER action lower case): = String describing required action (any combination in upper or = 'C' = 'W' = 'L' = 'R' : clear frame contents : wide title bar : Left justify title : Right justify title

CHARACTER title = Heading for top of frame

Effect
Prints a frame around an area of the screen, with a title string printed within the top of the frame. The title string can be printed at the left or right if required. By default it is centered. Strings which are too wide are truncated. Otherwise, as for IFrame. In modes which use box-character frames, the frame is drawn to either end of the title string and terminated with left/right 'tee' characters, by default. Optionally, a 'W' can be specified in the action argument for a wide title bar. This causes the title bar to extend across the full width of the frame in a manner which is more consistent with graphical frames (which always use a full frame-width title bar).

Example
CALL IFrameTitle(10,10,40,12,'CLW','Title in the Frame')

IFrameTitleBox Subroutine
Description
Print a frame, with a title in a box at top of frame.

68

Lahey/INTERACTER Starter Kit

IFrameType Subroutine
Syntax
IFrameTitleBox(ixleft,iytop,ixrght,iybot,action,title)

Arguments
INTEGER ixleft = Left column of box INTEGER iytop = Top row of box INTEGER ixrght = Right column of box INTEGER iybot = Bottom row of box CHARACTER action lower case): = String describing required action (any combination in upper or = 'C' = 'W' = 'L' = 'R' : clear frame contents : wide title bar : Left justify title : Right justify title

CHARACTER title = Heading for top of frame

Effect
Prints a frame around an area of the screen, with a title string printed at the top of the frame in a box of its own. The title string can be printed at the left or right if required. By default it is centered. Strings which are too wide are truncated. Otherwise, as for IFrame. Unlike IFrameTitle, the top frame edge, the title and the frame line under the title each occupy a separate text row. When 2D graphical frame styles are in use, the appearance of a frame drawn using IFrameTitleBox is similar to that drawn by IFrameTitle, except that there is more space around the title string. When 3D graphical frames are enabled, frames drawn via IFrameTitleBox look better than the IFrameTitle equivalents.

Example
CALL IFrameTitleBox(10,10,40,12,'CL','Title in a Box')

IFrameType Subroutine
Description
Select frame type.

Syntax
IFrameType(itype)
Lahey/INTERACTER Starter Kit

69

Chapter 11 Text Screen Output


Arguments
INTEGER itype = Frame type: Table 20: Frame Types
Name SingleLine1 DoubleLine1 SingleLine2 DropShadow Field3D1 Field3D2 Button3D1 Button3D2 Window3D1 Window3D2 No. 1 2 3 4 5 6 7 8 9 10 Description

Single line (#1) Double lines Single line (#2) Double lines (box-character frames) Drop shadow (graphical frames) 3D style best suited to field frames Same as (5) but thicker 3D style best suited to buttons Same as (7) but exchanged colors 3D style best suited to windows Same as (9) but thicker

Effect
Selects the frame type drawn by IFrame and the various other character graphics routines in this group. All INTERACTER routines which call the frame drawing routines internally (e.g., IWinOpen, IMenuVertic, InStringXYDef, etc.) will automatically use the selected frame type. The precise effect of calling this routine depends on the current frame drawing method:
(1) Box-character frames:

Single line frame characters are used by default (type 1). All odd numbered frame types use single line frame characters and even numbered frame types select double line frame characters.

70

Lahey/INTERACTER Starter Kit

IFrameType Subroutine
(2) Graphical frames:

All frame types are selectable on displays which draw graphical frames. The effect of selecting each type is as follows:
1

The frame is drawn at the outer edge of the single character-cell border area. If the area within the frame is cleared, then the border character area is also cleared. The same as frame type 1, but a second line is drawn part way into the border character area, giving a slightly more pleasing effect. The frame is drawn at the inner edge of the single character-width border area. Only the area within this frame line is cleared. This leaves all but one pixel of the frame border area visible. When used with a menu, the menu bar will thus extend to meet the frame border. The same as frame type 3 except that a drop shadow appears within the frame border area to the right and below the frame, in the same color as the frame. A 3D-effect frame is drawn at the inner edge of the single character-cell border area, using different colors for the top/left and bottom/right edges. This frame is well suited to input field frames. As for type 5 but slightly thicker. A 3D-effect frame is drawn at the inner edge of the single character-cell border area, as for type 5, plus a single-color/single-pixel border around the edge of the 3D effect. As for type 7 but the colors used for the 3D part of the frame are exchanged (the single pixel border color remains the same). A 3D-effect frame is drawn at the outer edge of the single character-cell border area, using different colors for the top/left and bottom/right edges. This frame is well suited to window and menu frames, leaving a slight space between the 3D effect border at characters printed at the edge of the window/menu.

6 7

10 As for type 9 but slightly thicker.

The colors used to print/draw the selected frame type are determined by the current text colors set by ITextColourN. Optionally, separate frame colors can be set via IFrameOptions(6/7,n).

Example
CALL IFrameType(2) CALL IWinOpen(0,0,40,10)

Lahey/INTERACTER Starter Kit

71

Chapter 11 Text Screen Output

ISplitFrameH Subroutine
Description
Split up a frame horizontally.

Syntax
ISplitFrameH(ixleft,iy,ixrght)

Arguments
INTEGER ixleft = Left hand end of line INTEGER iy = Row INTEGER ixrght = Right hand end of line

Effect
Prints a horizontal line from text co-ordinate (IXLEFT,IY) to (IXRGHT,IY). Where boxcharacters are used, a 'tee' is printed at either end of the line to split a frame drawn using IFrame, IFrameTitle or IFrameTitleBox.

Example
CALL CALL CALL CALL IFrame(10,10,70,20,' ') ISplitFrameH(10,15,70) IOutStringXY(30,12,'This is in the top half') IOutStringXY(30,17,'This is in the bottom half')

Group WN: Window Manager


This group provides a useful set of routines which allow text output to be restricted to certain areas of the screen. Several windows can be defined at once, though only one is selected at any one time. You 'open' windows using IWinOpen. The precise effect of opening a window is controlled by the IWinAction routine, which determines whether the area defined by the window is to be framed and/or cleared, and whether the pop-up feature is to be used. Every time you open a window, it becomes the 'currently selected window'. All the other windowing routines then operate on that window. Logically, windows are 'stacked' Last In First Out, though they need not physically lie on top of one another on screen. The most recently opened window is referred to as the 'top' window. Open and Close operations all apply to this top window only. All other operations apply to the currently selected window, which need not necessarily be the top one (though as explained above opening a new window makes that the 'current' window by default). IWinSelect can be used to select between the open windows. This is of most use when your windows have been laid out in a tiled (i.e., nonoverlapping) manner.

72

Lahey/INTERACTER Starter Kit

IWinAction Subroutine
Various operations re-select the top or current window: If IWinClose is called to close the top window, the window management system has no further knowledge of that window. The previously opened window (if any) becomes the top window. If IWinOpen is called again, the newly defined window becomes the 'current' and 'top' window. The position and attributes of the previous window are held in the stack. The previous window can be reselected as the current window by calling IWinSelect or as the top window by calling IWinClose. The maximum number of windows which can currently be managed is 20.

An important feature of the window management system is the 'pop-up' facility. This causes INTERACTER to copy the current screen contents before opening the window, enabling them to be restored later when it is closed. This enables windows to appear on screen rather like pieces of paper, which can be 'lifted' to reveal what was there before. Windows can even overlap in this case, so one window can be laid on top of another, on top of another and so on. As each one is closed, the contents of the one 'underneath' will reappear. This is particularly useful for instant 'help' windows, dialogue boxes, etc. The colors and attributes of all text output via the window management routines are determined by the most recent calls to the routines in the AT group.

IWinAction Subroutine
Description
Define action to be taken when opening a window.

Syntax
IWinAction(action)

Arguments
CHARACTER action = String describing action when opening a new window. If it contains any of the following characters (upper or lower case), the specified actions are taken: = 'F': Draw a frame round the window = 'B': Draw a frame round the window using IFrameTitleBox = 'C': Clear the window = 'P': Select 'pop-up' mode (i.e., Copy existing screen contents before opening window) = 'W': Wide titles in character graphics frames (graphical frame titles are always wide) = 'L': Left justify title = 'R': Right justify title
Lahey/INTERACTER Starter Kit

73

Chapter 11 Text Screen Output


Effect
Controls the action to be taken when IWinOpen or IWinOpenTitle opens a new window. The values set by a call to IWinAction remain in effect until another call to IWinAction. If action contains an 'F', windows will be framed using IFrame or IFrameTitle. Alternatively, specify a 'B' for a window with the title in a separate box, as drawn by IFrameTitleBox. The 'F' and 'B' options are mutually exclusive. If both are specified, 'F' takes priority.If a 'C' is specified, the window area will be cleared to the current background color or highlight. If 'pop-up' mode is selected, the screen area 'under' the window will be copied before opening the window, enabling the old window contents to be restored when it is closed. while 'popup' mode is enabled, the number of windows which can be opened is limited by the size of the internal buffer into which the old screen contents are copied. This buffer will hold the equivalent of 10000 characters of screen text. i.e., The total size (including frames) of all simultaneously open pop-up windows cannot exceed 10000 characters. To check the remaining space in this buffer, call InfoWindow. Specify a 'W' if your programs will run in text mode and full-window width title bars are required. Graphical frames always use full width titles. If 'W' is omitted from action, titles in character graphics frames are only as wide as their passed length. Using the 'W' option ensures consistency of behavior between screens which use each type of frame. The action codes L and R can be used to specify the position of titles supplied to IWinOpenTitle. By default titles are centered. The window management system derives much of its flexibility from this routine, since it also enables the window control facilities to be applied to text which is already on screen, by omitting C from the action argument. When the window system is initialized, frames are 'on', pop-up is 'off' , clearing is 'on' and all titles are wide.

Portability notes
Windows can pop-up over both text and graphics. To pop-up over graphics, relatively large amounts of screen data must be buffered. Normally, screen data is buffered to memory but see also the portability notes for the InPopUp routine.

Example
CALL IWinOpen(20,2,30,3) CALL IWinOutStringXY(2,2,'Cleared window with a frame') CALL IWinAction('pc') CALL IWinOpen(40,12,30,3) CALL IWinOutStringXY(2,2,'Pop-up window with no frame')

74

Lahey/INTERACTER Starter Kit

IWinClear Subroutine

IWinClear Subroutine
Description
Clear the whole of the currently selected window.

Syntax
IWinClear()

Effect
Clears the whole of the currently selected window. If a frame was requested for the window, this is left unaffected. The cursor is left at the top left corner of the window. The cleared window will be in color or reverse video if previously selected by ITextColourN or ITextAttribute.

Example
CALL IWinOpen(10,2,30,3) CALL IWinOutStringXY(1,1,'Here is some help info ...') CALL IWinOutStringXY(1,3,'Press SPACE to continue >') CALL InKeyEvent(Key) IF (Key.NE.ICHAR(' ')) THEN GO TO 10 END IF CALL IWinClear CALL IWinOutStringXY(1,1,'And here is some more help')

10

IWinClearArea Subroutine
Description
Clear an area of the currently selected window.

Syntax
IWinClearArea(ixtopl,iytopl,ixbotr,iybotr)

Arguments
INTEGER ixtopl = Top left window column of area to clear INTEGER iytopl = Top left window row of area to clear INTEGER ixbotr = Bottom right window column of area to clear INTEGER iybotr = Bottom right window row of area to clear
Lahey/INTERACTER Starter Kit

75

Chapter 11 Text Screen Output


Effect
Clears an area of the currently selected window, defined by the top left and bottom right window co-ordinates (IXTOPL,IYTOPL) and (IXBOTR,IYBOTR), leaving the cursor at (IXTOPL,IYTOPL). The cleared area will be in color or reverse video if previously selected by ITextColourN or ITextAttribute.

Example
CALL ITextColourN(7,5) NROW = 10 CALL IWinOpen(10,2,30,NROW) ! clear bottom half of window to cyan CALL ITextColourN(-1,4) CALL IWinClearArea(1,NROW/2+1,30,NROW)

IWinClose Subroutine
Description
Close top window & optionally restore screen.

Syntax
IWinClose(iconte)

Arguments
INTEGER iconte = Controls what happens to window contents:
0: Leave contents exactly as they are

other: Restore previous contents (if pop-up mode was on when the window was opened) or clear window.

Effect
Closes the top window, regardless of which window is currently selected for output. If popup mode was on when the window was first opened, the old screen contents can be restored as if the window had never been there. The next window down the stack (if any) now becomes the top window again. If the closed window was the current window, the top window also becomes the current window, otherwise the current window remains unchanged. If the current window is not the top window and it must be closed, all the windows 'above' it in the stack must also be closed.

76

Lahey/INTERACTER Starter Kit

IWinCursorXY Subroutine
Example
CALL IWinAction('PFC') CALL IWinOpen(10,2,30,3) CALL IWinOutStringXY(1,1,'Here is some help info ...') CALL IWinOutStringXY(1,3,'Press SPACE to continue >') CALL InKeyEvent(Key) IF (Key.NE.ICHAR(' ')) THEN GO TO 10 END IF CALL IWinClose(1)

10

IWinCursorXY Subroutine
Description
Position cursor within current window.

Syntax
IWinCursorXY(ix,iy)

Arguments
INTEGER ix = Column in current window INTEGER iy = Row in current window

Effect
Moves the cursor to the specified (x,y) position within the current window. Remember that in this context (1,1) is the top left corner of the window.

Example
CALL CALL CALL CALL CALL ICursorXY(5,5) IOutString('This is at (5,5)') IWinOpen(11,11,20,10) IWinCursorXY(5,5) IOutString('But this is at (15,15)')

IWinOpen Subroutine
Description
Open a new window.
Lahey/INTERACTER Starter Kit

77

Chapter 11 Text Screen Output


Syntax
IWinOpen(ixtopl,iytopl,iwidth,iheigh)

Arguments
INTEGER ixtopl = Top left column of window (= 0: center horizontally) INTEGER iytopl = Top left row of window (= 0: center vertically ) INTEGER iwidth = Width of window INTEGER center = Height of window

Effect
Opens a new window. This becomes both the top and the current window. The position of the previously opened window (if any) is not lost, so that window can be returned to when the current window is closed or reselected as the current window by calling IWinSelect. The precise action when opening the window is determined by a previous call to IWinAction: If a frame is required, it is drawn just outside the area specified, using IFrame. Hence, the actual screen area occupied by the window plus a frame will be one character larger on all sides. The frame style is determined by IFrameType and IFrameOptions. If pop-up mode has been selected, the contents of the area defined by this window (including any frame) will be copied into an internal buffer, so that they can be restored later by IWinClose. Windows can thus be overlaid on the screen rather like pieces of paper on a desk. If the window is to be cleared, this is done after a copy operation, to ensure that the original screen contents are correctly restored.

Selecting reverse video or a background color before calling IWinOpen (using ITextAttribute or ITextColourN) sets the initial color in which the window is printed/cleared. This is a useful technique for highlighting a newly opened window. A special feature of IWinOpen is that the window can be centered horizontally and/or vertically by specifying zero ixtopl and/or iytopl values. Similarly the window can be forced to appear at the far right or bottom of the screen by specifying a large ixtopl or iytopl value (e.g., 999), since the position of the window is automatically adjusted if it would lie wholly or partly off-screen. This is particularly useful when a program must be able to run on screens with differing dimensions. These positioning conventions are shared with the menu and input box routines in the MN/IN groups. As an alternative, windows can also be opened with a title using IWinOpenTitle.

78

Lahey/INTERACTER Starter Kit

IWinOpenTitle Subroutine
Errors
ErrMaxWindow (7): Maximum number of windows exceeded ErrWinBuffer (8): Window buffer space exceeded ErrWinCoOrds (9): Invalid window co-ordinates (e.g., negative width/height)

Example
CALL ITextColourN(7,5) CALL IWinAction('FCP') CALL IWinOpen(0,0,30,3) CALL IWinOutStringXY(1,1,'Here is some help info ...') CALL IWinOutStringXY(1,3,'Press SPACE to continue >') CALL InKeyEvent(Key) IF (Key.NE.ICHAR(' ')) THEN GO TO 10 END IF CALL IWinClose(1)

10

IWinOpenTitle Subroutine
Description
Open a new window with a title.

Syntax
IWinOpenTitle(ixtopl,iytopl,iwidth,iheigh,title)

Arguments
INTEGER ixtopl = Top left column of window (= 0: center horizontally) INTEGER iytopl = Top left row of window (= 0: center vertically ) INTEGER iwidth = Width of window INTEGER iheigh = Height of window CHARACTER title = Window heading

Effect
Opens a new window, with a title. The title will be printed within the top of the window frame, using IFrameTitle, if frames are currently selected. If frames have been disabled no title is printed. In all other respects this is exactly the same as IWinOpen (in fact, IWinOpenTitle is simply an alternative entry point to the IWinOpen routine). The position of the title (centered or left/right justified) can be specified using IWinAction. By default, titles are centered.
Lahey/INTERACTER Starter Kit

79

Chapter 11 Text Screen Output


Errors
ErrMaxWindow (7): Maximum number of windows exceeded ErrWinBuffer (8): Window buffer space exceeded ErrWinCoOrds (9): Invalid window co-ordinates (e.g., negative width/height)

Example
CALL IWinOpenTitle(10,2,30,3,'Help') CALL IWinOutStringXY(1,1,'Here is some help info ...')

IWinOutString Subroutine
Description
Output string at current window cursor position.

Syntax
IWinOutString(string)

Arguments
CHARACTER string = String to write out

Effect
Outputs the supplied string to the current window, at the current window cursor position. This is the window management equivalent of IOutString. If the text would extend beyond the right-hand column of the window the text is wrapped onto the next line. Text which would appear beyond the bottom of the window is not displayed. By default, text is written in the current colors/attributes as set by the routines in the AT group.

Example
CALL IWinOpen(20,10,40,10) CALL IWinOutStringXY(2,3,'Here is some text ...') CALL IWinOutString(' and this follows it.')

IWinOutStringXY Subroutine
Description
Output string at a specific window position.

80

Lahey/INTERACTER Starter Kit

IWinSelect Subroutine
Syntax
IWinOutStringXY(ix,iy,string)

Arguments
INTEGER ix = Column in current window INTEGER iy = Row in current window CHARACTER string = String to write out

Effect
Outputs the supplied string to the current window, starting at the specified window co-ordinate. This is the window management equivalent of IOutStringXY. If the text would extend beyond the right-hand column of the window the text is wrapped onto the next line. Text which would appear beyond the bottom of the window is not displayed. By default, text is written in the current colors/attributes as set by the routines in the AT group.

Example
CALL IWinOpen(20,10,40,11) CALL IWinOutStringXY(1,5, & 'This should appear halfway down the window')

IWinSelect Subroutine
Description
Select current window by number.

Syntax
IWinSelect(number)

Arguments
INTEGER number = Number of window to be selected rently open windows) (1<= number <= number of cur-

Effect
Selects the 'current' window by number. All window operations, with the exception of Open/ Close, will apply to the specified window.
Lahey/INTERACTER Starter Kit

81

Chapter 11 Text Screen Output


Whenever a window is opened, it is assigned a number corresponding to its position in the window 'stack'. The first window to be opened is thus number 1. If a second window is opened without closing the first that becomes number 2 and so on. Any window can be selected for output. By default, IWinOpen resets the 'current' window to the 'top' window. If an invalid window number is specified, the current window selection remains unchanged.
InfoWindow can be called to check how many windows have been opened (i.e., the number

of the 'top' window) and also the number of the 'current' window.

Example
CALL CALL CALL CALL CALL CALL CALL IScreenInit(' ') IWinOpen(2,2,78,8) IWinOpen(2,12,78,8) IWinSelect(1) IWinOutStringXY(5,2,'This is in window 1') IWinSelect(2) IWinOutStringXY(5,2,'This is in window 2')

82

Lahey/INTERACTER Starter Kit

12 Input Handling

Group KM: Keyboard/Mouse Event Handling


The routines in this group provide the most basic keyboard and mouse input event handling functions. In particular, InKeyEvent performs single key input and can also be used to report other input events such as those generated by a mouse, where available. InKeyEvent is able to read a keystroke without waiting for Return/Enter to be pressed and is able to identify non-printing (e.g., function) keys in a keyboard independent manner. The alternative routine InKeyEventImm performs exactly the same task, but in a non-blocking manner, i.e., it returns immediately if no keyboard or mouse events are waiting. InKeyEventCursor also performs the same task as InKeyEvent and simulates a cursor on displays with no hardware text cursor support. While InKeyEvent always reports keyboard events, the reporting of other events can be selectively enabled or disabled using InEventSelect. For keyboard debugging purposes, direct access to system dependent keyboard codes is also provided by means of the lower level InCharacter.

InCharacter Subroutine
Description
Get single character from keyboard (wait for key press).

Syntax
InCharacter(ichr)

Arguments
INTEGER ichr = ASCII code returned from keyboard
Lahey/INTERACTER Starter Kit

83

Chapter 12

Input Handling
Effect
Gets a single character from the keyboard queue. This routine will not return until a key has been pressed. When a normal printable ASCII character key (i.e., Space through tilde) is pressed, InCharacter returns a 7-bit integer ASCII code (i.e., 32-126). If a non-printing key is pressed, such keys often generate multi-byte sequences consisting of system/keyboard dependent codes. In this case these codes will be returned sequentially in consecutive calls to InCharacter.
InCharacter should be viewed as providing 'raw' keyboard input. As such, it fails to identify function/keypad/cursor keys in a meaningful way. InCharacter should not normally be used, except for debugging/diagnostic purposes, when it may prove useful to identify the precise low-level codes being generated by the keyboard. Otherwise, InKeyEvent should be used instead.

Portability notes
Keyboard input is via DOS interrupts. Where a standard ASCII key is detected, InCharacter only returns the ASCII code. If an extended key code is detected, two codes are returned in consecutive calls to InCharacter. 8-bit keycodes entered using Alt/keypad will be returned unmodified.

InEventSelect Subroutine
Description
Select events to be reported via InKeyEvent/InKeyEventImm.

Syntax
InEventSelect(nevent,iemask)

84

Lahey/INTERACTER Starter Kit

InEventSelect Subroutine
Arguments
INTEGER nevent = Event types to enable/disable: Table 21: nevent values
Name AllEvents ButtonDown ButtonUp MouseMoveText MouseMoveGraph ResizeExpose No. 0 1 2 3 4 6 Description

All events at once Mouse button-down events Mouse button-up events Mouse movement events (text) Mouse movement events (graphics) Graphics window expose/resize events

INTEGER iemask = Event mask for all events or one event: If nevent > 0 then iemask =: Table 22: iemask values (nevent > 0)
Name IntNo IntYes No. 0 1 Description

Disable event specified by nevent Enable event specified by nevent

If nevent = 0 then iemask = sum of: 1 : enable mouse button down events +2 : enable mouse button up events +4 : enable mouse movement events (text) +8 : enable mouse movement events (graphics) +32 : enable graphics window expose/resize events

Effect
Specifies the non-keyboard events which will be reported by InKeyEvent. Multiple events can be enabled and disabled in combination, in a single call by specifying nevent=0 and summing the relevant event mask values in iemask. Alternatively, single events can be switched on or off by specifying the appropriate event number in nevent and passing a binary flag in iemask.
Lahey/INTERACTER Starter Kit

85

Chapter 12

Input Handling
When reporting of any of the listed events is activated InKeyEvent returns special codes when the requested events occur. For mouse events, the position of the mouse cursor is then available via InfoInput and/or InfoGraphics. Two demonstration programs on the distribution media (doodlet and doodleg) show how event selection can be used to perform low level mouse handling. Only mouse button-down and expose/resize events are reported by default. Button-up and movement events should only be activated while they are required and disabled as soon as they are no longer needed. The fixed field input and menu routines all disable button-up and movement events internally then restore the current event selection on exit. Mouse movement events can either be selected as 'text' or 'graphics' movement: Text mouse movement events are available in both text and graphics screen modes and occur when the mouse crosses a text cell boundary. Graphics mouse movement events are available in graphics screen mode only and occur when the mouse moves to a new pixel position.

Both movement event types can be selected if required, though it will be more usual to only select one or other. Both types of movement event generate an InKeyEvent code of 257. To be able to detect mouse events, a mouse must be available (i.e., InfoHardware(13)>1). Event type 6 (graphics window expose/resize) can be used in a windowing environment, in the full version of INTERACTER, to identify when the graphics window needs to be redrawn. This event will never occur in the DOS version. The current event mask (equivalent to the value which would be passed in iemask when nevent=0) is available via InfoInput(66).

Example
See DOODLET and DOODLEG demos on distribution media

InKeyEvent Subroutine
Description
Get single key/mouse event, including function/keypad/cursor keys.

Syntax
InKeyEvent(icode)

86

Lahey/INTERACTER Starter Kit

InKeyEvent Subroutine
Arguments
INTEGER, OPTIONAL icode = Keyboard or mouse event code:
32-126: 7-bit ASCII chars 384-511: 8-bit keyboard code (i.e., 256 + key code) 560-569: Alt/0 to Alt/9 577-602: Alt/A to Alt/Z

or one of the specially assigned codes listed below: Table 23: icode values
Name KeyBackSpace KeyTab KeyReturn KeyEscape KeyDelete KeyCursorUp KeyCursorDown KeyCursorRight KeyCursorLeft KeyPageUp KeyPageDown KeyPageRight KeyPageLeft KeyUpExtreme KeyDownExtreme

icode
8

Key

Name KeyShiftTab KeyDeleteUnder Keypad0 Keypad1 Keypad2 Keypad3 Keypad4

icode
144

Key

Backspace Tab Return Escape Delete left Cursor up Cursor down Cursor right Cursor left Page up Page down Page right Page left Extreme up Extreme down

Shift/Tab Delete under cursor Keypad 0 Keypad 1 Keypad 2 Keypad 3 Keypad 4 Keypad 5 Keypad 6 Keypad 7 Keypad 8 Keypad 9 Keypad Keypad . Keypad +

9 13 27 127 128 129

143 150 151 152 153 154

130

Keypad5

155

131 132 133 134 135 136

Keypad6 Keypad7 Keypad8 Keypad9 KeypadMinus KeypadPoint

156 157 158 159 160 161

137

KeypadPlus

162

Lahey/INTERACTER Starter Kit

87

Chapter 12

Input Handling
Table 23: icode values
Name KeyRightExtreme KeyLeftExtreme KeyHome KeyEnd KeyInsert

icode
138

Key

Name KeypadDivide KeypadMultiply KeypadHash KeypadEnter KeyPrint

icode
163

Key

Extreme right Extreme left Home End Insert

Keypad / Keypad * Keypad # Keypad enter Print

139 140 141 142

164 165 166 170

Table 24: icode values


Name KeyF1 - KeyF20 KeyShiftF1 - KeyShiftF20 KeyCtrlF1 - KeyCtrlF20 KeyAltF1 - KeyAltF20 LeftButtonDown MiddleButtonDown RightButtonDown LeftButtonUp MiddleButtonUp RightButtonUp MouseMove ResizeEvent KeyAltBackspace

icode
171 - 190 191 - 210 211 - 230 231-250 251 252 253 254 255 256 257 259 520

Key(s)

F1 - F20 Shift/F1 - Shift/F20 Ctrl/F1 - Ctrl/F20 Alt/F1 - Alt/F20 Left mouse button down Middle mouse button down Right mouse button down Left mouse buttonup Middle mouse button up Right mouse button up Mouse moved Graphics window exposed/ resized Alt/Backspace

88

Lahey/INTERACTER Starter Kit

InKeyEvent Subroutine
Table 24: icode values
Name KeyAltTab KeyAltReturn KeyAltEscape

icode
521 525 539

Key(s)

Alt/Tab Alt/Return Alt/Escape

Effect
Gets the next event from the input queue. Keystroke events are always reported, providing portability to all display types. Mouse button-down events are also reported by default, where a mouse is known to be available. Other mouse events can optionally be reported, under the control of the InEventSelect routine. At its simplest level, InKeyEvent is a single key input routine, performing the same function as InCharacter except also uniquely identifying cursor, keypad, function and editing keys. Its additional ability to report mouse button/movement events makes it suitable for low level input handling on a wide variety of displays from dumb terminals to mouse driven windowing environments. InKeyEvent is recommended as the lowest level of keyboard and mouse handling which should be used. Ordinary printable keyboard characters are returned as 7-bit ASCII codes, i.e., as values in the range 32-126. Many keyboards are also able to generate system dependent 8-bit characters (e.g., to generate international characters). Since these key codes are in the range 128255, they conflict with INTERACTER's system independent codes allocated for function/cursor/keypad keys. InKeyEvent thus adds 256 to 8-bit keyboard codes to differentiate them from the non-ASCII control keys. Given the considerable variability in type of keyboard supported by the full version of INTERACTER, InKeyEvent attempts to standardize the key codes which are returned for non-printable keys. The table describes the key code assignments by function for an 'ideal' keyboard. Keyboard Codes on page 41 lists the actual keys which are recognized on PC keyboards. Some keyboards support keypad identification, but lack other dedicated special keys. The original ('standard') 83-key IBM PC keyboard does not have separate cursor keys. For the sake of such keyboards, INTERACTER supports two different modes of keypad interpretation numbered 2 and 3. Mode 2 is designated as 'special key substitution' mode which causes the keypad to return the same codes as the cursor keys, Page Up/Down, etc. For example, codes 128-135 etc. In keypad mode 3, the keypad keys return the codes listed in the table, i.e., 150-166. Refer to the InKeypad routine in the IP group for more information on keypad interpretation selection. Keyboard Codes on page 41 also gives more details. Where mouse input is available, InKeyEvent can also detect mouse events. The precise combination of events to be reported is controlled by the InEventSelect routine. By default, mouse-button down events are reported but button-up and mouse movement events
Lahey/INTERACTER Starter Kit

89

Chapter 12

Input Handling
are not. If a mouse event is reported, the position of the mouse when the event occurred is available via InfoInput(62)/(63). In graphics modes, the position may alternatively be available in graphics co-ordinates via InfoGraphics(5)/(6). A time stamp is also normally available for such mouse events, via InfoInput(70). In addition to keyboard and mouse events, InKeyEvent can also report when the graphics window needs to be redrawn in a windowing environment (icode = 259). This event code will never be reported in the DOS version.

Portability notes
See Keyboard Codes on page 41 for details of version/keyboard-specific keycodes.

Example
CALL IOutStringXY(5,20,'Use cursor & & keys/RETURN to select option') 10 CALL IOutStringXY(5,10+IOPT,'-->') CALL InKeyEvent(ICODE) IY = 10 + IOPT CALL IClearArea(5,10+IY,7,IY) IF (ICODE==128.AND.IOPT>1) THEN IOPT = IOPT - 1 END IF IF (ICODE==129.AND.IOPT<5) THEN IOPT = IOPT + 1 END IF IF (ICODE/=13) THEN GO TO 10 END IF

InKeyEventCursor Subroutine
Description
As InKeyEvent but also simulate a text cursor.

Syntax
InKeyEventCursor(icode)

Arguments
INTEGER, OPTIONAL icode = Keyboard or mouse event code (See InKeyEvent)

90

Lahey/INTERACTER Starter Kit

InKeyEventImm Subroutine
Effect
InKeyEventCursor performs the same function as InKeyEvent except that it will also dis-

play and remove a simulated text cursor on certain displays (see Portability notes). This is useful as a functional replacement for InKeyEvent in routines which perform low level text entry on screens where no cursor is visible. This routine is used internally by the fixed field input routines in the IN group. On displays which support a hardware text cursor, calling InKeyEventCursor is exactly equivalent to calling InKeyEvent.

Portability notes
A cursor is simulated in DOS graphics modes.

Example
CHARACTER (LEN=10) :: NAME CALL IOutStringXY(2,2,'Enter name: ') IPOS = 1 CALL InKeyEventCursor(ICODE) IF (ICODE>=32.AND.ICODE<=126) THEN NAME(IPOS:IPOS) = CHAR(ICODE) CALL IOutString(CHAR(ICODE)) GO TO 10 ELSE ...

10

InKeyEventImm Subroutine
Description
As InKeyEvent but immediate return if no event waiting.

Syntax
InKeyEventImm(icode)

Arguments
INTEGER, OPTIONAL icode = Keyboard or event code (See InKeyEvent) (-999 if no key currently available)

Effect
This performs the same function as InKeyEvent except that it will return immediately with a special code of -999 if no key or mouse event is waiting. Otherwise, the function and operation of this routine is exactly as for InKeyEvent, so refer to that routine for more information.
Lahey/INTERACTER Starter Kit

91

Chapter 12

Input Handling
Example
CALL IOutStringXY(1,2,'Press a function key at') CALL IOutStringXY(1,3,'any time to halt execution') 10 CALL UPDATE CALL InKeyEventImm(ICODE) IF (ICODE<170.OR.ICODE>250) THEN GO TO 10 END IF

Group IN: Fixed Field Input Handling


These routines are built on the lower level single key input facilities in the KM group. They provide a controlled substitute for the Fortran READ statement, preventing the user from typing outside a specified on-screen field. InString reads character data at the current cursor position. A more powerful variant of this routine, InStringDef, enables a default value to be presented to the user which can either be changed or accepted without modification. The two fixed field input routines described above both take input from the current cursor position. Two complementary routines offer the facility to specify the cursor position and whether a prompt and/or frame are required. These are InStringXY and InStringXYDef. A pop-up feature is also supported by the latter routines (see InPopup in the IP group). Frame styles are determined by IFrameType and IFrameOptions in the CG group.
InStringXY and InStringXYDef automatically adjust the on-screen position of the input

field/box if it would otherwise lie partly or wholly off screen. Similarly, these routines offer the ability to center the input field either horizontally or vertically in the same manner as the menu (MN) and window opening routines. These features are not offered by the equivalent input-at-cursor routines. All of the routines in this group activate the text cursor and restore it to its previous state on exit. Similarly, all routines in this group activate the mouse cursor (where available) on entry and restore it to its previous state on exit. The mouse can be used to move the text input cursor within the field by clicking on the required position. The mouse can optionally be used to exit from a fixed field input routine by clicking outside of the field (with any button) or inside the field (with the right button). The latter two features are controlled by InMouseOptions in the IP group. Editing control keys are selectable using InControlKey, which is described in the IP section later in this chapter.

92

Lahey/INTERACTER Starter Kit

InString Subroutine

InString Subroutine
Description
Get fixed length string (no default offered).

Syntax
InString(string,length)

Arguments
CHARACTER string = String entered by the user INTEGER, OPTIONAL length = Actual length of string entered by user, including trailing blanks

Effect
Fixed-field string input routine, providing a controlled replacement for the Fortran READ statement. The user is not allowed to enter a response longer than the receiving variable string. The actual length of the entered string (including trailing spaces) is returned in length which must therefore be a variable. A number of control keys are available, which can be redefined using the InControlKey routine or the initialization file. See the documentation for InControlKey for a complete list of the supported input control keys. Any control keys entered which are not among those currently selected, are trapped and ignored. The text cursor can be repositioned within the field using a mouse, where available. In addition to the standard 'confirm' key (which will usually be Return/Enter) all the other 'exit' keys can be used to tab to another field, ask for help or quit entering the value. The precise exit key which was used can be checked by calling InfoInput(55) (see group IF). InString will also exit when a mouse button is pressed outside of the input field. In this case, InfoInput(55) will return a control key of -2. The mouse button number and position will then be available via InfoInput(61-63) and/or InfoGraphics(5)/(6). To offer a default value, see the equivalent InStringDef routine.

Portability notes:
In graphics screen modes there is no hardware text cursor, so a cursor is simulated via InKeyEventCursor. This is removed automatically on exit.
Lahey/INTERACTER Starter Kit

93

Chapter 12

Input Handling
Example
CHARACTER (LEN=12) :: FILNAM CALL IOutStringXY(1,5,'Enter filename (max 8 characters):') CALL InString(FILNAM(:8),LENGTH) IF (LENGTH>0) THEN OPEN(20,FILE=FILNAM(:LENGTH),STATUS='OLD') END IF

InStringDef Subroutine
Description
Get fixed length string, offering a default.

Syntax
InStringDef(string,length)

Arguments
CHARACTER string = On entry, contains default response string. = On exit, contains final response string INTEGER, OPTIONAL length = On exit, contains the length of the string entered by user, including any typed trailing blanks

Effect
Fixed field string input routine, with a default reply supplied to save the user typing a full response (e.g., a standard filename). In all other respects, this routine is equivalent to InString. The default response string is displayed at the current cursor position. The cursor is placed at the beginning of the response. The user can then modify the response by typing over it and/ or clearing parts of it. Any of the 'exit' keys can be pressed to terminate input. By default (i.e., if the user types nothing at all) length is returned as the length of string excluding any trailing spaces. However, if the user types beyond the last non-blank character of the supplied string, length is returned accordingly including any trailing spaces which the user may explicitly type at the end of the string.

Portability notes
See InString

94

Lahey/INTERACTER Starter Kit

InStringXY Subroutine
Example
CHARACTER (LEN=8) :: FILNAM 100 CALL IOutStringXY(1,5,'Enter filename & & (max 8 characters):') FILNAM = 'MYDATA' CALL InStringDef(FILNAM,LENGTH) KEXIT = InfoInput(55) IF (KEXIT==21) THEN IF (LENGTH>0) THEN OPEN(LFN,FILE=FILNAM(:LENGTH),STATUS='OLD') ELSE GO TO 100 END IF ELSE IF (KEXIT==23) THEN CALL HELP GO TO 100 ELSE IF (KEXIT==24) THEN ! .. move to next field .. ELSE IF (KEXIT==25) THEN ! .. move to previous field ELSE CALL IScreenClose END IF

InStringXY Subroutine
Description
Get string at an (x,y) position (no default offered).

Syntax
InStringXY(ixpos,iypos,prompt,iframe,string,length)

Arguments
INTEGER ixpos = Column at which field is to be displayed (zero to center field horizontally) INTEGER iypos = Row on which field is to be displayed (zero to center field vertically) CHARACTER prompt = Optional prompt string (None used if blank) INTEGER iframe = 0: No frame drawn = 1: Frame round field, prompt to left (if specified) = 2: Frame round field, prompt above (if specified)

CHARACTER string = String entered by the user


Lahey/INTERACTER Starter Kit

95

Chapter 12

Input Handling
INTEGER, OPTIONAL length = Actual length of string entered by user, including trailing blanks

Effect
Fixed-field string input routine. This is directly equivalent to calling InString except that position, prompt and frame can all be specified, and the input field can be made to pop up. The pop-up mode is selectable by calling InPopup and the appearance of the input field is controlled by InHighlight. The text and mouse cursors are automatically enabled for the duration of the call and restored to their previous state on exit.

Portability notes
See InString

Example
CHARACTER (LEN=8) :: USERID CALL InHighlight('W','BLUE') CALL InStringXY(5,5,'Enter i.d. ',0,USERID,LENGTH)

InStringXYDef Subroutine
Description
Get string at an (x,y) position, offering a default.

Syntax
InStringXYDef(ixpos,iypos,prompt,iframe,string,length)

Arguments
INTEGER ixpos = Column at which field is to be displayed (zero to center field horizontally) INTEGER iypos = Row on which field is to be displayed (zero to center field vertically) CHARACTER prompt = Optional prompt string (None used if blank) INTEGER iframe = 0: No frame drawn = 1: Frame round field, prompt to left (if specified) = 2: Frame round field, prompt above (if specified) = On entry, contains default response string. = On exit, contains final response string.

CHARACTER string

INTEGER, OPTIONAL length = On exit, contains the length of the string entered by user, including any typed trailing blanks

96

Lahey/INTERACTER Starter Kit

Group MN: Menu Handling


Effect
Fixed-field string input routine, with a default reply supplied. This is directly equivalent to calling InStringDef except that position, prompt and frame can all be specified, and the input field can be made to pop up. The pop-up mode is selectable by calling InPopup and the appearance of the input field is controlled by InHighlight. The text and mouse cursors are automatically enabled for the duration of the call and restored to their previous state on exit.

Portability notes
See InString

Example
CHARACTER (LEN=20) :: FILNAM FILNAM = 'datafile.dat' CALL InStringXYDef(5,5,'Filename: ',1,FILNAM,LENGTH)

Group MN: Menu Handling


Menus can be presented in either horizontal or vertical layouts. Both routines in this group display a menu and then get a choice from the user. Choices are made by means of a simple to use pointer/highlight method. A highlight bar is moved using the cursor keys and/or space bar and the Return key is pressed to select. For the more familiar user a single-key selection facility is also available to speed option selection. Control keys can also be redefined if preferred, using InControlKey in the IP group or by an initialization file keyword. All menu input functions in this group activate the mouse cursor (where available) on entry and restore it to its previous state on exit. The mouse can be used to select menu options. The mouse can also be used to exit from a menu function by selecting a position outside of the menu, though this feature can be disabled via InMouseOptions in the IP group. Similarly, the 'feel' of mouse input via the menu routines is also controllable via InMouseOptions(3,n). By default, a Windows-like mechanism is used. The menus presented by the routines in this MN group can be made to 'pop up'. This means that the menu can be displayed, a selection made and the previous screen contents restored with no special action by the calling program other than enabling 'pop up' mode (see the InPopup routine in the IP group). This feature can be extended using the 'linked pop-up' mode to create menu chains which are only closed when the last sub-menu item is selected. Linked mode is also selectable via InPopup. All menus are displayed using the text attributes most recently selected by the routines in the AT group. Also, the means by which a currently selectable item is highlighted can be determined using InHighlight. This defines the preferred highlighting method, but
Lahey/INTERACTER Starter Kit

97

Chapter 12

Input Handling
INTERACTER will adapt the actual highlight used depending on the display hardware in use. This is a very useful portability aid. Whatever highlight is used to display a selectable menu option, the current text attributes selected by the AT routines are undisturbed on exit from an MN routine. Frame/border styles are determined by the IFrameType and IFrameOptions routines in the CG group. Where a menu displayed by one of the MN functions would lie partly or wholly off-screen, its position is adjusted to fit on screen. Where a menu is too large to fit on screen, no such adjustment is made. The menu functions offer the ability to center the menu either horizontally or vertically in the same manner as the input box and window opening routines.

IMenuHoriz Function
Description
Horizontal pointer/highlight menu.

Syntax
IMenuHoriz(option,maxopt,ixpos,iypos,iwidth,ibordr,istopt)

Arguments
CHARACTER option (:) = Array of option names INTEGER maxopt = Number of options in option array INTEGER ixpos = Left hand column of menu (zero to center the menu horizontally) INTEGER iypos = Top row of menu (zero to center the menu vertically) INTEGER iwidth = Width of menu INTEGER ibordr = 1: Print a line above menu only = 2: Print a line below menu only = 3: Print lines above and below menu = 4: Print a frame around the menu = any other value for no border

INTEGER istopt = First option to be highlighted (1 to maxopt - defaults to 1 if outside this range. If negative don't redraw menu - see below)

Returns
An INTEGER with the option number chosen

98

Lahey/INTERACTER Starter Kit

IMenuHoriz Function
Effect
Presents a horizontal (possibly multi-line) pointer/highlight menu described in the array option and gets a selection from the user. It returns the option number which has been chosen by simply pointing to the required menu item. All the available options can be displayed at one time. Options are displayed across multiple lines, such that the menu occupies the specified screen width starting at the specified column. If iwidth is too wide to fit on the screen, the menu width is reduced accordingly. The user selects an item from the menu in one of the following ways: Using the cursor keys or 'next-item' key to move a highlight to the required option, then pressing the 'confirm' key. The 'next-item' and 'confirm' keys are as defined by InControlKey or the initialization file (usually Space and Return). The user may also select an option directly by pressing the initial letter of that option. Alt and an initial letter can also be used, provided that this key combination has not been defined as an exit key. Hence, X and Alt/X would normally be equivalent. If mouse input is enabled (see InEventSelect) a mouse cursor is enabled which can be used to select a menu option. This returns an InfoInput(55) exit key code of 21 as though the 'confirm' key had been pressed. The calling program can thus check for an exit key code of 21 regardless of whether a mouse is available or not. IMenuHoriz will exit with an InfoInput(55) value of -2 if a mouse button is clicked outside the menu. A button release outside the menu normally has the same effect. (See also InEventSelect and InMouseOptions)..

In addition to the 'confirm' key, tab/back-tab/help/quit keys can also be used to exit from the menu. Again these keys are as defined by InControlKey or the initialization file. The actual exit key which was pressed can be checked by a call to InfoInput(55). It is the responsibility of the calling program to decide whether to allow the use of these exit keys and to take appropriate action if they are used instead of the usual confirm key. Another exit code which may prove useful is InfoInput(61). This identifies whether a mouse button was used to exit from the menu and if so which one. This is always set to zero if a keyboard key is used to exit from the menu, but returns the mouse button number otherwise. When used in combination with InfoInput(55) and InfoInput(62)/(63) (the mouse position) this mechanism allows button dependent exit processing to be performed. The first option to be highlighted is specified by istopt. As an extension to this feature, istopt can be specified as a negative value, in which case the following is assumed:
IABS(istopt) specifies the option to be highlighted.

The menu is assumed to already be on the screen and will not be redrawn. This is useful to avoid unnecessary menu 'repainting'. In this case IABS(istopt) must specify the same option as was returned by the call to IMenuHoriz which printed the menu previously.
Lahey/INTERACTER Starter Kit

99

Chapter 12

Input Handling
The menu is displayed according to the current text styles set by ITextAttribute and ITextColourN. The way in which the current option is highlighted can be controlled using the InHighlight routine. A pop-up feature is also available controlled by InPopup. The text cursor is automatically disabled for the duration of the menu. If a border is requested, this is located outside the area specifed by the function parameters. For example, if you ask for a frame, the top left corner of the frame will thus be at (ixpos1,iypos-1), since the frame occupies 1 row and column. If only a line above the menu were requested, it would start at (ixpos,iypos-1) and so on. Options which start with a hyphen ('-') are displayed, but non-selectable. This enables options to be temporarily disabled without changing the order or relative position of other menu options. In other words, any option which starts with a dash (e.g., '----') will appear in the menu but the user will not be able to place the highlight bar on that line or select the option using its initial letter or the mouse.

Errors
ErrMenuOpt (19): All options start with '-'. At least one menu item must start with a character other than '-'. IMenuHoriz is returned as 0 in this situation.

Example
CHARACTER (LEN=4) :: OPTION(4) = & (/'Help','Run ','Edit','Quit'/) LOGICAL :: LOADED IXPOS = 21 IYPOS = 2 IWIDTH = 40 IBORDR = 4 CALL InHighlight(' ',' ') IF (.NOT.LOADED) THEN OPTION(2) = '---' END IF IOPT = IMenuHoriz(OPTION,4,IXPOS,IYPOS,IWIDTH,IBORDR,1)

IMenuVertic Function
Description
Vertical pointer/highlight menu.

Syntax
IMenuVertic(option,maxopt,ixpos,iypos,title,ispace,iframe,istopt)

100

Lahey/INTERACTER Starter Kit

IMenuVertic Function
Arguments
CHARACTER option (:) = Array of option names INTEGER maxopt = Number of options in option array INTEGER ixpos = Left column of menu (zero to center the menu horizontally) INTEGER iypos = Top row of menu (zero to center the menu vertically) CHARACTER title = Menu heading (blank for no heading) INTEGER ispace = Menu line spacing (0=no spacing, 1=one line, etc.) INTEGER iframe = 0: for no frame to be drawn = 1: draw a frame, placing title within top of frame if title is nonblank > 1: draw a frame, placing title in a box at top of frame if title is non-blank

INTEGER istopt = First option to be highlighted (1 to maxopt defaults to 1 if outside this range. If negative don't redraw menu - see below)

Returns
An INTEGER with the option number chosen

Effect
Presents a vertical pointer/highlight menu described in the array option and gets a selection from the user. It returns the option number which has been chosen by simply pointing to the required menu item. The user selects an item from the menu in one of the following ways: Using the cursor keys or 'next-item' key to move a highlight to the required option, then pressing the 'confirm' key. The 'next-item' and 'confirm' keys are as defined by InControlKey or the initialization file (usually Space and Return). The user may also select an option directly by pressing the initial letter of that option. Alt and an initial letter can also be used, provided that this key combination has not been defined as an exit key. Hence, X and Alt/X would normally be equivalent. If mouse input is enabled (see InEventSelect) a mouse cursor is enabled which can be used to select a menu option. This returns an InfoInput(55) exit key code of 21 as though the 'confirm' key had been pressed. The calling program can thus check for an exit key code of 21 regardless of whether a mouse is available or not. IMenuVertic will exit with an InfoInput(55) value of -2 if a mouse button is pressed outside the menu. A button release outside the menu normally has the same effect. (See also InEventSelect and InMouseOptions)..
Lahey/INTERACTER Starter Kit

101

Chapter 12

Input Handling
In addition to the 'confirm' key, tab/back-tab/help/quit keys can also be used to exit from the menu. Again these keys are as defined by InControlKey or the initialization file. The actual exit key which was pressed can be checked by a call to InfoInput(55). It is the responsibility of the calling program to decide whether to allow the use of these exit keys and to take appropriate action if they are used instead of the usual confirm key. Another useful exit code is InfoInput(61). This identifies whether a mouse button was used to exit from the menu and if so which one. This is always set to zero if a keyboard key is used to exit from the menu, but returns the mouse button number otherwise. When used in combination with InfoInput(55) and InfoInput(62)/(63) (the mouse position) this mechanism allows button dependent exit processing to be performed. If a frame is requested, it is placed around the area specified by the function parameters. Hence the position of the menu itself is the same regardless of whether a frame is requested or not. The first option to be highlighted is specified by istopt. As an extension to this feature, istopt can be specified as a negative value, in which case the following is assumed:
IABS(istopt) specifies the option to be highlighted.

The menu is assumed to already be on the screen and will not be redrawn. This is useful to avoid unnecessary menu 'repainting'. In this case IABS(istopt) must specify the same option as was returned by the call to IMenuVertic which printed the menu previously.

The menu is displayed according to the current text styles set by ITextAttribute and ITextColourN. The way in which the current option is highlighted can be controlled using the InHighlight routine. A pop-up feature is also available, controlled by InPopup. The text cursor is automatically disabled for the duration of the menu. If a frame is requested, then a menu title may also be supplied. If title is non-blank, it will be printed at the top of the frame. If both a frame and a title are requested, the value of iframe determines whether the title is printed within the frame (using IFrameTitle) or in a box at the top of the frame (using IFrameTitleBox). The frame is always printed outside the menu area specified by the subroutine parameters. Options which start with a hyphen ('-') are displayed, but non-selectable. This enables separator lines to be included in the list of options, allowing menus to be sub-divided by function if required. In other words, any option which starts with a dash will appear in the menu but the user will not be able to place the highlight bar on that line or select the option using its initial letter or the mouse.

Errors:
ErrMenuOpt (19): All options start with '-'. At least one menu item must start with a character other than '-'. IMenuHoriz is returned as 0 in this situation.

102

Lahey/INTERACTER Starter Kit

Group IP: Input Control Parameter Selection


Example
CHARACTER (LEN=4) :: OPTION(6) OPTION(1) = 'Save' OPTION(2) = 'Load' OPTION(3) = 'Edit' OPTION(4) = '----' OPTION(5) = 'Help OPTION(6) = 'Quit' IXPOS = 20 IYPOS = 5 ISPACE = 1 IFRAME = 1 CALL InHighlight('CYA','BLA') IOPT = IMenuVertic(OPTION,6,IXPOS,IYPOS,& 'Menu',ISPACE,IFRAME,5)

Group IP: Input Control Parameter Selection


The behavior of the input and menu handling routines in the IN, WN and MN groups can be modified using the parameter selection routines in this group. The control keys used by the various fixed field input routines and the menu routines can all be redefined using InControlKey. The text attributes for menu highlight bars and data entry fields can be determined using InHighlight. This defines the preferred highlighting method, but INTERACTER will adapt the actual highlight used depending on the display hardware in use.
InKeypad provides general purpose keypad interpretation control and affects all routines

which take input from the keyboard. Mouse processing in single key and fixed field input routines and menus can be controlled via the InMouseOptions mouse options routine.

InControlKey Subroutine
Description
Define control keys for all input handling routines.

Syntax
InControlKey(keycnt,keycod)
Lahey/INTERACTER Starter Kit

103

Chapter 12

Input Handling
Arguments
INTEGER keycnt = Control key number: Table 25: keycnt values
Name ControlUp ControlDown ControlRight ControlLeft ControlPageUp ControlPageDown ControlPageRight ControlPageLeft ControlExtremeUp ControlExtremeDown ControlExtremeRight ControlExtremeLeft ControlClearStart ControlClearEnd ControlMoveStart ControlMoveEnd ControlInsert ControlBackspace1 ControlBackspace2 ControlDelete ControlConfirm ControlHelp

keycnt
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

Action

Cursor up Cursor down Cursor right Cursor left Extended cursor up (Page up) Extended cursor down (Page down) Extended cursor right Extended cursor left Extreme cursor up Extreme cursor down Extreme cursor right Extreme cursor left Clear to start of field Clear to end of field Move to start Move to end Toggle insert mode Backspace and delete (key 1) Backspace and delete (key 2) Delete character under cursor Confirm input Help

104

Lahey/INTERACTER Starter Kit

InControlKey Subroutine
Table 25: keycnt values
Name ControlQuit ControlTab ControlBackTab

keycnt
23 24 25 26-30

Action

Quit Tab Back-tab Spare exit codes (group 1) Next item/next page Spare exit codes (group 2)

ControlNext

35 36-70

INTEGER keycod = Actual INTERACTER InKeyEvent code of key or event to be treated as the specified control key or zero to suppress key

Effect
Allows any one of the listed input control keys to be redefined. These are the keys which the user is able to press when using any INTERACTER routines which involve data input (i.e., all of the routines in the IN/MN groups) The current value of any of the listed keys is available via InfoInput(1-50)/(151-170). For example to redefine the 'help' key to be function key number 2, keycnt would be specified as 22 and keycod as 172, since this is the INTERACTER InKeyEvent code for F2. The initial default values for all of the above are implementation dependent, since the natural keys to use vary from one system to another. These default assignments are listed in Keyboard Codes on page 41. Any key which has a zero value assigned to it becomes unavailable to the user. This is a useful way of temporarily deactivating keys such as Tab, Back-tab or quit. In this case, it is advisable to first read the current value using InfoInput, save this value, then call InControlKey with a zero keycod value to suppress the use of a particular key. When using the various fixed field input routines the cursor can be moved to the start or end of field using the specially assigned control keys 15 and 16. Alternatively, the extended left/ right cursor control keys 8 and 7 can be used for the same purpose. Keys 18 and 19 define two different 'backspace and delete' keys. This is because some nonPC keyboards generate backspace (ASCII 8) and some generate delete (ASCII 127), and many generate both depending on which key is pressed. INTERACTER overcomes this problem by allowing both keys to do the same job. Of course, if you only want one 'backspace and delete' code, simply set the second one to zero. Keys 21-25 all act as 'exit' keys when used with the fixed field input and menu routines. In other words, keyboard input ceases when any of these keys are pressed and the currently entered value is passed back to the calling program. Keys 26-30 and 36-70 are also availLahey/INTERACTER Starter Kit

105

Chapter 12

Input Handling
able for this purpose but are initially undefined. They can be activated by calling InControlKey with a suitable INTERACTER key code value.(Note that keys in group 1 (26-30) have special meaning in the full version of INTERACTER when using the form editor.) A further point about exit keys is that they all perform exactly the same task of terminating keyboard input and nothing else. They are defined separately to enable the calling program to take different action depending on the context in which a particular input routine is being used. Since any InKeyEvent code can be assigned as a control 'key' this means that nonkeyboard event codes (e.g., mouse events) can also be assigned as exit 'keys'. The most recently used exit key is available via InfoInput(55), which returns the control key number rather than the InKeyEvent code assigned to it. Key 35 (normally the space bar) is used by the menu routines to move the highlight onto the next menu item. As an alternative to calling InControlKey, control keys can be defined at run time using the initialization file, thus offering the user total flexibility in selecting the keyboard interface. See Initialization Data File Format on page 27.

Portability notes:
The control keys for DOS systems are listed in Keyboard Codes on page 41.

Example
! define 'help' to be F2 CALL InControlKey(22,172) ! disable use of space bar as 'next item' key

CALL InControlKey(35,0)

InHighlight Subroutine
Description
Select highlight for menu & input-at-(x,y) routines.

Syntax
InHighlight(high1,high2)

106

Lahey/INTERACTER Starter Kit

InHighlight Subroutine
Arguments
CHARACTER high1and high2 =A pair of strings containing blanks, the word 'BOLD', or color names as follows: Table 26: high1 and high2 values
high1 high2
Highlight style

blank
BOLD BOLD

blank blank colourF colourB colourB blank

Reverse video Bold text in current foreground color Bold text in foreground colourF Foreground colourF / background colourB Current foreground color / background colourB Foreground colourF / Current background color

colourF blank colourF

(where ColourF or ColourB is a color name as definable to ITextColour) Defines the preferred highlighting method to be used in subsequent calls to the menu routines IMenuHoriz and IMenuVertic, and the fixed-field input routines InStringXY and InStringXYDef. The currently selected menu option or input field will be highlighted using one of reverse video, bold text or a foreground / background color combination. The default preferred highlight is bold white on blue until changed by InHighlight. high1 can be one of three highlight definitions: blank (for reverse video or background color only), 'bold' in lower or upper case, (for bold text with an optional foreground color) or the name of a foreground color. high2 can either be blank (in which case high1 completely defines the highlight) or it can be a color name (either foreground or background depending on what was specified for high1). If the current hardware/screen mode does not support the requested highlight, INTERACTER will automatically select an alternative. For example, requesting colors in a monochrome screen mode, will cause reverse video to be used instead. Thus color can be used, without sacrificing portability since the pointer/highlight facilities will still operate when color is not available.

Example
CALL IOPT CALL IOPT CALL IOPT InHighlight('BOLD','RED') = IMenuVertic(OPT,MAXOPT,IX,IY,'Menu',ISPC,IFRM,ISTOPT) InHighlight('BLUE','WHITE') = IMenuVertic(OPT,MAXOPT,IX,IY,'Menu',ISPC,IFRM,ISTOPT) InHighlight(' ','BLUE') = IMenuVertic(OPT,MAXOPT,IX,IY,'Menu',ISPC,IFRM,ISTOPT)

Lahey/INTERACTER Starter Kit

107

Chapter 12

Input Handling

InKeypad Subroutine
Description
Select keypad detection/interpretation mode.

Syntax
InKeypad(mode)

Arguments
INTEGER mode = mode for keypad interpretation: Table 27: Keypad mode values
Name NumericMode SubstMode FullMode

keycnt
1 2 3

Action

Numeric mode Special key substitution mode Full keypad mode

Effect
Selects the manner in which keys on the numeric keypad will be interpreted by InKeyEvent/InKeyEventImm. This in turn determines how keypad keys are treated by the fixed field input routines. This table summarizes the codes returned by the keypad in each of the three modes: Table 28: Keypad Codes
Keypad Key 0 1 2 3 4 5 6 7 Mode 1 48 49 50 51 52 53 54 55 Mode 2 142 (Insert) 141 (End) 129 (Cursor down) 133 (Page down) 131 (Cursor left) 155 130 (Cursor right) 140 (Home) Mode 3 150 151 152 153 154 155 156 157

108

Lahey/INTERACTER Starter Kit

InKeypad Subroutine
Table 28: Keypad Codes
Keypad Key 8 9 . + or , / * # Enter Mode 1 56 57 45 46 43 or 44 47 42 35 13 Mode 2 128 (Cursor up) 132 (Page up) 160 143 (Delete) 162 163 164 165 166 Mode 3 158 159 160 161 162 163 164 165 166

In numeric mode (mode=1) the keys return the codes shown on the key tops, e.g., keypad 9 generates character '9' and so on. In this mode keys on the keypad are indistinguishable from equivalent keys on the main keyboard. In full keypad mode (mode=3) keypad keys generate unique codes 150 to 166. Unfortunately, while most keyboards have a keypad the availability of other important keys is more variable. For example, on the original ('standard') 83-key IBM PC keyboard, there are no separate cursor keys. (Similarly, a VT100 keyboard does not have 'Insert' or Page up/down keys). Given these limitations, keypad mode 2 is provided. In this mode some keypad keys return the same codes as the cursor and other special keys. To check whether keypad keys are identifiable and whether cursor/keypad keys are separate, call InfoInput(56).

Portability notes
The initial keypad mode is 2, since some PC's do not have separate cursor keys and keypad. InKeypad has the documented effect when Num-Lock is off. Enabling Num-Lock effectively forces the keypad into mode 1.

Lahey/INTERACTER Starter Kit

109

Chapter 12

Input Handling
Example
CALL InKeypad(3) CALL InKeyEvent(KEY) IF (KEY>=128.AND.KEY<=131) THEN CALL IOutStringXY(10,10,'Cursor key detected ') ELSE IF (KEY>=150.AND.KEY<=159) THEN CALL IOutStringXY(10,10,'Keypad key detected ') ELSE IF (KEY<=127) THEN CALL IOutStringXY(10,10, & 'Normal keyboard character detected') END IF

InMouseOptions Subroutine
Description
Specify mouse options for fixed field/menu input.

Syntax
InMouseOptions(noptn,ivalue)

Arguments
INTEGER noptn = Option number (see below)

110

Lahey/INTERACTER Starter Kit

InMouseOptions Subroutine
INTEGER ivalue = Option value (see below) Table 29: noptn and ivalue
Name

noptn

ivalue

MouseExit

Set behavior on a mouse button press outside 'input area': NoMouseExit (0): do nothing ExitOutside (1): exit NoMouseExitBell (2): ring bell Select mouse feel:
SelectOnButDown (0): Select on button-down DragRelease (1): Windows 3.x-like feel FollowCursor (2): Windows 4.x-like feel

MouseFeel

ConfirmFixedButton

106

Button to confirm a fixed-width input field: IntNone (0): none LeftButton (1): left MiddleButton (2): middle RightButton (3): right

Effect
Defines mouse options for the single key, fixed field and menu routines. noptn values outside the specified range are ignored. Option 2 allows fixed-field input and menu routines to exit when a mouse button selection occurs outside the area defined by the relevant routine. A couple of definitions are required here: A mouse button selection means a button-down event. When option 3 is enabled (the default) this also means a button-up event outside a menu following a button-down inside the menu. Outside means the area beyond the frame (or beyond the area which the frame would surround, if no frame is selected).

When option 2 is set to 1 (the default), a mouse button selection outside a field/menu will return an InfoInput(55) exit key code of -2. The mouse button number and position when the selection occurred will then be available via InfoInput(61-63) and/or InfoGraphics(5)/(6). ivalue = 0 and 2 are identical except that the latter rings the bell. Option 3 determines the mouse 'feel' in menus. Three possible 'feel' selections are available: ivalue=0: Selects the behavior of INTERACTER 3.0 and earlier, where selection occurs as soon as a button is clicked.
Lahey/INTERACTER Starter Kit

111

Chapter 12

Input Handling
ivalue=1: Selects a Windows 3.x style feel. This is the default. Selection in menus occurs when a mouse button is released, with the highlight bar following mouse movement while a button is held down. Releasing a button outside of a menu after a button press inside a window is ignored by default but generates exit code -2 if option 2 is enabled (see above). ivalue=2: Selects a Windows 4.x style feel. The effect is the same as ivalue=1, except that the menu highlight automatically tracks mouse cursor movement, regardless of whether a button is held down. Enabling option 106 cause mouse clicks in an input field (see IN group) to confirm the field, rather than moving the cursor. If ivalue is zero, the specified button action is disabled. The default is 3. The current setting can be interrogated via InfoInput(106).

Example
CALL InMouseOptions(2,1) IOPT = IMenuVertic(OPT,MAXOPT,IX,IY,'Menu',ISPC,IFRM,ISTOPT) KEXIT = InfoInput(55) IF (KEXIT==-2) THEN MOUSEX = InfoInput(62) MOUSEY = InfoInput(63) ELSE IF (KEXIT==23) THEN ...

InPopup Subroutine
Description
Select pop-up mode for menu & input-at-(x,y) routines.

Syntax
InPopup(mode)

Arguments
CHARACTER mode = 'ON': switch single pop-up mode on (upper or lower case) = 'LI' : select linked pop-up mode (upper or lower case) = any other value to disable pop-up mode

Effect
Selects the 'pop-up' mode for the pointer/highlight menu routines, IMenuHoriz and IMenuVertic, plus the fixed field input-box routines InStringXY and InStringXYDef. Three pop-up modes are available, namely single, disabled or linked. The default mode as selected at start-up by IScreenopen is 'disabled'.

112

Lahey/INTERACTER Starter Kit

InPopup Subroutine
Single pop-up mode: When enabled, this feature causes menus and input boxes to be overlaid on top of whatever is already on the screen. The original screen contents are then restored as soon as a selection has been made or a value has been entered. This is simpler to use than linked mode (see below), since each pop-up uses its own workspace and operates entirely independently of other parts of the library. Disabled pop-up mode: When the pop-up feature is switched off, menu or field contents remain on the screen. The underlying screen area cannot be restored. Linked pop-up mode: Pop-up menus and input boxes can alternatively be linked. This is the most complex mode of operation, but one which offers greatest flexibility. It is referred to as 'linked' mode for two reasons: Menus and/or input boxes can be linked together, with the original screen contents only being restored at the end of the chain. For the duration of the chain, the menu/input-box routines are linked to the window management system. Each menu or input box opens its own pop-up window, using the window manager's workspace. This also means that windows can also be opened as part of the chain using the usual IWinOpen/ IWinOpenTitle routines.

When InPopup('LI') is called, a new menu chain is opened (and any existing chain is closed, but see below). Thereafter, each call to a menu/input-box routine opens a pop-up window of exactly the size occupied by the menu or box. Each menu/box becomes another window in the stack which can be closed using a IWinClose(1) call. Alternatively, the entire chain can be closed with another call to InPopup with any argument. Each time InPopup is called it will check whether there is an outstanding menu chain and close all windows which have been opened since that chain was created with a InPopup('LI') call. It is thus important to 'bracket' sections of code which manipulate linked menus with InPopup('LI') and InPopup('ON')/InPopup(' ') calls. This way, INTERACTER knows that it should go back to treating menus and windows as separate entities. Linked pop-up mode should be used with care, since it is possible to unwittingly open more windows than intended, particularly where 'walking' menus are constructed which allow a user to move both down and up a menu chain. When 'unwinding' back up a menu chain and re-entering a previous menu, the istopt (initially highlighted option) argument must be negative to signify that the menu is not to be redrawn and that no pop-up is required. This will prevent an additional window being opened over the top of the existing menu. See the LINKMENU demonstration program on your distribution disk for an example of how to use linked menu mode. The example is a little too long to reproduce here. In linked pop-up mode, the size of menu which can be displayed is limited by the available space in the window buffer. This limit is documented under IWinAction. In single pop-up mode, any size of menu can be displayed, within the limits of the physical screen size.
Lahey/INTERACTER Starter Kit

113

Chapter 12

Input Handling
Portability notes
Menus and input-boxes can pop-up over both text and graphics. Graphics screen data is buffered to a compressed memory buffer of approx 400k, which is shared with the text window manager. The available space in this buffer for a menu or input-box in "single pop-up" mode therefore depends on whether any pop-up windows are currently open. In the rare situation where a pop-up requires more buffer space than is available in the memory buffer, excess screen data is buffered to a disk buffer (on drive C:). In practice, a disk buffer is only used in high resolution 256 color SVGA modes, for pop-up menus which occupy very large screen areas.

Example
CHARACTER (LEN=12) :: OPTION(4) = & (/'Help Screen','Run Analysis', 'Edit Data' ! ! ,'Quit Program'/) CALL InHighlight('BLU','WHI') use single pop-up mode to make the menu close as soon as a selection has been made &

CALL InPopup('ON') IOPT = IMenuVertic(OPTION,4,20,5,'Pop Up Menu',1,1,1) CALL InPopup('OFF')

Group MC: Mouse Cursor Control


This group provides basic mouse cursor enable/disable routines.

IMouseCursorHide Subroutine
Description
Hide mouse cursor.

Syntax
IMouseCursorHide()

Effect
Removes the mouse cursor from the screen. See also IMouseCursorShow which displays the mouse cursor.

114

Lahey/INTERACTER Starter Kit

IMouseCursorShow Subroutine
Portability notes
It is advisable to temporarily remove the mouse cursor from the screen before generating screen output, otherwise the cursor may become corrupted. This call is supported in both text and graphics screen modes under DOS provided MOUSE.COM is loaded.

Example
See DOODLET and DOODLEG demos on distribution media.

IMouseCursorShow Subroutine
Description
Show mouse cursor.

Syntax
IMouseCursorShow()

Effect
Displays the mouse cursor at the current mouse position. See also IMouseCursorHide which removes the mouse cursor.

Portability notes
See IMouseCursorHide.

Example
See DOODLET and DOODLEG demos on distribution media.

Lahey/INTERACTER Starter Kit

115

Chapter 12

Input Handling

116

Lahey/INTERACTER Starter Kit

13 High Resolution Graphics


The graphics routines in the following groups are designed to be portable to virtually any type of high resolution graphics device. The routines described in this chapter are divided into 4 groups: GG General Graphics (Housekeeping, etc.) GS Graphics Style selection (color, line type, fill style) GD Graphics Drawing and Movement (Line/fill primitives) GC Graphics Character Output (Text primitives) Given the variability of graphics facilities offered by different devices, the InfoGrScreen function is provided in the IF group. The main hardware dependencies are associated with the routines in the GS group. Also available in the IF group is the InfoGraphics function which reports various graphics parameter settings.

Group GG: General Graphics


Starting and Finishing

INTERACTER's graphics routines are automatically initialized by IScreenOpen. If IScreenOpen entered a text screen mode use IScreenMode to switch between text and graphics modes. The screen must be in graphics mode to be able to draw graphics. INTERACTER graphics remain available until IScreenClose is called.
Co-ordinate System

While in graphics mode, the co-ordinate system is user-definable and is not related to the physical resolution of the output device, making graphics based programs device and screen mode independent. The area of the screen or output page to be used for the graphics display can also be defined. The IGrArea and IGrUnits routines control the main graphics area and co-ordinate system respectively. Calls to routines in other groups, such as IGrLineTo, IGrCharOut, etc. all use (x,y) co-ordinates defined in terms of the range set by the call to
Lahey/INTERACTER Starter Kit

117

Chapter 13

High Resolution Graphics


IGrUnits. So if IGrUnits sets the min and max X values as 0-1000 and the min and max Y values as 0-500, all co-ordinate values should be in these ranges too. Attempts to draw outside this area will be clipped at the edge of the graphics area. By default (0,0) is the bottom

left corner of the graphics area. Initially, the main graphics area is set to the full screen/page.
Skeleton Graphics Program

In general, any graphics program should be based on this skeleton:


USE INTERACTER ! Initialize INTERACTER, enter graphics mode CALL IScreenOpen(' ','G',NX,NY,NCOLORS) ! modify graphics area and co-ordinate system, if required CALL IGrArea(..co-ordinates..) CALL IGrUnits(..co-ordinates..) ! ** draw your graphics here ** ! ! end of current picture CALL IGrPause(' ') ! ! ** draw some more graphics ** CALL IGrPause(' ') ! end of graphics output CALL IScreenClose() END

IGrArea Subroutine
Description
Define size of graphics area.

Syntax
IGrArea(xleft,ylower,xright,yupper)

Arguments
REAL xleft = Left limit of main graphics area (0.0 <= xleft < 0) REAL ylower = Lower limit of main graphics area (0.0 <= ylower <1.0) REAL xright = Right limit of main graphics area (0.0 < xright <= 1.0) REAL yupper = Upper limit of main graphics area (0.0 < yupper <= 1.0)

118

Lahey/INTERACTER Starter Kit

IGrAreaClear Subroutine
Effect
Defines the area of the screen to be used by all following graphics commands. The full screen is defined as being 1 unit high and 1 unit wide, so you should describe your area in values in the range 0.0 - 1.0 as shown above. When you call IGrUnits, that then defines the coordinate system to be used within the area defined by IGrArea. The default values for both the IGrArea and IGrUnits ranges, are 0.0 to 1.0 occupying the whole of the graphics screen. The current graphics area dimensions can be interrogated via the InfoGraphics function.
IGrArea is particularly useful when you wish to rescale a graphics image without changing

your co-ordinate system or any other parameters. In the example below, a full screen display is reduced to a quarter size, at the top right of the screen, by a single call to IGrArea. It is important to appreciate that if you set a graphics area in which the sides are no longer equal (e.g., 0.5 high and 1.0 wide) then regular shapes will be distorted accordingly. For example, circles become elliptical, squares become rectangular and so on.

Errors:
ErrBadArea (44): Invalid X and/or Y range. Range reset to 0-1.

Example
CALL CALL CALL CALL CALL IGrArea(0.0,0.0,1.0,1.0) MYGRAF IGrPause(' ') IGrArea(0.5,0.5,1.0,1.0) MYGRAF

IGrAreaClear Subroutine
Description
Clear the current graphics screen area.

Syntax
IGrAreaClear()

Effect
Clears the current main graphics area as defined by IGrArea, to the current background color. Part of the graphics screen can therefore be cleared without affecting the rest of the screen. When the graphics area is defined to be 0.0-1.0 in both x and y directions, the whole screen is cleared.
Lahey/INTERACTER Starter Kit

119

Chapter 13

High Resolution Graphics


Example
CALL IGrArea(0.05,0.05,0.4,0.4) CALL IGrAreaClear CALL MYGRAF

IGrGetPixelRGB Subroutine
Description
Read a screen pixel color value

Syntax
IGrGetPixelRGB(xpos,ypos,ired,igreen,iblue)

Arguments
REAL xpos = X co-ordinate REAL ypos = Y co-ordinate INTEGER ired = Red component of specified point (0-255) INTEGER igreen = Green component of specified point (0-255) INTEGER iblue = Blue component of specified point (0-255)

Effect
Returns the color of the specified screen co-ordinate, as an (r,g,b) triplet. The (x,y) co-ordinate should be expressed in the normal INTERACTER user units as set via IGrUnits. The returned 24-bit color value uses the same color range as the corresponding IGrPaletteRGB routine. Results are undefined when screen graphics are not enabled. If the specified co-ordinate lies outside the graphics area the RGB value is returned as (-1,1,-1). On a monochrome screen, the returned RGB value does not take account of palette changes applied to the two foreground/background colors. Background pixels return (0,0,0) and foreground pixels return (255,255,255).

IGrInit Subroutine
Description
Start graphics output.

120

Lahey/INTERACTER Starter Kit

IGrInit Subroutine
Syntax
IGrInit(type,nx,ny,ncolor)

Arguments
CHARACTER type = Type of mode, one only of the following: = C: priority to number of colors when selecting screen mode = R: priority to resolution when selecting screen mode (default)

INTEGER nx = Preferred number of horizontal screen pixels INTEGER ny = Preferred number or vertical screen pixels INTEGER ncolor = Preferred number of screen colors

Effect
Re-initializes graphics output. This routine is called by IScreenOpen, so it should not normally be necessary to call it again unless the whole of the graphics system needs to be reset to its default state. In INTERACTER v3.xx and earlier, IGrInit needed to be called before any graphics processing, but this is no longer the case. In general, use of IGrInit is discouraged, though its use for re-initialization remains valid. The graphics mode with the nearest resolution to that requested will be selected by default. However, the mode with the nearest number of colors can be given priority by specifying type as 'C'. If the type of mode to be selected is not important, type can be left blank. Attempting to enter graphics screen mode when the currently selected display type does not support graphics will cause IGrInit to call the IOsExitProgram routine to terminate program execution, with exit code 13.
IScreenMode can be called to switch to and fro between text and graphics modes, without any necessity to re-initialize the graphics system. Since IGrInit uses IScreenMode to enter graphics screen mode, it indirectly calls IScreenModeN.

Example
CALL CALL CALL CALL CALL CALL CALL CALL IGrInit('C',800,600,16) IGrUnits(0.,0.,1000.,1000.) MYGRAF IGrPause(' ') IScreenMode('t',80,25,16) IOutString('Back to text mode') InKeyEvent(K) IScreenMode('G',800,600,16)

Lahey/INTERACTER Starter Kit

121

Chapter 13

High Resolution Graphics

IGrPause Subroutine
Description
Pause before clearing screen to start a new picture.

Syntax
IGrPause(action)

Arguments
CHARACTER action then clear screen) = String describing required action (default is wait for confirm key = 'A': Any key can be pressed instead of just 'confirm' = 'P': Preserve contents of graphics screen

Effect
This should be called when the drawing of a graphics screen has been completed. IGrPause sounds the bell, then proceeds according to the action argument: If action contains an 'A' any key can be pressed to continue. By default, the user must press the 'confirm' key. The resulting InKeyEvent code is available via InfoInput(67). The screen is cleared unless action contains a 'P' to indicate that the contents of the screen must be preserved.

Both upper and lower case are accepted for action arguments.

IGrUnits Subroutine
Description
Define plotting units to be used.

Syntax
IGrUnits(xleft,ylower,xright,yupper)

Arguments
REAL xleft = Lower X co-ordinate limit REAL ylower = Lower Y co-ordinate limit REAL xright = Upper X co-ordinate limit REAL yupper = Upper Y co-ordinate limit

122

Lahey/INTERACTER Starter Kit

Group GS: Graphics Style Selection


IGrUnits defines the plotting units (the 'user co-ordinate system') to be used when drawing in the main graphics area defined by IGrArea. The initial ranges are 0.0 to 1.0 on both axes. The example below shows how you to plot values in the range 500-1000 on the x axis and values of 300-600 on the y axis. The current plotting units can be interrogated via the InfoGraphics function.

Selecting an invalid X or Y range, sets the limits for that axis to 0-1.

Errors
ErrBadUnits (16): Lower X or Y value is greater than or equal to upper X or Y

Example
CALL IGrUnits(500.0,300.0,1000.0,600.0) CALL IGrCircle(750.,450.,50.)

Group GS: Graphics Style Selection


The subroutines in this group affect the appearance of output from other graphics routines. The current graphics color is selected using IGrcolorN. The number of available colors is highly device dependent, so INTERACTER uses the same color numbering scheme regardless of screen mode or output device, based on 256 nominal colors. When less than 256 colors are available, a near equivalent is always selected. Hence, programs can be written to use color without having to be too concerned with the details of which colors are actually available on the current device. On monochrome devices, the color handling routines can still be called but their effect will be limited to selecting either background/foreground color or they may have no effect at all. Color 0 is treated as the background color and all others as foreground. However, color 0 can still be selected as the current color for graphics operations, though it will obviously only be visible if the operation takes place on top of some non-background color. The color palette (the relationship between color numbers and actual colors displayed) can be redefined on many displays using IGrPaletteRGB. By default the background color is black, and the other displayed colors depend on the screen mode selected. In addition to color control, line type and fill style are selectable via IGrLineType and IGrFillPattern.

IGrColorN Subroutine
Description
Select graphics color using a color number.
Lahey/INTERACTER Starter Kit

123

Chapter 13

High Resolution Graphics


Syntax
IGrColorN(ncolor)

Arguments
INTEGER ncolor = color number (0-255)

Effect
Selects the graphics color for lines, points, text and fills, using a single color number. The INTERACTER color numbering scheme is device independent. The same color numbers are used regardless of the actual number of colors available on the output device. INTERACTER performs an internal mapping between its device independent color scheme and the actual color numbers used by the current hardware. The 256 color numbers are organized into 16 groups, each consisting of 16 shades of a given color. On devices which support less than 256 colors, a single palette value from each sub-group is used (either a maximum or minimum intensity). For example, in a 16 color mode, values of 16-31 all give bright red and 3247 give dark red.

124

Lahey/INTERACTER Starter Kit

IGrColorN Subroutine
Color zero is treated specially by INTERACTER as the background color. This can still be selected as the current graphics color, enabling you to draw or fill in one foreground color and then plot on top of that using the current background color. The default palette associated with the INTERACTER 256-color numbering scheme is as follows (values are ( r,g,b) triplets where maximum intensity = 255): Table 30: 256-Color Numbering Scheme Default Palette
Actual Color Black Light red Dark red Light yellow Dark yellow Light green Dark green Light cyan Dark cyan Light blue Dark blue Light magenta Dark magenta White Light gray Dark gray Color # 0-15 16-31 32-47 48-63 64-79 80-95 96-111 112-127 128-143 144-159 160-175 176-191 192-207 208-223 224-239 240-255 256-Color Palette ( 0, 0, 0, 0, 0) -> ( 60, 60, 60) 0) -> (255, 0) -> (191, 0, 0, 0) 0) 0) 0) 0) 0)

(195, (131,

(195,195, (131,131, ( ( ( ( ( ( 0,195, 0,131,

0) -> (255,255, 0) -> (191,191, 0) -> ( 0) -> ( 0,255, 0,191,

0,195,195) -> ( 0,131,131) -> ( 0, 0, 0,195) -> ( 0,131) -> (

0,255,255) 0,191,191) 0, 0, 0,255) 0,191) 0,255) 0,191)

(195, (131,

0,195) -> (255, 0,131) -> (191,

(195,195,195) -> (255,255,255) (131,131,131) -> (191,191,191) ( 64, 64, 64) -> (128,128,128)

Lahey/INTERACTER Starter Kit

125

Chapter 13

High Resolution Graphics


In 16 or 8 color output, a subset of the above palette is used: Table 31: 16 or 8 Color Palette
Actual Color Black Light red Dark red Light yellow Dark yellow Light green Dark green Light cyan Dark cyan Light blue Dark blue Light magenta Dark magenta White Light gray Dark gray Color # 0-15 16-31 32-47 48-63 64-79 80-95 96-111 112-127 128-143 144-159 160-175 176-191 192-207 208-223 224-239 240-255 16-color palette ( 0, 0, 0, 0, 0) 0) 0) 0) 0) 0) 0) 8-color palette ( 0, 0, 0, 0, 0) 0) 0) 0) 0) 0) 0)

(255, (191,

(255, (255,

(255,255, (191,191, ( ( ( ( ( ( 0,255, 0,191,

(255,255, (255,255, ( ( ( ( ( ( 0,255, 0,255,

0,255,255) 0,191,191) 0, 0, 0,255) 0,191) 0,255) 0,191)

0,255,255) 0,255,255) 0, 0, 0,255) 0,255) 0,255) 0,255)

(255, (191,

(255, (255,

(255,255,255) (191,191,191) ( 64, 64, 64)

(255,255,255) (255,255,255) ( 0, 0, 0)

126

Lahey/INTERACTER Starter Kit

IGrColorN Subroutine
If black and white are reversed, by specifying 'W' in the type argument to IScreenOpen, black, gray, and white shades are reversed as follows: Table 32: Reversed Black, Gray, and White Shades
Actual Color White Black Dark Gray Light Gray Color # 0-15 208-223 224-239 256-color palette (255,255,255) -> (195,195,195) ( 60, 60, 60) -> ( 0, 0, 0) 16-color palette (255,255,255) ( 0, 0, 0)

(124,124,124) -> ( 64, 64, 64)

( 64, 64, 64)

240-255

(191,191,191) -> (131,131,131)

(191,191,191)

In monochrome modes color zero selects the background color and any non-zero color number is treated as a foreground color. Normally, the monochrome palette is a black background and a white foreground, unless reversed by IScreenOpen. Whatever color number is used, IGrColourN has no effect on the actual color which is associated with that number. It simply sets the logical color number to be used by any following graphics operations. To redefine the association of displayed colors with logical colors you should use IGrPaletteRGB. Two consecutive calls to IGrColourN will select the colors to be used by mixed-color area fills (see IGrFillPattern). The default graphics color at initialization is white. The actual number of colors available can be checked using InfoGrScreen(30). Requesting a color number outside the range 0-255 is ignored and an error code is set. The two most recently requested colors are available via InfoGrScreen(34) and (35). See the COL256 demo program. This illustrates all of the available colors in the default palette.

Errors
ErrBadcolor (42): Unknown color number. Current color unchanged

Example
DO ICOL = 16,240,32 CALL IGrcolorN(ICOL) CALL IGrMoveTo(0.0,0.0) CALL IGrLineTo(0.5,REAL(ICOL)) END DO

Lahey/INTERACTER Starter Kit

127

Chapter 13

High Resolution Graphics

IGrFillPattern Subroutine
Description
Define fill pattern (solid/stippled/hatched).

Syntax
IGrFillPattern(istyle,idense,iangle)

Arguments
INTEGER istyle = Fill style: Table 33: Fill styles
Name CrossHatchNoOut HatchedNoOut Outline Hatched CrossHatch MixedColor Solid No. -2 -1 0 1 2 3 4 Information

Cross-hatched fill with no outline Hatched fill with no outline No fill, ouline only (default) Hatched fills Cross-hatched fills Mixed-color fills (stippled) Solid fills

INTEGER idense = Hatched fill density: Table 34: Hatched Fill Density
Name Sparse Medium Dense1 Dense2 Dense3 No. 1 2 3 4 5 Information

Sparse Medium (default) Dense Very dense Very very dense

128

Lahey/INTERACTER Starter Kit

IGrFillPattern Subroutine
INTEGER iangle = Hatched line angle: Table 35: Hatched Line Angle
Name FillHoriz FillVertic No. 3 4 Information

Horizontal lines (default) Vertical lines

IGrFillPattern defines the fill pattern (if any) to be used by IGrCircle and IGrPolygonComplex. The basic choice is between no fills and hatched, solid or mixed-color

fills. The default fill style is zero which gives outlines only. In this case, the density and angle parameters are ignored. Hatched fills draw lines at intervals across the area to be filled. If a hatched fill is selected, the density and angle parameters define the precise style of the fill. A dense fill uses roughly twice as many lines to fill the area as a sparse fill. The angle parameter controls the direction of the fill lines. Type 1 hatched fills draw lines in one direction only, according to the selected iangle value. Type 2 (cross-hatched) fills draw lines in both directions. If a borderless hatched fills are required, specify a fill style of -1 or -2. Type 4 (solid) fills use a pure color, as most recently defined by a call to IGrcolorN. Type 3 (mixed) fills are similar to solid ones, except that the two colors as defined by the last two calls to IGrcolorN are mixed. Hence if two successive calls to IGrcolorN specify Yellow then Red, a type 3 fill will mix these colors. Stippled fills are used. These give the appearance of many more color shades than a device actually supports by plotting alternate pixels in each color. In 2-color modes, there is obviously only one stippled fill shade (black+white=gray, assuming the default palette). In 16 and 256 color modes there are 120 or 32640 stippled shades respectively. Selecting the same color twice in succession gives a solid fill. In monochrome modes, the foreground/background colors are automatically mixed in stippled fills, regardless of the last two colors specified, unless those colors were identical in which case a solid fill is selected. When solid/stippled fills are requested, angle and density are ignored. If an invalid style, density or angle is specified, then the indicated defaults are used.

Example
CALL CALL CALL CALL IGrcolorN(48) IGrcolorN(144) IGrFillPattern(3,0,0) IGrCircle(150.,500.,30.)

Lahey/INTERACTER Starter Kit

129

Chapter 13

High Resolution Graphics

IGrLineType Subroutine
Description
Select line type (solid, dots, dashes or dot/dash).

Syntax
IGrLineType(ltype)

Arguments
INTEGER ltype = Line type: Table 36: Line Types
Name SolidLine Dotted Dashed DotDash DotDotDash LongShort ShortDash No. 0 1 2 3 4 5 6 Information

Solid (default) Dots Dashes Dot/dash Dot/dot/dash Long/short dashes Short dashes

Effect
Selects the line type for subsequent drawing operations. A call to IGrLineType restarts the selected dot pattern, even if that pattern was already selected. The currently requested line type is available via InfoGrScreen(36).

Example
CALL IGrLineType(1) ! draw a grid of dotted lines DO I = 1, 9 CALL IGrMoveTo(0.0, 0.1*REAL(I)) CALL IGrLineToRel(1.0,0.0) CALL IGrMoveTo(0.1*REAL(I),0.0) CALL IGrLineToRel(0.0,1.0) END DO

130

Lahey/INTERACTER Starter Kit

IGrPaletteRGB Subroutine

IGrPaletteRGB Subroutine
Description
Redefine color palette using RGB color scheme.

Syntax
IGrPaletteRGB(ncolor,ired,igreen,iblue)

Arguments
INTEGER ncolor = Logical color number to which an actual color is to be assigned (same numbering scheme as IGrcolorN) INTEGER ired = Amount of red to assign to displayed color (0-255) INTEGER igreen = Amount of green to assign to displayed color (0-255) INTEGER iblue = Amount of blue to assign to displayed color (0-255)

Effect
Controls the graphics color palette, using the Red, Green, Blue (RGB) color scheme. An actual color combination is assigned to a logical color number. On a screen, redefinition of the palette normally takes place immediately (but see the Portability notes) so that all screen pixels of the specified logical color number are displayed in the specified actual color. Note that the whole of the background color can be reset by calling IGrPaletteRGB with an ncolor value of 0. The displayed color is specified in terms of its RGB (red/green/blue) components. Since the number of colors available on different devices varies widely, the RGB components are expressed in an arbitrary range of 0-255. In theory this allows for up 16 million different colors! In practice, most output devices support significantly fewer colors (see Portability notes), so each RGB value is scaled accordingly. For example, where a display supports 4 shades of each color (giving 4x4x4=64 colors) each supplied RGB component will be scaled to a value in the range 0 to 3. If 16 levels were available they would be scaled to values in the range 0 to 15 and so on. The logical color number specifies the color which would be selected by supplying exactly the same value to IGrColourN. Hence the logical color should lie in the range 0 to 255 and will be converted to an appropriate actual color number for the current screen mode, using the same rules as IGrColourN.
Lahey/INTERACTER Starter Kit

131

Chapter 13

High Resolution Graphics


Palette redefinition capabilities vary considerably between devices. A number of items of information are therefore available via InfoGrScreen functions in the IF group, to identify the capabilities of the current device:
InfoGrScreen(8) and (9) identify whether the current display supports redefinition, of any sort, of the background and foreground palettes.

On some devices color redefinition only affects subsequent plotting, a condition which can be identified using InfoGrScreen(24).

The default palettes are always reset when IScreenMode, IScreenModeN, or IGrInit are called. See IGrcolorN for a description of the colors available in the default palettes.

Portability notes
When using an MCGA or VGA, INTERACTER allows all logical colors to be programmed using 64 levels of RGB component, giving 262,144 possible actual colors in all available graphics modes. On an EGA in 350-line mode (number 16), 4 levels of red/green/blue are supported, for all 16 logical colors, giving 64 possible displayed colors. On an EGA in 200-line mode 14, the color palette is restricted to 16 colors. Each RGB component is either on or off, (i.e., >=128 or <128) with the resulting color being displayed at either high or low intensity. On a CGA, in mode 6, palette redefinition is limited to the foreground color. As for the 200line EGA mode, the palette consists of 16 possible colors. The exceptions to the above are monochrome graphics modes numbered 8 (Hercules), 9 (AT&T/Olivetti 640x400) and 15 (EGA/VGA 640x350). Palette redefinition is not supported in any of these modes.

Example
! if foreground palette redefiniton available set ! color ICOL to black ICOL = 100 IF (InfoGrScreen(9)>0) THEN CALL IGrPaletteRGB(ICOL,0,0,0) END IF ! draw some graphs in black on black, then make graphs appear CALL GRAPHS(ICOL) CALL IGrPaletteRGB(ICOL,255,255,255)

132

Lahey/INTERACTER Starter Kit

Group GD: Graphics Drawing/Movement

Group GD: Graphics Drawing/Movement


The routines in this group provide the main INTERACTER graphics drawing primitives. An important concept here is the 'current plotting position'. This can be set explicitly using IGrMoveTo, but is automatically updated by other drawing and character output routines in the GD and GC groups.
IGrCircle and IGrPolygonComplex can draw shapes in a variety of styles which are determined by the IGrFillPattern routine in the GS group. By default they simply draw

an outline of the appropriate shape, but they can also perform hatched, mixed-color or solid fills. Simple straight line drawing can be performed using IGrLineTo. Single points can be plotted using IGrPoint.

IGrCircle Subroutine
Description
Draw/fill circle at an absolute position.

Syntax
IGrCircle(xpos,ypos,radius)

Arguments
REAL xpos = X co-ordinate of circle center REAL ypos = Y co-ordinate of circle center REAL radius = Radius of circle in current plotting units

Effect
Draws a circle of a given radius centered at the specified absolute plotting position, in the current graphics color as selected by IGrcolorN. The circle will be filled, if required, using the fill pattern selected by IGrFillPattern. The current plotting position becomes (xpos,ypos). Aspect ratio is preserved regardless of output device.

Errors
ErrBadRadius (20): radius <= zero. Nothing will be drawn.

Portability notes
See IGrFillPattern.
Lahey/INTERACTER Starter Kit

133

Chapter 13

High Resolution Graphics


Example
CALL IGrUnits(50.,100.,500.,300.) CALL IGrFillPattern(2,2,3) CALL IGrCircle(100.,200.,20.)

IGrLineTo Subroutine
Description
Draw line to a new absolute position.

Syntax
IGrLineTo(xpos,ypos)

Arguments
REAL xpos = X co-ordinate to draw to REAL ypos = Y co-ordinate to draw to

Effect
Draws a line from the current plotting position (as set by a previous call to IGrMoveTo or IGrLineTo itself) to the new absolute plotting position specified by (xpos,ypos). On exit, (xpos,ypos)becomes the current plotting position.

Example
CALL IGrUnits(0.0,0.0,1000.0,500.0) CALL IGrMoveTo(200.0,100.0) CALL IGrLineTo(800.0,100.0)

IGrMoveTo Subroutine
Description
Move current plotting position to a new absolute position.

Syntax
IGrMoveTo(xpos,ypos)

Arguments
REAL xpos = X co-ordinate REAL ypos = Y co-ordinate

134

Lahey/INTERACTER Starter Kit

IGrPoint Subroutine
Effect
Moves the current plotting position to the absolute position (xpos,ypos) without any visible effect.

Example
CALL IGrUnits(100.,0.,300.,400.) CALL IGrMoveTo(150.,200.) CALL IGrLineTo(200.,300.)

IGrPoint Subroutine
Description
Draw a single point at new absolute position.

Syntax
IGrPoint(xpos,ypos)

Arguments
REAL xpos = X co-ordinate REAL ypos = Y co-ordinate

Effect
Sets the current plotting position to the absolute position (xpos,ypos) and plots a point at that position.

Example
CALL IGrUnits(100.,0.,300.,400.) CALL IGrPoint(150.,200.)

IGrPolygonComplex Subroutine
Description
Draw/fill a complex (possibly intersecting) polygon.

Syntax
IGrPolygonComplex(x,y,nvert)

Arguments
REAL x(:) = Array of X co-ordinates
Lahey/INTERACTER Starter Kit

135

Chapter 13

High Resolution Graphics


REAL y(:) = Array of Y co-ordinates INTEGER nvert = Number of vertices in supplied x/y arrays (<=4095) Draws an irregular polygon defined by the specified absolute plotting positions, with possibly intersecting borders. The polygon is drawn in the current graphics color as selected by IGrColourN. The polygon will be filled, if required, using the pattern set by IGrFillPattern.The polygon will be closed, i.e. the last point will be joined to the first. Up to 4095 vertices are allowed.
IGrPolygonComplex uses a device-specific primitive for solid and mixed-color fills, where available (see Portability notes). Where such a primitive is not available or is known to be unreliable, a generic (i.e., device independent) scan-line search method is used. The generic method is also used for hatch filling on all devices.

In very rare situations, a polygon may be too complex for IGrPolygonComplex's generic algorithm, in which case the routine will exit with error code 49. This is only likely to occur in very extreme cases. If no fill is specified, IGrPolygonComplex simply draws a poly-line, i.e., it joins the points specified in x and y regardless of whether the borders cross. Whether filled or not, the current plotting position becomes (x(1),y(1)).

Errors
ErrFillComplex (49): Fill too complex. Unable to fill polygon.

Portability notes:
IGrPolygonComplex's generic algorithm is used for DOS screen graphics.

Example
REAL, DIMENSION (4095) :: X, Y READ(20,*) N N = MIN(N,4095) DO I = 1,N READ(20,*) X(I),Y(I) END DO CALL IGrPolygonComplex(X,Y,N)

Group GC: Graphics Character Output


This group provides a routines to control graphics text output. The routine which actually writes graphics text strings is IGrCharOut. The primary advantage of the GC routines is that they are able to use software defined device-independent character sets (outline or vector

136

Lahey/INTERACTER Starter Kit

IGrCharJustify Subroutine
fonts) which are loaded from disk using IGrCharSet, in addition to hardware-dependent character sets. When the latter are selected, INTERACTER will automatically substitute an equivalent software font, where a hardware-specific font is unavailable or unsuitable. The justification of graphics mode text can be controlled using IGrCharJustify. The size of text is set using IGrCharSize. By default text is monospaced, but proportional spacing is selectable via IGrCharSpacing. The relative length of a graphics text string (taking account of proportional spacing if enabled) is returned by the IGrCharLength function. Two overall strategies are available for font selection: (1) Always use INTERACTER's software character sets, by calling IGrCharSet to load font files from the charsets directory. This has the benefit of total device independence and is well suited to DOS graphics. However, it does not take advantage of format specific font handling capabilities (e.g. Windows or PostScript) which are supported by the full version of INTERACTER. (2) Leave the character set selection as 'hardware dependent'. This is the initial default. This will utilize device/format specific font handling capabilities where appropriate but will automatically substitute an INTERACTER-equivalent outline font where format-specific capabilities are not up to the required standard. This solution requires no use of IGrCharSet. Instead, all font selection is determined by IGrCharSpacing. Both of the above strategies require that fonts from the charsets directory be distributed with your application. Strategy (2) only requires the character set files for the 'swiss' and 'fixed' outline fonts.

IGrCharJustify Subroutine
Description
Select graphics text justification.

Syntax
IGrCharJustify(justif)

Arguments
CHARACTER justif = Justification mode for graphics text output: = C: centered (default) (can be upper or lower case) = L: Left justified (can be upper or lower case) = R: Right justified (can be upper or lower case)
Lahey/INTERACTER Starter Kit

137

Chapter 13

High Resolution Graphics


Effect
Sets the justification to be used when outputting graphics text IGrCharOut. The default, as set by IGrInit is centered. If a string is supplied which starts with a letter other than C, L, or R the default is also centered. The specified justification applies to both software and hardware character set text output. Justification always takes place relative to a plotting position. So left justified text is printed starting from a given position, right justified text finishes at that position and centered text appears either side of it. In this sense, 'left' and 'right' refer to which end of the string is actually at the specified plotting position.

Example
CALL CALL CALL CALL IGrCharJustify('Left') IGrCharOut(100.,100.,'This starts at (100,100)') IGrCharJustify('r') IGrCharOut(100.,150.,'This finishes at (100,150)')

IGrCharLength Function
Description
Measure the length of a graphics text string.

Syntax
REAL IGrCharLength(string)

Arguments
CHARACTER string = String or character to measure

Effect
When proportional spacing is enabled, this function returns the relative length of the specified string. So, IGrCharSpace('I') would return 0.56, IGrCharSpace('IM') would return 0.56+1.42=1.98, and so on. In addition to providing a mechanism for interrogating the spacing table, this function also allows a proportionally spaced string to be measured in user units simply by multiplying the result by InfoGraphics(3) (the width of a fixed space character expressed in user units). When fixed spacing is enabled, IGrCharLength(string) always returns REAL(LEN(string)). Hence the result of IGrCharLength multiplied by InfoGraphics(3) always returns the width the string in user-units, regardless of what type of spacing is enabled.

138

Lahey/INTERACTER Starter Kit

IGrCharOut Subroutine
Example
! write a red proportionally spaced string underlined in green CALL IGrCharSpacing('P') WIDTH = IGrCharLength(STRING)*InfoGraphics(3) HEIGHT = InfoGraphics(4) CALL IGrColourN(96) CALL IGrMoveTo(X,Y) CALL IGrLineTo(X+WIDTH,Y) CALL IGrCharJustify('L') CALL IGrColourN(32) CALL IGrCharOut(X,Y+HEIGHT/2.0,STRING)

IGrCharOut Subroutine
Description
Output character string at an absolute (x,y) position.

Syntax
IGrCharOut(xpos,ypos,string)

Arguments
REAL xpos = X co-ordinate REAL ypos = Y co-ordinate CHARACTER string = String to write

Effect
Outputs string at the graphics co-ordinate (xpos,ypos). Color is as previously defined by IGrcolorN. If a vector-based software character set has been selected, characters are drawn using a solid line style. The position of the text relative to (xpos,ypos) is determined by the most recent call to IGrCharJustify, and can be centered or left/right justified. The default is centered. Text is written horizontally. ypos specifies a position half-way up a character. In left/right justification mode the other coordinate specifies an extreme end of the string. On exit the current plotting position is updated to a point within the next character cell after the string which has been written. The exact position within the cell will depend on the current justification mode. The font/character set used by IGrCharOut is determined by IGrCharSet and IGrCharSpacing. The default is fixed space hardware characters.
Lahey/INTERACTER Starter Kit

139

Chapter 13

High Resolution Graphics


Text size is governed by IGrCharSize, though this is dependent on which character set and output device is selected. Full software text size control is available on all devices. Hardware text size control is device dependent. See IGrCharSize. Whichever justification or character set is used, text which would extend beyond the limits of the main graphics area (as defined by IGrArea) is clipped at the edge of that area. Text which would be completely outside the graphics area is not printed. Text written by this routine can contain both 7-bit and 8-bit characters, as defined in the ISO Latin-1 standard (i.e. character codes in the range 32-126 and 161-255).

Errors
ErrNoSoftFont (53): Unable to find a software (outline) font to substitute for an unavailable hardware font size/style.

Example
CALL IGrCharOut(100.0,200.0, & 'This is centered at (100,200)') CALL IGrCharJustify('L') CALL IGrCharOut(300.0,200.0,'This starts at (300,200)')

IGrCharSet Subroutine
Description
Select graphics character set to use for text output.

Syntax
IGrCharSet(filnam)

Arguments
CHARACTER filnam = Filename or string describing character set to use = 'H' or 'h': select hardware-dependent text = ' ' : load/select default software character set = 'filename': load software character set from 'filename'

Effect
Selects the character set to be used by future calls to IGrCharOut to output text in graphics mode.

140

Lahey/INTERACTER Starter Kit

IGrCharSet Subroutine
By default hardware-dependent text is enabled. This is re-selectable here by specifying a single 'H'. Hardware text is device dependent in terms of both its size and appearance. When hardware text is selected, IGrCharSpacing determines the actual font selected. Where a font of the required type/size/quality is not available on the current device, an equivalent software outline font is automatically substituted. Calling IGrCharSet with an argument other than 'H' loads a software character set from a file, makes it the current font and disables hardware-text (and hardware text substitution). There are two ways to load a software character set: 1) By specifying a blank filnam, a default character set filename is used. The default name is assigned by IScreenOpen ('standard.chr'). An alternative default character set filename can be specified in the initialization file using the CHARSET keyword. 2) By specifying the name of a file containing an INTERACTER-compatible character set. Each character in a software font is formed by filling a polygon (outline fonts) or by drawing a series of lines (vector fonts). Whilst somewhat slower to plot, software characters can always be scaled to any size (using IGrCharSize) and have a consistent appearance on all displays and in all screen modes. A software graphics character set file contains a set of definitions of the shape of the standard ASCII characters in the range 33 to 126 and the ISO Latin-1 8-bit characters in the range 161 to 255. If a software character set has already been loaded, a subsequent request to load it reselects that as the current character set without actually reading the character set file again. This check for a previously loaded filename is case sensitive. A selection of character sets are supplied, some of which are based on the well known Hershey fonts. The default software character set is 'Standard'. The supplied outline font character sets are as follows: Table 37: Outline Font Character Sets
Generic Filename swiss.chr fixed.chr Character Set Name Swiss Fixed Description

Equivalent to PostScript Helvetica Equivalent to PostScript Courier

Lahey/INTERACTER Starter Kit

141

Chapter 13

High Resolution Graphics


The supplied vector font character sets are as follows: Table 38: Vector Font Character Sets
Generic Filename standard.chr duplexr.chr triplexr.chr Character Set Name Standard Duplex Roman Triplex Roman Description

Simple general purpose 'plotter-style' font More detailed font Heavier font with serifs

All of these character sets should be stored in the same directory, the name of which can be defined in an operating system variable called INTCHDIR. This name can also be specified via the CHARDIR initialization file keyword. By default, INTERACTER will attempt to open the character set file exactly as specified by filnam. If this fails, it will try to open the same file in the directory named in INTCHDIR/CHARDIR. This enables system independent code to be written. By specifying the generic filename, with no directory specification, you can leave INTERACTER to pick up the name of the character sets directory externally.

Errors
ErrFileOpen (1): Error opening file. The current character set selection remains in force. ErrFileIO (2): Error reading from file or unexpected end-of-file.

Hardware-dependent

text is selected and any in-memory character set is lost.


ErrFileClose (3): Error closing file. Since by this stage the required character set data has been read from the file, that set is selected regardless of the error.

Example
CALL IGrCharSet('H') CALL IGrCharOut(100.,200.,'Hardware character set') CALL IGrCharSet(' ') IERROR = InfoError(1) IF (IERROR==1.OR.IERROR==2) THEN CALL IGrCharOut(100.,100.,'Cannot open/read char set file') ELSE CALL IGrCharOut(100.,100.,'Default Software character set') END IF CALL IGrCharSet('triplexr.chr') IERROR = InfoError(1) IF (IERROR==1.OR.IERROR==2) THEN CALL IGrCharOut(100.,100.,'Cannot open/read char set file') ELSE CALL IGrCharOut(100.,100.,'Triplex Roman') END IF

142

Lahey/INTERACTER Starter Kit

IGrCharSize Subroutine

IGrCharSize Subroutine
Description
Select graphics text size.

Syntax
IGrCharSize(xsize,ysize)

Arguments
REAL xsize = Character width (1.0 = base character width is equivalent to 75 per line ) REAL ysize = Character height (1.0 = base character height is equivalent to 25 per column)

Effect
Sets the size of characters printed by IGrCharOut. Width/height values of 1.0 give standard size text, corresponding to 75 columns by 25 rows. This character size is completely independent of screen mode, ensuring a consistent character size, regardless of the resolution of the display. Character sizes of 2.0, for example, would give text which is twice as wide and high as the default, but the X and Y sizes need not be the same. Text size is dependent on the size of the main graphics area as set by IGrArea. If IGrArea is called to rescale the size of this area, the size of graphics text is rescaled automatically. Hence, setting the width of the main graphics area to say 0.25 - 0.75, would give text which by default was half as wide, i.e., equivalent to 150 characters per line. This ensures that the size of text relative to other graphics in the main graphics area remains consistent regardless of the size of that area. However, text can quickly become unreadable in this situation, so it may be appropriate to call IGrCharSize to increase the character size when changing the main graphics area in this way. Hardware text size control is supported on most displays, though only discrete font sizes are available under DOS. Where a hardware font of the current size (or a near equivalent) is not available, INTERACTER will attempt to substitute a software font, to ensure consistent behavior across all output formats. The default character size as selected by IGrInit is 1.0 for both height and width. Attempting to select a size which is less than or equal to zero resets that size to 1.0. Text is written using fixed spacing by default, but proportionally spaced text is selectable via IGrCharSpacing('P'). When propotional spacing is enabled the exact number of characters which will fit in a given screen width will vary according to what characters are actually printed. All proportional spacing is measured in terms of the equivalent fixed character spacing, so the size factor specified here is equally applicable to both fixed and proportionally spaced text.
Lahey/INTERACTER Starter Kit

143

Chapter 13

High Resolution Graphics


Portability notes
A degree of hardware text size control is supported. A bit mapped fonts is supported which is based on a minimum text size of 8x8 pixels. Text sizes are multiples of 8 pixels, i.e., 8x8, 8x16, 16x8, 16x16, etc. The nearest appropriate size is selected according to the IGrCharSize parameters.

Example
CALL CALL CALL CALL CALL IGrCharSet(' ') IGrCharSize(1.0,1.0) IGrCharOut(100.,200.,'Standard Size Text') IGrCharSize(2.0,1.0) IGrCharOut(100.,100.,'Double width Text')

IGrCharSpacing Subroutine
Description
Select fixed or proportional spacing for graphics text.

Syntax
IGrCharSpacing(fixprop)

Arguments
CHARACTER fixprop = Required character spacing : = F: Fixed (default) (can be upper or lower case) = P: Proportional (can be upper or lower case)

Effect
Selects fixed or proportional character spacing. By default, fixed spacing is selected which causes all characters to occupy equally sized character cells. This makes text string lengths and individual character positions easy to calculate. When proportional spacing is selected, characters are spaced according to the width of a character (e.g., a W occupies nearly 3 times the width of an I). The length of a proportionally spaced string can be measured using IGrCharLength. All software character sets support proportional spacing. When hardware text is selected the effect of selecting fixed or proportional spacing is as follows: Proportional spacing: A hardware-specific Helvetica style of font will be selected, if available. If this is not available (e.g. DOS graphics mode) an equivalent software outline font will be substituted automatically (provided the character set file can be found).

144

Lahey/INTERACTER Starter Kit

IGrCharSpacing Subroutine
Fixed spacing: A Courier font or equivalent hardware font will be selected. An equivalent software outline font ('fixed') may be substituted automatically if a suitable hardware font is not available.

Example
CALL CALL CALL CALL CALL IGrCharSet('swiss.chr') IGrCharSpacing('F') IGrCharOut(100.,100.,'Fixed spacing') IGrCharSpacing('P') IGrCharOut(100.,200.,'Proportional Spacing')

Lahey/INTERACTER Starter Kit

145

Chapter 13

High Resolution Graphics

146

Lahey/INTERACTER Starter Kit

14 General Functions

Group SC: Screen Manipulation


The routines in this group control miscellaneous screen features. Most important are the INTERACTER initialization and termination routines (IScreenOpen/IScreenClose). Other routines provide screen mode selection (IScreenMode, IScreenModeN) and bell control (IScreenBell).

IScreenBell Subroutine
Description
Enable/disable/ring the bell.

Syntax
IScreenBell(onoff)

Arguments
CHARACTER onoff = 'ON' : enable the bell (upper or lower case) = 'OFF': disable the bell (upper or lower case) = Any other value to ring bell if currently enabled

Effect
Rings the bell or switches the bell on/off. By default the bell is enabled so a call to IScreenBell with a blank argument would ring the bell. However, in some environments the bell can become irritating if used frequently (it is called by IGrPause at the end of a graphics screen and by the various fixed field input routines). To stop IScreenBell producing any sound, the on/off option is provided. This does not physically switch sound off (as is possible on some hardware), it simply controls the action taken by IScreenBell when an argument other than 'ON' or 'OFF' is supplied.
Lahey/INTERACTER Starter Kit

147

Chapter 14

General Functions
Example
LOGICAL :: SOUNDOK IF (SOUNDOK) THEN CALL IScreenBell('ON') ELSE CALL IScreenBell('OFF') END IF ! now check state of bell CALL IScreenBell(' ')

IScreenClose Subroutine
Description
Terminate INTERACTER screen I/O.

Syntax
IScreenClose()

Effect
Quit/terminate INTERACTER screen handling. Call this routine when you have finished using INTERACTER to tidy up. In a windowing environment, it removes the program window. In a full-screen environment, it clears the screen and returns to a text mode. Any system dependent close down processing is also performed here. This need not be the last statement in your program, but you should not call any further INTERACTER routines without calling IScreenOpen again.
Portability notes :

If opened, the temporary graphics mode window/menu pop-up buffer file is deleted.

Example
CALL IScreenClose ! Fortran screen I/O now available again WRITE(*,*)'Bye bye ...' END

IScreenMode Subroutine
Description
Select screen mode by resolution and colors.

148

Lahey/INTERACTER Starter Kit

IScreenMode Subroutine
Syntax
IScreenMode(type,nx,ny,ncolor)

Arguments
CHARACTER type = String describing type of screen mode required: contains 'T': select text screen mode (default) contains 'G': select graphics screen mode contains 'R': give priority to resolution (default) contains 'C': give priority to number of colors (All upper or lower case)

INTEGER nx = Number of columns required (if a text mode requested) or horizontal pixels (if a graphics mode requested) INTEGER ny = Number or rows required (if a text mode requested) or vertical pixels (if a graphics mode requested) INTEGER ncolor = Number of text or graphics colors required

Effect
Selects a text or graphics screen mode using a system independent screen description. INTERACTER will then use its hardware information to select the nearest screen mode for the current display. The hardware will have been automatically identified or explicitly defined using an initialization data file, in the first call to IScreenOpen or a later call to IDisplay. It is strongly recommended that the IScreenMode routine should be used to select screen display mode, to ensure portability, in preference to the machine dependent IScreenModeN routine, unless InfoScreenMode has been used to verify a particular mode's availability. The type argument has two purposes. The first is obviously to select Text or Graphics mode. Its second, more subtle purpose is to specify how to select a mode when more than one text or graphics mode is available. By default IScreenMode will select a mode according to the following order of priorities: 1) Select mode with nearest possible horizontal resolution 2) Select mode with nearest possible number of colors 3) Select mode with nearest possible vertical resolution The first two priorities can be reversed by including a 'C' in the type argument to indicate that the number of colors should be given priority over horizontal resolution. This ensures that programs can be written on a machine with one type of display but still behave as intended on another where different modes may be available. This facility is of most use in graphics modes where code can be written to request a very high resolution, with a number of colors, yet still use a color mode when executed on a low specification display.
Lahey/INTERACTER Starter Kit

149

Chapter 14

General Functions
Attempting to select a graphics mode when the currently selected display type does not support graphics will cause IScreenMode to call the IOsExitProgram routine to terminate program execution, with exit code 13. See Error Codes on page 35. Any values are allowed for nx, ny and ncolor since INTERACTER will select a mode with the nearest equivalent. See IScreenModeN for details of display modes available on the various types of supported hardware. Since IScreenMode calls IScreenModeN, the comments under that routine regarding the resetting of colors, use of IScreenModeN in graphics mode, etc. also apply when calling IScreenMode. See also IScreenModeOptions which allows additional screen mode selection parameters to be specified.

Example
! select a graphics mode ! color more important than resolution CALL IScreenMode('GC',640,480,16) CALL IGrColourN(32) ! select a text mode: ! priority is 80 columns then 16 colors CALL IScreenMode('tr',80,25,16) ! same as last call, because we are using defaults CALL IScreenMode(' ',80,25,16)

IScreenModeN Subroutine
Description
Select screen mode by number.

Syntax
IScreenModeN(mode)

Arguments
INTEGER mode = Screen mode number (see Portability notes)

Effect
Selects screen mode by means of a system dependent mode number and clears the screen. Normally, the system independent IScreenMode should be used for this purpose, since that does not rely on system specific mode numbers. However, IScreenModeN is provided for those who wish to produce software for a particular target system. INTERACTER uses IScreenModeN for all internal mode selection, to maintain a record of screen size/resolution as well as switching between graphics and text modes.

150

Lahey/INTERACTER Starter Kit

IScreenModeN Subroutine
The values allowed for mode depend on the display hardware being used (see below). This hardware will have been automatically identified or explicitly defined using an initialization file, in the first call to IScreenOpen or a later call to IDisplay. Selecting a new mode using IScreenModeN clears the screen and resets the palette to the INTERACTER default. The screen is normally cleared to a black or 'normal-video' background (though this may be affected by the REVERSE initialization file keyword on monochrome displays). Selecting an unrecognized or unsupported screen mode clears the screen, sets an error code and leaves the current mode unchanged. InfoScreenMode can be used to check whether a mode is available before selecting it. Certain screen mode parameters can be specified via IScreenModeOptions.

Errors
ErrBadMode (41): Unknown or unsupported screen mode requested

Portability notes:
A variety of modes are supported, depending on which display adapter (CGA, EGA, MDA, HGC, MCGA or VGA) and monitor (direct drive mono, composite mono, RGB color, Enhanced color, etc.) is fitted: Table 39: DOS Screen Modes
mode
2/3 6 7 8 9 10 11 12 14 15 16 17 Text Graphics Colors Displays

80x25 80x25 80x25 90x43 80x50 132x25* 100x37* 80x30* 80x25 80x25 80x25 80x30 800x600* 640x480* 640x200 640x350 640x350 640x480 720x348 640x400 640x200

16 mono mono mono mono 16 16 256 16 mono 16 mono

VGA, MCGA, EGA, CGA VGA, MCGA, EGA, CGA VGA, Hercules, MDA, EGA+directdrive mono monitor Hercules Sub-VGA Olivetti/AT&T/Toshiba SVGA SVGA SVGA VGA, EGA+ECD, EGA+RGB VGA, EGA+direct drive mono VGA, EGA+ECD VGA, MCGA

Lahey/INTERACTER Starter Kit

151

Chapter 14

General Functions
Table 39: DOS Screen Modes
mode
18 19 20 21 22 256 257 258 259 260 261 262 263 264 265 266 267 268 284 Text Graphics Colors Displays

80x30 40x25 80x28 80x43 80x50 80x28 80x30 100x37 100x37 128x48 128x48 160x64 160x64 80x60 132x25 132x43 132x50 132x60 200x75

640x480 320x200

16 256 16 16 16

VGA VGA, MCGA VGA VGA VGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA VESA-compatible SVGA

640x400 640x480 800x600 800x600 1024x768 1024x768 1280x1024 1280x1024

256 256 16 256 16 256 16 256 16 16 16 16 16

1600x120

256

* = mode size redefinable using MODE10/MODE11/MODE12 keyword The sheer variety of IBM screen adapters can be confusing. This is another good reason why it is better to use IScreenMode, leaving INTERACTER to choose the best mode.

152

Lahey/INTERACTER Starter Kit

IScreenModeN Subroutine
There appear to be two mode numbers for the 80 column 16-color text mode, namely 2 and 3. On some monochrome CGA's mode 2 should be used, otherwise stick to mode 3. In practice both mode numbers select the same screen mode on EGA/VGA displays. Hercules graphics mode number 8 is actually an 'alternative' mode 7, but is assigned a separate mode number by INTERACTER to avoid confusion. (Mode 8 is a 'spare' mode number originally used on the long defunct IBM PC jr). Hardware text is simulated in this mode giving 90 columns by 43 rows. Additionally, INTERACTER uses mode numbers 9 to 12 to provide support for various popular non-standard screen modes. By default these modes are disabled. Each of modes 9-12 can be activated on any suitable display using MODEnn keywords in the initialization file, as documented in Initialization Data File Format on page 27. The dimensions of modes 1012 can be specified as MODEnn keyword parameters, providing support for a wide range of extra screen modes. The following mode-specific notes may be useful:
9

The 640x400 'Olivetti/AT&T' mono graphics mode requires a display using a 4-way interleave stored at segment B800h. The size of the 16-color extended text mode number 10 is definable using the MODE10 keyword. A mode which is stored at segment B800h with similar internal organization to mode 3 must be used. A multisync or SVGA monitor may be required. This is an alphanumeric mode not a graphics mode. Any text mode up to 8000 characters in size can be used. The size of the 16-color SVGA graphics mode 11 is definable using the MODE11 keyword. Four mode sizes are supported, namely 800x600, 1024x768, 1280x1024 and 1600x1200. Due to differences in VGA types, the chipset upon which a VGA board is based must also be defined with the MODE11 keyword for all except 800x600 mode.

10

11

12

The size of the 256-color SVGA graphics mode 12 is definable using the MODE12 keyword. This mode can be anything up to 1600x1200 in size. Due to differences in VGA types, the chipset upon which a VGA board is based must also be defined with the MODE12 keyword, for all modes.

On most VGA's, three additional 80 column text modes are supported with 28, 43 and 50 rows. These have been assigned INTERACTER mode numbers 20, 21 and 22 respectively (internally they are variants of screen mode 3). If display type 13 has been selected on a VESA compatible SVGA (either automatically or manually), some or all of mode numbers 256-284 will become available. Availability of these modes is identified automatically, when display 13 is selected. Otherwise, these modes will not be available and SVGA mode availability should be specified via the MODE10/ MODE11/MODE12 initialization file keywords. Text resolutions in EGA/VGA graphics modes 11, 12, 15-18, 256-263 and 284 are partly redefinable via the IScreenModeOptions routine. The text resolutions shown in the table above are the defaults if IScreenModeOptions has not been called.
Lahey/INTERACTER Starter Kit

153

Chapter 14

General Functions
Example
CALL IGrInit('C',640,200,2) ! select mode 16 on a PC with EGA and ECD IF (InfoHardware(1)==6) THEN CALL IScreenModeN(16) END IF

IScreenModeOptions Subroutine
Description
Set screen mode selection options.

Syntax
IScreenModeOptions(noptn,ivalue)

Arguments
INTEGER noptn = Option number (see below) INTEGER ivalue = Option value (see below) Table 40: IScreenModeOptions Arguments
noptn
GrModeRow TextModeBorder Flashing16

value
2 7 8

ivalue

Number of text rows in graphics mode Text mode border color (as for ITextColourN) Enable flashing text in 16-color DOS text modes IntNo (0): No IntYes (1): Yes

Effect
Defines options to be used by IScreenModeN (and hence by IScreenOpen, IScreenMode or IGrInit) when selecting screen mode. IScreenModeOptions should be called before the call which it is intended to affect. Unlike most INTERACTER routines, this means that IScreenModeOptions can therefore be called before IScreenOpen, allowing initial window size to be controlled by the program.

154

Lahey/INTERACTER Starter Kit

IScreenOpen Subroutine
When noptn = 2, ivalue specifies the preferred number of text rows to be used for menus/ windows/etc. in graphics mode. Three character heights are available to be selected in graphics modes with a vertical resolution of 350 pixels or more (except AT&T mono 640x400 mode). The available character heights are 8, 14 or 16 pixels, giving the following possible text resolutions: Table 41: DOS Screen Resolutions
Modes 12, 15, 16 12, 256 12, 17, 18, 257 11, 12, 258, 259 11, 12, 260, 261 11, 12, 262, 263 11, 12, 284 Pixels Text Resolutions

640x350 640x400 640x480 800x600 1024x768 1280x1024 1600x1200

80x21 80x25 80x43 80x25 80x28 80x50 80x30 80x34 80x60 100x37 100x42 100x75 128x48 128x54 128x96 160x64 160x73 160x128 200x75 200x85 200x150

IScreenModeN will try to select the nearest suitable vertical text resolution in graphics mode to that specified using ivalue=2. A fixed character height of 8 pixels is used in other graphics modes, so option 2 has no effect in modes 6, 8, 9, 14 and 19. IScreenModeN selects a modedependent default text resolution if IScreenModeOptions is not called or if ivalue is passed as zero.

Option 7 is supported in all 16 color text modes: 2, 3, 10, 20-22 and 264-268. Enabling option 8 limits background colors to 'normal' intensity (i.e. just 8 colors). Disabling flashing text allows bold intensity background colors to be selected. Option 8 has no effect on CGA's, where flashing text is always enabled in 16-color mode.

Example
CALL IScreenModeOptions(2,40) CALL IScreenOpen(' ','G',800,600,16)

IScreenOpen Subroutine
Description
Initialize INTERACTER screen I/O.
Lahey/INTERACTER Starter Kit

155

Chapter 14

General Functions
Syntax
IScreenOpen(initfn,type,nx,ny,ncolor)

Arguments
CHARACTER initfn CHARACTER type = Initialization data file name (blank to open default file and/or use default values) = String describing type of screen mode required One of: 'G': Select graphics screen mode (default) 'T': Select text screen mode One of: 'R': Give priority to resolution (default) 'C': Give priority to number of colors and one of: 'B' : Use a white-on-black palette (default) 'W' : Use a black-on-white palette (All upper or lower case) = Number of columns required (if a text mode requested) or horizontal pixels (if a graphics mode requested) = Number or rows required (if a text mode requested) or vertical pixels (if a graphics mode requested) = Number of text or graphics colors required

INTEGER nx INTEGER ny INTEGER ncolor

Effect
Initializes INTERACTER screen handling, attempts to read an initialization file and enters the nearest screen mode to that requested. This routine supercedes IScreenInit, which was used to initialize INTERACTER in version 3.xx and earlier. IScreenOpen allows direct entry to graphics mode and activates a slightly different set of default settings. IScreenInit is retained as a backwards compatibility routine. It is described in Appendix A, along with details of the alternative v3.xx compatible default settings which that routine activates.
Initialization File:

initfn specifies the name of an optional initialization data file which can be used to supply various information, including the display hardware, default filenames and so on. Where a filename is supplied, a suffix of .ini is recommended. The file name can be left blank if you prefer. In this case, IScreenOpen takes the following action: If the environment system variable INTINIT has been set up, the file which it specifies will be opened. If INTINIT has not been set up or the file which it points to cannot be opened, IScreenOpen searches for a file with a default name. (see Portability notes)

156

Lahey/INTERACTER Starter Kit

IScreenOpen Subroutine
If none of the above steps result in an initialization file being found, IScreenOpen will call IDisplay and IMouse with zero parameters. This causes these routines to either select default values or to attempt to automatically identify the hardware in use. In all cases, default values are assigned for any user definable initialization values which have not been read from an initialization file. (See Portability notes)
Screen Mode:

The remaining arguments specify what type of screen mode is required. The type argument is the most important of these. It should consist of up to two characters, either or both of which can be omitted in which case the indicated default is assumed. The first character can be one of:
G

Enter graphics screen mode and initialize screen graphics. This is the default. If a graphics mode is not available, IScreenOpen enters a text mode (80x25x16 or nearest equivalent). Enter text mode.

The second character can be one of:


R

Give priority to the specified resolution when more than one graphics mode is available. This is the default. Give priority to the requested number of colors, when more than one graphics mode is available.

The third character can be one of:


B

Use black as the default background color in both text and graphics modes. This is the default. Use white as the default background color. This gives a more Windows-like effect.

The nx, ny and ncolor arguments then specify the preferred resolution/color combination, in the same manner as IScreenMode. Where more than one mode of the required type is available, the nearest matching mode is selected, based on the specified priority criteria (resolution or colors).

Lahey/INTERACTER Starter Kit

157

Chapter 14

General Functions
General: IScreenOpen calls IGrInit internally to initialize INTERACTER's graphics system, with

the following effects: Calls IGrArea with parameters (0.0,0.0,1.0,1.0) Calls IGrUnits with parameters (0.0,0.0,1.0,1.0) Sets current plotting position to (0.0,0.0) Sets fill pattern to default (no fill) Sets plotting color to 223 (usually white) Sets secondary color for mixed-color fills to color 0 (usually black) Sets line type to solid Selects hardware character set and fixed spacing Sets character size to width and height of 1.0

Normally, it should not be necesary to call IGrInit directly, though it can be used to re-initialize INTERACTER's graphics. Don't call IScreenOpen twice in your programs without calling IScreenClose (the equivalent termination routine) in between. In other words, start screen handling using IScreenOpen, end it using IScreenClose and if you wish to start again call IScreenOpen, etc.
Portability notes:

Default initialization data file name Default display Default software character set file Default graphics mode menu/window pop-up buffer

: INTERACT.INI : Auto-identified : STANDARD.CHR : C:\INTTEMPW.$$$

Example
CALL IScreenOpen('initinfo.ini','G',800,600,16)

Group IF: Information


To help you find out exactly what facilities are available on the current system or to simply interrogate the state of certain INTERACTER variables, a number of functions are provided to return information to the calling program. In all cases one call to an Info function returns one item of information. The item number is normally supplied as the only argument to the function, to identify what information is required (except for InfoScreenMode which takes a second argument).

158

Lahey/INTERACTER Starter Kit

InfoAttribute Function
Several of the information functions correspond to a specific subroutine group. Hence, for information relating to the text attribute routines in group AT call InfoAttribute. Other functions return infomation which is not specific to one subroutine group, such as InfoError which provides error information. Graphics information is accessed through InfoGraphics and InfoGrScreen. InfoGraphics returns REAL data, describing the current state of various graphics parameters. InfoGrScreen returns screen graphics capability information. In all cases, specifying an invalid item number to an Info routine returns an undefined result.

InfoAttribute Function
Description
Return text attributes information.

Syntax
InfoAttribute(item)

Arguments
INTEGER item = Number of information item required: Table 42: Attribute Information items
Name BoldText No. 1 Information

Bold text suported (IntNo (0): no; or IntYes (1): yes) Flashing text supported (IntNo (0): no; or IntYes (1): yes) Reverse video supported (IntNo (0): no; or IntYes (1): yes) Underlining supported (IntNo (0): no; or IntYes (1): yes) Number of foreground text colors Number of background text colors Bold text requested (IntNo (0): no; or IntYes (1): yes)

FlashingText

ReverseVideo

UnderlineText ForeTextCol BackTextCol BoldRequest

5 6 7 8

Lahey/INTERACTER Starter Kit

159

Chapter 14

General Functions
Table 42: Attribute Information items
Name FlashingRequest No. 9 Information

Flashing text requested (IntNo (0): no; or IntYes (1): yes) Reverse video requested (IntNo (0): no; or IntYes (1): yes) Underlining requested (IntNo (0): no; or IntYes (1): yes) Foreground text color requested (0-15) Background text color requested (0-15)

ReverseRequest

11

UnderlineRequest ForeColRequest BackColRequest

12 13 14

Effect
Returns information about the availability and requests for text attributes. item's 1-7 return attribute support information for the current screen mode on the current display. If the current mode is monochrome the number of colors (item's 6 and 7) are both returned as one, otherwise values of 8 or 16 are returned. item values 8-14 can be used to determine what attributes or colors have been most recently requested. This information is independent of whether specific attributes or color are actually supported on the current display. Text color numbers are returned using the same numbering scheme as ITextColourN.

Example
IF (InfoAttribute(6>2) THEN CALL ITextColourN(1,-1) END IF

InfoError Function
Description
Return error information.

Syntax
InfoError(item)

160

Lahey/INTERACTER Starter Kit

InfoError Function
Arguments
INTEGER item = Number of information item required: Table 43: Error Information items
Name No. Information

LastError

Last error set by INTERACTER (0 if no errors since last call to InfoError(1) (see Error Codes on page 35 for a list) System-dependent I/O code for last type 1 or 2 error (file open or read/write error), otherwise undefined

IOErrorCode

Effect
Returns information about the last error to be detected. If no errors have occurred since startup or since the last call to InfoError, the last error is returned as zero. If several errors have occurred since the last call to InfoError, only the most recent error is returned. A call to InfoError also resets the 'last error', or IOSTAT value (depending on the value of item) to zero. This feature can be used to clear the error flags, when your program is uncertain of what errors may already have occurred. If a type 1 or type 2 error occurs (error on file/device open, read or write), a call with an item value of 2 returns the associated Fortran OPEN/READ/WRITE statement IOSTAT value or operating system I/O routine error code. Such I/O errors can occur in IScreenInit or IGrCharSet. This IOSTAT value will still be available if further I/O is performed or other non I/O errors occur. i.e., The error code for an I/O error remains available until it is cleared using InfoError(2) or until another I/O error occurs.

Example
CHARACTER (LEN=6) :: STR ! clear error flag first IErrorOld = InfoError(1) IStatOld = InfoError(2) CALL IGrCharSet('myset.chr') IError = InfoError(1) IF (IError==1.OR.IError==2) THEN CALL IOutString('Load error: I/O error code = ') IStat = InfoError(2) CALL IntegerToString(IStat,STR,'(I6)') CALL IOutString(STR) END IF

Lahey/INTERACTER Starter Kit

161

Chapter 14

General Functions

InfoGraphics Function
Description
Return real graphics mode information.

Syntax
InfoGraphics(item)

Arguments
INTEGER item = Number of information item required: Table 44: Graphics Mode Information items
Name GraphicsX No. 1 Information

Current X plotting position (in user units as set in IGrUnits) Current Y plotting position (in user units as set in IGrUnits) Current character width (in user units as set in IGrUnits) Current character height (in user units as set in IGrUnits) Mouse X position at last mouse/key event (in user units as set in IGrUnits) Mouse Y position at last mouse/key event (in user units as set in IGrUnits) Left limit of main graphics area Lower limit of main graphics area Right limit of main graphics area Upper limit of main graphics area Lower X co-ordinate limit Lower Y co-ordinate limit Upper X co-ordinate limit Upper Y co-ordinate limit

GraphicsY

GraphicsChWidth

GraphicsChHeight

GraphicsMouseX

GraphicsMousey GraphicsAreaMinX GraphicsAreaMinY GraphicsAreaMaxX GraphicsAreaMaxY GraphicsUnitMinX GraphicsUnitMinY GraphicsUnitMaxX GraphicsUnitMaxY

6 7 8 9 10 11 12 13 14

162

Lahey/INTERACTER Starter Kit

InfoGrScreen Function
Effect
Returns certain REAL graphics mode parameters. These are generally dynamic values which change depending on calls to other graphics routines. See also InfoGrScreen which returns INTEGER data, mainly describing the capabilities of the current display or screen mode. The current plotting position, as set by IGrMoveTo and other routines, is accessible using item values 1 and 2. The current graphics text character size (item's 3 and 4) is derived from the size set using IGrCharSize and converted to user plotting units. This can be useful in calculating the extent of a graphics string to be output by IGrCharOut. item's 5 and 6 will normally be interrogated as a pair, since they return the graphics co-ordinate of the mouse cursor at the last mouse or keyboard press. This information will be meaningful when InfoInput(55) returns -2 or when InKeyEvent/InKeyEventImm returns anything other than an expose/resize event. The former situation will occur if a mouse button is pressed outside the input area in a fixed-field/menu input routine and InMouseOptions(2,1) has been called. InfoGraphics(5/6) should only be interrogated when graphics screen mode is enabled. item's 7 to 10 return the graphics area dimensions as most recently specified to IGrArea. Similarly, item's 11 to 14 return the user definable graphics area co-ordinates as most recently specified to IGrUnits. Be sure to declare InfoGraphics as REAL, as in the example below.

Example
REAL :: InfoGraphics ! write a blue string on a white background WIDTH = FLOAT(LEN(STRING))*InfoGraphics(3) HEIGHT = InfoGraphics(4) CALL IGrMoveTo(X,Y) CALL IGrColourN(223) CALL IGrFillPattern(4,0,0) CALL RECTANGLE(WIDTH,HEIGHT) CALL IGrCharSet(' ') CALL IGrCharJustify('L') CALL IGrcolorN(159) CALL IGrCharOut(X,Y+HEIGHT/2.0,STRING)

InfoGrScreen Function
Description
Return graphics facilities information (screen).
Lahey/INTERACTER Starter Kit

163

Chapter 14

General Functions
Syntax
InfoGrScreen(item)

Arguments
INTEGER item = Number of information item required: Table 45: Graphics Screen Information items
Name GraphicsAvail No. 1 Information

GraphicsAvailable (IntNo (0): no; or IntYes (1): yes) Background color redefinable (IntNo (0): no; or IntYes (1): yes) Foreground colors redefinable (IntNo (0): no; or IntYes (1): yes) Hardware text size control (IntNo (0): no; or IntYes (1): yes) Palette changes affect existing plot (IntNo (0): no; or IntYes (1): yes) Presentation quality hardware fonts (IntNo (0): no; or IntYes (1): yes) Number of colors in current mode Number of colors in any mode Aspect ratio as a percentage Last but one requested graphics color Most recently requested color Most recently requested line type

PaletteBack

PaletteFore

HardTextSize

19

PaletteChange

24

QualityFonts ColNumAvailable ColNumMax AspectRatio PrevColReq ColorReq LineTypeReq

27 30 31 32 34 35 36

Effect
Returns information about the graphics facilities available on the current display in the current mode. The value returned is an INTEGER. Some displays do not support graphics at all. This can be interrogated using an item value of 1. When called on a display which does not support graphics or in a non-graphics screen mode, the information returned for other item numbers is undefined.

164

Lahey/INTERACTER Starter Kit

InfoHardware Function
item values 8, 9 and 24 determine the palette redefinition capabilities of the current display, as controlled by IGrPaletteRGB. The ability to redefine the background color (color 0) or the foreground colors (color 1 upwards) can be determined by specifying item=8 or 9. If palette changes affect graphics which have already been plotted, item 24 will return 1. Otherwise, if only subsequent plotting is affected, it returns 0. If hardware text size control is available via IGrCharSize, InfoGrScreen(19) will return 1. item 27 identifies whether presentation quality hardware fonts are available (i.e. TrueType or equivalents). Since the number of colors available varies significantly from one display to another and from one mode to another, information item numbers 30 and 31 are provided. These return the number of colors available in the current mode and the maximum number available in any mode on the current display. In a monochrome mode the number of colors is returned as two. The aspect ratio of the current display is returned as a percentage. For example, on a display with an aspect ratio of 1.4, InfoGrScreen(32) would return a value of 140. This aspect ratio is used internally by INTERACTER when drawing circles/ellipses, but can also be useful in applications which require a shape to be rotated without distortion. item's 34 and 35 return the last two color numbers which have been requested. The color returned by item 34 is only used in stippled fills. item 35 is the currently selected color. item 36 returns the last line type requested via IGrLineType.

Example
IF (InfoGrScreen(1)==0) THEN CALL IOutString('Sorry but you don't have graphics') ELSE CALL IGrInit(' ',640,250,16) END IF

InfoHardware Function
Description
Return hardware information.

Syntax
InfoHardware(item)
Lahey/INTERACTER Starter Kit

165

Chapter 14

General Functions
Arguments
INTEGER item = Number of information item required: Table 46: Graphics Screen Information items
Name DisplayType MouseType No. 10 13 Information

Display type (see IDisplay) Mouse type (see IMouse) Report VESA support 0: If VESA BIOS not available non-zero: VESA BIOS installed

VESAsupport

32

Effect
Returns information about the hardware on which the program is currently running. The value returned is an INTEGER. The display and mouse type are as described in Supported Hardware on page 19. They may be identified automatically, or set via IDisplay/IMouse, or defined in an initialization file. item 32 is intended for use with the DOS version of INTERACTER, but is implemented in such a way that it can safely be used with all implementations. It determines whether a VESA video BIOS is installed (either in hardware or as a TSR). If not, a value of 0 is returned (all non-DOS versions always return 0). A non-zero result means that the video BIOS reports one or more VESA standard SVGA modes as being available. In this case, the returned value bit encodes mode availability. Bit 0 is set if mode 256 is available, bit 1 is set of mode 257 is available and so on. See the Portability notes for IScreenModeN for a list of VESA mode numbers.

Example
IF (InfoHardware(13)<3) THEN CALL IOutStringXY(1,1,'This program & & requires a 3 button mouse !') CALL InKeyEvent(KEY) END IF

InfoInput Function
Description
Return keyboard input facilities information.

166

Lahey/INTERACTER Starter Kit

InfoInput Function
Syntax
InfoInput(item)

Arguments
INTEGER item = Number of information item required: Table 47: Input Handling Information items
Name No. 1-50 NumFunKeys KeypadMode EditMode 51 53 54 Information

Key code assigned to input control key 1-50 (see InControlKey for list of control keys) Number of function keys available Current keypad mode as set by InKeypad(1-3) Current insert/overtype mode (OverMode (0): overtype; InsMode (1): insert) Last key used to exit from an input/menu routine (-2, -1, 21-30, or 36-50) Cursor/keypad keys availability (NoKeypad (-1): no keypad identification; SharedKP (0): shared; SeparateKP (1): separate) Current pop-up mode as set by InPopup (IntNone (0): disabled; SinglePop (1): single; LinkedPop (2): linked) Mouse button pressed on exit from field/menu (IntNone (0): none; LeftButton (1): left; MiddleButton (2): middle; RightButton (3): right) Text column of mouse cursor at last mouse/key event Text row of mouse cursor at last mouse/key event Event mask as set by InEventSelect
InEventKey code returned by IGrPause

LastExitKey

55

KeypadType

56

PopUps

58

ExitMouseButton

61

MouseTextCol MouseTextRow EventMask PauseKey

62 63 66 67

Lahey/INTERACTER Starter Kit

167

Chapter 14

General Functions
Table 47: Input Handling Information items
Name ExitOutside MouseTime ConfirmFixedButton No. 68 70 106 151170 Information

Exit on mouse click outside input area (0=no; 1=yes) Time of last mouse event in centiseconds Special-action mouse button set by InMouseOptions Key code assigned to input control key nos. 51-70 (see InControlKey for list of control keys)

Effect
Returns information about the input control keys and the input handling facilities. The value returned is an INTEGER. Each of the input control keys which are definable using InControlKey can be interrogated using item numbers in the range range 1-50 or 151-170. item 51 returns the number of function keys which INTERACTER believes to be available on the current display. item 54 identifies the insert/overtype state as most recently set by the user pressing the 'toggle insert' key. item 55, the last 'exit' key to be pressed, is a particularly useful piece of information when processing input. It returns a value in the range 21-30 or 36-70 indicating which of the 'exit' keys (as defined by InControlKey) was pressed to terminate input to the most recently called input routine. InfoInput(55) is set by any of the routines from groups IN or MN. A value of 22 for example means that the help key was pressed. Under certain circumstances it can also return another possible value: If 'exit on click-outside input area' is enabled, (see InMouseOptions(2,n)), fields/ menus can return InfoInput(55) set to -2. The mouse button number/position are then available via InfoInput(61-63).

item 56 returns a flag which indicates whether keypad keys are identifiable and if so whether separate cursor and keypad keys are available. A return value of -1 indicates that the keypad cannot be identified as such at all. A return value of 0 or 1 means that the keypad can be identified. If the cursor keys and keypad are shared (as on the old 'Standard' keyboard) a value of 0 is returned. This may be useful in selecting the keypad mode to use with InKeypad. item 58 returns the current menu/input-box pop-up mode, as set by InPopup. item 61 returns the mouse button number used to exit from a fixed field or menu routine. This will be available when any of these routines return InfoInput(55) set to -2 or when a menu returns a value of 21. In the latter case, item 61 will return zero if a keyboard key was used to confirm a menu option.

168

Lahey/INTERACTER Starter Kit

InfoScreen Function
item's 62 and 63 will normally be interrogated as a pair, since they return the text column/ row position at which a mouse or keyboard event last occurred. These values are updated by any routine which performs input processing, so it is important that they should be interrogated immediately after the subroutine call to which they relate. item 66 returns the current event mask as set or modified by InEventSelect. This describes the current selection state of all events as would be set by a single call to InEventSelect(0,n). This value is therefore suitable for saving and restoring the event state in a general purpose routine since it can be passed directly to InEventSelect(0,n). item 67 returns the code which was returned by the call to InKeyEvent in the IGrPause routine. If non-keyboard event reporting is enabled via InEventSelect, this may be a nonkeystroke value. item 68 returns the current setting of the 'exit on mouse click outside input area' option, selectable via InMouseOptions(2,n). item 70 returns the time at which the last mouse button up/down or movement event occurred. The time is reported in centi-seconds since an arbitrary start time. This start time varies between implementations. Note that the time stamp can wrap round to zero after an implementation dependent period of time, so time stamp checks should allow for this possibility. item 106 returns the mouse button numbers assigned to special actions by the equivalent InMouseOptions option (0=none).

Portability notes
item 56 can be used to establish whether a standard or enhanced keyboard is being used. A standard keyboard returns 0 and an enhanced keyboard returns 1.

Example
CALL InMouseOptions(2,1) IOPT = IMenuVertic(OPT,MAXOPT,IX,IY,'Menu',ISPC,IFRM,ISTOPT) KEXIT = InfoInput(55) IF (KEXIT==-2) THEN MOUSEX = InfoInput(62) MOUSEY = InfoInput(63) ELSE IF (KEXIT==23) THEN ...

InfoScreen Function
Description
Return screen mode information (current mode).
Lahey/INTERACTER Starter Kit

169

Chapter 14

General Functions
Syntax
InfoScreen(item)

Arguments
INTEGER item = Number of information item required: Table 48: Screen Mode Information items
Name ScrMode TextColumns TextRows HorizPixels No. 1 2 3 4 Information

Current screen mode Number of text columns in current mode Number of text rows in current mode Horizontal graphics pixel resolution (zero in a text mode) Vertical graphics pixel resolution (zero in a text mode) Max number of modes available

VerticPixels ScrMaxModes

5 6

Effect
Returns information about the current screen mode. The value returned is an INTEGER. See also InfoScreenMode which returns information about any mode. The current screen mode number is display dependent. See IScreenModeN for lists of supported screen mode numbers. The number of columns and rows returned by item values 2 and 3 define the dimensions of the text screen as written to by the text handling routines in the OU, CU, CG, WN, IN, MN, etc. groups. When called in a graphics mode these values have nothing to do with the dimensions of graphics hardware text as output by IGrCharOut. The pixel resolution of the current graphics mode should not normally be required since the graphics routines are independent of screen resolution, but this information is made available for those wishing to produce hardware dependent graphics displays. item 6 returns the highest valid screen mode number recognized by IScreenModeN in the current implementation of INTERACTER. This is also the highest mode number which can be specified to the complementary InfoScreenMode function which can return information about any screen mode.

170

Lahey/INTERACTER Starter Kit

InfoScreenMode Function
Example
NROWS = InfoScreen(3) CALL IOutStringXY(1,NROWS,'This is & & on the bottom screen row')

InfoScreenMode Function
Description
Return screen mode information (any mode).

Syntax
InfoScreenMode(item,mode)

Arguments
INTEGER item = Number of information item required: Table 49: Screen Mode Information items
Name No. Information

ModeType

Mode availability/type (IntNo (0): unavailable; TextOnly (1): text-only mode; TextAndGraphics (2): Graphics and text mode; Redundant (-1): Redundant text-only mode) Number of text columns in specified mode Number of text rows in specified mode Horizontal graphics pixel resolution (zero in a text mode) Vertical graphics pixel resolution (zero in a text mode) Number of colors

TextColumns TextRows HorizPixels

2 3 4

VerticPixels NumColors

5 6

INTEGER mode = Screen mode number (0 to InfoScreen(6)) Returns information about the availability and characteristics of the specified screen mode. The value returned is an INTEGER. See also InfoScreen which returns information about the current mode. Unlike most other functions in the IF subroutine group, InfoScreenMode takes two arguments. The mode argument must be a valid screen mode number in the range
Lahey/INTERACTER Starter Kit

171

Chapter 14

General Functions
0 to InfoScreen(6). The latter is the highest valid mode number on the current display. Specifying a mode number which is outside this range will return a value of 0, regardless of

which item code is specified. item 1 identifies whether a mode is available and, if so, its type. The last return code only occurs on certain systems. See the Portability notes below for details. The values returned by item's 2-6 are undefined if item 1 returns 0. Always check that a mode is available, before interrogating its dimensions or number of colors. The number of columns and rows returned by item values 2 and 3 define the dimensions of the text screen as written to by the text handling routines in the OU, CU, CG, WN, MN, etc. groups. When mode identifies a graphics mode these values have nothing to do with the dimensions of graphics hardware text output by IGrCharOut. The pixel resolutions returned by item's 4 and 5 will only be non-zero if mode identifies a graphics mode. A demo program called 'whatmode' is supplied which shows how InfoScreenMode can be used to build a menu of available graphics modes, to allow mode selection on screens which support more than one graphics mode.

Portability notes
item 1 only returns a value of -1 in PC screen modes 2 or 3. These modes are effectively identical, with only one of the two modes ever being used on a particular display. The mode which is not used, remains selectable via IScreenModeN, but returns -1 via InfoScreenMode(1,MODE) to indicate that the mode is available but effectively redundant.

172

Lahey/INTERACTER Starter Kit

InfoWindow Function
Example
MAXMOD = InfoScreen(6) DO MODE = 0,MAXMOD IF (InfoScreenMode(1,MODE)==1.OR. & InfoScreenMode(1,MODE)==3) THEN IF (InfoScreenMode(2,MODE)==132) THEN CALL IScreenMode('T',132, & InfoScreenMode(3,MODE),& InfoScreenMode(6,MODE)) EXIT END IF END IF END DO CALL IOsExitProgram('Cannot find a 132 column text mode.',99)

InfoWindow Function
Description
Return window management system information.

Syntax
InfoWindow(item)

Arguments
INTEGER item = Number of information item required: Table 50: Window Information items
Name WinCurNumber WinAvailable WinBufferSpace WinLeftColumn WinTopRow WinWidth WinHeight No. 1 2 3 4 5 6 7 Information

Current window number Number of windows still available to be opened Remaining space in the internal window buffer Screen column of top left corner of window Screen row of top left corner of window Width of current window excluding frame Height of current window excluding frame

Lahey/INTERACTER Starter Kit

173

Chapter 14

General Functions
Table 50: Window Information items
Name WinTopNumber WinCursorX WinCursorY WinFrameMode No. 8 9 10 11 Information

Top window number (i.e., number of open windows) Current window (X) cursor position Current windows (Y) cursor position Frame mode selected (0=none 1=Titled 3=Boxed title) Pop-up mode selected (IntNo (0): no; IntYes (1): yes) Clear mode selected (IntNo (0): no; IntYes (1): yes) Title justification (WindowLeft (1): left; WindowCenter (2): center; WindowRight (3): right) Wide title mode selected (0=no; 1=yes)

WinPopupMode

12

WinClearMode

13

WinTitle

14

WinTitleMode

17

Effect
Returns information about the current status of the text window management system. The value returned is an INTEGER. The current and top window numbers can be interrogated using item numbers 1 and 8 respectively. By default, these will be the same when IWinOpen has just been called. There is a limit on the number of simultaneously open windows. Specify an item value of 2 to find how many are still available to be opened. The internal window buffer is used to store the old screen contents when 'pop-up' mode has been enabled by IWinAction. There must be sufficient space available in this buffer to enable the pop-up window feature to operate correctly. The returned value is expressed in terms of the number of screen character positions which can still be copied into the buffer. This information is consistent across all displays in all screen modes. Hence, if a window is to be opened which will occupy 40 columns by 10 rows (including frame), there must be room for at least 400 screen characters in the buffer. item values 4 to 7 return the position and size of the current window, excluding any frame.

174

Lahey/INTERACTER Starter Kit

Group OS: Operating System Interface


The current position of the window cursor, as set by IWinCursorXY or any of the window output routines, can be obtained using item values 9 and 10. These are cursor positions relative to the top left corner of the window. item's 11-14 and 17 return the various modes used by the window manager when opening a window, as set by IWinAction.

Example
IAVAIL = InfoWindow(2) IF (IAVAIL>0) THEN CALL IWinOpen(20,10,60,20) END IF

Group OS: Operating System Interface


The routines in this group provide access to environment variables (IOsVariable) and allow controlled program termination with a message (IOsExitProgram).

IOsExitProgram Subroutine
Description
Abort program with an error message and error code.

Syntax
IOsExitProgram(errmes,iexcod)

Arguments
CHARACTER errmes = Error message to display to the user. (if blank, error message display is suppressed) INTEGER iexcod = Exit code to return to operating system

Effect
Aborts the current program, in a controlled manner. This routine is designed to be used when an unexpected fatal error is encountered. It first tidies up the screen and keyboard handling, then exits from the program. An exit code is returned to the operating system and the following optional message is displayed on the screen:
** Abnormal exit ** Exit code: nn ** your-error-message

Lahey/INTERACTER Starter Kit

175

Chapter 14

General Functions
The actual exit code and message will depend on what was passed in iercod and errmes. If you do not want a message to be displayed, but prefer to check the returned exit code within an operating system command procedure, leave errmes blank. The above error message will then be suppressed. See the Portability notes for more information on checking program exit codes. In general it is recommended that exit codes greater than 20 are used. Codes from 1 to 20 are reserved for use by INTERACTER. See Exit Codes on page 37 for a list of the possible exit codes which INTERACTER can generate. These exit codes should not be confused with the error codes in Error Codes on page 35. INTERACTER will virtually always set an error code in preference to calling IOsExitProgram, as this enables the calling application to decide what action is appropriate. If you wish to leave a program immediately, but without issuing either an error message or a non-zero exit code, simply supply a blank error message and an IEXCOD value of zero.

Portability notes
In a DOS batch file, the exit code can be checked using IF ERRORLEVEL , e.g.
INTPROG IF ERRORLEVEL 21 GOTO USERERR IF ERRORLEVEL 1 GOTO INTERR GOTO EXIT :USERERR ECHO User programmed abort. GOTO EXIT :INTERR ECHO INTERACTER generated abort :EXIT

Example
IClearOldError = InfoError(1) CALL IGrCharSet('chars.chr') IF (InfoError(1)==1) & CALL IOsExitProgram('Cannot open character set file',21)

IOsVariable Subroutine
Description
Return the value of an operating system (environment) variable.

Syntax
IOsVariable(vname,value)

176

Lahey/INTERACTER Starter Kit

Group HW: Hardware Identification


Arguments
CHARACTER vname = Name of variable to interrogate CHARACTER value = Returned value (blank if not found)

Effect
Returns the value of the specified environment variable. They provide a useful method of passing system dependent values, such as filenames, to a program without the need to use a data file or command line arguments. If the specified variable name has not been initialized or has no value, value will be returned blank. In general it is a good idea to stick to upper case for environment variables. IOsVariable performs no case translation, so it pays to be consistent.

Portability notes
IOsVariable returns environment variables as assigned using the SET command. The oper-

ating system converts all variable names to upper case, so the supplied variable name vname must also be in upper case. When defining environment variables using SET, avoid trailing spaces between the variable name and the '=' since these will be treated as part of the variable name. IOsVariable strips trailing blanks from the supplied variable name.

Example
CHARACTER (LEN=80) :: FILNAM CALL IOsVariable('DEFDATA',FILNAM) IF (IActualLength(FILNAM)>0) THEN OPEN(20,FILE=FILNAM,STATUS='OLD') ELSE OPEN(20,FILE='default',STATUS='OLD') END IF

Group HW: Hardware Identification


These routines are used to identify the display or mouse hardware being used. In general, there should be no need to call these routines directly. They are all called automatically by IScreenOpen, so the information they require is better supplied via the initialization file.

IDisplay Subroutine
Description
Select display type
Lahey/INTERACTER Starter Kit

177

Chapter 14

General Functions
Syntax
IDisplay(idispl)

Arguments
INTEGER idispl = Display type number (seeSupported Hardware on page 19)

Effect
Defines the display hardware, and clears the screen. This ensures that INTERACTER knows precisely what screen facilities are available and what is on the screen. This routine is always called by the start up routine IScreenOpen, either with a parameter of zero or with a user supplied display number (specified via the INTTERM environment variable or the initialization file DISPLAY keyword). If you can't specify the hardware at start up, IDisplay can be called directly, later in your program to ensure that INTERACTER takes best advantage of the screen hardware being used. If an invalid display number is specified (e.g., zero), IDisplay attempts to identify the display being used or selects a 'lowest common denominator' default value. However, there will normally be little advantage in doing this since IScreenInit will already have called IDisplay with at least a zero parameter. Whatever method of display identification is used, you can interrogate the currently identified hardware type using InfoHardware.

Portability notes
See Supported Hardware on page 19.

Example
CALL IScreenOpen(' ') ! this program requires an IBM PC with VGA/color CALL IDisplay(10)

IMouse Subroutine
Description
Select mouse type.

Syntax
IMouse(imous)

Arguments
INTEGER imous = Mouse number (see chapter 5 of the User Guide)

178

Lahey/INTERACTER Starter Kit

Group CH: Character Manipulation


Effect
Defines the type of mouse to be used. A value of 1 for imous indicates that no mouse is fitted (or is to be disabled), in which case the keyboard will always be used. This routine is always called by the start up routine IScreenOpen, either with a parameter of zero or a value specified in the initialization file using the MOUSE keyword. If the mouse type is not defined explicitly at start up, IMouse can be called directly, later in your program to ensure that INTERACTER takes best advantage of the mouse type being used. If a value other than those listed in Supported Hardware on page 19 is specified (e.g., zero, as may be the case when IScreenInit calls IMouse), INTERACTER will select its own value. See the Portability notes for the precise action. Whatever method of mouse identification is used, you can interrogate the currently identified hardware type using InfoHardware.

Portability notes
IMouse always checks whether the MOUSE.COM (or equivalent) mouse driver has been

installed and whether the mouse hardware is responding. If no mouse is found, the mouse type is forced to 1, regardless of the value of imous. If a mouse is found, action depends on imous. If imous = 1the mouse will be ignored; If imous = 2/3, a 2 or 3 button mouse, as specified: If imous = any other value, then a 2 or 3 button mouse according to information returned by the mouse driver software.

Example
CALL IScreenOpen(' ') ! this program requires at least a two-button mouse IF (InfoHardware(13)==1) THEN CALL IOutStringXY(1,2,'This program requires a mouse') CALL InKeyEvent(Key) END IF

Group CH: Character Manipulation


The routines in this group are not strictly screen control functions. However, since any screen handling involves considerable manipulation of textual information, they provide useful basic facilities such as string to numeric conversion, sub-string location, case conversion and so on. Some duplicate Fortran 90 intrinsics, but are required internally by INTERACTER (which also supports FORTRAN 77 compilers).
Lahey/INTERACTER Starter Kit

179

Chapter 14

General Functions

IActualLength Function
Description
Return actual length of string excluding trailing blanks or nulls.

Syntax
IActualLength(string)

Arguments
CHARACTER string = String to search

Effect
Returns an INTEGER with the actual length of the character string held in string, excluding any trailing spaces or nulls. If the string is completely blank, (i.e., only contains spaces and/ or nulls) zero is returned. IActualLength is a replacement for the standard LEN function which simply returns the length of a character variable not the length of the string which is held in it.

Example
CHARACTER (LEN=9) :: STR LASTCH = IActualLength(STR) IF (LASTCH/=LEN(FILNAM)) & IOutString('STR has trailing blanks')

IFillString Subroutine
Description
Fill a character string with a given character.

Syntax
IFillString(string,chr)

Arguments
CHARACTER string = String to be filled CHARACTER chr = Character to fill string with (note: only first character of chr is used)

Effect
Fills the whole of string with the first character of chr.

180

Lahey/INTERACTER Starter Kit

IJustifyString Subroutine
Example
CHARACTER (LEN=80) :: STARS CALL IFillString(STARS,'*')

IJustifyString Subroutine
Description
Justify a string within a character variable.

Syntax
IJustifyString(string,lcr)

Arguments
CHARACTER string = Variable containing string to justify (also receives returned string) CHARACTER lcr = Justification required: = 'L' : Left justify (upper or lower case) = 'C' : center justify (default) ) (upper or lower case) = 'R' : Right justify (upper or lower case)

Effect
Justifies a string within the character variable which holds it. This routine is provided to overcome the inability of many Fortran compilers to reference the same character variable on both sides of an assignment statement. Moving a string within a character variable normally requires two steps via a temporary variable. IJustifyString packages up this operation into a simple subroutine call, dealing at the same time with the chores of calculating the old and new string positions. Note that in the sense used here, a "string" is defined as all characters from the first non-blank character to the last non-blank character within the character variable string. Since IJustifyString justifies the string within the supplied variable itself, string must be passed as a variable rather than as a literal string. If string is blank, IJustifyString takes no action.

Example
CHARACTER (LEN=12) :: TITLE TITLE = ' Help Menu ' CALL IJustifyString(TITLE,'L') ! variable TITLE will now contain: 'Help menu ' CALL IJustifyString(TITLE,'C') ! variable TITLE will now contain: ' Help menu ' CALL IJustifyString(TITLE,'R') ! variable TITLE will now contain: ' Help menu'

Lahey/INTERACTER Starter Kit

181

Chapter 14

General Functions

ILocateChar Function
Description
Locate position of first non blank character.

Syntax
ILocateChar(string)

Arguments
CHARACTER string = String to search

Effect
Locates and returns the position (an INTEGER) of the first non-blank/non-null character within string. If the string contains only blanks and nulls, zero is returned.

Example
CHARACTER (LEN=20) :: FILNAM CALL InString(FILNAM,LEN) IPOS1 = ILocateChar(FILNAM)

ILocateString Subroutine
Description
Locate position of first non blank sub-string.

Syntax
ILocateString(string,istart,iend)

Arguments
CHARACTER string = String to search INTEGER istart = Start position of first non-blank string INTEGER iend = End position of first non-blank string Locates the first sub-string within string, returning the start and end positions in istart and iend. If string is blank istart and iend are returned as zero. This routine is similar to the function ILocateChar except here the start and end positions are returned, rather than just the start position.

182

Lahey/INTERACTER Starter Kit

ILowerCase Subroutine
Example
CHARACTER (LEN=80) :: STRING READ(LFN,'(A80)') STRING CALL ILocateString(STRING,ISTART,IEND) IF (ISTART>0) THEN CALL IOutStringXY(10,4, & 'First substring is ',STRING(ISTART:IEND)) ELSE CALL IOutStringXY(10,4,'Blank string') END IF

ILowerCase Subroutine
Description
Convert a string to lower case.

Syntax
ILowerCase(string)

Arguments
CHARACTER string = String to be converted to lower case

Effect
Converts any upper case characters in string to lower case.

Example
CHARACTER (LEN=10) :: STRING STRING = 'ABCDE12345' CALL ILowerCase(STRING) ! string should now be abcde12345

IntegerToString Subroutine
Description
Convert an integer value to a string.

Syntax
IntegerToString(ivalue,string,frmat)
Lahey/INTERACTER Starter Kit

183

Chapter 14

General Functions
Arguments
INTEGER ivalue = Integer value to convert to a string CHARACTER string = Character variable to receive numeric CHARACTER frmat = Character string defining format to use (a bracketed expression as in a Fortran FORMAT)

Effect
Converts an INTEGER value into a string using the specified Fortran format. If an error occurs, (e.g., ivalue is too large) string is filled with asterisks. IntegerToString is the reverse of IStringToInteger.

Errors
ErrNumToStr (18): Numeric-to-string conversion error.

Example
CHARACTER (LEN=5) :: CHR I = 100 CALL IntegerToString(I,CHR,'(I5)') CALL IOutString(CHR)

IStringToInteger Subroutine
Description
Convert a string to an integer value.

Syntax
IStringToInteger(string,ivalue)

Arguments
CHARACTER string = String containing number to be converted. INTEGER ivalue = INTEGER value to be returned

Effect
Converts the first substring of string into an integer value. The numeric in string must be a valid INTEGER, optionally including a leading +/- sign. If an error occurs during conversion ivalue is returned as zero and the INTERACTER error flag is set. IStringToInteger is the reverse of IntegerToString.

Errors
ErrLargeNum (4) : Number too large (exceeds 4-byte INTEGER limits)

184

Lahey/INTERACTER Starter Kit

IUpperCase Subroutine
ErrNoSubstring (10): No substring found (string is blank) ErrBadChar (12): Invalid character detected (i.e., not 0123456789 or leading +/-)

Example
CHARACTER (LEN=80) :: LINE CHARACTER (LEN=10) :: VALSTR CALL InString(LINE,LENLIN) CALL IStringToInteger(LINE(:LENLIN),IVALUE) IF (InfoError(1)>0) THEN CALL IOutStringXY(10,4,'Wrong !!') ELSE CALL IntegerToString(IVALUE,VALSTR,'(I10)') CALL IOutStringXY(10,4,'Value = '//VALSTR) END IF

IUpperCase Subroutine
Description
Convert a string to upper case.

Syntax
IUpperCase(string)

Arguments
CHARACTER string = String to be converted to upper case

Effect
Converts any lower case characters in string to upper case.

Example
CHARACTER (LEN=10) :: STRING STRING = 'abcde12345' CALL IUpperCase(STRING) ! string should now be ABCDE12345

Lahey/INTERACTER Starter Kit

185

Chapter 14

General Functions

186

Lahey/INTERACTER Starter Kit

A Obsolete Routines

Since INTERACTER is a continuously developing product, some features inevitably become superceded. Routines which are no longer required or recommended are moved to this "Obsolete Routines" group. Mostly, they are routines which are still supported, for the sake of backwards compatibility but are not intended to be used in new applications. Up to version 3.xx, INTERACTER's initialization and termination routines were best suited to full screen environments such as DOS. Graphics mode entry and termination was handled separately via IGrInit/IGrQuit. At version 4.0, IScreenOpen and IScreenClose were introduced to allow direct entry to graphics mode at initialization and tidier termination in windowing environments. At the same time a number of new, more appropriate default settings were introduced which are automatically enabled by calling IScreenOpen. The old IScreenInit, IScreenQuit and IGrQuit routines have therefore been moved to this Obsolete Routines group, but are still callable and still activate v3.xx compatible defaults. This ensures backwards compatibility. However, conversion to the new initialization/termination routines will ensure better results in windowing environments and simplified programming thanks to more appropriate defaults.

IGrQuit Subroutine
Terminates graphics processing, returning to the mode which was selected when IGrInit was last called. Since graphics initialization and termination is now incorporated into IScreenOpen and IScreenClose, there is no longer any need to call this routine. Typically this routine should only be called in programs which use IScreenInit/IScreenQuit and only in combination with IGrInit.

Lahey/INTERACTER Starter Kit

187

Appendix A Obsolete Routines

IScreenInit Subroutine
CHARACTER initfn = Initialization data file name (blank to open default file and/or use default values)

Initializes INTERACTER screen handling, attempts to read an initialization file and clears the screen to an 80 column text mode. This routine has been superceded by IScreenOpen which performs the same task except that it also initializes INTERACTER's graphics and provides the capability of entering graphics screen mode directly. All pre-v4 INTERACTER programs will use IScreenInit, so it is an essential backwards compatibility routine. However, we strongly recommend the use of IScreenOpen in new software. Calling IScreenInit activates certain v3.xx compatible defaults, which have been changed from version 4 onwards: Text window title bars do not occupy the full window width, when character graphic frames are in use (See IWinAction). Keyboard input under DOS is performed via BIOS interrupts instead of DOS interrupts. Graphics mode resize/expose event reporting in windowing environments is disabled (See InEventSelect). Frame titles are displayed in the current colors as set by ITextColourN (See
IFrameOptions(4/5,n)).

The click-outside-to-exit option is disabled (See InMouseOptions(2,n)). Mouse button options 106 is disabled (See InMouseOptions(106,n)). The default menu highlight is reverse video (See InHighlight). Menu option single-key selection characters are not highlighted. Insert/Overstrike mode defaults to overstrike mode.

IScreenQuit Subroutine
CHARACTER action = Action to take on exit = 'C': Clear the screen Quit/terminate INTERACTER screen handling. This routine was used in combination with IScreenInit in pre-v4 programs. It clears the screen if requested, reselecting the screen mode which was in use on entry to the program if possible. Any system dependent close

188

Lahey/INTERACTER Starter Kit

IScreenQuit Subroutine
down processing is also performed here. This routine has been superceded by IScreenClose which always clears the screen under DOS. IScreenQuit should only continue to be used in programs which still use IScreenInit.

Lahey/INTERACTER Starter Kit

189

Appendix A Obsolete Routines

190

Lahey/INTERACTER Starter Kit

Index
A
Attributes 159

B
Box-character frames 70

ErrNumToStr 35 Error Codes 35 Error Reporting 8 ErrWinBuffer 35 ErrWinCoOrds 35 Exit Codes 37

C
CGA 20 Character Graphics 65 Character Graphics Routines 50 Character Manipulation 179 Character Manipulation Routines 53 CHARSET 3, 28 chipset 29, 31 Clearing 60 Clearing Routines 50 Co-ordinate System 117 Cursor Control 57 Cursor Control Routines 50

F
Filename Specification 39 Fill styles 128 Fixed Field Input Handling 92 Fixed Field Input Handling Routines 51 Fixed-field/Menu Input Parameter Selection Routines 51 Fortran I/O 5 Frame Types 70

G
General Functions 50, 147 General Graphics 117 General Graphics Routines 52 Graphical frames 71 Graphics Character Output 136 Graphics Character Output Routines 52 Graphics Drawing Primitives 52 Graphics Drawing/Movement 133 Graphics Style Selection 52, 123

D
DISPLAY 3, 19, 29 Display Types 20 DOS graphics modes 8 duplexr.chr 1

E
Efficiency Considerations 9 EGA 20 ErrBadArea 36 ErrBadChar 35 ErrBadClear 35 ErrBadColor 36 ErrBadMode 36 ErrBadRadius 36 ErrBadUnits 35 ErrFileClose 35 ErrFileIO 35 ErrFillComplex 36 ErrLargeNum 35 ErrMaxWindow 35 ErrMenuOpt 35 ErrNoSubstring 35

H
Hardware Identification 177 Hardware Identification Routines 53 Hatched Fill Density 128 Hatched Line Angle 129 HGC 20 High Resolution Graphics 49, 117

I
IActualLength 180 IBM PC (Enhanced Keyboard) 45 IBM PC (Standard Keyboard) 41 IClearArea 60 IClearScreen 61 ICursor 58

ICursorLeft 58 ICursorRight 59 ICursorXY 59 IDisplay 19, 177 IFillString 180 IFrame 65 IFrameOptions 66 IFrameTitle 68 IFrameTitleBox 68 IFrameType 69 IGrArea 118 IGrAreaClear 119 IGrCharJustify 137 IGrCharOut 138, 139 IGrCharSet 140 IGrCharSize 143 IGrCharSpacing 144 IGrCircle 133 IGrColorN 123 IGrFillPattern 128 IGrGetPixelRGB 120 IGrInit 120 IGrLineTo 134 IGrLineType 130 IGrMoveTo 134 IGrPaletteRGB 131 IGrPause 122 IGrPoint 135 IGrPolygonComplex 135 IGrQuit 187 IGrUnits 122 IJustifyString 181 ILocateChar 182 ILocateString 182 ILowerCase 183 IMenuHoriz 98 IMenuVertic 100 IMouse 19, 178 IMouseCursorHide 114 IMouseCursorShow 115 InCharacter 83 InControlKey 103 InEventSelect 84 InfoAttribute 159 InfoError 8, 35, 160

Lahey Fortran 90 Language Reference

191

Index

InfoGraphics 162 InfoGrScreen 163 InfoHardware 165 InfoInput 166 Information 158 Information Routines 53 InfoScreen 169 InfoScreenMode 171 InfoWindow 173 InHighlight 106 Initialization Data File Format 27 InKeyEvent 41, 86 InKeyEventCursor 90 InKeyEventImm 41, 91 InKeypad 108 InMouseOptions 110 InPopup 112 Input Control Parameter Selection 103 Input Handling 49 InString 93 InStringDef 94 InStringXY 95 InStringXYDef 96 INTCHAR 3 INTCHDIR 3 IntegerToString 183 INTERACT.INI 27 INTINIT 3, 27 INTTERM 3 IOsExitProgram 175 IOsVariable 176 IOutString 55 IOutStringXY 56 IOutVertical 56 IOutVerticalXY 57 IScreenBell 147 IScreenClose 148 IScreenInit 9, 188 IScreenMode 7, 148 IScreenModeN 7, 150 IScreenModeOptions 154 IScreenOpen 155 IScreenQuit 188 ISplitFrameH 72 IStringToInteger 184 ITextAttribute 62 ITextColourN 63 IUpperCase 185 IWinAction 73

IWinClear 75 IWinClearArea 75 IWinClose 73, 76 IWinCursorXY 77 IWineOpenTitle 79 IWinOpen 73, 77 IWinOutString 80 IWinOutStringXY 80 IWinSelect 81

Screen Manipulation Routines 53 Screen Modes 151 standard.chr 1 Subroutine Arguments 6 SVGA 20 Symbolic Names 7

T
Text and Graphics Screen Modes 7 Text Attribute Routines 50 Text Attributes 61 Text Colors 64 Text Output 55 Text output in graphics modes 8 Text Output Routines 50 Text Screen Output 49, 55 triplexr.chr 1

K
Keyboard Codes 41 Keyboard/Mouse Event Handling 83 Keyboard/Mouse Event Handling Routines 51 KEYnn 29 Keypad Codes 108 Keywords 28

V L
Line Types 130 lisk.lib 1 VESA 20 VESAINFO.EXE 1, 24 VGA 20

M
MCGA 20 MDA 20 Menu Handling 97 Menu Handling Routines 51 Mice 24 MODE10 29 MODE11 30 MODE12 33 MODE9 29 MODEnn 22 MOUSE 19 Mouse Cursor Control 52, 114

W
Window Management Routines 51 Window Manager 72

N
Naming Conventions 7

O
Obsolete Routines 187 Operating System Interface 53, 175

R
read.me 1

S
Screen Manipulation 147

192

Lahey Fortran 90 Language Reference