LISKREF

Lahey/ INTERACTER Starter Kit

Revision C

P. O. Box 6091Incline Village, NV 89450

Printed on 50%

recycled paper

d. Alll mayto anyanual,

product

bliga-n no l dam-ade to ahey ise this

nt the y/

ding

ent

ner nd

CopyrightCopyright © 1995-1997 by Lahey Computer Systems, Inc. and Interactive Software Services, Ltrights reserved worldwide. This manual is protected by federal copyright law. No part of this manuabe copied or distributed, transmitted, transcribed, stored in a retrieval system, or translated inhuman or computer language, in any form or by any means, electronic, mechanical, magnetic, mor otherwise, or disclosed to third parties.

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

DisclaimerLahey Computer Systems, Inc. reserves the right to revise its software and publications with no otion of Lahey Computer Systems, Inc. to notify any person or any organization of such revision. Ievent shall Lahey Computer Systems, Inc. be liable for any loss of profit or any other commerciaage, including but not limited to special, consequential, or other damages. While every effort is mensure the accuracy of the information in this User Guide, Interactive Software Services Ltd. and LComputer Systems Inc. cannot be held responsible for any errors therein. The right is reserved to revdocument and the associated software without notice.

Conditions of UseUse 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 grauser of this software ("The Licencee") a non-exclusive and non-transferable licence to use the LaheINTERACTER Starter Kit ("The Software") including its associated utilities and documentation accorto the following terms and conditions :

1) The Software may only be copied for back-up purposes, to support its use for software developmpurposes on one processor at any one time.

2) The object and executable code files supplied with The Software may not be modified in any manwhatsoever. The supplied source code example files may be modified for the purposes of training aproduct familiarisation.

.

ftware such n pro-uch pro-

in the should

he Soft-h The

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 Somay be distributed to any third party. The Licencors do not claim any run-time licence or royalty fees onsoftware. The character set files supplied with the Software may also be distributed with such applicatiograms to any third party, so long as they are required by those application programs and provided that sgrams make substantial use of The Software.

5) Application programs developed using The Software should include a clear and prominent commentsource code acknowledging use of The Software. Technical and User documentation for such softwarealso 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. Tware may be transferred from one processor ("The Original") to another so long as all files supplied witSoftware 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 PARTICU-LAR 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 6091Incline Village, NV 89450-6091

(702) 831-2500

Fax: (702) 831-8123BBS: (702) 831-8023

Technical Support(702) 831-2500

[email protected]

Table of Contents

..

73

6

7

5

9

Introduction...........................................viiText Screen Output .......................................viiiInput Handling..............................................viiiHigh Resolution Graphics .............................. ixGeneral Functions............................................ x

Supplied Files .........................................1

Configuration ..........................................3

Getting Started with INTERACTER .......5Fundamentals................................................... 5A Worked Example ......................................... 9

Supported Hardware ............................19Displays ......................................................... 20Mice ............................................................... 24

Initialization Data File Format..............27Keyword Quick Reference Summary............ 28Keywords in Detail ........................................ 28

Error Codes...........................................35

Exit Codes .............................................37

Filename Specification.........................39

Keyboard Codes ...................................41IBM PC (Standard Keyboard) ....................... 41IBM PC (Enhanced Keyboard)...................... 45

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

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

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

High Resolution Graphics..................117Group GG: General Graphics.......................11Group GS: Graphics Style Selection............12Group GD: Graphics Drawing/Movement...133Group GC: Graphics Character Output........13

General Functions ..............................147Group SC: Screen Manipulation ..................14Group IF: Information..................................158Group OS: Operating System Interface .......17Group HW: Hardware Identification ...........177Group CH: Character Manipulation.............17

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

Lahey/INTERACTER Starter Kit v

Contents

vi Lahey/INTERACTER Starter Kit

Introduction

r has ieved of le

nd

tran

ith

bove.

arac- ine e ore here in

Traditionally, platform-independent interactive Fortran software has been uncommon orelied on a simple teletype style interface. Full screen interaction is more commonly achusing software interfaces which tie a program to a particular platform. This dilutes oneFortran's main assets, namely its portability. The INTERACTER user-interface and graphicslibrary from ISS was designed to overcome this by providing a wide selection of portabscreen 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 aUnix/VMS workstations running X Windows.

The Lahey/INTERACTER Starter Kit (LISK) is derived from the full version of INTER-ACTER and is targetted at one specific platform, namely DOS running Lahey 32-bit Forcompilers. A companion product, the Winteracter Starter Kit (WiSK) is provided for creat-ing Windows programs with LF90. This replaces the Windows version of LISK shipped wprevious 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 aThe 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-chter codes, e.g., CU for cursor control, MN for menus and so on. The following sectionsprovide a general summary of the types of facilities provided by each of these subroutgroups. Before starting to use INTERACTER it is recommended that you browse through threst of this introduction to familiarize yourself with the range of features on offer and mimportantly, where to find them. Note that the subroutine group summaries presented follow the same order as the final chapters of this manual which describe each routinedetail.

Lahey/INTERACTER Starter Kit vii

Introduction

xist of text

ic posi-

itched

ing,

aphics l facil-

e very re

input.

Text Screen OutputBroadly, INTERACTER treats text and graphics output separately, though both can co-eon the same screen. The subroutine groups in this category deal with various aspectsscreen output.

OU: Text OutputText can simply be 'pushed' out at the current cursor position or can be placed at speciftions. Vertical output is also available.

CU: Cursor ControlThe position and movement of the cursor can be controlled. The cursor can also be swon and off on most displays.

CL: ClearingAreas and the entire screen can be cleared.

AT: Text AttributesText attributes (or 'highlights') can be specified. Attributes available are color, bold, flashitalics, reverse and underlining, depending on display.

CG: Character GraphicsA number of routines are provided to draw frames around text areas on both text and grscreens, using either line-graphics characters or graphics primitives. For more powerfuities see the high resolution graphics routines.

WN: Window Management SystemThe window system enables output to be restricted to specific areas of the screen. Thuseful 'pop-up' feature allows windows to be overlaid so that the old screen contents arestored when they are closed.

Input HandlingThis category provides a set of functions which handle various types of text and option

viii Lahey/INTERACTER Starter Kit

KM: Keyboard/Mouse Event Handling

n

is

de hor-

input

ics ini-.

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

IN: Fixed Field Input HandlingFlexible string input routines are provided which replace Fortran READ statements. Thgroup also features prompt/response boxes, with a pop-up option.

MN: Menu HandlingThese menu routines make use of single-character input and mouse detection, to proviizontal/vertical pointer/highlight menus, greatly simplifying option selection. A pop-up facility is also included.

IP: Input/Menu Handling Parameter SelectionThe manner in which the input and menu handling routines behave can be modified. All control keys can be redefined. Pop-up mode is selectable.

MC: Mouse Cursor ControlThe mouse cursor can be enabled/disabled.

High Resolution GraphicsThese routines provide high resolution graphics output facilities.

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

GS: Graphics Style SelectionControl is provided over color, line-type and fill style.

Lahey/INTERACTER Starter Kit ix

Introduction

poly-

rious

nter-

of the

need

ant .

GD: Graphics Drawing/MovementThese are the basic drawing primitives. In addition to simple move and draw functions,gon and circle fill routines are provided.

GC: Graphics Character OutputText output in graphics mode supports both hardware and software character sets. Vavector and outline software character sets are provided.

General FunctionsThe remaining routines provide a variety of functions which are likely to be required in iactive applications.

SC: Screen ManipulationOf particular importance are the INTERACTER screen handling initialization and terminationroutines. Other facilities are mode selection and screen bell control.

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

OS: Operating SystemEnvironment variable access and termination with exit code routines are provided.

HW: Hardware IdentificationDisplay and mouse identification routines are provided, though these will not normally to be called directly.

CH: Character ManipulationWhile not strictly screen input/output handling functions, these routines provide importstring manipulation facilities which are of considerable value in interactive applications

x Lahey/INTERACTER Starter Kit

1 Supplied Files

rd:

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 “Configura-tion” 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 pro-gram can be used to determine what screen modes can be used with your graphics ca

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 Standard vector-based software character set

charsets\duplexr.chr Duplex Roman vector-based software character set

charsets\triplexr.chr Triplex Roman vector-based software character set

charsets\fixed.chr Courier-like outline character set

charsets\swiss.chr Helvetica-like outline character set

demos\*.f90 Source for various demo programs

demos\interact.f90 INTERACTER module (interface definitions and symbolicnames)

init\*.ini Sample initialization file entries for various displays

init\readme.txt Guide to selecting initialization file settings

Lahey/INTERACTER Starter Kit 1

Chapter 1 Supplied Files

2 Lahey/INTERACTER Starter Kit

2 Configuration

set up

g

s

ers

pro- to

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 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 runningin.

In addition to the initialization file itself, you may also find it useful to set up the followinoperating 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 def-initions 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 apart of the variable name.)

The two environment variable assignments above will also be required by your end-uswhen 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 “Initial-ization Data File Format” on page 27).

To illustrate INTERACTER's features, various demonstrations are supplied, including a gram called INPUT. Refer to the compiler’s user documentation for information on howcompile and link these programs with Lahey Fortran.


Chapter 2 Configuration


3 Getting Started with INTERACTER

some as st the

n to

s

ularly imply n

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 describedin the LF90 User’s Guide.

The first section summarizes some basic rules which need to be observed along with important basic concepts. Since INTERACTER has been designed to be as simple to use possible, these are kept to a minimum. However, a few minutes effort to read and digenext few pages will prove worthwhile.

Later in this chapter you will find a worked example which provides a gentle introductiowriting an INTERACTER application.

FundamentalsCertain basic principles apply regardless of which INTERACTER features you use.

Screen Control Codes and Fortran I/OAll screen I/O should be performed via INTERACTER. This means that screen control code(such as ANSI escape codes) must not be used. These will almost certainly confuse INTER-ACTER and cause unintended effects. This cannot be stressed too strongly. This particapplies to codes which may affect the cursor position or cause some effect other than splacing text on screen. Similarly, Fortran READ's and WRITE's direct from/to the screeshould 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.


Chapter 3 Getting Started with INTERACTER

tent

roups ortran

d-ted

piler

le,

o

o

tion) SK to

ill not

ere-

While you may find that WRITE(* or READ(* works in some cases under DOS, consisbehavior cannot be guaranteed. Consequently, you should always use INTERACTER subrou-tine calls to write to or read from the screen. The routines in the IN and OU subroutine gcan be viewed as functional replacements for Fortran READ and WRITE statements. FI/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 passelength character type CHARACTER*(*) is used in all cases, except where explictly staotherwise.

ALL subroutine arguments of type INTEGER are 4-byte integers, regardless of the comdefault. 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 moduthen add the following statement at the beginning of every program unit that calls INTER-ACTER routines:

USE INTERACTER

This will cause the compiler to check the number and type of arguments in each INTER-ACTER call. All of the demos in the LISK\DEMOS directory USE this module, so be sure tcompile it before building any demos.

Use of this module is now required. Users upgrading from an earlier version of LISK whhave not previously included a USE INTERACTER statement in their programs will need toadd such statements before using the latest version.

Certain subroutines now use assumed shape arrays (which require an interface definiwhere previously they used assumed size (which did not). This change has allowed LIbecome compatible with both LF90 and Essential LF90. Note that the full version of INTER-ACTER still uses assumed shape arrays. Users planning to upgrade to the full version wencounter problems however, because the INTERACTER module supplied with the full library declares the affected subroutine arguments differently. No code changes will thfore be required when upgrading.


Naming Conventions

ed in eric

ability. cu-

ate-

e nts

with

ted by

en tines

text

Symbolic Names

LISK programs can make extensive use of pre-defined symbolic names which are definthe INTERACTER Fortran 90 module. These symbolic names can be used in place of numsubroutine arguments/results and are designed to be meaningful, aiding program readWhilst use of these symbolic names is not obligatory, it is recommended. They are domented 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 stments 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 thfull INTERACTER library and consequently contains a number of PARAMETER statemewhich are not directly applicable to the Lahey/INTERACTER Starter Kit.

Naming ConventionsAll externally callable routines in INTERACTER start with the letter I . Various internal sub-routines and COMMON blocks are used. All internal subroutines have names startingthe letters XX (e.g., XXOUTU). Internal COMMON blocks are named INTRnn where nn is a 2-digit 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 ModesIn this manual a distinction is drawn between text and graphics screen modes (as selecIScreenMode /IScreenModeN ), and the routines which can be called in each. INTER-ACTER allows text screen handling routines to be called in both text and graphics scremodes, while graphics routines can only be called in graphics modes. Text handling rouare 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 handlingroutines.

Text and graphics look best when integrated, which involves using INTERACTER in graphics screen mode. The following notes summarize some of the considerations when usingscreen routines in graphics modes.



is

e

y

e any

ed

are

Issues to consider when generating text output in DOS graphics modes are:

• Text attribute support varies in graphics modes, depending on which screen mode being used. Underlining and reverse video are available in all graphics modes. Boldtext and background colors are available in color modes. Flashing text and italics arnot supported.

• Text output in graphics modes is slower, due to the manner in which screen memoris 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. Intext 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 modesand is consequently slower.

• Menus and text windows use 'graphical' frames in graphics mode, rather than box-drawing characters.

• Operation in graphics mode within a DOS box inside Windows may present prob-lems, resulting from poorly written Windows video drivers and/or the inability of Windows to window a particular type of graphics mode.

Error ReportingAll 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 aglobal 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 issuappropriate error messages. When INTERACTER encounters an error it will simply updatethe 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 documentwith 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 codesdefined in the INTERACTER module.


Some Efficiency Considerations

re that

a -

e

nt

dling high-

o ways

m

Some Efficiency ConsiderationsWhile 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 ensuyou get the best from the library:

• Monochrome graphics screen modes are faster than color ones. Similarly, there is 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 somgraphics operations.

• When using a software character set to annotate graphics, use a relatively simple fosuch as 'Standard'.

• When filling areas in graphics mode, solid fills are typically quicker than stippled/dithered ones.

A Worked ExampleThe 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 hanroutines. The short program is built up step by step, with newly introduced statementslighted 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 handlingsystem by calling IScreenOpen . This sets up various information required by INTER-ACTER, 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, toensure it behaves correctly and makes best use of the available hardware. There are twin 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 bethe termination routine IScreenClose , which terminates screen handling. A bare minimuINTERACTER program therefore looks like this:



of a

READ ch rou-

har-

he mes-

user t, it is it

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 formgraph. 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 statement which allows the size of the response to be restricted. There are several sutines but the one we will use is InStringXY ("Input a String at a specified X,Y position"):

PROGRAM LISK_EXAMPLEUSE INTERACTERIMPLICIT 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() STOPEND 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 cacters. 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 tsage 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, theis trapped in a loop until a name is entered. However, unlike a Fortran READ statemenpossible to determine which key the user actually pressed to terminate input, i.e. was Return, Escape, Tab, etc.?


A Worked Example

can

y):

t data ).

elp'

dif-

he

In INTERACTER these are referred to as 'exit' keys. After calling any input routines you 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 ke

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

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,*) NVALUE *

READ(20,*) (VALUES(I),I=1,NVALUE) *

CLOSE(20) *

! *

1000 CALL IScreenClose() *

STOP

END PROGRAM LISK_EXAMPLE

The program now terminates if the user presses the quit key or reads some free formafrom a file. (The data file handling is deliberately simplified for the sake of this exampleNow let's extend the idea of using an exit key by adding a 'pop-up' help facility. The 'hkey 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 slightlyferent 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 thelp window has been displayed:



-

p mpt

sed.

PROGRAM LISK_EXAMPLEUSE INTERACTERIMPLICIT NONECHARACTER (LEN=40) :: FILENAMEREAL, DIMENSION(50) :: VALUESINTEGER :: IBOX,LENGTH,LASTY,I,NVALUECALL IScreenOpen(' ','G',640,480,16)!IBOX = 1FILENAME = 'MYDATA.DAT' *

100 CALL ITextColourN(TextBlack,TextWhite)CALL InStringXYDef(2,2,'Filename: ',IBOX,FILENAME,LENGTH) *IF (InfoInput(55).EQ.23) THEN GO TO 1000ELSE 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 100END IF!OPEN(20,FILE=FILENAME,STATUS='OLD')READ(20,*) NVALUEREAD(20,*) (VALUES(I),I=1,NVALUE)CLOSE(20)!

1000 CALL IScreenClose()STOPEND 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-umode. A 30 column by 5 row window is opened and some text is 'poured' into it. A prois then centred on the bottom window line.

A single keyboard or mouse event is read from the input queue and the window is cloSince 'pop-up' mode was selected, the window disappears from the screen.


A Worked Example

gram-
Now let's try plotting the data that has been loaded, in the form of a graph using a prosupplied routine called PLOT:
PROGRAM LISK_EXAMPLE

USE INTERACTER

IMPLICIT NONE

INTERFACE *

SUBROUTINE PLOT(VALUES,NVALUE) *

IMPLICIT NONE *

REAL , INTENT (IN), DIMENSION(:) :: VALUES *

INTEGER, INTENT (IN) :: NVALUE *

END SUBROUTINE PLOT *

END INTERFACE *

CHARACTER (LEN=40) :: FILENAME

REAL, DIMENSION(50) :: VALUES

INTEGER :: IBOX,LENGTH,LASTY,I,NVALUE


!

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



the draw

!OPEN(20,FILE=FILENAME,STATUS='OLD')READ(20,*) NVALUEREAD(20,*) (VALUES(I),I=1,NVALUE)CLOSE(20)! *CALL IClearScreen() *CALL PLOT(VALUES,NVALUE) *!

1000 CALL IScreenClose()STOPEND 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 screen. A simple graph can now be constructed using a series of low level move and commands:


A Worked Example

m aped

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 systewhich leaves a border around the area in which the graph will be plotted. A simple L-shaxis is plotted, followed by the data itself. IGrLineTo is effectively a Pen-Down and drawoperation, so the DO loop creates a connected line graph.

And finally, to add some annotation to the X axis:



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


A Worked Example

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



4 Supported Hardware

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

Chapter 4 Supported Hardware

PC

niden- this

Displays

Notes: 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 theand 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 Herculesscreens can be identified automatically. By process of elimination this means that an utified screen is probably a CGA, though the precise monitor type will not be known. Insituation INTERACTER assumes a CGA with RGB monitor (display type 3).

Table 1: DOS Display Types

Display Number Display Type

1 MDA with direct drive monochrome monitor

2 CGA with composite monochrome monitor

3 CGA with RGB color monitor

4 EGA with direct drive monochrome monitor

5 EGA with RGB color monitor

6 EGA with Enhanced color Display

7 MCGA with analog monochrome monitor

8 MCGA with analog color monitor

9 VGA/SVGA with analog monochrome monitor

10 VGA/SVGA with analog color monitor

11 HGC with direct drive monochrome monitor

12 CGA with b & w monitor (no gray scaling)

13 VESA compatible SVGA


Displays

rts

e and tandard

ode iffer-

nnot.

t com-

ndard amely mode card on an 132

cer--color

ore tend

The following adapter-specific notes may be useful.

MDA The old Monochrome Display Adapter (MDA) supplied with the original IBM PC suppoa 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 modadds a single monochrome graphics mode. Despite its age it has been a widely used sdue to its low cost and relatively good graphics resolution (720x348).

CGA INTERACTER effectively supports two screen modes on the CGA: 80x25 16-color text mand 640x200 monochrome graphics. When selecting a CGA display, it is important to dentiate 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 caIf 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 othermonochrome monitors.

Some CGA-standard displays add support for non-standard graphics modes. The mosmon is the monochrome 640x400 'AT&T/Olivetti' mode. Various Toshiba laptops and Olivetti PC's implement this mode. See the MODE9 initialization file keyword in“Initializa-tion Data File Format” on page 27 for more details.

EGA The Enhanced Graphics Adapter (EGA) was the first halfway decent color graphics stafor 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, ndirect drive mono, RGB or ECD. On a mono display one text mode and one graphics are supported (functionally, this is quite similar to the Hercules Graphics card). An EGAwith an RGB display is very similar to a CGA except that 16 colors can be displayed in640x200 graphics mode. The Enhanced color Display provides the best output quality EGA with support for a 640x350 16-color mode. Certain non-IBM EGA's also support acolumn 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 tain bottom of the range PS/2 systems. It adds 640x480 monochrome and 320x200 256graphics modes to those available on the CGA.

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



y ng a 8/43/ESA di-

are ideo des to

256-

pass

A

de

ESA

of ble.

ting

,

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

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

VESA Display type (13)

Most newer SVGA's are VESA compatible. That is, they include a BIOS (either in hardwor in a TSR on the utilities disk) which implements standard functions defined by the VElectronics Standards Association. Such a BIOS is intended to allow SVGA screen mobe selected and controlled in a manufacturer-independent manner. INTERACTER will auto-matically identify the presence of such a video BIOS and select display type 13. It willinterrogate the BIOS to identify the available VESA compatible screen modes (numbers268/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 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 VESscreen modes which are supported by INTERACTER on the current display. For complete-ness, it also lists the MODEnn keywords which can be used with the alternative SVGA moselection 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 VESAmodes gives problems. In this situation, set the display type to 10 and add selected VMODEnn keywords, as reported by VESAINFO, to the initialization file.

Note that InfoHardware(32) can be used to test from within a program for the presencea VESA video BIOS. The returned value also identifies which VESA modes are availa

Initialization File MODE nn Keywords:

On a non-VESA compatible SVGA, an alternative mechanism for identifying and selecSVGA 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 modeswhich have been assigned mode numbers of 10/11/12:

Table 2: MODE nn Keywords

nn Screen Mode

10 Extended 16-color text mode (up to 132x66 )

11 16-color SVGA graphics mode (up to 1600x1200)

12 256 color SVGA graphics mode (up to 1600x1200)


Displays

everal general

d

o the

GA on

Each type of SVGA card requires different settings to select these modes. There are spossible reasons for choosing to use these adapter-specific modes in preference to the purpose "VESA compatible SVGA" option (display type 13):

• Some SVGA's are not VESA-compatible and a VESA TSR may not be immediatelyavailable.

• 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 harto 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. TheMODE10 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 trail-ing C argument.

If the MODEnn mode selection mechanism is used, for one of the above reasons, refer tdescriptions of the MODE10, MODE11 and MODE12 initialization file keywords in “Initializa-tion Data File Format” on page 27. Also, numerous examples are provided in the INIT sub-directory. In general, it is necessary to identify the type of chipset which a particular SVis based on before selecting the settings to use in the initialization file (e.g., is it basedTseng 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 'brand-name' 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:



her

s ill mouse

-

as a

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 cor-responding .ini examples file in the INIT directory. If the SVGA type cannot be identifiedthere are VESA BIOS versions of each of the possible MODEnn keywords. These are reportedby 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). Itmay 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 whetthe currently identified graphics modes are working on the current display.

Mice

Under DOS, a Microsoft (2-button) or Mouse Systems (3-button) compatible mouse isrequired. MOUSE.COM or the equivalent driver must be installed before running programwhich use the mouse. INTERACTER will check to see whether the driver is loaded and walso attempt to determine whether a 2- or 3-button mouse is attached. Where fitted, the 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 usedmouse with INTERACTER provided a suitable MOUSE.COM equivalent is loaded.

Table 3: Mouse Types

Mouse Number Mouse Type

1 No mouse fitted/don't use mouse

2 2-button mouse

3 3-button mouse


Mice

r '

ent to . In

Virtually all available mouse drivers (including Microsoft's) fail to work correctly in AT&Tand Super VGA modes (INTERACTER modes 9-12). Typical problems include a missing oincorrectly displayed mouse cursor and erratic cursor movement. In this situation add aC' 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 movembe identified in a different way thereby also curing the erratic cursor movement problemVESA modes 256+ (available when display type 13 has been selected) INTERACTER auto-matically activates these fixes, so no user action is required. See “Initialization Data File Format” on page 27 for more information on initialization file keywords.




5 Initialization Data File Format

y

t

rious

d, an ecords proc-hich

The INTERACTER initialization file is an ordinary text file which can be prepared with antext 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 recom-mended method, since it allows you to create a single initialization file and access ifrom 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 vainformation 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 keyworequals sign and a value. Keywords can be in upper or lower case. The format of these ris quite flexible and comments are allowed for. Records of up to 90 characters can beessed allowing filenames of up to 80 characters to be specified. Only that information wyou wish to define need be included and it can be in any order.


Chapter 5 Initialization Data File Format

Keyword Quick Reference SummaryThe following initialization file keywords are recognized. See “Initialization Data File For-mat” on page 27 for full details of these keywords.

Keywords in DetailThe following keywords can be set to the indicated types of values:

CHARDIR = stringThe 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 = stringThe 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.

Table 4: INTERACTER Keywords

Keyword Meaning

CHARDIR = Directory containing INTERACTER character sets

CHARSET = Default character set file name

DISPLAY = Display type

KEYnn = Control keys (i.e., KEY1->KEY50)

MODE9 = AT&T 640x400 mono graphics mode availability

MODE10 = Extended EGA/VGA/SVGA text mode availability

MODE11 = 16-color SVGA graphics mode availability

MODE12 = 256-color SVGA graphics mode availability

MOUSE = Mouse type

REVERSE = Reverse foreground/background on mono displays

VER = Show version number


Keywords in Detail

n r

on cer-ying

ero. par-

le ini-

er on ursor

/

on the

DISPLAY = numeric-valueThe 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 aoperating system variable called INTTERM. The selected display type is accessible in youprograms via InfoHardware(10) .

KEYnn = numeric valueThe ASCII code or special INTERACTER code (see InKeyEvent ) of the specified input con-trol 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 tain sub-VGA PC screens. Up to 4 decimal numeric values should be supplied, identifthe 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 zCommonly, all that will need to be specified is the screen mode number allocated by aticular 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 samptialization 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 charactthe line, if specified. Most Microsoft compatible mouse drivers do not support a mouse cin 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 EGAVGA/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 line, if specified.



r for e

lec-

s

uote

The chipset argument is not used when selecting mode 10 but must be included as a place-holder, 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 adaptedetails of appropriate values. Here are some examples (many more are included in thLISK\INIT sub-directory):

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 setion 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 chipsetrequire 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 qmode numbers as hex values (e.g., 58h instead of 88). The values in a MODE11 record must be expressed in decimal.

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

MODE10 = 85 C MODE10 = 84 0 0 0 2 132 43 C

VGA based on Paradise (West-ern Digital) chipset

MODE10 = 28421 65 C MODE10 = 28421 69 0 0 3 132 28 CVGA based on Video 7 chipset


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 Chipset

0 Tseng Labs ET3000 (default)

1 Tseng Labs ET4000

2 Paradise (Western Digital)

3 Video 7

4 Everex

5 ATI x8800

6 Trident

7 Chips & Technologies 82c452/82c453

8 Ahead B

9 Oak Technologies OTI-037C/067/077

10 Genoa 6x00 GVGA

11 NCR 77C20/21/22E

12 S3 86C911/924

13 Cirrus 540x-5424/62xx

14 Primus 2000

15 AcuMos AVGA

16 RealTek 3106

17 Ahead A

18 VESA BIOS

19 Oak Technologies OTI-087

20 Cirrus 64xx



and itched

ues

on the

Any trailing values which are omitted take the default values shown. If the mode widthheight are omitted, the chipset can also be omitted since 800x600 mode is not bank-sw(and is therefore not chipset dependent). See “Supported Hardware” on page 19 for infor-mation regarding chipset identification. Supported 16-color mode width and height valare 800x600, 1024x768, 1280x1024 and 1600x1200.


Here are some examples (many more are included in the LISK\INIT sub-directory):

21 Avance Logic ALG2xxx

22 UMC 85c408

23 MXIC MX860x0

24 Weitek W5x86

25 Hualon HM86304

26 Cirrus 5426-545x



MODE11 = 55 0 0 0 1 1024 768 C MODE11 = 61 0 0 0 1 1280 1024 C


MODE11 = 88 C MODE11 = 100 0 0 0 2 1280 1024

VGA based on Paradise (Western Dig-ital) chipset

MODE11 = 28421 98 C MODE11 = 28421 101 0 0 3 1024 768 C

VGA based on Video 7 chipset

Table 6: Chipset = Argument Values

Value Chipset


Keywords in Detail

num-

,

on the

s via

Alternatively, many (but not all) SVGA adapters support a 'generic' 800x600x16 mode, ber 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 SVGAgraphics) on the PC. See “IScreenModeN Subroutine” on page 150. The first 4 argumentsax/bx/cx/dx , are the INT 10h mode selection register values as described under theMODE11 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 key-word, 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.


Here are some examples (many more are included in the LISK\INIT sub-directory):

MOUSE = numeric-valueThe mouse type number as can be specified to IMouse . Mouse numbers are listed in “Sup-ported Hardware” on page 19. The selected mouse type is accessible in your programInfoHardware(13) .



MODE12 = 46 0 0 0 1 C MODE12 = 56 0 0 0 1 1024 768 C


MODE12 = 94 0 0 0 2 640 400 C MODE12 = 95 0 0 0 2 C

VGA based on Paradise (Western Dig-ital) chipset

MODE12 = 28421 103 0 0 3 C MODE12 = 28421 105 0 0 3 800 600 C

VGA based on Video 7 chipset



ing

-uoted

REVERSE = stringForeground/background colors can be reveresed on monochrome displays by specifyREVERSE=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 qwhen reporting problems. Note that the equals sign (=) is required as usual, but there is nofollowing value.

Example PC Initialization FileREM 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


6 Error Codes
The following error values are set by various INTERACTER routines and are returned by theerror information function InfoError . The listed symbolic names are all defined in the INTPARAM module.
Table 9: INTERACTER Error Codes

Name No. Description

ErrFileOpen 1 Error opening a file.

ErrFileIO 2 Error reading from a file.

ErrFileClose 3 Error closing a file or device.

ErrLargeNum 4 Number too large in string-to-numeric conversion.

ErrMaxWindow 7 Max number of windows exceeded.

ErrWinBuffer 8 Window buffer space exceeded.

ErrWinCoOrds 9 Invalid window co-ordinates.

ErrNoSubstring 10 No substring found.

ErrBadChar 12 Invalid character detected.

ErrBadClear 14 Invalid text co-ordinates for clear operation.

ErrBadUnits 16X or Y graphics unit range is invalid. Default of 0-1 used.

ErrNumToStr 18Numeric to string conversion error. String filled with * 's.

ErrMenuOpt 19 All options start with '- ' in a menu.


Chapter 6 Error Codes

ErrBadRadius 20 Radius of a circle is <= zero.

ErrBadMode 41Unknown or unsupported screen mode requested in call to IScreenModeN

ErrBadColour 42Unknown color number specified to IGrColourN . Current color remains unchanged.

ErrBadArea 44Invalid X and/or Y range specified to IGrArea . Range reset to 0-1 .

ErrFillComplex 49 Fill too complex in IGrPolygonComplex .

ErrNoSoftFont 53Unable to find software font file in IGrCharOut to substitute for unavailable hardware font

Table 9: INTERACTER Error Codes



7 Exit Codes

f the

-

In the event of INTERACTER detecting an unrecoverable error, it calls the IOsExitPro-

gram routine and passes an exit code to the operating system. The following is a list oexit 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

1 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.

13IScreenModeIGrInitIScreenOpen

An attempt has been made to select a graphics screen mode when the currently identified display type does not support graphics. Check the selectedINTERACTER display type.


Chapter 7 Exit Codes


8 Filename Specification

es ned

for

f no iron-

t

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 takpriority. The format of the filename will normally be system specific, having been obtaifrom an operating system variable (using IOsVariable ) or from the screen (using InString /InStringDef /etc.). In general, hard coding filenames is not recommended 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. Isuch name was specified, the contents of an environment variable are used. If the envment variable has not been set up either, INTERACTER finally uses a system specific defaul


Chapter 8 Filename Specification

s and
(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 nametypical system specific default filenames are listed below:
Table 11: Filename Specification

RoutineInitialization File Keyword

Environment Variable

Typical Default Filename

IScreenOpen - INTINIT INTERACT.INI

IGrCharSet CHARSET INTCHAR STANDARD.CHR


9 Keyboard Codes

is-

'ideal'

keypad ard.

e

r and etc.

re

The availability of non-ASCII keys, such as function keys, varies considerably on the dplays supported by INTERACTER. To overcome this, InKeyEvent returns a set of standardized key codes which correspond to an 'ideal' keyboard. The definition of thesekey codes appears under the InKeyEvent routine. This chapter lists the actual keys whichare 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 can be identified separately from keys with the same keytop legend on the main keyboFor 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 mod3 they return their uniquely assigned codes. Refer to the documentation for the InKeypad rou-tine 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 (see“Initialization 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 cursoediting keys. Keypad mode 2 is therefore the default on the PC to enable the cursor keys 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. Whethe 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 combina-tions 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.


Chapter 9 Keyboard Codes

.

Table 12: Key Codes on a Standard 83-key PC Keyboard under DOS in keypad mode 2

Code Key Code Key Code Key

9 Tab 140 Keypad 7 162 Keypad +

13 Return 141 Keypad 1 163

27 Escape 142 Keypad 0 164 Keypad *

32-126

ASCII chars 143 Keypad . 165

127Ctrl/Back-space

144 Shift/Tab 166

128 Keypad 8 150 170

129 Keypad 2 151171-180

F1-F10

130 Keypad 6 152191-200

Shift/F1-Shift/F10

131 Keypad 4 153211-220

Ctrl/F1-Ctrl/F10

132 Keypad 9 154231-240

Alt/F1-Alt/F10

133 Keypad 3 155 Keypad 5384-511

Alt/Keypad 8-bit char

134 Ctrl/Keypad 6 156 520 Alt/Backspace

135 Ctrl/Keypad 4 157 521 Alt/Tab

136 Ctrl/Keypad 9 158 525 Alt/Return

137 Ctrl/Keypad 3 159 539 Alt/Escape

138 Ctrl/Keypad 1 160 Keypad -560-569

Alt/0-Alt/9

139 Ctrl/Keypad 7 161577-602

Alt/A-Alt/Z


IBM PC (Standard Keyboard)

Table 13: Key Codes on a Standard 83-key PC Keyboard under DOS in keypad mode 3


9 Tab 140 162 Keypad +

13 Return 141 163

27 Escape 142 164 Keypad *

32-126

ASCII chars 143 165

127Ctrl/Back-space

144 Shift/Tab 166

128 150 Keypad 0 170

129 151 Keypad 1171-180

F1-F10

130 152 Keypad 2191-200

Shift/F1-Shift/F10

131 153 Keypad 3211-220

Ctrl/F1-Ctrl/F10

132 154 Keypad 4231-240

Alt/F1-Alt/F10

133 155 Keypad 5384-511


134 Ctrl/Keypad 6 156 Keypad 6 520 Alt/Backspace

135 Ctrl/Keypad 4 157 Keypad 7 521 Alt/Tab

136 Ctrl/Keypad 9 158 Keypad 8 525 Alt/Return

137 Ctrl/Keypad 3 159 Keypad 9 539 Alt/Escape

138 Ctrl/Keypad 1 160 Keypad -560-569

Alt/0-Alt/9

139 Ctrl/Keypad 7 161 Keypad .577-602

Alt/A-Alt/Z



Table 14: DOS - Default Control Key Assignments

Control Key Number

Contol Key FunctionInKeyEvent Code

Actual Key(s)

1 cursor up 128 Keypad 8/Cursor Up

2 cursor down 129 Keypad 2/Cursor Down

3 cursor right 130 Keypad 6/Cursor Right

4 cursor left 131 Keypad 4/Cursor Left

5 extended cur/up 132 Keypad 9/ Page Up

6 extended cur/down 133Keypad 3/ Page Dn

7extended cur/right

134 Ctrl/Keypad 6

8 extended cur/left 135Ctrl/Keypad 4

9 extreme cur/up 136 Ctrl/Keypad 9

10 extreme cur/down 137 Ctrl/Keypad 3

11 extreme cur/right 138Ctrl/Keypad 1

12 extreme cur/left 139 Ctrl/Keypad 7

13 clear to start 173 F3

14 clear to end 174 F4

15 move to start 140 Keypad 7/Home

16 move to end 141 Keypad 1/End

17 toggle insert mode 142 Keypad 0/Insert

18backspace/delete 1

8 Backspace

19backspace/delete 2

127 Ctrl/Backspace


IBM PC (Enhanced Keyboard)

e the s and ult on anced

ere

under

IBM PC (Enhanced Keyboard)The newer 'enhanced' PC keyboard has 101/102 keys and has largely come to replacoriginal 'standard' keyboard. The enhanced keyboard has separate cursor/editing keytwo extra function keys. There is less need to use keypad mode 2, but this is the defaall PC's to ensure consistent behavior on systems with either keyboard type. On an enhkeyboard InfoInput(56) will return 1.

The Alt/ Keypad technique for generating specific ASCII codes is fully supported. Whthe 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 combina-tions 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 the Standard Keyboard.

20delete under cursor

143 Keypad . / Delete

21 confirm input 13 Return

22 help 171 F1

23 quit 27 Escape

24 tab 9 Tab

25 back-tab 144 Shift/Tab

26-30 spare exit keys 0 undefined

35 next item 32 Space Bar

36-70 spare exit keys 0 undefined

Table 14: DOS - Default Control Key Assignments

Control Key Number

Contol Key FunctionInKeyEvent Code

Actual Key(s)



.

Table 15: Key Codes on Enhanced PC Keyboard under DOS in keypad mode 2


9 Tab 140 Home 162 Keypad +

13 Return 141 End 163 Keypad /

27 Escape 142 Insert 164 Keypad *

32-126

ASCII chars 143 Delete 165

127Ctrl/Back-space

144 Shift/Tab 166 Keypad Enter

128 Cursor Up 150 170

129 Cursor Down 151171-182

F1-F12

130 Cursor Right 152191-202

Shift/F1-Shift/F12

131 Cursor Left 153211-222

Ctrl/F1-Ctrl/F12

132 Page Up 154231-242

Alt/F1-Alt/F12

133 Page Down 155 Keypad 5384-511


134 Ctrl/Keypad 6 156 520 Alt/Backspace

135 Ctrl/Keypad 4 157 521 Alt/Tab

136Ctrl/Cursor Up

158 525 Alt/Return

137Ctrl/Cursor Down

159 539 Alt/Escape

138Ctrl/Cursor Right

160 Keypad -560-569

Alt/0-Alt/9

139Ctrl/Cursor Left

161577-602

Alt/A-Alt/Z


IBM PC (Enhanced Keyboard)

Table 16: Key Codes on Enhanced PC Keyboard under DOS in keypad mode 3


9 Tab 140 Home 162 Keypad +

13 Return 141 End 163 Keypad /

27 Escape 142 Insert 164 Keypad *

32-126

ASCII chars 143 Delete 165

127Ctrl/Back-space

144 Shift/Tab 166 Keypad Enter

128 Cursor Up 150 Keypad 0 170

129 Cursor Down 151 Keypad 1171-182

F1-F12

130 Cursor Right 152 Keypad 2191-202

Shift/F1-Shift/F12

131 Cursor Left 153 Keypad 3211-222

Ctrl/F1-Ctrl/F12

132 Page Up 154 Keypad 4231-242

Alt/F1-Alt/F12

133 Page Down 155 Keypad 5384-511


134 Ctrl/Keypad 6 156 Keypad 6 520 Alt/Backspace

135 Ctrl/Keypad 4 157 Keypad 7 521 Alt/Tab

136Ctrl/Cursor Up

158 Keypad 8 525 Alt/Return

137Ctrl/Cursor Down

159 Keypad 9 539 Alt/Escape

138Ctrl/Cursor Right

160 Keypad -560-569

Alt/0-Alt/9

139Ctrl/Cursor Left

161 Keypad .577-602

Alt/A-Alt/Z




10 Subroutine Summary

Subroutine Groups

Text Screen OutputGroup OU: Text Output

Group CU: Cursor Control

Group CL: Clearing

Group AT: Text Attributes

Group CG: Character Graphics

Group WN: Window Manager

Input HandlingGroup KM: Keyboard/Mouse Event Handling

Group IN: Fixed Field Input Handling

Group MN: Menu Handling

Group IP: Input Control Parameter Selection

Group MC: Mouse Cursor Control

High Resolution GraphicsGroup GG: General Graphics

Group GS: Graphics Style Selection

Group GD: Graphics Drawing/Movement

Group GC: Graphics Character Output


Chapter 10 Subroutine Summary

General FunctionsGroup SC: Screen ManipulationGroup IF: InformationGroup OS: Operating System InterfaceGroup HW: Hardware IdentificationGroup CH: Character Manipulation

Subroutine Summary

Group OU: Text Output RoutinesIOutString Output string at current cursor pos IOutStringXY Output string at a specific (x,y) pos IOutVertical Output string vertically from current cursor pos IOutVerticalXY Output string vertically at a specific (x,y) pos

Group CU: Cursor Control RoutinesICursor Enable/disable cursor ICursorLeft Move cursor left N columns & wrap at edge of screen ICursorRight Move cursor right N columns & wrap at edge of screen ICursorXY Move cursor to a specific (x,y) position

Group CL: Clearing RoutinesIClearArea Clear a screen area IClearScreen Clear the whole screen

Group AT: Text Attribute RoutinesITextAttribute Set bold/flash/italic/reverse/underline combination ITextColourN Select foreground/background text colors by number

Group CG: Character Graphics RoutinesIFrame Print a frame round a screen area IFrameOptions Specify frame options (colors, etc.) IFrameTitle Print a frame, with a title within top of frame IFrameTitleBox Print a frame, with a title in a box at top of frame IFrameType Select frame type ISplitFrameH Split up a frame horizontally


Group WN: Window Management Routines

Group WN: Window Management RoutinesIWinAction Define action to be taken when opening a window IWinClear Clear the whole of the currently selected window IWinClearArea Clear an area of the currently selected window IWinClose Close top window & optionally restore screen IWinCursorXY Position cursor within current window IWinOpen Open a new window IWinOpenTitle Open a new window with a title IWinOutString Output string at current window cursor position IWinOutStringXY Output string at a specific window positionIWinSelect Select current window by number

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

Group IN: Fixed Field Input Handling RoutinesInString Get fixed length string (no default offered) InStringDef Get fixed length string, offering a default InStringXY Get string at an (x,y) position (no default offered) InStringXYDef Get string at an (x,y) position, offering a default

Group MN: Menu Handling RoutinesIMenuHoriz Horizontal pointer/highlight menu IMenuVertic Vertical pointer/highlight menu

Group IP: Fixed-field/Menu Input Parameter Selection RoutinesInControlKey Define control keys for all input handling routines InHighlight Select highlight for menu & input-at-(x,y) routines InKeypad Select keypad detection/interpretation mode InMouseOptions Specify mouse options for fixed field/menu input InPopup Select pop-up mode for menu & input-at-(x,y) routines



Group MC: Mouse Cursor ControlIMouseCursorHide Hide mouse cursor

IMouseCursorShow Show mouse cursor

Group GG: General Graphics RoutinesIGrArea Define size of graphics area

IGrAreaClear Clear the current graphics screen area

IGrGetPixelRGB Get the a screen pixel value as an ( r, g, b) triplet

IGrInit Start graphics output

IGrPause Pause before clearing screen to start a new picture

IGrQuit End graphics output

IGrUnits Define plotting units to be used

Group GS: Graphics Style SelectionIGrcolorN Select graphics color using a color number

IGrFillPattern Define fill pattern (solid/stippled/hatched)

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

IGrPaletteRGB Redefine color palette using RGB color scheme

Group GD: Graphics Drawing PrimitivesIGrCircle Draw/fill circle at an absolute position

IGrLineTo Draw line to a new absolute position

IGrMoveTo Move current plotting position to a new absolute position

IGrPoint Draw a single point at new absolute position

IGrPolygonComplex Draw/fill a complex (possibly intersecting) polygon

Group GC: Graphics Character Output RoutinesIGrCharJustify Select graphics text justification

IGrCharLength Return relative length of string allowing for prop spacing

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

IGrCharSet Select graphics character set to use for text output

IGrCharSize Select graphics text/symbol size

IGrCharSpacing Select fixed or proportional spacing


Group SC: Screen Manipulation Routines

Group SC: Screen Manipulation RoutinesIScreenBell Enable/disable/ring the bellIScreenClose Terminate INTERACTER screen handlingIScreenMode Select screen mode by resolution & colorsIScreenModeN Select screen mode by numberIScreenModeOptions Specify screen mode selection optionsIScreenOpen Initialize INTERACTER screen handling

Group IF: Information RoutinesInfoAttribute Return text attributes information InfoError Return error information InfoGraphics Return real graphics mode information InfoGrScreen Return graphics facilities information (screen) InfoHardware Return hardware information InfoInput Return keyboard input facilities information InfoScreen Return screen mode information (current mode) InfoScreenMode Return screen mode information (any mode) InfoWindow Return window management system information

Group OS: Operating System InterfaceIOsExitProgram Abort program with an error message & error code IOsVariable Return the value of an operating system (environment) variable

Group HW: Hardware Identification RoutinesIDisplay Select display type IMouse Select mouse type

Group CH: Character Manipulation RoutinesIActualLength Return actual length of string excluding trailing blanks IFillString Fill a character string with a given character IJustifyString Justify a string within a character variable ILocateChar Locate position of first non blank character ILocateString Locate position of first non blank sub-string ILowerCase Convert a string to lower case IntegerToString Convert an integer value to a string IStringToInteger Convert a string to an integer value IUpperCase Convert a string to upper case




11 Text Screen Output

of

been

, i.e.,

t the

an essed.

Group OU: Text OutputThese routines provide the most fundamental text screen output facilities at the heart 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 haswritten. IOutStringXY performs the same task, but at a specified column/row. IOutVer-

tical and IOutVerticalXY provide equivalent functions for outputting text vertically.

Cursor position specification follows the same conventions as described in the CU groupthe top left corner is (1,1) .

IOutString Subroutine

DescriptionOutput string at current cursor position.

SyntaxIOutString(string)

ArgumentsCHARACTER string = String to output

EffectOutputs string, at the current cursor position, in the current text style. The cursor is left aend of the string.

Text which would extend beyond the end of the current screen line is truncated. Text csafely be written to the bottom right hand corner of the screen, since scrolling is suppr


Chapter 11 Text Screen Output

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

IOutStringXY Subroutine

DescriptionOutput string at a specific (x,y) position.

SyntaxIOutStringXY(ix,iy,string)

ArgumentsINTEGER ix = Column

INTEGER iy = Row

CHARACTER string = String to write out

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

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

IOutVertical Subroutine

DescriptionOutput string vertically from current cursor position.

SyntaxIOutVertical(string)

ArgumentsCHARACTER string = String to output


IOutVerticalXY Subroutine

ld ich is -

EffectOutputs string, vertically (downwards) from the current cursor position. Text which wouextend beyond the bottom line of the screen is truncated in a similar manner to text whoutput 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 .)

ExampleCALL ICursorXY(2,1)

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

IOutVerticalXY Subroutine

DescriptionOutput string vertically at a specific (x,y) position.

SyntaxIOutVerticalXY(ix,iy,string)


INTEGER iy = Row


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

ExampleCALL ICursorXY(IX,1)

CALL IOutVertical('Vertical !')

! this is simpler ...

CALL IOutVerticalXY(IX,1,'Vertical !')

Group CU: Cursor ControlThe 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 IScreen-

Mode or IScreenModeN , which are available in the SC group.



f tines

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

ICursor Subroutine

DescriptionEnable/disable cursor.

SyntaxICursor(onoff)

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

EffectEnables or disables the cursor. Certain INTERACTER routines automatically set the state othe hardware cursor. The menu handling routines disable it and the fixed field input rouenable 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 , IScreen-

Mode or IScreenModeN ) is enabled in text mode and disabled in graphics mode.

Portability notesThere is no hardware cursor in graphics screen modes.

ExampleCALL ICursor('OFF')

CALL IOutStringXY(10,2,'The cursor should now be off ...')

CALL InKeyEvent(IKEY)

CALL ICursor('ON')

CALL IOutStringXY(10,4,'And now it should be back on ...')

ICursorLeft Subroutine

DescriptionMove cursor left N columns & wrap at edge of screen.


ICursorRight Subroutine

yond een.

yond

SyntaxICursorLeft(ncols)

ArgumentsINTEGER ncols = Number of columns by which to move left

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

ExampleCALL ICursorLeft(10)

ICursorRight Subroutine

DescriptionMove cursor right N columns & wrap at edge of screen.

SyntaxICursorRight(ncols)

ArgumentsINTEGER ncols = Number of columns by which to move right

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

ExampleCALL ICursorRight(5)

ICursorXY Subroutine

DescriptionMove cursor to a specific (x,y) position.

SyntaxICursorXY(ix,iy)



rrently


INTEGER iy = Row

EffectMoves 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.

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

Group CL: ClearingThese routines allow all or part of the screen to be cleared. They always clear to the cuselected background text attribute as set by the ITextColourN or ITextAttribute rou-tines in the AT group.

IClearArea Subroutine

DescriptionClear a screen area.

SyntaxIClearArea(ixtopl,iytopl,ixbotr,iybotr)

ArgumentsINTEGER 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

EffectClears 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 bottomY value.


IClearScreen Subroutine

re

se under-rther

hich

If the specified area extends beyond the current screen limits, the area co-ordinates aadjusted accordingly.

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

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

IClearScreen Subroutine

DescriptionClears the whole screen.

SyntaxIClearScreen()

EffectClears the screen, leaving the cursor at position (1,1) .

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

Group AT: Text AttributesDisplayed text can be greatly enhanced using these text attribute control routines. Theallow colors to be selected (where available) as well as supporting highlights such as lining, bold text and so on. Both routines simply select the attribute to be used by any futext output. They have no immediate on-screen effect until other routines are called wdisplay 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.



to he

string ble

auses s are can be

orted. mode s.

ore-

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

ITextAttribute Subroutine

DescriptionSet bold/flash/italics/reverse/underline combination.

SyntaxITextAttribute(bfiru)

ArgumentsCHARACTER bfiru = A string containing any or none of the following characters inupper or lower case:

B : Select bold text F : Select flashing text I : Select italics R : Select reverse video U : Select underlining

EffectSelects a combination of text attributes. Only those attributes indicated in the argumentwill be enabled and the others will be disabled. All attributes are off at start-up. To disaall text attributes, call ITextAttribute with a blank argument.

Text attribute support is display dependent. InfoAttribute reports the availability of eachattribute. Selecting an unavailable attribute will have no effect.

Portability notesBold is supported on the PC in all modes except mono graphics modes. Enabling bold ctext to be displayed in a higher intensity. Thus if foreground and background text colorthe same and bold is enabled, text is still readable. On a color screen, the same effectachieved by specifying a bold color number to ITextColourN .

Flashing text is only supported in monochrome text screen modes. Italics are not suppReverse video is supported in all modes. Underlining is supported in mono text screen7 (available on the MDA, Hercules, EGA and VGA adapters) and in all graphics mode

On true monochrome displays (i.e., not gray scaled CGA or VGA mono screens) the fground/background 'colors' can be exchanged by using the REVERSE initialization file keyword.


ITextColourN Subroutine

e fol-

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

ITextColourN Subroutine

DescriptionSelect foreground/background text colors by number.

SyntaxITextColourN(nfcolr,nbcolr)

ArgumentsINTEGER nfcolr = Foreground text color number (see below)

INTEGER nbcolr = Background text color number (see below)

EffectSelects foreground and background text colors, by number. The color numbering schemlows 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.



er

Invalid color numbers are ignored, as are calls made in monochrome screen modes.

In a graphics mode, the text palette is the same as the 16-color palette described undIGr-

ColourN . Redefining the following graphics color numbers will therefore typically also redefine the corresponding text colors:

Table 17: Text Colors

Name No. Color Name No. Color

TextBlack 0 Black TextBlackBold 8 Dark gray

TextRed 1 Red TextRedBold 9 Bold Red

TextYellow 2 Yellow TextYellowBold 10 Bold Yellow

TextGreen 3 Green TextGreenBold 11 Bold Green

TextCyan 4 Cyan TextCyanBold 12 Bold Cyan

TextBlue 5 Blue TextBlueBold 13 Bold Blue

TextMagenta 6 Magenta TextMagentaBold 14 Bold Magenta

TextWhite 7 Off-white TextWhiteBold 15 Bold White

Table 18: Redefining Graphcis and Text Colors

ColorText Color #

Graphics Color #

ColorText Color #

Graphics Color #

Black 0 0 Dark gray 8 240

Red 1 47 Bold Red 9 31

Yellow 2 79 Bold Yellow 10 63

Green 3 111 Bold Green 11 95

Cyan 4 143 Bold Cyan 12 127

Blue 5 175 Bold Blue 13 159

Magenta 6 207 Bold Magenta 14 191

Off-white 7 239 Bold White 15 223


Group CG: Character Graphics

k-fault. nd also tion 8.

ow facil-n ys,

frame ox-ingle e cur-

Portability notesA color screen adapter (CGA/MCGA/EGA/VGA) is required. Both foreground and bacground colors are selectable in all color screen modes. All 16 colors are available by deIf IScreenModeOptions (8,1) has been called (to enable flashing text), only 8 backgroucolors are available in 16-color text modes on MCGA/EGA/VGA screens. The latter is true of background colors on a CGA screen regardless of the state of screen mode opSpecifying a normal intensity color in combination with the 'bold' attribute (as set by ITex-

tAttribute ) has the same effect as specify a bold color directly.

ExampleCALL ITextColourN(5,7) CALL IOutStringXY(1,3,' Blue text on a white background ') CALL ITextColourN(1,-1) CALL 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 GraphicsThe routines in this group are used by the fixed-field-input (IN), menu (MN) and text wind(WN) routines, to draw frames around text areas. Unlike the high- resolution graphics ities described in “High Resolution Graphics” on page 117, these routines are available iboth text and graphics modes. Character graphics frames are drawn in one of two wadepending 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 ais considered to be equivalent to that of one text character. This is obviously true for bdrawing characters, but graphical frames are designed to always lie within the same scharacter cell width/height. This ensures a consistent calling interface, regardless of thrent frame drawing method.

IFrame Subroutine

DescriptionPrint a frame round a screen area.



b-

lid

SyntaxIFrame(ixleft,iytop,ixrght,iybot,action)

ArgumentsINTEGER 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)

EffectDraws 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 suroutine 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 invacorner co-ordinates of the frame are adjusted to fit within the screen area.

ExampleCALL IFrame(10,10,40,12,'C')

CALL ICursorXY(12,11)

CALL IOutString('This is inside the frame')

IFrameOptions Subroutine

DescriptionSpecify frame options (colors, etc.).

SyntaxIFrameOptions(noptn,ivalue)

ArgumentsINTEGER noptn = Option number (see below)

INTEGER ivalue = Option value (see below)


IFrameOptions Subroutine

. If

osi-

cted

y set

lors sed to

EffectDefines options to be applied when drawing text frames.

Option 3 is updated automatically by IFrame , IFrameTitle and IFrameTitleBox to indi-cate the title position within the most recently drawn frame. This information is used byISplitFrameV to determine the top of its vertical line when graphical frames are in useISplitFrameV must be called for a frame which was called earlier with a different title ption, option 3 allows this to be identified.

Options 4/5 allow frame title colors to be controlled independently of the currently selecolors 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. Thethe 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 latteris the default, so frames use the colors most recently selected by ITextColourN . The 'pri-mary' and 'secondary' border colors represent the foreground and background text cowhen using box-character frames. In 3D graphical frames they control the color pairs ucreate the 3D effect.

ExampleCALL 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')

Table 19: IFrameOptions Arguments

Symbolic Name noptn ivalue Default

TitlePos 3

Frame title position (0=as IFrame , i.e., none

1=as IFrameTitle 2=as IFrameTitleBox )

Varies

TitleForeCol 4 Title foreground color (see below)Bold

white

TitleBackCol 5 Title background color (see below) Blue

BorderCol 6 Primary border color (see below) -1

BorderCol2 7 Secondary border color -1



r

the red.

string

ll ays

IFrameTitle Subroutine

DescriptionPrint a frame, with a title within top of frame.

SyntaxIFrameTitle(ixleft,iytop,ixrght,iybot,action,title)





CHARACTER action = String describing required action (any combination in upper olower case):

= 'C' : clear frame contents = 'W' : wide title bar = 'L' : Left justify title = 'R' : Right justify title

CHARACTER title = Heading for top of frame

EffectPrints a frame around an area of the screen, with a title string printed within the top offrame. The title string can be printed at the left or right if required. By default it is centeStrings 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 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 fuwidth of the frame in a manner which is more consistent with graphical frames (which alwuse a full frame-width title bar).

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

IFrameTitleBox Subroutine

DescriptionPrint a frame, with a title in a box at top of frame.


IFrameType Subroutine

r

frame lt it

h ce of a

mes

SyntaxIFrameTitleBox(ixleft,iytop,ixrght,iybot,action,title)





CHARACTER action = String describing required action (any combination in upper olower case):

= 'C' : clear frame contents = 'W' : wide title bar = 'L' : Left justify title = 'R' : Right justify title

CHARACTER title = Heading for top of frame

EffectPrints a frame around an area of the screen, with a title string printed at the top of the in a box of its own. The title string can be printed at the left or right if required. By defauis 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 eacoccupy a separate text row. When 2D graphical frame styles are in use, the appearanframe 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, fradrawn via IFrameTitleBox look better than the IFrameTitle equivalents.

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


DescriptionSelect frame type.

SyntaxIFrameType(itype)



in .,

e

:

e

ArgumentsINTEGER itype = Frame type:

EffectSelects the frame type drawn by IFrame and the various other character graphics routinesthis group. All INTERACTER routines which call the frame drawing routines internally (e.gIWinOpen , IMenuVertic , InStringXYDef , etc.) will automatically use the selected framtype.

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 us

single line frame characters and even numbered frame types select double line framecharacters.

Table 20: Frame Types


SingleLine1 1 Single line (#1)

DoubleLine1 2 Double lines

SingleLine2 3 Single line (#2)

DropShadow 4Double lines (box-character frames)

Drop shadow (graphical frames)

Field3D1 5 3D style best suited to field frames

Field3D2 6 Same as (5) but thicker

Button3D1 7 3D style best suited to buttons

Button3D2 8 Same as (7) but exchanged colors

Window3D1 9 3D style best suited to windows

Window3D2 10 Same as (9) but thicker



elect-

y

t

,

,

-

,

r-

xt col-

(2) Graphical frames:

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

1 The frame is drawn at the outer edge of the single character-cell border area. If thearea within the frame is cleared, then the border character area is also cleared.

2 The same as frame type 1, but a second line is drawn part way into the border char-acter area, giving a slightly more pleasing effect.

3 The frame is drawn at the inner edge of the single character-width border area. Onlthe 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 meethe frame border.

4 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.

5 A 3D-effect frame is drawn at the inner edge of the single character-cell border areausing different colors for the top/left and bottom/right edges. This frame is well suited to input field frames.

6 As for type 5 but slightly thicker.

7 A 3D-effect frame is drawn at the inner edge of the single character-cell border areaas for type 5, plus a single-color/single-pixel border around the edge of the 3D effect.

8 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).

9 A 3D-effect frame is drawn at the outer edge of the single character-cell border areausing 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 boder at characters printed at the edge of the window/menu.

10 As for type 9 but slightly thicker.

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

Example

CALL IFrameType(2)




ing

rtain cted at

the

win-First ently

to this ed es that n-

ISplitFrameH Subroutine

DescriptionSplit up a frame horizontally.

SyntaxISplitFrameH(ixleft,iy,ixrght)

ArgumentsINTEGER ixleft = Left hand end of line

INTEGER iy = Row

INTEGER ixrght = Right hand end of line

EffectPrints a horizontal line from text co-ordinate (IXLEFT,IY) to (IXRGHT,IY) . Where box-characters are used, a 'tee' is printed at either end of the line to split a frame drawn usIFrame , IFrameTitle or IFrameTitleBox .

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

Group WN: Window ManagerThis group provides a useful set of routines which allow text output to be restricted to ceareas of the screen. Several windows can be defined at once, though only one is seleany one time. You 'open' windows using IWinOpen . The precise effect of opening a windowis controlled by the IWinAction routine, which determines whether the area defined by 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 otherdowing routines then operate on that window. Logically, windows are 'stacked' Last In Out, though they need not physically lie on top of one another on screen. The most recopened window is referred to as the 'top' window. Open and Close operations all apply top window only. All other operations apply to the currently selected window, which nenot necessarily be the top one (though as explained above opening a new window makthe 'current' window by default). IWinSelect can be used to select between the open widows. This is of most use when your windows have been laid out in a tiled (i.e., non-overlapping) manner.


IWinAction Subroutine

uses hem r like en d so articu-

ter-

n-ken:

es

Various operations re-select the top or current window:

• If IWinClose is called to close the top window, the window management system hasno 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 caINTERACTER to copy the current screen contents before opening the window, enabling tto be restored later when it is closed. This enables windows to appear on screen rathepieces of paper, which can be 'lifted' to reveal what was there before. Windows can evoverlap in this case, so one window can be laid on top of another, on top of another anon. As each one is closed, the contents of the one 'underneath' will reappear. This is plarly useful for instant 'help' windows, dialogue boxes, etc.

The colors and attributes of all text output via the window management routines are demined by the most recent calls to the routines in the AT group.

IWinAction Subroutine

DescriptionDefine action to be taken when opening a window.

SyntaxIWinAction(action)

ArgumentsCHARACTER action = String describing action when opening a new window. If it cotains any of the following characters (upper or lower case), the specified actions are ta

= '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 titlare always wide) = 'L': Left justify title = 'R': Right justify title



und

ening pop-ze of he all emain-

it n, by

d all

large ry but

EffectControls 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 . Alterna-tively, 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 backgrocolor or highlight.

If 'pop-up' mode is selected, the screen area 'under' the window will be copied before opthe window, enabling the old window contents to be restored when it is closed. while 'up' mode is enabled, the number of windows which can be opened is limited by the sithe internal buffer into which the old screen contents are copied. This buffer will hold tequivalent of 10000 characters of screen text. i.e., The total size (including frames) ofsimultaneously open pop-up windows cannot exceed 10000 characters. To check the ring 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 IWinOpen-

Title . By default titles are centered.

The window management system derives much of its flexibility from this routine, sincealso enables the window control facilities to be applied to text which is already on screeomitting C from the action argument.

When the window system is initialized, frames are 'on', pop-up is 'off' , clearing is 'on' antitles are wide.

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

ExampleCALL IWinOpen(20,2,30,3)

CALL IWinOutStringXY(2,2,'Cleared window with a frame')

CALL IWinAction('pc')


CALL IWinOutStringXY(2,2,'Pop-up window with no frame')


IWinClear Subroutine

dow, win-

IWinClear Subroutine

DescriptionClear the whole of the currently selected window.

SyntaxIWinClear()

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


CALL IWinOutStringXY(1,1,'Here is some help info ...')

CALL IWinOutStringXY(1,3,'Press SPACE to continue >')

10 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')

IWinClearArea Subroutine

DescriptionClear an area of the currently selected window.

SyntaxIWinClearArea(ixtopl,iytopl,ixbotr,iybotr)

ArgumentsINTEGER 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



t win-

ted

the

pop-stored

win-ged.

ve' it

EffectClears an area of the currently selected window, defined by the top left and bottom righdow 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 selecby ITextColourN or ITextAttribute .

ExampleCALL 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

DescriptionClose top window & optionally restore screen.

SyntaxIWinClose(iconte)

ArgumentsINTEGER 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

window was opened) or clear window.

EffectCloses the top window, regardless of which window is currently selected for output. If up mode was on when the window was first opened, the old screen contents can be reas 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 dow also becomes the current window, otherwise the current window remains unchan

If the current window is not the top window and it must be closed, all the windows 'aboin the stack must also be closed.


IWinCursorXY Subroutine

t

ExampleCALL IWinAction('PFC')



CALL IWinOutStringXY(1,3,'Press SPACE to continue >')

10 CALL InKeyEvent(Key)

IF (Key.NE.ICHAR(' ')) THEN

GO TO 10

END IF

CALL IWinClose(1)

IWinCursorXY Subroutine

DescriptionPosition cursor within current window.

SyntaxIWinCursorXY(ix,iy)

ArgumentsINTEGER ix = Column in current window

INTEGER iy = Row in current window

EffectMoves the cursor to the specified (x,y) position within the current window. Remember thain this context (1,1) is the top left corner of the window.

ExampleCALL ICursorXY(5,5)

CALL IOutString('This is at (5,5)')


CALL IWinCursorXY(5,5)

CALL IOutString('But this is at (15,15)')

IWinOpen Subroutine

DescriptionOpen a new window.



n of hen

r-

e

.

rti-

reens input

SyntaxIWinOpen(ixtopl,iytopl,iwidth,iheigh)

ArgumentsINTEGER 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

EffectOpens a new window. This becomes both the top and the current window. The positiothe previously opened window (if any) is not lost, so that window can be returned to wthe 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 chaacter 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 thoriginal screen contents are correctly restored.

Selecting reverse video or a background color before calling IWinOpen (using ITextAt-

tribute or ITextColourN ) sets the initial color in which the window is printed/clearedThis 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 vecally by specifying zero ixtopl and/or iytopl values. Similarly the window can be forced toappear 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 orpartly off-screen. This is particularly useful when a program must be able to run on scwith differing dimensions. These positioning conventions are shared with the menu andbox routines in the MN/IN groups.

As an alternative, windows can also be opened with a title using IWinOpenTitle .


IWinOpenTitle Subroutine

no

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

ExampleCALL 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 >')

10 CALL InKeyEvent(Key) IF (Key.NE.ICHAR(' ')) THEN GO TO 10 END IFCALL IWinClose(1)

IWinOpenTitle Subroutine

DescriptionOpen a new window with a title.

SyntaxIWinOpenTitle(ixtopl,iytopl,iwidth,iheigh,title)

ArgumentsINTEGER 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

EffectOpens 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 disabledtitle is printed. In all other respects this is exactly the same as IWinOpen (in fact, IWinO-

penTitle 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.



This uld

T

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

ExampleCALL IWinOpenTitle(10,2,30,3,'Help')


IWinOutString Subroutine

DescriptionOutput string at current window cursor position.

SyntaxIWinOutString(string)

ArgumentsCHARACTER string = String to write out

EffectOutputs the supplied string to the current window, at the current window cursor position.is the window management equivalent of IOutString . If the text would extend beyond theright-hand column of the window the text is wrapped onto the next line. Text which woappear 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 Agroup.


CALL IWinOutStringXY(2,3,'Here is some text ...')

CALL IWinOutString(' and this follows it.')

IWinOutStringXY Subroutine

DescriptionOutput string at a specific window position.


IWinSelect Subroutine

ordi-

xt

T

pen/

SyntaxIWinOutStringXY(ix,iy,string)

ArgumentsINTEGER ix = Column in current window

INTEGER iy = Row in current window


EffectOutputs the supplied string to the current window, starting at the specified window co-nate. 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. Tewhich 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 Agroup.


CALL IWinOutStringXY(1,5, &

'This should appear halfway down the window')

IWinSelect Subroutine

DescriptionSelect current window by number.

SyntaxIWinSelect(number)

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

EffectSelects the 'current' window by number. All window operations, with the exception of OClose, will apply to the specified window.



n the e

ged. mber

Whenever a window is opened, it is assigned a number corresponding to its position iwindow 'stack'. The first window to be opened is thus number 1. If a second window isopened without closing the first that becomes number 2 and so on. Any window can bselected 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 unchanInfoWindow can be called to check how many windows have been opened (i.e., the nuof the 'top' window) and also the number of the 'current' window.

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


12 Input Handling

dling

ative i.e.,

re

be

s is also

Group KM: Keyboard/Mouse Event HandlingThe routines in this group provide the most basic keyboard and mouse input event hanfunctions. 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 toidentify non-printing (e.g., function) keys in a keyboard independent manner. The alternroutine InKeyEventImm performs exactly the same task, but in a non-blocking manner, 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 hardwatext cursor support.

While InKeyEvent always reports keyboard events, the reporting of other events can selectively enabled or disabled using InEventSelect .

For keyboard debugging purposes, direct access to system dependent keyboard codeprovided by means of the lower level InCharacter .

InCharacter Subroutine

DescriptionGet single character from keyboard (wait for key press).

SyntaxInCharacter(ichr)

ArgumentsINTEGER ichr = ASCII code returned from keyboard


Chapter 12 Input Handling

y has

yboard calls to

en-

ify the

turned

EffectGets a single character from the keyboard queue. This routine will not return until a kebeen 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/kedependent codes. In this case these codes will be returned sequentially in consecutiveInCharacter .

InCharacter should be viewed as providing 'raw' keyboard input. As such, it fails to idtify 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 identprecise low-level codes being generated by the keyboard. Otherwise, InKeyEvent should be used instead.

Portability notesKeyboard input is via DOS interrupts. Where a standard ASCII key is detected, InCharac-

ter only returns the ASCII code. If an extended key code is detected, two codes are rein consecutive calls to InCharacter . 8-bit keycodes entered using Alt/ keypad will be returned unmodified.

InEventSelect Subroutine

DescriptionSelect events to be reported via InKeyEvent /InKeyEventImm .

SyntaxInEventSelect(nevent,iemask)


InEventSelect Subroutine

d

Arguments

INTEGER nevent = Event types to enable/disable:

INTEGER iemask = Event mask for all events or one event: If nevent > 0 then iemask =:

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 sum-ming the relevant event mask values in iemask. Alternatively, single events can be switcheon or off by specifying the appropriate event number in nevent and passing a binary flag in iemask.

Table 21: nevent values


AllEvents 0 All events at once

ButtonDown 1 Mouse button-down events

ButtonUp 2 Mouse button-up events

MouseMoveText 3 Mouse movement events (text)

MouseMoveGraph 4 Mouse movement events (graphics)

ResizeExpose 6 Graphics window expose/resize events

Table 22: iemask values ( nevent > 0)


IntNo 0 Disable event specified by nevent

IntYes 1 Enable event specified by nevent



is then -

rm

and on as p and

s

only

t, in n.

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 cursoravailable via InfoInput and/or InfoGraphics . Two demonstration programs on the distribution media (doodlet and doodleg ) show how event selection can be used to perfolow level mouse handling.

Only mouse button-down and expose/resize events are reported by default. Button-upmovement events should only be activated while they are required and disabled as sothey are no longer needed. The fixed field input and menu routines all disable button-umovement 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 modeand occur when the mouse crosses a text cell boundary.

• Graphics mouse movement events are available in graphics screen mode only andoccur when the mouse moves to a new pixel position.

Both movement event types can be selected if required, though it will be more usual toselect 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 environmenthe full version of INTERACTER, to identify when the graphics window needs to be redrawThis 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)



ArgumentsINTEGER, 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 icode Key Name icode Key

KeyBack-Space

8 Backspace KeyShiftTab 144 Shift/Tab

KeyTab 9 TabKeyDelete-Under

143Delete under cursor

KeyReturn 13 Return Keypad0 150 Keypad 0

KeyEscape 27 Escape Keypad1 151 Keypad 1

KeyDelete 127 Delete left Keypad2 152 Keypad 2

KeyCursorUp 128 Cursor up Keypad3 153 Keypad 3

KeyCursor-Down

129 Cursor down Keypad4 154 Keypad 4

KeyCursor-Right

130 Cursor right Keypad5 155 Keypad 5

KeyCursor-Left

131 Cursor left Keypad6 156 Keypad 6

KeyPageUp 132 Page up Keypad7 157 Keypad 7

KeyPageDown 133 Page down Keypad8 158 Keypad 8

KeyPageRi-ght

134 Page right Keypad9 159 Keypad 9

KeyPageLeft 135 Page left KeypadMinus 160 Keypad -

KeyUpEx-treme

136 Extreme up KeypadPoint 161 Keypad .

KeyDownEx-treme

137 Extreme down KeypadPlus 162 Keypad +



KeyRightEx-treme

138 Extreme rightKeypadDi-vide

163 Keypad /

KeyLeftEx-treme

139 Extreme leftKeypadMul-tiply

164 Keypad *

KeyHome 140 Home KeypadHash 165 Keypad #

KeyEnd 141 End KeypadEnter 166 Keypad enter

KeyInsert 142 Insert KeyPrint 170 Print


Name icode Key(s)

KeyF1 - KeyF20 171 - 190 F1 - F20

KeyShiftF1 - KeyShiftF20 191 - 210 Shift/F1 - Shift/F20

KeyCtrlF1 - KeyCtrlF20 211 - 230 Ctrl/F1 - Ctrl/F20

KeyAltF1 - KeyAltF20 231-250 Alt/F1 - Alt/F20

LeftButtonDown 251 Left mouse button down

MiddleButtonDown 252 Middle mouse button down

RightButtonDown 253 Right mouse button down

LeftButtonUp 254 Left mouse buttonup

MiddleButtonUp 255 Middle mouse button up

RightButtonUp 256 Right mouse button up

MouseMove 257 Mouse moved

ResizeEvent 259Graphics window exposed/resized

KeyAltBackspace 520 Alt/Backspace


Name icode Key Name icode Key



iding here er the

n ys. level ow-

use

es in arac-e ur-

for ideal'

C

The the -ses

le, d

events

EffectGets the next event from the input queue. Keystroke events are always reported, provportability to all display types. Mouse button-down events are also reported by default, wa mouse is known to be available. Other mouse events can optionally be reported, undcontrol of the InEventSelect routine.

At its simplest level, InKeyEvent is a single key input routine, performing the same functioas InCharacter except also uniquely identifying cursor, keypad, function and editing keIts additional ability to report mouse button/movement events makes it suitable for low input handling on a wide variety of displays from dumb terminals to mouse driven winding environments. InKeyEvent is recommended as the lowest level of keyboard and mohandling which should be used.

Ordinary printable keyboard characters are returned as 7-bit ASCII codes, i.e., as valuthe range 32-126 . Many keyboards are also able to generate system dependent 8-bit chters (e.g., to generate international characters). Since these key codes are in the rang128-

255 , they conflict with INTERACTER's system independent codes allocated for function/csor/keypad keys. InKeyEvent thus adds 256 to 8-bit keyboard codes to differentiate themfrom 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 non-printable keys. The table describes the key code assignments by function for an 'keyboard. “Keyboard Codes” on page 41 lists the actual keys which are recognized on Pkeyboards.

Some keyboards support keypad identification, but lack other dedicated special keys. original ('standard') 83-key IBM PC keyboard does not have separate cursor keys. Forsake 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 cauthe 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 tabi.e., 150-166 . Refer to the InKeypad routine in the IP group for more information on keypainterpretation selection. “Keyboard Codes” on page 41 also gives more details.

Where mouse input is available, InKeyEvent can also detect mouse events. The precisecombination 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

KeyAltTab 521 Alt/Tab

KeyAltReturn 525 Alt/Return

KeyAltEscape 539 Alt/Escape


Name icode Key(s)



ed is e

are not. If a mouse event is reported, the position of the mouse when the event occurravailable via InfoInput(62)/(63) . In graphics modes, the position may alternatively bavailable in graphics co-ordinates via InfoGraphics(5)/(6) . A time stamp is also nor-mally available for such mouse events, via InfoInput(70) .

In addition to keyboard and mouse events, InKeyEvent can also report when the graphicswindow needs to be redrawn in a windowing environment (icode = 259 ). This event code will never be reported in the DOS version.

Portability notesSee “Keyboard Codes” on page 41 for details of version/keyboard-specific keycodes.

ExampleCALL 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

DescriptionAs InKeyEvent but also simulate a text cursor.

SyntaxInKeyEventCursor(icode)

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


InKeyEventImm Subroutine

is is

field

er-

EffectInKeyEventCursor 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). Thuseful 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 fixedinput routines in the IN group.

On displays which support a hardware text cursor, calling InKeyEventCursor is exactly equivalent to calling InKeyEvent .

Portability notesA cursor is simulated in DOS graphics modes.

ExampleCHARACTER (LEN=10) :: NAME

CALL IOutStringXY(2,2,'Enter name: ')

IPOS = 1

10 CALL InKeyEventCursor(ICODE)

IF (ICODE>=32.AND.ICODE<=126) THEN

NAME(IPOS:IPOS) = CHAR(ICODE)

CALL IOutString(CHAR(ICODE))

GO TO 10

ELSE ...

InKeyEventImm Subroutine

DescriptionAs InKeyEvent but immediate return if no event waiting.

SyntaxInKeyEventImm(icode)

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

EffectThis 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 opation of this routine is exactly as for InKeyEvent , so refer to that routine for more information.



hey typ-

or n.

sor nd

ut fer s the alent

te on

and ursor exit the

ExampleCALL 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 HandlingThese routines are built on the lower level single key input facilities in the KM group. Tprovide a controlled substitute for the Fortran READ statement, preventing the user froming outside a specified on-screen field. InString reads character data at the current cursposition. A more powerful variant of this routine, InStringDef , enables a default value tobe presented to the user which can either be changed or accepted without modificatio

The two fixed field input routines described above both take input from the current curposition. Two complementary routines offer the facility to specify the cursor position awhether 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 inpfield/box if it would otherwise lie partly or wholly off screen. Similarly, these routines ofthe ability to center the input field either horizontally or vertically in the same manner amenu (MN) and window opening routines. These features are not offered by the equivinput-at-cursor routines.

All of the routines in this group activate the text cursor and restore it to its previous staexit.

Similarly, all routines in this group activate the mouse cursor (where available) on entryrestore it to its previous state on exit. The mouse can be used to move the text input cwithin the field by clicking on the required position. The mouse can optionally be used tofrom a fixed field input routine by clicking outside of the field (with any button) or inside 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 sec-tion later in this chapter.


InString Subroutine

g

D ble

hose the

e pre-

is i-

a

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 trailinblanks

Effect

Fixed-field string input routine, providing a controlled replacement for the Fortran REAstatement. The user is not allowed to enter a response longer than the receiving variastring. 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 tcurrently selected, are trapped and ignored. The text cursor can be repositioned withinfield 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. Thcise 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 thcase, InfoInput(55) will return a control key of -2 . The mouse button number and postion 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 viInKeyEventCursor . This is removed automatically on exit.



er,

ull

d at it and/ (i.e.,

string, ly

ExampleCHARACTER (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

DescriptionGet fixed length string, offering a default.

SyntaxInStringDef(string,length)

ArgumentsCHARACTER 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 usincluding any typed trailing blanks

EffectFixed field string input routine, with a default reply supplied to save the user typing a fresponse (e.g., a standard filename). In all other respects, this routine is equivalent toInString .

The default response string is displayed at the current cursor position. The cursor is placethe beginning of the response. The user can then modify the response by typing over or clearing parts of it. Any of the 'exit' keys can be pressed to terminate input. By defaultif 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 suppliedlength is returned accordingly including any trailing spaces which the user may explicittype at the end of the string.

Portability notesSee InString


InStringXY Subroutine

lly)


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

DescriptionGet string at an (x,y) position (no default offered).

SyntaxInStringXY(ixpos,iypos,prompt,iframe,string,length)

ArgumentsINTEGER ixpos = Column at which field is to be displayed (zero to center field horizonta

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



g

p up.

the

lly)

er,

INTEGER, OPTIONAL length = Actual length of string entered by user, including trailinblanks

EffectFixed-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 po

The pop-up mode is selectable by calling InPopup and the appearance of the input field iscontrolled by InHighlight . The text and mouse cursors are automatically enabled for duration of the call and restored to their previous state on exit.


ExampleCHARACTER (LEN=8) :: USERID

CALL InHighlight('W','BLUE')

CALL InStringXY(5,5,'Enter i.d. ',0,USERID,LENGTH)

InStringXYDef Subroutine

DescriptionGet string at an (x,y) position, offering a default.

SyntaxInStringXYDef(ixpos,iypos,prompt,iframe,string,length)

ArgumentsINTEGER ixpos = Column at which field is to be displayed (zero to center field horizonta

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 = 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 usincluding any typed trailing blanks


Group MN: Menu Handling

to he

the

roup

ar is

elec-

ntry ns. The f the

eans stored e p' lected.

in the eter-

EffectFixed-field string input routine, with a default reply supplied. This is directly equivalentcalling InStringDef except that position, prompt and frame can all be specified, and tinput field can be made to pop up.

The pop-up mode is selectable by calling InPopup and the appearance of the input field iscontrolled by InHighlight . The text and mouse cursors are automatically enabled for duration of the call and restored to their previous state on exit.


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

Group MN: Menu HandlingMenus can be presented in either horizontal or vertical layouts. Both routines in this gdisplay 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 bmoved 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 stion. 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 eand restore it to its previous state on exit. The mouse can be used to select menu optiomouse can also be used to exit from a menu function by selecting a position outside omenu, 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 InMouseOp-

tions(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 mthat the menu can be displayed, a selection made and the previous screen contents rewith no special action by the calling program other than enabling 'pop up' mode (see thInPopup routine in the IP group). This feature can be extended using the 'linked pop-umode to create menu chains which are only closed when the last sub-menu item is seLinked mode is also selectable via InPopup .

All menus are displayed using the text attributes most recently selected by the routinesAT group. Also, the means by which a currently selectable item is highlighted can be dmined using InHighlight . This defines the preferred highlighting method, but



use. enu m an

en, such izon-

INTERACTER will adapt the actual highlight used depending on the display hardware inThis is a very useful portability aid. Whatever highlight is used to display a selectable moption, the current text attributes selected by the AT routines are undisturbed on exit froMN 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-screits position is adjusted to fit on screen. Where a menu is too large to fit on screen, no adjustment is made. The menu functions offer the ability to center the menu either hortally or vertically in the same manner as the input box and window opening routines.

IMenuHoriz Function

DescriptionHorizontal pointer/highlight menu.

SyntaxIMenuHoriz(option,maxopt,ixpos,iypos,iwidth,ibordr,istopt)

ArgumentsCHARACTER 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)

ReturnsAn INTEGER with the option number chosen


IMenuHoriz Function

y hosen

ltiple lumn.

.

e

the

take

zero other-

med.

EffectPresents a horizontal (possibly multi-line) pointer/highlight menu described in the arraoption and gets a selection from the user. It returns the option number which has been cby simply pointing to the required menu item.

All the available options can be displayed at one time. Options are displayed across mulines, such that the menu occupies the specified screen width starting at the specified coIf 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 byInControlKey or the initialization file (usually Space and Return ).

• The user may also select an option directly by pressing the initial letter of that optionAlt and an initial letter can also be used, provided that this key combination has notbeen 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 sameffect. (See also InEventSelect and InMouseOptions )..

In addition to the 'confirm' key, tab/back-tab/help/quit keys can also be used to exit frommenu. 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 responsi-bility of the calling program to decide whether to allow the use of these exit keys and toappropriate 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 toif a keyboard key is used to exit from the menu, but returns the mouse button number wise. When used in combination with InfoInput(55) and InfoInput(62)/(63) (the mouse position) this mechanism allows button dependent exit processing to be perfor

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 isuseful 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.



ing

eters.

were

her ar in ption

r-

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 usthe 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 paramFor example, if you ask for a frame, the top left corner of the frame will thus be at ( ixpos-1, iypos-1) , since the frame occupies 1 row and column. If only a line above the menu 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 otmenu options. In other words, any option which starts with a dash (e.g., '----') will appethe menu but the user will not be able to place the highlight bar on that line or select the ousing its initial letter or the mouse.

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

ExampleCHARACTER (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

DescriptionVertical pointer/highlight menu.

SyntaxIMenuVertic(option,maxopt,ixpos,iypos,title,ispace,iframe,istopt)


IMenuVertic Function

to the

.

e

ArgumentsCHARACTER 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 non-blank > 1 : draw a frame, placing title in a box at top of frame if title isnon-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)

ReturnsAn INTEGER with the option number chosen

EffectPresents 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 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 byInControlKey or the initialization file (usually Space and Return ).

• The user may also select an option directly by pressing the initial letter of that optionAlt and an initial letter can also be used, provided that this key combination has notbeen 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 sameffect. (See also InEventSelect and InMouseOptions )..



the

take

d key sed in

rs. uested

ing

u

pa-tion but g its

r-

In addition to the 'confirm' key, tab/back-tab/help/quit keys can also be used to exit frommenu. 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 responsi-bility of the calling program to decide whether to allow the use of these exit keys and toappropriate action if they are used instead of the usual confirm key.

Another useful exit code is InfoInput(61) . This identifies whether a mouse button wasused to exit from the menu and if so which one. This is always set to zero if a keyboaris used to exit from the menu, but returns the mouse button number otherwise. When ucombination 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 parameteHence the position of the menu itself is the same regardless of whether a frame is reqor 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 isuseful to avoid unnecessary menu 'repainting'. In this case IABS( istopt) must spec-ify 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 usthe 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 menarea specified by the subroutine parameters.

Options which start with a hyphen ('- ') are displayed, but non-selectable. This enables serator lines to be included in the list of options, allowing menus to be sub-divided by funcif required. In other words, any option which starts with a dash will appear in the menuthe user will not be able to place the highlight bar on that line or select the option usininitial letter or the mouse.

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


Group IP: Input Control Parameter Selection

n be

an all

ng

es

lled

ExampleCHARACTER (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 SelectionThe behavior of the input and menu handling routines in the IN, WN and MN groups camodified using the parameter selection routines in this group.

The control keys used by the various fixed field input routines and the menu routines cbe redefined using InControlKey .

The text attributes for menu highlight bars and data entry fields can be determined usiInHighlight . 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 routinwhich take input from the keyboard.

Mouse processing in single key and fixed field input routines and menus can be controvia the InMouseOptions mouse options routine.

InControlKey Subroutine

DescriptionDefine control keys for all input handling routines.

SyntaxInControlKey(keycnt,keycod)



ArgumentsINTEGER keycnt = Control key number:

Table 25: keycnt values

Name keycnt Action

ControlUp 1 Cursor up

ControlDown 2 Cursor down

ControlRight 3 Cursor right

ControlLeft 4 Cursor left

ControlPageUp 5 Extended cursor up (’Page up’)

ControlPageDown 6Extended cursor down (’Page down’)

ControlPageRight 7 Extended cursor right

ControlPageLeft 8 Extended cursor left

ControlExtremeUp 9 Extreme cursor up

ControlExtremeDown 10 Extreme cursor down

ControlExtremeRight 11 Extreme cursor right

ControlExtremeLeft 12 Extreme cursor left

ControlClearStart 13 Clear to start of field

ControlClearEnd 14 Clear to end of field

ControlMoveStart 15 Move to start

ControlMoveEnd 16 Move to end

ControlInsert 17 Toggle insert mode

ControlBackspace1 18 Backspace and delete (key 1)

ControlBackspace2 19 Backspace and delete (key 2)

ControlDelete 20 Delete character under cursor

ControlConfirm 21 Confirm input

ControlHelp 22 Help


InControlKey Subroutine

h the

vail-

s to

a use-s

r end

e non-

ace

. In ently

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

EffectAllows any one of the listed input control keys to be redefined. These are the keys whicuser 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 aable 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 keyuse 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 isful way of temporarily deactivating keys such as Tab, Back-tab or quit. In this case, it iadvisable to first read the current value using InfoInput , save this value, then call InCon-

trolKey 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 oof 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 somPC keyboards generate backspace (ASCII 8) and some generate delete (ASCII 127 ), and many generate both depending on which key is pressed. INTERACTER overcomes this prob-lem by allowing both keys to do the same job. Of course, if you only want one 'backspand 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 routinesother words, keyboard input ceases when any of these keys are pressed and the currentered value is passed back to the calling program. Keys 26-30 and 36-70 are also avail-

ControlQuit 23 Quit

ControlTab 24 Tab

ControlBackTab 25 Back-tab

26-30 Spare ’exit’ codes (group 1)

ControlNext 35 Next item/next page

36-70 Spare ’exit’ codes (group 2)

Table 25: keycnt values

Name keycnt Action



ting gram eing n-ost

-

to

e e.

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 terminakeyboard input and nothing else. They are defined separately to enable the calling proto take different action depending on the context in which a particular input routine is bused. Since any InKeyEvent code can be assigned as a control 'key' this means that nokeyboard event codes (e.g., mouse events) can also be assigned as exit 'keys'. The mrecently 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 onthe next menu item.

As an alternative to calling InControlKey , control keys can be defined at run time using thinitialization file, thus offering the user total flexibility in selecting the keyboard interfacSee “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)


InHighlight Subroutine

utines

ng fault

olor the

nding

e thout ot

ArgumentsCHARACTER high1and high2 =A pair of strings containing blanks, the word 'BOLD', or color names as follows:

(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 roIMenuHoriz and IMenuVertic , and the fixed-field input routines InStringXY and InStringXYDef . The currently selected menu option or input field will be highlighted usione of reverse video, bold text or a foreground / background color combination. The depreferred highlight is bold white on blue until changed by InHighlight .

high1 can be one of three highlight definitions: blank (for reverse video or background conly), 'bold' in lower or upper case, (for bold text with an optional foreground color) or 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 depeon 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 monochromscreen mode, will cause reverse video to be used instead. Thus color can be used, wisacrificing portability since the pointer/highlight facilities will still operate when color is navailable.

ExampleCALL InHighlight('BOLD','RED')

IOPT = IMenuVertic(OPT,MAXOPT,IX,IY,'Menu',ISPC,IFRM,ISTOPT)

CALL InHighlight('BLUE','WHITE')


CALL InHighlight(' ','BLUE')


Table 26: high1 and high2 values

high1 high2 Highlight style

blank blank Reverse video

’BOLD’ blank Bold text in current foreground color

’BOLD’ colourF Bold text in foreground colourF

colourF colourB Foreground colourF / background colourB

blank colourB Current foreground color / background colourB

colourF blank Foreground colourF / Current background color



the

InKeypad Subroutine

DescriptionSelect keypad detection/interpretation mode.

SyntaxInKeypad(mode)

ArgumentsINTEGER mode = mode for keypad interpretation:

EffectSelects 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 fixed field input routines.

This table summarizes the codes returned by the keypad in each of the three modes:

Table 27: Keypad mode values

Name keycnt Action

NumericMode 1 Numeric mode

SubstMode 2 Special key substitution mode

FullMode 3 Full keypad mode

Table 28: Keypad Codes

Keypad Key Mode 1 Mode 2 Mode 3

0 48 142 (Insert) 150

1 49 141 (End) 151

2 50 129 (Cursor down) 152

3 51 133 (Page down) 153

4 52 131 (Cursor left) 154

5 53 155 155

6 54 130 (Cursor right) 156

7 55 140 (Home) 157


InKeypad Subroutine

d rom

keys ere

parate,

pad.

In numeric mode (mode=1) the keys return the codes shown on the key tops, e.g., keypa9 generates character '9' and so on. In this mode keys on the keypad are indistinguishable fequivalent 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 is more variable. For example, on the original ('standard') 83-key IBM PC keyboard, thare 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 secall InfoInput(56) .

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

8 56 128 (Cursor up) 158

9 57 132 (Page up) 159

- 45 160 160

. 46 143 (Delete) 161

+ or , 43 or 44 162 162

/ 47 163 163

* 42 164 164

# 35 165 165

Enter 13 166 166

Table 28: Keypad Codes

Keypad Key Mode 1 Mode 2 Mode 3



ExampleCALL 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

DescriptionSpecify mouse options for fixed field/menu input.

SyntaxInMouseOptions(noptn,ivalue)

ArgumentsINTEGER noptn = Option number (see below)


InMouseOptions Subroutine

ion uired

ld

ll n

ailable:

t


EffectDefines 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 selectoccurs outside the area defined by the relevant routine. A couple of definitions are reqhere:

• 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-downinside the menu.

• Outside means the area beyond the frame (or beyond the area which the frame wousurround, if no frame is selected).

When option 2 is set to 1 (the default), a mouse button selection outside a field/menu wireturn an InfoInput(55) exit key code of -2 . The mouse button number and position whethe selection occurred will then be available via InfoInput(61-63) and/or InfoGraph-

ics(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 av

ivalue=0: Selects the behavior of INTERACTER 3.0 and earlier, where selection occurs assoon as a button is clicked.

Table 29: noptn and ivalue

Name noptn ivalue

MouseExit 2

Set behavior on a mouse button press outside 'inpuarea':NoMouseExit (0): do nothingExitOutside (1): exitNoMouseExitBell (2): ring bell

MouseFeel 3

Select mouse feel:SelectOnButDown (0): Select on button-downDragRelease (1): Windows 3.x-like feelFollowCursor (2): Windows 4.x-like feel

ConfirmFixed-Button

106

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



urs ile a

a win-

er a

ld, e

e as

ivalue=1: Selects a Windows 3.x style feel. This is the default. Selection in menus occwhen a mouse button is released, with the highlight bar following mouse movement whbutton is held down. Releasing a button outside of a menu after a button press inside dow 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 whethbutton is held down.

Enabling option 106 cause mouse clicks in an input field (see IN group) to confirm the fierather than moving the cursor. If ivalue is zero, the specified button action is disabled. Thdefault is 3. The current setting can be interrogated via InfoInput(106) .

ExampleCALL InMouseOptions(2,1)


KEXIT = InfoInput(55)

IF (KEXIT==-2) THEN

MOUSEX = InfoInput(62)

MOUSEY = InfoInput(63)

ELSE IF (KEXIT==23) THEN

...

InPopup Subroutine

DescriptionSelect pop-up mode for menu & input-at-(x,y) routines.

SyntaxInPopup(mode)

ArgumentsCHARACTER 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

EffectSelects the 'pop-up' mode for the pointer/highlight menu routines, IMenuHoriz and IMenu-

Vertic , plus the fixed field input-box routines InStringXY and InStringXYDef .

Three pop-up modes are available, namely single, disabled or linked. The default modselected at start-up by IScreenopen is 'disabled'.


InPopup Subroutine

over-stored use than tirely

ts

is rred

d

s p win-

er

win-

more w a in and - will

ked

lable

.

Single pop-up mode: When enabled, this feature causes menus and input boxes to be laid on top of whatever is already on the screen. The original screen contents are then reas soon as a selection has been made or a value has been entered. This is simpler to linked mode (see below), since each pop-up uses its own workspace and operates enindependently of other parts of the library.

Disabled pop-up mode: When the pop-up feature is switched off, menu or field contenremain on the screen. The underlying screen area cannot be restored.

Linked pop-up mode: Pop-up menus and input boxes can alternatively be linked. Thisthe most complex mode of operation, but one which offers greatest flexibility. It is refeto as 'linked' mode for two reasons:

• Menus and/or input boxes can be linked together, with the original screen contentsonly being restored at the end of the chain.

• For the duration of the chain, the menu/input-box routines are linked to the windowmanagement system. Each menu or input box opens its own pop-up window, usingthe window manager's workspace. This also means that windows can also be openeas 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 iclosed, but see below). Thereafter, each call to a menu/input-box routine opens a pop-udow of exactly the size occupied by the menu or box. Each menu/box becomes anothwindow 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 alldows 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 windows than intended, particularly where 'walking' menus are constructed which allouser to move both down and up a menu chain. When 'unwinding' back up a menu chare-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. Thisprevent an additional window being opened over the top of the existing menu. See the LINK-

MENU demonstration program on your distribution disk for an example of how to use linmenu 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 avaispace 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



is buff-dow ode

ation cess ed in reen

Portability notesMenus and input-boxes can pop-up over both text and graphics. Graphics screen dataered to a compressed memory buffer of approx 400k, which is shared with the text winmanager. The available space in this buffer for a menu or input-box in "single pop-up" mtherefore depends on whether any pop-up windows are currently open. In the rare situwhere a pop-up requires more buffer space than is available in the memory buffer, exscreen data is buffered to a disk buffer (on drive C:). In practice, a disk buffer is only ushigh resolution 256 color SVGA modes, for pop-up menus which occupy very large scareas.

ExampleCHARACTER (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 ControlThis group provides basic mouse cursor enable/disable routines.

IMouseCursorHide Subroutine

DescriptionHide mouse cursor.

SyntaxIMouseCursorHide()

EffectRemoves the mouse cursor from the screen.

See also IMouseCursorShow which displays the mouse cursor.


IMouseCursorShow Subroutine

ting th text

Portability notesIt is advisable to temporarily remove the mouse cursor from the screen before generascreen output, otherwise the cursor may become corrupted. This call is supported in boand graphics screen modes under DOS provided MOUSE.COM is loaded.

ExampleSee DOODLET and DOODLEG demos on distribution media.

IMouseCursorShow Subroutine

DescriptionShow mouse cursor.

SyntaxIMouseCursorShow()

EffectDisplays the mouse cursor at the current mouse position.

See also IMouseCursorHide which removes the mouse cursor.

Portability notesSee IMouseCursorHide .

ExampleSee DOODLET and DOODLEG demos on distribution media.




13 High Resolution Graphics

type

with

the creen

display d

The graphics routines in the following groups are designed to be portable to virtually anyof 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 associatedthe routines in the GS group. Also available in the IF group is the InfoGraphics function which reports various graphics parameter settings.

Group GG: General GraphicsStarting and FinishingINTERACTER'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. INTER-ACTER graphics remain available until IScreenClose is called.

Co-ordinate SystemWhile in graphics mode, the co-ordinate system is user-definable and is not related tophysical resolution of the output device, making graphics based programs device and smode independent. The area of the screen or output page to be used for the graphics can also be defined. The IGrArea and IGrUnits routines control the main graphics area anco-ordinate system respectively. Calls to routines in other groups, such as IGrLineTo , IGr-

CharOut , etc. all use (x,y) co-ordinates defined in terms of the range set by the call to


Chapter 13 High Resolution Graphics

out-

/page.

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 drawside 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

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

DescriptionDefine size of graphics area.

SyntaxIGrArea(xleft,ylower,xright,yupper)

ArgumentsREAL 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 )


IGrAreaClear Subroutine

creen ues in

ging isplay

nger r

f the

EffectDefines the area of the screen to be used by all following graphics commands. The full sis defined as being 1 unit high and 1 unit wide, so you should describe your area in valthe range 0.0 - 1.0 as shown above. When you call IGrUnits , that then defines the co-ordinate 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 chanyour co-ordinate system or any other parameters. In the example below, a full screen dis 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 loequal (e.g., 0.5 high and 1.0 wide) then regular shapes will be distorted accordingly. Foexample, circles become elliptical, squares become rectangular and so on.

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

ExampleCALL IGrArea(0.0,0.0,1.0,1.0)

CALL MYGRAF

CALL IGrPause(' ')

CALL IGrArea(0.5,0.5,1.0,1.0)

CALL MYGRAF

IGrAreaClear Subroutine

DescriptionClear the current graphics screen area.

SyntaxIGrAreaClear()

EffectClears 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 oscreen.

When the graphics area is defined to be 0.0-1.0 in both x and y directions, the whole screenis cleared.



s (-1,-

hanges

ExampleCALL IGrArea(0.05,0.05,0.4,0.4)

CALL IGrAreaClear

CALL MYGRAF

IGrGetPixelRGB Subroutine

DescriptionRead a screen pixel color value

SyntaxIGrGetPixelRGB(xpos,ypos,ired,igreen,iblue)

ArgumentsREAL 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 )

EffectReturns the color of the specified screen co-ordinate, as an (r,g,b) triplet. The (x,y) co-ordi-nate 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 a1,-1).

On a monochrome screen, the returned RGB value does not take account of palette capplied to the two foreground/background colors. Background pixels return (0,0,0) and foreground pixels return (255,255,255) .

IGrInit Subroutine

DescriptionStart graphics output.


IGrInit Subroutine

e reset

fault.

ort -

hout

SyntaxIGrInit(type,nx,ny,ncolor)

ArgumentsCHARACTER 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

EffectRe-initializes graphics output. This routine is called by IScreenOpen , so it should not nor-mally be necessary to call it again unless the whole of the graphics system needs to bto its default state. In INTERACTER v3.xx and earlier, IGrInit needed to be called beforeany graphics processing, but this is no longer the case. In general, use of IGrInit is discour-aged, though its use for re-initialization remains valid.

The graphics mode with the nearest resolution to that requested will be selected by deHowever, the mode with the nearest number of colors can be given priority by specifyingtype 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 suppgraphics 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, witany necessity to re-initialize the graphics system. Since IGrInit uses IScreenMode to enter graphics screen mode, it indirectly calls IScreenModeN .

ExampleCALL IGrInit('C',800,600,16)

CALL IGrUnits(0.,0.,1000.,1000.)

CALL MYGRAF

CALL IGrPause(' ')

CALL IScreenMode('t',80,25,16)

CALL IOutString('Back to text mode')

CALL InKeyEvent(K)

CALL IScreenMode('G',800,600,16)



y

IGrPause Subroutine

DescriptionPause before clearing screen to start a new picture.

SyntaxIGrPause(action)

ArgumentsCHARACTER action = String describing required action (default is wait for confirm kethen clear screen)

= 'A': Any key can be pressed instead of just 'confirm' = 'P': Preserve contents of graphics screen

EffectThis 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 mustpress 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

DescriptionDefine plotting units to be used.

SyntaxIGrUnits(xleft,ylower,xright,yupper)

ArgumentsREAL 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


Group GS: Graphics Style Selection

wing

e

ines.

d- colors use vail-till be hey

ly be

) can

IGrUnits defines the plotting units (the 'user co-ordinate system') to be used when drain 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 thInfoGraphics function.

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

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

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

Group GS: Graphics Style SelectionThe subroutines in this group affect the appearance of output from other graphics rout

The current graphics color is selected using IGrcolorN . The number of available colors ishighly device dependent, so INTERACTER uses the same color numbering scheme regarless of screen mode or output device, based on 256 nominal colors. When less than 256are available, a near equivalent is always selected. Hence, programs can be written tocolor without having to be too concerned with the details of which colors are actually aable on the current device. On monochrome devices, the color handling routines can scalled but their effect will be limited to selecting either background/foreground color or tmay 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 onvisible if the operation takes place on top of some non-background color.

The color palette (the relationship between color numbers and actual colors displayedbe 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

DescriptionSelect graphics color using a color number.



bers

d the ed into s than ini-

SyntaxIGrColorN(ncolor)

ArgumentsINTEGER ncolor = color number (0-255 )

EffectSelects 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 numare used regardless of the actual number of colors available on the output device. INTER-ACTER performs an internal mapping between its device independent color scheme anactual color numbers used by the current hardware. The 256 color numbers are organiz16 groups, each consisting of 16 shades of a given color. On devices which support les256 colors, a single palette value from each sub-group is used (either a maximum or mmum intensity). For example, in a 16 color mode, values of 16-31 all give bright red and 32-

47 give dark red.



olor ciated

Color zero is treated specially by INTERACTER as the background color. This can still beselected as the current graphics color, enabling you to draw or fill in one foreground cand then plot on top of that using the current background color. The default palette assowith 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 Color # 256-Color Palette

Black 0-15 ( 0, 0, 0) -> ( 60, 60, 60)

Light red 16-31 (195, 0, 0) -> (255, 0, 0)

Dark red 32-47 (131, 0, 0) -> (191, 0, 0)

Light yellow 48-63 (195,195, 0) -> (255,255, 0)

Dark yellow 64-79 (131,131, 0) -> (191,191, 0)

Light green 80-95 ( 0,195, 0) -> ( 0,255, 0)

Dark green 96-111 ( 0,131, 0) -> ( 0,191, 0)

Light cyan 112-127 ( 0,195,195) -> ( 0,255,255)

Dark cyan 128-143 ( 0,131,131) -> ( 0,191,191)

Light blue 144-159 ( 0, 0,195) -> ( 0, 0,255)

Dark blue 160-175 ( 0, 0,131) -> ( 0, 0,191)

Light magenta 176-191 (195, 0,195) -> (255, 0,255)

Dark magenta 192-207 (131, 0,131) -> (191, 0,191)

White 208-223 (195,195,195) -> (255,255,255)

Light gray 224-239 (131,131,131) -> (191,191,191)

Dark gray 240-255 ( 64, 64, 64) -> (128,128,128)



In 16 or 8 color output, a subset of the above palette is used:

Table 31: 16 or 8 Color Palette

Actual Color Color # 16-color palette 8-color palette

Black 0-15 ( 0, 0, 0) ( 0, 0, 0)

Light red 16-31 (255, 0, 0) (255, 0, 0)

Dark red 32-47 (191, 0, 0) (255, 0, 0)

Light yellow 48-63 (255,255, 0) (255,255, 0)

Dark yellow 64-79 (191,191, 0) (255,255, 0)

Light green 80-95 ( 0,255, 0) ( 0,255, 0)

Dark green 96-111 ( 0,191, 0) ( 0,255, 0)

Light cyan 112-127 ( 0,255,255) ( 0,255,255)

Dark cyan 128-143 ( 0,191,191) ( 0,255,255)

Light blue 144-159 ( 0, 0,255) ( 0, 0,255)

Dark blue 160-175 ( 0, 0,191) ( 0, 0,255)

Light magenta 176-191 (255, 0,255) (255, 0,255)

Dark magenta 192-207 (191, 0,191) (255, 0,255)

White 208-223 (255,255,255) (255,255,255)

Light gray 224-239 (191,191,191) (255,255,255)

Dark gray 240-255 ( 64, 64, 64) ( 0, 0, 0)



r num-round

o-ing

you

a

e

If black and white are reversed, by specifying 'W' in the type argument to IScreenOpen , black, gray, and white shades are reversed as follows:

In monochrome modes color zero selects the background color and any non-zero colober is treated as a foreground color. Normally, the monochrome palette is a black backgand a white foreground, unless reversed by IScreenOpen .

Whatever color number is used, IGrColourN has no effect on the actual color which is assciated with that number. It simply sets the logical color number to be used by any followgraphics operations. To redefine the association of displayed colors with logical colorsshould use IGrPaletteRGB .

Two consecutive calls to IGrColourN will select the colors to be used by mixed-color arefills (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. Thtwo 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.

ErrorsErrBadcolor (42) : Unknown color number. Current color unchanged

ExampleDO ICOL = 16,240,32

CALL IGrcolorN(ICOL)

CALL IGrMoveTo(0.0,0.0)

CALL IGrLineTo(0.5,REAL(ICOL))

END DO

Table 32: Reversed Black, Gray, and White Shades

Actual Color

Color # 256-color palette 16-color palette

White 0-15 (255,255,255) -> (195,195,195) (255,255,255)

Black 208-223 ( 60, 60, 60) -> ( 0, 0, 0) ( 0, 0, 0)

Dark Gray

224-239 (124,124,124) -> ( 64, 64, 64) ( 64, 64, 64)

Light Gray

240-255 (191,191,191) -> (131,131,131) (191,191,191)



IGrFillPattern Subroutine

DescriptionDefine fill pattern (solid/stippled/hatched).

SyntaxIGrFillPattern(istyle,idense,iangle)

ArgumentsINTEGER istyle = Fill style:

INTEGER idense = Hatched fill density:

Table 33: Fill styles

Name No. Information

CrossHatchNoOut -2 Cross-hatched fill with no outline

HatchedNoOut -1 Hatched fill with no outline

Outline 0 No fill, ouline only (default)

Hatched 1 Hatched fills

CrossHatch 2 Cross-hatched fills

MixedColor 3 Mixed-color fills (stippled)

Solid 4 Solid fills

Table 34: Hatched Fill Density


Sparse 1 Sparse

Medium 2 Medium (default)

Dense1 3 Dense

Dense2 4 Very dense

Dense3 5 Very very dense


IGrFillPattern Subroutine

lor

le

ted, ughly ection ted

last

ernate

120 ives a ixed ntical

INTEGER iangle = Hatched line angle:

IGrFillPattern defines the fill pattern (if any) to be used by IGrCircle and IGr-

PolygonComplex . The basic choice is between no fills and hatched, solid or mixed-cofills.

The default fill style is zero which gives outlines only. In this case, the density and angparameters are ignored.

Hatched fills draw lines at intervals across the area to be filled. If a hatched fill is selecthe density and angle parameters define the precise style of the fill. A dense fill uses rotwice as many lines to fill the area as a sparse fill. The angle parameter controls the dirof the fill lines. Type 1 hatched fills draw lines in one direction only, according to the seleciangle 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 thetwo calls to IGrcolorN are mixed. Hence if two successive calls to IGrcolorN specify Yel-low 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 altpixels 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 areor 32640 stippled shades respectively. Selecting the same color twice in succession gsolid fill. In monochrome modes, the foreground/background colors are automatically min stippled fills, regardless of the last two colors specified, unless those colors were idein 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.

ExampleCALL IGrcolorN(48)

CALL IGrcolorN(144)

CALL IGrFillPattern(3,0,0)

CALL IGrCircle(150.,500.,30.)

Table 35: Hatched Line Angle


FillHoriz 3 Horizontal lines (default)

FillVertic 4 Vertical lines



IGrLineType Subroutine

DescriptionSelect line type (solid, dots, dashes or dot/dash).

SyntaxIGrLineType(ltype)

ArgumentsINTEGER ltype = Line type:

EffectSelects 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) .

ExampleCALL 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

Table 36: Line Types


SolidLine 0 Solid (default)

Dotted 1 Dots

Dashed 2 Dashes

DotDash 3 Dot/dash

DotDotDash 4 Dot/dot/dash

LongShort 5 Long/short dashes

ShortDash 6 Short dashes


IGrPaletteRGB Subroutine

me

An n of creen Note

e the e col-

rts 4 caled in

ctly

sing

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 (sanumbering 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. actual color combination is assigned to a logical color number. On a screen, redefinitiothe palette normally takes place immediately (but see the Portability notes) so that all spixels of the specified logical color number are displayed in the specified actual color. 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. Sincnumber of colors available on different devices varies widely, the RGB components arexpressed in an arbitrary range of 0-255. In theory this allows for up 16 million differentors! In practice, most output devices support significantly fewer colors (see Portability notes), so each RGB value is scaled accordingly. For example, where a display supposhades of each color (giving 4x4x4=64 colors) each supplied RGB component will be sto a value in the range 0 to 3. If 16 levels were available they would be scaled to values the range 0 to 15 and so on.

The logical color number specifies the color which would be selected by supplying exathe 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, uthe same rules as IGrColourN .



of

le

ll

m-

0-

Palette redefinition capabilities vary considerably between devices. A number of itemsinformation 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 redefini-tion, 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 programmedusing 64 levels of RGB component, giving 262,144 possible actual colors in all availabgraphics modes.

On an EGA in 350-line mode (number 16), 4 levels of red/green/blue are supported, for a16 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 coponent 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 20line 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 sup-ported 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)


Group GD: Graphics Drawing/Movement

the

solid

the

Group GD: Graphics Drawing/MovementThe 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 IGr-

MoveTo, but is automatically updated by other drawing and character output routines inGD 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 drawan outline of the appropriate shape, but they can also perform hatched, mixed-color orfills.

Simple straight line drawing can be performed using IGrLineTo . Single points can be plot-ted using IGrPoint .

IGrCircle Subroutine

DescriptionDraw/fill circle at an absolute position.

SyntaxIGrCircle(xpos,ypos,radius)

ArgumentsREAL xpos = X co-ordinate of circle center

REAL ypos = Y co-ordinate of circle center

REAL radius = Radius of circle in current plotting units

EffectDraws a circle of a given radius centered at the specified absolute plotting position, incurrent 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.

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

Portability notesSee IGrFillPattern .



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

IGrLineTo Subroutine

DescriptionDraw line to a new absolute position.

SyntaxIGrLineTo(xpos,ypos)

ArgumentsREAL xpos = X co-ordinate to draw to

REAL ypos = Y co-ordinate to draw to

EffectDraws 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.

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

IGrMoveTo Subroutine

DescriptionMove current plotting position to a new absolute position.

SyntaxIGrMoveTo(xpos,ypos)




IGrPoint Subroutine

EffectMoves the current plotting position to the absolute position ( xpos, ypos) without any visible effect.

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

IGrPoint Subroutine

DescriptionDraw a single point at new absolute position.

SyntaxIGrPoint(xpos,ypos)



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

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

IGrPolygonComplex Subroutine

DescriptionDraw/fill a complex (possibly intersecting) polygon.

SyntaxIGrPolygonComplex(x,y,nvert)

ArgumentsREAL x(:) = Array of X co-ordinates



ossi-d by

re be eneric

cur

rrent

lly at ctor

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 pbly intersecting borders. The polygon is drawn in the current graphics color as selecteIGrColourN . The polygon will be filled, if required, using the pattern set by IGrFillPat-

tern .The polygon will be closed, i.e. the last point will be joined to the first. Up to 4095vertices are allowed.

IGrPolygonComplex uses a device-specific primitive for solid and mixed-color fills, wheavailable (see Portability notes). Where such a primitive is not available or is known tounreliable, a generic (i.e., device independent) scan-line search method is used. The gmethod 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 ocin very extreme cases.

If no fill is specified, IGrPolygonComplex simply draws a poly-line, i.e., it joins the pointsspecified in x and y regardless of whether the borders cross. Whether filled or not, the cuplotting position becomes ( x(1), y(1)) .

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

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

ExampleREAL, 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 OutputThis group provides a routines to control graphics text output. The routine which actuawrites graphics text strings is IGrCharOut . The primary advantage of the GC routines is ththey are able to use software defined device-independent character sets (outline or ve


IGrCharJustify Subroutine

g

lt.

with xed'

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 spacinis 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 independ-ence 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 defauThis will utilize device/format specific font handling capabilities where appropriate but will automatically substitute an INTERACTER-equivalent outline font where for-mat-specific capabilities are not up to the required standard. This solution requiresno use of IGrCharSet . Instead, all font selection is determined by IGrCharSpacing .

Both of the above strategies require that fonts from the charsets directory be distributedyour application. Strategy (2) only requires the character set files for the 'swiss' and 'fioutline fonts.

IGrCharJustify Subroutine

DescriptionSelect graphics text justification.

SyntaxIGrCharJustify(justif)

ArgumentsCHARACTER 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)



hard-

ted text actu-

peci-

ng red in

cing

EffectSets 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 andware character set text output.

Justification always takes place relative to a plotting position. So left justified text is prinstarting from a given position, right justified text finishes at that position and centered appears either side of it. In this sense, 'left' and 'right' refer to which end of the string isally at the specified plotting position.

ExampleCALL IGrCharJustify('Left')

CALL IGrCharOut(100.,100.,'This starts at (100,100)')

CALL IGrCharJustify('r')

CALL IGrCharOut(100.,150.,'This finishes at (100,150)')

IGrCharLength Function

DescriptionMeasure the length of a graphics text string.

SyntaxREAL IGrCharLength(string)

ArgumentsCHARACTER string = String or character to measure

EffectWhen proportional spacing is enabled, this function returns the relative length of the sfied 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 interrogatithe spacing table, this function also allows a proportionally spaced string to be measuuser 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 InfoGraph-

ics(3) always returns the width the string in user-units, regardless of what type of spais enabled.


IGrCharOut Subroutine

drawn

is

r co-

after cur-

Example! write a red proportionally spaced string underlined in greenCALL 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

DescriptionOutput character string at an absolute (x,y) position.

SyntaxIGrCharOut(xpos,ypos,string)



CHARACTER string = String to write

EffectOutputs 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 areusing a solid line style.

The position of the text relative to ( xpos, ypos) is determined by the most recent call to IGr-

CharJustify , and can be centered or left/right justified. The default is centered. Text written horizontally.

ypos specifies a position half-way up a character. In left/right justification mode the otheordinate specifies an extreme end of the string.

On exit the current plotting position is updated to a point within the next character cell the string which has been written. The exact position within the cell will depend on therent justification mode.

The font/character set used by IGrCharOut is determined by IGrCharSet and IGr-

CharSpacing . The default is fixed space hardware characters.



nd ware

mits t

ISO

ail-

Text size is governed by IGrCharSize , though this is dependent on which character set aoutput device is selected. Full software text size control is available on all devices. Hardtext size control is device dependent. See IGrCharSize .

Whichever justification or character set is used, text which would extend beyond the liof the main graphics area (as defined by IGrArea ) is clipped at the edge of that area. Texwhich 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 theLatin-1 standard (i.e. character codes in the range 32-126 and 161-255).

ErrorsErrNoSoftFont (53) : Unable to find a software (outline) font to substitute for an unavable hardware font size/style.

ExampleCALL 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

DescriptionSelect graphics character set to use for text output.

SyntaxIGrCharSet(filnam)

ArgumentsCHARACTER 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'

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


IGrCharSet Subroutine

a sin-hen t soft-

on).

ing n all

ndard

selects his

Her-

By default hardware-dependent text is enabled. This is re-selectable here by specifyinggle 'H'. Hardware text is device dependent in terms of both its size and appearance. Whardware text is selected, IGrCharSpacing determines the actual font selected. Where afont of the required type/size/quality is not available on the current device, an equivalenware outline font is automatically substituted.

Calling IGrCharSet with an argument other than 'H' loads a software character set from afile, makes it the current font and disables hardware-text (and hardware text substitutiThere 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 drawa series of lines (vector fonts). Whilst somewhat slower to plot, software characters caalways be scaled to any size (using IGrCharSize ) and have a consistent appearance on displays and in all screen modes.

A software graphics character set file contains a set of definitions of the shape of the staASCII 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 rethat as the current character set without actually reading the character set file again. Tcheck for a previously loaded filename is case sensitive.

A selection of character sets are supplied, some of which are based on the well knownshey 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

Character Set Name Description

swiss.chr Swiss Equivalent to PostScript Helvetica

fixed.chr Fixed Equivalent to PostScript Courier



can be

e an

rce.

ent

ata

The supplied vector font character sets are as follows:

All of these character sets should be stored in the same directory, the name of which defined in an operating system variable called INTCHDIR. This name can also be specifiedvia 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 codto be written. By specifying the generic filename, with no directory specification, you cleave INTERACTER to pick up the name of the character sets directory externally.

ErrorsErrFileOpen (1) : Error opening file. The current character set selection remains in fo

ErrFileIO (2) : Error reading from file or unexpected end-of-file. Hardware-dependtext is selected and any in-memory character set is lost.

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

ExampleCALL 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

Table 38: Vector Font Character Sets

Generic Filename

Character Set Name Description

standard.chr Standard Simple general purpose 'plotter-style' font

duplexr.chr Duplex Roman More detailed font

triplexr.chr Triplex Roman Heavier font with serifs


IGrCharSize Subroutine

)

n)

nde-tion of

d

ally.

ures tent

is situ-

s are is not

e via ar-

har-

IGrCharSize Subroutine

DescriptionSelect graphics text size.

SyntaxIGrCharSize(xsize,ysize)

ArgumentsREAL 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 colum

EffectSets 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 ipendent of screen mode, ensuring a consistent character size, regardless of the resoluthe display. Character sizes of 2.0 , for example, would give text which is twice as wide anhigh 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 automaticHence, 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 ensthat the size of text relative to other graphics in the main graphics area remains consisregardless of the size of that area. However, text can quickly become unreadable in thation, 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 sizeavailable under DOS. Where a hardware font of the current size (or a near equivalent)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. Attempt-ing 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 selectablIGrCharSpacing('P') . When propotional spacing is enabled the exact number of chacters 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 cacter spacing, so the size factor specified here is equally applicable to both fixed and proportionally spaced text.



hich 8x8,

hich ngths cted, ly 3

ed the

ail-t will

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

Size parameters.

ExampleCALL IGrCharSet(' ')

CALL IGrCharSize(1.0,1.0)

CALL IGrCharOut(100.,200.,'Standard Size Text')

CALL IGrCharSize(2.0,1.0)

CALL IGrCharOut(100.,100.,'Double width Text')

IGrCharSpacing Subroutine

DescriptionSelect fixed or proportional spacing for graphics text.

SyntaxIGrCharSpacing(fixprop)

ArgumentsCHARACTER fixprop = Required character spacing :

= F: Fixed (default) (can be upper or lower case)

= P: Proportional (can be upper or lower case)

EffectSelects fixed or proportional character spacing. By default, fixed spacing is selected wcauses all characters to occupy equally sized character cells. This makes text string leand individual character positions easy to calculate. When proportional spacing is selecharacters are spaced according to the width of a character (e.g., a ’W’ occupies neartimes 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 selecteffect of selecting fixed or proportional spacing is as follows:

Proportional spacing: A hardware-specific Helvetica style of font will be selected, if avable. If this is not available (e.g. DOS graphics mode) an equivalent software outline fonbe substituted automatically (provided the character set file can be found).


IGrCharSpacing Subroutine

nt nt

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

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




14 General Functions

he

tly (it ut

ls the

Group SC: Screen ManipulationThe routines in this group control miscellaneous screen features. Most important are tINTERACTER initialization and termination routines (IScreenOpen /IScreenClose ). Other routines provide screen mode selection (IScreenMode , IScreenModeN ) and bell control (IScreenBell ).

IScreenBell Subroutine

DescriptionEnable/disable/ring the bell.

SyntaxIScreenBell(onoff)

ArgumentsCHARACTER 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

EffectRings 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 frequenis called by IGrPause at the end of a graphics screen and by the various fixed field inproutines). To stop IScreenBell producing any sound, the on/off option is provided. Thisdoes not physically switch sound off (as is possible on some hardware), it simply controaction taken by IScreenBell when an argument other than 'ON' or 'OFF' is supplied.


Chapter 14 General Functions

-ystem tement

ExampleLOGICAL :: SOUNDOK

IF (SOUNDOK) THEN

CALL IScreenBell('ON')

ELSE

CALL IScreenBell('OFF')

END IF

! now check state of bell

CALL IScreenBell(' ')

IScreenClose Subroutine

DescriptionTerminate INTERACTER screen I/O.

SyntaxIScreenClose()

EffectQuit/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 sdependent close down processing is also performed here. This need not be the last stain 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.

ExampleCALL IScreenClose

! Fortran screen I/O now available again

WRITE(*,*)'Bye bye ...'

END

IScreenMode Subroutine

DescriptionSelect screen mode by resolution and colors.


IScreenMode Subroutine

els

a

n. for

ent

ode. e text

that nded hics olors,

SyntaxIScreenMode(type,nx,ny,ncolor)

ArgumentsCHARACTER 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 pix(if a graphics mode requested)

INTEGER ny = Number or rows required (if a text mode requested) or vertical pixels (ifgraphics mode requested)

INTEGER ncolor = Number of text or graphics colors required

EffectSelects a text or graphics screen mode using a system independent screen descriptioINTERACTER will then use its hardware information to select the nearest screen modethe 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 dependIScreenModeN 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 mIts second, more subtle purpose is to specify how to select a mode when more than onor graphics mode is available. By default IScreenMode will select a mode according to thefollowing 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 programs can be written on a machine with one type of display but still behave as inteon another where different modes may be available. This facility is of most use in grapmodes where code can be written to request a very high resolution, with a number of cyet still use a color mode when executed on a low specification display.



ot sup-

s

screen. at

tion

Attempting to select a graphics mode when the currently selected display type does nport 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 varioutypes 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

DescriptionSelect screen mode by number.

SyntaxIScreenModeN(mode)

ArgumentsINTEGER mode = Screen mode number (see Portability notes)

EffectSelects screen mode by means of a system dependent mode number and clears the Normally, the system independent IScreenMode should be used for this purpose, since thdoes 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/resoluas well as switching between graphics and text modes.



his ion

e

ror code

DA,

The values allowed for mode depend on the display hardware being used (see below). Thardware will have been automatically identified or explicitly defined using an initializatfile, in the first call to IScreenOpen or a later call to IDisplay . Selecting a new mode usingIScreenModeN 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 baffected by the REVERSE initialization file keyword on monochrome displays).

Selecting an unrecognized or unsupported screen mode clears the screen, sets an erand leaves the current mode unchanged. InfoScreenMode can be used to check whether amode is available before selecting it.

Certain screen mode parameters can be specified via IScreenModeOptions .

ErrorsErrBadMode (41) : Unknown or unsupported screen mode requested

Portability notes: A variety of modes are supported, depending on which display adapter (CGA, EGA, MHGC, MCGA or VGA) and monitor (direct drive mono, composite mono, RGB color, Enhanced color, etc.) is fitted:

Table 39: DOS Screen Modes

mode Text Graphics Colors Displays

2/3 80x25 16 VGA, MCGA, EGA, CGA

6 80x25 640x200 mono VGA, MCGA, EGA, CGA

7 80x25 monoVGA, Hercules, MDA, EGA+direct-drive mono monitor

8 90x43 720x348 mono Hercules

9 80x50 640x400 mono Sub-VGA Olivetti/AT&T/Toshiba

10 132x25* 16 SVGA

11 100x37* 800x600* 16 SVGA

12 80x30* 640x480* 256 SVGA

14 80x25 640x200 16 VGA, EGA+ECD, EGA+RGB

15 80x25 640x350 mono VGA, EGA+direct drive mono

16 80x25 640x350 16 VGA, EGA+ECD

17 80x30 640x480 mono VGA, MCGA



n why

* = mode size redefinable using MODE10/MODE11/MODE12 keyword

The sheer variety of IBM screen adapters can be confusing. This is another good reasoit is better to use IScreenMode , leaving INTERACTER to choose the best mode.

18 80x30 640x480 16 VGA

19 40x25 320x200 256 VGA, MCGA

20 80x28 16 VGA

21 80x43 16 VGA

22 80x50 16 VGA

256 80x28 640x400 256 VESA-compatible SVGA








264 80x60 16 VESA-compatible SVGA






Table 39: DOS Screen Modes

mode Text Graphics Colors Displays



- giv-

s

f

50

or

s

e

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 prac-tice 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 numberoriginally used on the long defunct IBM PC jr). Hardware text is simulated in this modeing 90 columns by 43 rows.

Additionally, INTERACTER uses mode numbers 9 to 12 to provide support for various pop-ular non-standard screen modes. By default these modes are disabled. Each of mode9-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 10-

12 can be specified as MODEnn keyword parameters, providing support for a wide range oextra 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 .

10 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 inter-nal 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 to8000 characters in size can be used.

11 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.

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 dif-ferences in VGA types, the chipset upon which a VGA board is based must also bedefined with the MODE12 keyword, for all modes.

On most VGA's, three additional 80 column text modes are supported with 28, 43 androws. 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 automaticallymanually), 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 modewill 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 tablabove are the defaults if IScreenModeOptions has not been called.



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)


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 win-dow size to be controlled by the program.

Table 40: IScreenModeOptions Arguments

noptn value ivalue

GrModeRow 2 Number of text rows in graphics mode

TextModeBorder 7 Text mode border color (as for ITextColourN )

Flashing16 8Enable flashing text in 16-color DOS text modes IntNo (0) : No IntYes (1) : Yes


IScreenOpen Subroutine

s/ graph-0 sible

ode cs

ing

de.

When noptn = 2, ivalue specifies the preferred number of text rows to be used for menuwindows/etc. in graphics mode. Three character heights are available to be selected inics modes with a vertical resolution of 350 pixels or more (except AT&T mono 640x40mode). The available character heights are 8, 14 or 16 pixels, giving the following postext resolutions:

IScreenModeN will try to select the nearest suitable vertical text resolution in graphics mto that specified using ivalue=2. A fixed character height of 8 pixels is used in other graphimodes, so option 2 has no effect in modes 6, 8, 9, 14 and 19. IScreenModeN selects a mode-dependent 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 flashtext 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 mo

ExampleCALL IScreenModeOptions(2,40)



DescriptionInitialize INTERACTER screen I/O.

Table 41: DOS Screen Resolutions

Modes Pixels Text Resolutions

12, 15, 16 640x350 80x21 80x25 80x43

12, 256 640x400 80x25 80x28 80x50

12, 17, 18, 257 640x480 80x30 80x34 80x60

11, 12, 258, 259 800x600 100x37 100x42 100x75

11, 12, 260, 261 1024x768 128x48 128x54 128x96

11, 12, 262, 263 1280x1024 160x64 160x73 160x128

11, 12, 284 1600x1200 200x75 200x85 200x150



se

the

-

ply re a u

SyntaxIScreenOpen(initfn,type,nx,ny,ncolor)

ArgumentsCHARACTER initfn = Initialization data file name (blank to open default file and/or u

default values)

CHARACTER type = String describing type of screen mode requiredOne of:'G': Select graphics screen mode (default)'T': Select text screen modeOne of:'R': Give priority to resolution (default)'C': Give priority to number of colorsand one of:'B' : Use a white-on-black palette (default)'W' : Use a black-on-white palette(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

EffectInitializes INTERACTER screen handling, attempts to read an initialization file and entersnearest screen mode to that requested.

This routine supercedes IScreenInit , which was used to initialize INTERACTER in ver-sion 3.xx and earlier. IScreenOpen allows direct entry to graphics mode and activates aslightly 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 supvarious information, including the display hardware, default filenames and so on. Whefilename is supplied, a suffix of .ini is recommended. The file name can be left blank if yoprefer. In this case, IScreenOpen takes the following action:

• If the environment system variable INTINIT has been set up, the file which it spec-ifies 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)



t

ich

of er can

-

, in ail-

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 selecdefault values or to attempt to automatically identify the hardware in use.

In all cases, default values are assigned for any user definable initialization values whhave 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 bothwhich can be omitted in which case the indicated default is assumed. The first charactbe 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 near-est equivalent).

T 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.

C Give priority to the requested number of colors, when more than one graphics modeis available.

The third character can be one of:

B Use black as the default background color in both text and graphics modes. This isthe default.

W 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 combinationthe same manner as IScreenMode . Where more than one mode of the required type is avable, the nearest matching mode is selected, based on the specified priority criteria (resolution or colors).



-

ply d urns the

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 equiv-alent 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 : INTERACT.INI

Default display : Auto-identified

Default software character set file : STANDARD.CHR

Default graphics mode menu/window pop-up buffer : C:\INTTEMPW.$$$

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

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


InfoAttribute Function

, for

lt.

Several of the information functions correspond to a specific subroutine group. Henceinformation 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 InfoEr-

ror 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 capa-bility information.

In all cases, specifying an invalid item number to an Info routine returns an undefined resu

InfoAttribute Function

DescriptionReturn text attributes information.

SyntaxInfoAttribute(item)

ArgumentsINTEGER item = Number of information item required:

Table 42: Attribute Information item s


BoldText 1Bold text suported (IntNo (0): no; or IntYes (1): yes)

FlashingText 2Flashing text supported (IntNo (0): no; or IntYes (1): yes)

ReverseVideo 4Reverse video supported (IntNo (0): no; or IntYes (1): yes)

UnderlineText 5Underlining supported (IntNo (0): no; or IntYes (1): yes)

ForeTextCol 6 Number of foreground text colors

BackTextCol 7 Number of background text colors

BoldRequest 8Bold text requested (IntNo (0): no; or IntYes (1): yes)



t dis-

ently tually bering

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 currenplay. 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 recrequested. This information is independent of whether specific attributes or color are acsupported on the current display. Text color numbers are returned using the same numscheme as ITextColourN .

ExampleIF (InfoAttribute(6>2) THEN

CALL ITextColourN(1,-1)

END IF

InfoError Function

Description

Return error information.

Syntax

InfoError(item)

FlashingRequest 9Flashing text requested (IntNo (0): no; or IntYes (1): yes)

ReverseRequest 11Reverse video requested (IntNo (0): no; or IntYes (1): yes)

UnderlineRequest 12Underlining requested (IntNo (0): no; or IntYes (1): yes)

ForeColRequest 13 Foreground text color requested (0-15 )

BackColRequest 14 Background text color requested (0-15 )

Table 42: Attribute Information item s



InfoError Function

start-ve

ertain

n sing


EffectReturns information about the last error to be detected. If no errors have occurred sinceup or since the last call to InfoError , the last error is returned as zero. If several errors haoccurred 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 ofitem) to zero. This feature can be used to clear the error flags, when your program is uncof 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 IGr-

CharSet . This IOSTAT value will still be available if further I/O is performed or other noI/O errors occur. i.e., The error code for an I/O error remains available until it is cleared uInfoError(2) or until another I/O error occurs.

ExampleCHARACTER (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

Table 43: Error Information item s


LastError 1Last error set by INTERACTER

(0 if no errors since last call to InfoError(1) (see “Error Codes” on page 35 for a list)

IOErrorCode 2

System-dependent I/O code for last type 1 or 2 error (file open or read/write error), otherwise

undefined



InfoGraphics Function

DescriptionReturn real graphics mode information.

SyntaxInfoGraphics(item)


Table 44: Graphics Mode Information item s


GraphicsX 1Current X plotting position(in user units as set in IGrUnits )

GraphicsY 2Current Y plotting position(in user units as set in IGrUnits )

GraphicsChWidth 3Current character width(in user units as set in IGrUnits )

GraphicsChHeight 4Current character height(in user units as set in IGrUnits )

GraphicsMouseX 5Mouse X position at last mouse/key event(in user units as set in IGrUnits )

GraphicsMousey 6Mouse Y position at last mouse/key event(in user units as set in IGrUnits )

GraphicsAreaMinX 7 Left limit of main graphics area

GraphicsAreaMinY 8 Lower limit of main graphics area

GraphicsAreaMaxX 9 Right limit of main graphics area

GraphicsAreaMaxY 10 Upper limit of main graphics area

GraphicsUnitMinX 11 Lower X co-ordinate limit

GraphicsUnitMinY 12 Lower Y co-ordinate limit

GraphicsUnitMaxX 13 Upper X co-ordinate limit

GraphicsUnitMaxY 14 Upper Y co-ordinate limit


InfoGrScreen Function

which

e.

rdi-

ouse

EffectReturns certain REAL graphics mode parameters. These are generally dynamic valueschange depending on calls to other graphics routines. See also InfoGrScreen which returns INTEGER data, mainly describing the capabilities of the current display or screen mod

The current plotting position, as set by IGrMoveTo and other routines, is accessible usingitem 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 theextent 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-onate of the mouse cursor at the last mouse or keyboard press. This information will bemeaningful when InfoInput(55) returns -2 or when InKeyEvent/InKeyEventImm returns anything other than an expose/resize event. The former situation will occur if a mbutton is pressed outside the input area in a fixed-field/menu input routine and InMouseOp-

tions(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.

ExampleREAL :: 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

DescriptionReturn graphics facilities information (screen).



cur-

en

SyntaxInfoGrScreen(item)


EffectReturns information about the graphics facilities available on the current display in therent 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 scremode, the information returned for other item numbers is undefined.

Table 45: Graphics Screen Information item s


GraphicsAvail 1GraphicsAvailable (IntNo (0): no; or IntYes (1): yes)

PaletteBack 8Background color redefinable (IntNo (0): no; or IntYes (1): yes)

PaletteFore 9Foreground colors redefinable (IntNo (0): no; or IntYes (1): yes)

HardTextSize 19Hardware text size control (IntNo (0): no; or IntYes (1): yes)

PaletteChange 24Palette changes affect existing plot (IntNo (0): no; or IntYes (1): yes)

QualityFonts 27Presentation quality hardware fonts (IntNo (0): no; or IntYes (1): yes)

ColNumAvailable 30 Number of colors in current mode

ColNumMax 31 Number of colors in any mode

AspectRatio 32 Aspect ratio as a percentage

PrevColReq 34 Last but one requested graphics color

ColorReq 35 Most recently requested color

LineTypeReq 36 Most recently requested line type


InfoHardware Function

ay,

ype

nd in any s two.

display

ful

or

item values 8, 9 and 24 determine the palette redefinition capabilities of the current displas 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 pal-ette 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. TrueTor equivalents).

Since the number of colors available varies significantly from one display to another afrom one mode to another, information item numbers 30 and 31 are provided. These returnthe number of colors available in the current mode and the maximum number available mode on the current display. In a monochrome mode the number of colors is returned a

The aspect ratio of the current display is returned as a percentage. For example, on a 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 usein 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 colreturned 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 .

ExampleIF (InfoGrScreen(1)==0) THEN

CALL IOutString('Sorry but you don't have graphics')

ELSE

CALL IGrInit(' ',640,250,16)

END IF

InfoHardware Function

DescriptionReturn hardware information.

SyntaxInfoHardware(item)



he

ESA

ne lue bit


EffectReturns information about the hardware on which the program is currently running. Tvalue 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 Vvideo 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 oor more VESA standard SVGA modes as being available. In this case, the returned vaencodes 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.

ExampleIF (InfoHardware(13)<3) THEN

CALL IOutStringXY(1,1,'This program &

& requires a 3 button mouse !')

CALL InKeyEvent(KEY)

END IF

InfoInput Function

DescriptionReturn keyboard input facilities information.

Table 46: Graphics Screen Information item s


DisplayType 10 Display type (see IDisplay )

MouseType 13 Mouse type (see IMouse )

VESAsupport 32

Report VESA support0: If VESA BIOS not availablenon-zero: VESA BIOS installed


InfoInput Function

Syntax

InfoInput(item)

Arguments

INTEGER item = Number of information item required:

Table 47: Input Handling Information item s


1-50Key code assigned to input control key 1-50

(see InControlKey for list of control keys)

NumFunKeys 51 Number of function keys available

KeypadMode 53 Current keypad mode as set by InKeypad(1-3)

EditMode 54Current insert/overtype mode(OverMode (0): overtype; InsMode (1): insert)

LastExitKey 55Last key used to exit from an input/menu routine(-2 , -1 , 21-30 , or 36-50 )

KeypadType 56

Cursor/keypad keys availability(NoKeypad (-1 ): no keypad identification;SharedKP (0): shared;SeparateKP (1): separate)

PopUps 58

Current ’pop-up’ mode as set by InPopup

(IntNone (0): disabled;SinglePop (1): single;LinkedPop (2): linked)

ExitMouseButton 61

Mouse button pressed on exit from field/menu(IntNone (0): none;LeftButton (1): left;MiddleButton (2): middle;RightButton (3): right)

MouseTextCol 62Text column of mouse cursor at last mouse/key event

MouseTextRow 63 Text row of mouse cursor at last mouse/key event

EventMask 66 Event mask as set by InEventSelect

PauseKey 67 InEventKey code returned by IGrPause



alue

'toggle

en

ces it

ther n-alue of

This

EffectReturns information about the input control keys and the input handling facilities. The vreturned is an INTEGER. Each of the input control keys which are definable using InCon-

trolKey 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 onthe current display.

item 54 identifies the insert/overtype state as most recently set by the user pressing the insert' key.

item 55, the last 'exit' key to be pressed, is a particularly useful piece of information whprocessing 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 recentlycalled input routine. InfoInput(55) is set by any of the routines from groups IN or MN. Avalue of 22 for example means that the help key was pressed. Under certain circumstancan 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 wheseparate cursor and keypad keys are available. A return value of -1 indicates that the keypadcannot be identified as such at all. A return value of 0 or 1 means that the keypad can be idetified. If the cursor keys and keypad are shared (as on the old 'Standard' keyboard) a v0 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.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 wasused to confirm a menu option.

ExitOutside 68Exit on mouse click outside input area(0=no; 1=yes)

MouseTime 70 Time of last mouse event in centiseconds

ConfirmFixedButton 106Special-action mouse button set by InMouseOptions

151-170

Key code assigned to input control key nos. 51-70

(see InControlKey for list of control keys)

Table 47: Input Handling Information item s



InfoScreen Function

n/ted by rro-

a

,

urred. s ple-ility.

ent

sed. A

item's 62 and 63 will normally be interrogated as a pair, since they return the text columrow position at which a mouse or keyboard event last occurred. These values are updaany routine which performs input processing, so it is important that they should be integated 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 InEventSe-

lect(0, n) . This value is therefore suitable for saving and restoring the event state in 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 non-keystroke value.

item 68 returns the current setting of the 'exit on mouse click outside input area' optionselectable via InMouseOptions(2, n) .

item 70 returns the time at which the last mouse button up/down or movement event occThe time is reported in centi-seconds since an arbitrary start time. This start time variebetween implementations. Note that the time stamp can wrap round to zero after an immentation dependent period of time, so time stamp checks should allow for this possib

item 106 returns the mouse button numbers assigned to special actions by the equivalInMouseOptions option (0=none).

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

ExampleCALL InMouseOptions(2,1)


KEXIT = InfoInput(55)

IF (KEXIT==-2) THEN

MOUSEX = InfoInput(62)

MOUSEY = InfoInput(63)

ELSE IF (KEXIT==23) THEN

...

InfoScreen Function

DescriptionReturn screen mode information (current mode).



. See

MN, dimen-

e the ilable

n

Syntax

InfoScreen(item)

Arguments

INTEGER item = Number of information item required:

Effect

Returns information about the current screen mode. The value returned is an INTEGERalso InfoScreenMode which returns information about any mode.

The current screen mode number is display dependent. See IScreenModeN for lists of sup-ported 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, etc. groups. When called in a graphics mode these values have nothing to do with the sions of graphics hardware text as output by IGrCharOut .

The pixel resolution of the current graphics mode should not normally be required sincgraphics routines are independent of screen resolution, but this information is made avafor 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 cabe specified to the complementary InfoScreenMode function which can return informationabout any screen mode.

Table 48: Screen Mode Information item s


ScrMode 1 Current screen mode

TextColumns 2 Number of text columns in current mode

TextRows 3 Number of text rows in current mode

HorizPixels 4Horizontal graphics pixel resolution(zero in a text mode)

VerticPixels 5Vertical graphics pixel resolution(zero in a text mode)

ScrMaxModes 6 Max number of modes available


InfoScreenMode Function

ode.

nge

ExampleNROWS = InfoScreen(3)

CALL IOutStringXY(1,NROWS,'This is &

& on the bottom screen row')

InfoScreenMode Function

DescriptionReturn screen mode information (any mode).

SyntaxInfoScreenMode(item,mode)


INTEGER mode = Screen mode number (0 to InfoScreen(6) )

Returns information about the availability and characteristics of the specified screen mThe 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 ra

Table 49: Screen Mode Information item s


ModeType 1

Mode availability/type(IntNo (0): unavailable;TextOnly (1): text-only mode;TextAndGraphics (2): Graphics and text mode;Redundant (-1 ): Redundant text-only mode)

TextColumns 2 Number of text columns in specified mode

TextRows 3 Number of text rows in specified mode

HorizPixels 4Horizontal graphics pixel resolution(zero in a text mode)

VerticPixels 5Vertical graphics pixel resolution(zero in a text mode)

NumColors 6 Number of colors



y.

nly

, etc.

which

ode

0 to InfoScreen(6) . The latter is the highest valid mode number on the current displaSpecifying 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 ooccurs 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, MNgroups. When mode identifies a graphics mode these values have nothing to do with thedimensions 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 screenssupport more than one graphics mode.

Portability notesitem 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 mwhich is not used, remains selectable via IScreenModeN , but returns -1 via InfoScreen-

Mode(1,MODE) to indicate that the mode is available but effectively redundant.


InfoWindow Function

ExampleMAXMOD = 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

DescriptionReturn window management system information.

SyntaxInfoWindow(item)


Table 50: Window Information item s


WinCurNumber 1 Current window number

WinAvailable 2 Number of windows still available to be opened

WinBufferSpace 3 Remaining space in the internal window buffer

WinLeftColumn 4 Screen column of top left corner of window

WinTopRow 5 Screen row of top left corner of window

WinWidth 6 Width of current window excluding frame

WinHeight 7 Height of current window excluding frame



The

e has

d in ffer. ow is e

e.

Effect

Returns information about the current status of the text window management system. value returned is an INTEGER.

The current and top window numbers can be interrogated using item numbers 1 and 8 respec-tively. 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' modbeen 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 expresseterms of the number of screen character positions which can still be copied into the buThis information is consistent across all displays in all screen modes. Hence, if a windto be opened which will occupy 40 columns by 10 rows (including frame), there must broom 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 fram

WinTopNumber 8Top window number (i.e., number of open windows)

WinCursorX 9 Current window (X) cursor position

WinCursorY 10 Current windows (Y) cursor position

WinFrameMode 11Frame mode selected (0=none 1=Titled 3=Boxed title)

WinPopupMode 12Pop-up mode selected(IntNo (0): no; IntYes (1): yes)

WinClearMode 13Clear mode selected(IntNo (0): no; IntYes (1): yes)

WinTitle 14

Title justification(WindowLeft (1): left;WindowCenter (2): center;WindowRight (3): right)

WinTitleMode 17Wide title mode selected(0=no; 1=yes)

Table 50: Window Information item s



Group OS: Operating System Interface

-

ng a

play

when dling,

ollow-

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 openiwindow, as set by IWinAction .

ExampleIAVAIL = InfoWindow(2) IF (IAVAIL>0) THEN

CALL IWinOpen(20,10,60,20)END IF

Group OS: Operating System InterfaceThe routines in this group provide access to environment variables (IOsVariable ) and allow controlled program termination with a message (IOsExitProgram ).

IOsExitProgram Subroutine

DescriptionAbort program with an error message and error code.

SyntaxIOsExitProgram(errmes,iexcod)

ArgumentsCHARACTER errmes = Error message to display to the user. (if blank, error message disis suppressed)

INTEGER iexcod = Exit code to return to operating system

EffectAborts the current program, in a controlled manner. This routine is designed to be usedan unexpected fatal error is encountered. It first tidies up the screen and keyboard hanthen exits from the program. An exit code is returned to the operating system and the fing optional message is displayed on the screen:

** Abnormal exit ** Exit code: nn

** your-error-message



within ll m exit

t the

e or a

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 codean operating system command procedure, leave errmes blank. The above error message withen be suppressed. See the Portability notes for more information on checking progracodes.

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 exicodes which INTERACTER can generate. These exit codes should not be confused witherror 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 messagnon-zero exit code, simply supply a blank error message and an IEXCOD value of zero.

Portability notesIn 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

ExampleIClearOldError = InfoError(1)

CALL IGrCharSet('chars.chr') IF (InfoError(1)==1) &

CALL IOsExitProgram('Cannot open character set file',21)

IOsVariable Subroutine

DescriptionReturn the value of an operating system (environment) variable.

SyntaxIOsVariable(vname,value)


Group HW: Hardware Identification

of to use a lized

le

eral, ly by .

ArgumentsCHARACTER vname = Name of variable to interrogate

CHARACTER value = Returned value (blank if not found)

EffectReturns the value of the specified environment variable. They provide a useful methodpassing system dependent values, such as filenames, to a program without the need data file or command line arguments. If the specified variable name has not been initiaor 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 notesIOsVariable returns environment variables as assigned using the SET command. The oper-ating system converts all variable names to upper case, so the supplied variable namevname 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 variabname. IOsVariable strips trailing blanks from the supplied variable name.


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 IdentificationThese routines are used to identify the display or mouse hardware being used. In genthere should be no need to call these routines directly. They are all called automaticalIScreenOpen , so the information they require is better supplied via the initialization file

IDisplay Subroutine

DescriptionSelect display type



p,

re will

enti-

SyntaxIDisplay(idispl)

ArgumentsINTEGER idispl = Display type number (see“Supported Hardware” on page 19)

EffectDefines 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 vari-able or the initialization file DISPLAY keyword). If you can't specify the hardware at start uIDisplay 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 dis-play being used or selects a 'lowest common denominator' default value. However, thenormally 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 idfied hardware type using InfoHardware .

Portability notesSee “Supported Hardware” on page 19.

ExampleCALL IScreenOpen(' ')

! this program requires an IBM PC with VGA/color

CALL IDisplay(10)

IMouse Subroutine

DescriptionSelect mouse type.

SyntaxIMouse(imous)

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


Group CH: Character Manipulation

,

tified

ouse n

n

creen l n and

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 programto 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., zeroas 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 idenhardware 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 mtype is forced to 1, regardless of the value of imous. If a mouse is found, action depends oimous. 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 informatioreturned by the mouse driver software.

ExampleCALL 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 ManipulationThe routines in this group are not strictly screen control functions. However, since any shandling involves considerable manipulation of textual information, they provide usefubasic facilities such as string to numeric conversion, sub-string location, case conversioso on. Some duplicate Fortran 90 intrinsics, but are required internally by INTERACTER (which also supports FORTRAN 77 compilers).



s and/

h is

IActualLength Function

DescriptionReturn actual length of string excluding trailing blanks or nulls.

SyntaxIActualLength(string)

ArgumentsCHARACTER string = String to search

EffectReturns 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 spaceor 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 whicheld in it.

ExampleCHARACTER (LEN=9) :: STR

LASTCH = IActualLength(STR)

IF (LASTCH/=LEN(FILNAM)) &

IOutString('STR has trailing blanks')

IFillString Subroutine

DescriptionFill a character string with a given character.

SyntaxIFillString(string,chr)

ArgumentsCHARACTER string = String to be filled

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

EffectFills the whole of string with the first character of chr.


IJustifyString Subroutine

)

e the ithin a

the

-blank

ExampleCHARACTER (LEN=80) :: STARS CALL IFillString(STARS,'*')

IJustifyString Subroutine

DescriptionJustify a string within a character variable.

SyntaxIJustifyString(string,lcr)

ArgumentsCHARACTER 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)

EffectJustifies a string within the character variable which holds it.

This routine is provided to overcome the inability of many Fortran compilers to referencsame character variable on both sides of an assignment statement. Moving a string wcharacter variable normally requires two steps via a temporary variable. IJustifyString packages up this operation into a simple subroutine call, dealing at the same time withchores 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 noncharacter to the last non-blank character within the character variable string. Since IJusti-

fyString justifies the string within the supplied variable itself, string must be passed as avariable rather than as a literal string. If string is blank, IJustifyString takes no action.

ExampleCHARACTER (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'



er

c-t the

ILocateChar Function

DescriptionLocate position of first non blank character.

SyntaxILocateChar(string)


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


CALL InString(FILNAM,LEN)

IPOS1 = ILocateChar(FILNAM)

ILocateString Subroutine

DescriptionLocate position of first non blank sub-string.

SyntaxILocateString(string,istart,iend)


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 funtion ILocateChar except here the start and end positions are returned, rather than jusstart position.


ILowerCase Subroutine

ExampleCHARACTER (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

DescriptionConvert a string to lower case.

SyntaxILowerCase(string)

ArgumentsCHARACTER string = String to be converted to lower case

EffectConverts any upper case characters in string to lower case.


STRING = 'ABCDE12345'

CALL ILowerCase(STRING)

! string should now be abcde12345

IntegerToString Subroutine

DescriptionConvert an integer value to a string.

SyntaxIntegerToString(ivalue,string,frmat)



s in

r

ArgumentsINTEGER 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 aa Fortran FORMAT)

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

ErrorsErrNumToStr (18) : Numeric-to-string conversion error.

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

IStringToInteger Subroutine

DescriptionConvert a string to an integer value.

SyntaxIStringToInteger(string,ivalue)

ArgumentsCHARACTER string = String containing number to be converted.

INTEGER ivalue = INTEGER value to be returned

EffectConverts 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 conver-sion ivalue is returned as zero and the INTERACTER error flag is set. IStringToInteger is the reverse of IntegerToString .

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


IUpperCase Subroutine

ErrNoSubstring (10) : No substring found (string is blank)

ErrBadChar (12) : Invalid character detected (i.e., not 0123456789 or leading +/- )

ExampleCHARACTER (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

EffectConverts any lower case characters in string to upper case.


STRING = 'abcde12345'

CALL IUpperCase(STRING)

! string should now be ABCDE12345




A Obsolete Routines

me is sake

d ndled

in lt set-

lts. rmi-

lly

Since INTERACTER is a continuously developing product, some features inevitably becosuperceded. Routines which are no longer required or recommended are moved to th"Obsolete Routines" group. Mostly, they are routines which are still supported, for the 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 suiteto full screen environments such as DOS. Graphics mode entry and termination was haseparately via IGrInit /IGrQuit . At version 4.0, IScreenOpen and IScreenClose were introduced to allow direct entry to graphics mode at initialization and tidier terminationwindowing environments. At the same time a number of new, more appropriate defautings 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 defauThis ensures backwards compatibility. However, conversion to the new initialization/tenation routines will ensure better results in windowing environments and simplified programming thanks to more appropriate defaults.

IGrQuit SubroutineTerminates 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. Typicathis routine should only be called in programs which use IScreenInit /IScreenQuit and only in combination with IGrInit .


Appendix A Obsolete Routines

the

rom

d

h een se

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 clearsscreen 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 fversion 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 disable(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 witIScreenInit in pre-v4 programs. It clears the screen if requested, reselecting the scrmode which was in use on entry to the program if possible. Any system dependent clo


IScreenQuit Subroutine

down processing is also performed here. This routine has been superceded by IScreen-

Close which always clears the screen under DOS. IScreenQuit should only continue to be used in programs which still use IScreenInit .


Appendix A Obsolete Routines


Index

AAttributes 159

BBox-character frames 70

CCGA 20Character Graphics 65Character Graphics Routines 50Character Manipulation 179Character Manipulation

Routines 53CHARSET 3, 28chipset 29, 31Clearing 60Clearing Routines 50Co-ordinate System 117Cursor Control 57Cursor Control Routines 50

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

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

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

FFilename Specification 39Fill styles 128Fixed Field Input Handling 92Fixed Field Input Handling

Routines 51Fixed-field/Menu Input Parameter

Selection Routines 51Fortran I/O 5Frame Types 70

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

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

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

Lahey F

2

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

ortran 90 Language Reference 191

Index

InfoGraphics 162InfoGrScreen 163InfoHardware 165InfoInput 166Information 158Information Routines 53InfoScreen 169InfoScreenMode 171InfoWindow 173InHighlight 106Initialization Data File Format 27InKeyEvent 41, 86InKeyEventCursor 90InKeyEventImm 41, 91InKeypad 108InMouseOptions 110InPopup 112Input Control Parameter

Selection 103Input Handling 49InString 93InStringDef 94InStringXY 95InStringXYDef 96INTCHAR 3INTCHDIR 3IntegerToString 183INTERACT.INI 27INTINIT 3, 27INTTERM 3IOsExitProgram 175IOsVariable 176IOutString 55IOutStringXY 56IOutVertical 56IOutVerticalXY 57IScreenBell 147IScreenClose 148IScreenInit 9, 188IScreenMode 7, 148IScreenModeN 7, 150IScreenModeOptions 154IScreenOpen 155IScreenQuit 188ISplitFrameH 72IStringToInteger 184ITextAttribute 62ITextColourN 63IUpperCase 185IWinAction 73

192 Lahey Fortran 90 Language

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

KKeyboard Codes 41Keyboard/Mouse Event Handling 83Keyboard/Mouse Event Handling

Routines 51KEYnn 29Keypad Codes 108Keywords 28

LLine Types 130lisk.lib 1

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

NNaming Conventions 7

OObsolete Routines 187Operating System Interface 53, 175

Rread.me 1

SScreen Manipulation 147

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

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

VVESA 20VESAINFO.EXE 1, 24VGA 20

WWindow Management Routines 51Window Manager 72

Reference

Documents

LISKREF