Sei sulla pagina 1di 184

Winteracter Starter Kit

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


Printed on 50% recycled paper

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

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

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

Conditions of Use
Use of the Winteracter Starter Kit package shall be in accordance with the Winteracter Starter Kit licence agreement.

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

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

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

Table of Contents
Introduction............................................iii
Window Handling...........................................iii Input Handling ................................................ iv Dialog Management ....................................... iv High Resolution Graphics ............................... v General Functions............................................ v Bitmaps ..........................................................62 Icons ...............................................................63 String Table....................................................63

Error Codes ...........................................65 Subroutine Summary ...........................67 Window Handling..................................71


Group WM: Window Management ...............71 WindowClose Subroutine ..............................71 WindowCloseChild Subroutine .....................72 WindowOpen Subroutine...............................73 WindowOpenChild Subroutine......................75 WindowSelect Subroutine..............................77 Group TX: Text Output..................................78 WindowOutString Subroutine........................79 WindowStringLength Function......................79 Group CL: Area Clearing...............................80 WindowClear Subroutine...............................80 WindowClearArea Subroutine .......................80 Group FS: Font Selection...............................81 WindowFont Subroutine ................................81

Supplied Files .........................................1 Building a WiSK Program ......................3


Command Line ................................................ 3 ED for Windows .............................................. 4

Writing Winteracter Programs...............5


Basics............................................................... 5 Elements of a Winteracter Program................. 8 A Worked Example ....................................... 11

MenuEd - Menu Resource Editor ........19


Mouse And Keyboard Input .......................... 19 File Options ................................................... 20 Edit Options ................................................... 21 Menu Options ................................................ 23 View Options ................................................. 23 Creating Your First Menu Resource.............. 25

Input Handling.......................................85
Group MH: Message Handling ......................85 WMessage Subroutine ...................................85 WMessageEnable Subroutine ........................91 WMessagePeek Subroutine............................91 Group MN: Menu Handling...........................92 WMenuGetState Function..............................92 WMenuRoot Subroutine ................................93 WMenuSetState Subroutine ...........................94 WMenuSetString Subroutine .........................95

DialogEd - Dialog Resource Editor .....27


Mouse and Keyboard Input ........................... 27 File Options ................................................... 28 Edit Options ................................................... 29 Dialog Options............................................... 30 Field Options ................................................. 31 View Options ................................................. 44 Using Bitmaps and Icons in Dialogs ............. 46 Creating Your First Dialog Resource. ........... 46

Dialog Manager .....................................97


Group DM(1): General Dialog Management .99 WDialogHide Subroutine...............................99 WDialogLoad Subroutine ............................100 WDialogSelect Subroutine...........................101 WDialogShow Subroutine ...........................101

Resource File Format ...........................49


Menus ............................................................ 50 Accelerators ................................................... 52 Dialogs........................................................... 53 User-defined Dialog Data .............................. 61

Winteracter Starter Kit

Contents
WDialogUnload Subroutine ........................ 104 Group DM(2): Assign/Retrieve Fields ........ 104 WDialogGetCheckBox Subroutine ............. 105 WDialogGetMenu Subroutine.................... 105 WDialogGetRadioButton Subroutine.......... 106 WDialogGetString Subroutine .................... 107 WDialogPutCheckBox Subroutine.............. 108 WDialogPutImage Subroutine .................... 108 WDialogPutMenu Subroutine ..................... 109 WDialogPutOption Subroutine ................... 110 WDialogPutRadioButton Subroutine .......... 111 WDialogPutString Subroutine..................... 112 Group CD: Common Dialogs...................... 112 WMessageBox Subroutine .......................... 113 WSelectFile Subroutine............................... 115

General Functions ..............................145


Group IF: Information..................................145 InfoError Function .......................................145 InfoGraphics Function .................................147 InfoGrScreen Function.................................148 WInfoDialog Function .................................149 WInfoFont Function.....................................151 WInfoScreen Function .................................153 WInfoWindow Function ..............................154 Group OS: Operating System Interface .......155 IOsExitProgram Subroutine.........................155 IOsVariable Subroutine ...............................156 Group MI: Miscellaneous ............................157 WindowBell Subroutine...............................157 WInitialise Subroutine .................................158 Group CH: Character Manipulation.............159 IActualLength Function ...............................159 IFillString Subroutine ..................................160 IJustifyString Subroutine .............................160 ILocateChar Function ..................................161 ILocateString Subroutine .............................161 ILowerCase Subroutine ...............................162 IntegerToString Subroutine .........................163 IStringToInteger Subroutine ........................163 IUpperCase Subroutine................................164

High Resolution Graphics ................. 119


Group GG: General Graphics...................... 119 IGrArea Subroutine ..................................... 120 IGrAreaClear Subroutine ............................ 121 IGrGetPixelRGB Subroutine....................... 121 IGrInit Subroutine ....................................... 122 IGrPause Subroutine.................................... 123 IGrUnits Subroutine .................................... 124 Group GS: Graphics Style Selection ........... 124 IGrColourN Subroutine ............................... 125 IGrFillPattern Subroutine ............................ 128 IGrLineType Subroutine ............................. 130 IGrPaletteInit Subroutine ............................ 131 IGrPaletteRGB Subroutine.......................... 132 Group GD: Graphics Drawing/Movement .. 133 IGrCircle Subroutine ................................... 133 IGrLineTo Subroutine ................................. 134 IGrMoveTo Subroutine ............................... 134 IGrPoint Subroutine .................................... 135 IGrPolygonComplex Subroutine................. 135 Group GC: Graphics Character Output ....... 136 IGrCharJustify Subroutine .......................... 137 IGrCharLength Function ............................. 137 IGrCharOut Subroutine ............................... 138 IGrCharSet Subroutine ................................ 139 IGrCharSize Subroutine .............................. 142 IGrCharSpacing Subroutine ........................ 143

Glossary ..............................................167

ii

Winteracter Starter Kit

Introduction

Winteracter is a Win32 and Fortran 90 dedicated user-interface and graphics development tool. Winteracters graphics are compatible with the platform independent INTERACTER library. The user-interface features were designed specifically for Win32 operating systems. In addition to a Fortran 90 subroutine library, W interacter also provides visual tools for menu and dialog design. The Winteracter Starter Kit (WiSK) is derived from the full version of Winteracter. It includes WiSK-specific versions of the visual menu and dialog designers plus a library of subroutines organised in five categories : Window Management Input Handling Dialog Management High Resolution Graphics General Functions Each category is sub-divided into groups, which are identified by two-character codes, e.g. FS for font selection, MH for message handling and so on. The following sections provide a general summary of the facilities provided by each of these subroutine groups. Before starting to use WiSK it is recommended that you browse through the following sections to familiarise yourself with the range of features on offer and more importantly, where to find them. The subroutine group summaries presented here follow the same order as the subroutine reference sections later in this manual.

Window Handling
Winteracter supports a single root window and multiple child windows. The subroutine groups here provide control over the management of these windows.
Winteracter Starter Kit

iii

Introduction

WM: Window Management


These routines open and close root and child windows. The root window can be hidden, if required. The current output window is also selectable.

TX: Text Output


Text can be written at specific positions within any output window.

CL: Clearing
All or part of the current window can be cleared using this group.

FS: Text Attributes


Font style and attributes such as color, bold, italics and underlining are selectable here.

Input Handling
This group provides the fundemental message delivery mechanism plus menu handling facilities.

MH: Message Handling


All input is reported to the program via the message delivery routines in this group. In particular, a typical Winteracter program will revolve around an event loop which repeatedly calls the WMessage routine.

MN: Menu Handling


Menu layouts are defined separately in a resource file, using MenuEd, the Winteracter menu editor. Menu selections are reported via the message handling routines in the MH group. This group therefore deals with menu activation and updating the state of individual menu items (e.g. setting the checked/unchecked state).

Dialog Management
Dialog layouts are defined externally in a resource script, using DialogEd, the Winteracter dialog editor. The routines in the Dialog Manager are therefore mostly concerned with activating, controlling and interrogating these dialogs. Access is also provided to certain predefined Windows dialogs.

iv

Winteracter Starter Kit

DM(1): General Form Creation & Editing

DM(1): General Form Creation & Editing


Dialog activation and selection is controlled through this group.

DM(2): Assign/Retrieve Field Contents


The individual contents of each dialog field are accessed via these routines.

CD : Common Dialogs
Pre-defined Windows dialogs are accessible for file selection and message boxes.

High Resolution Graphics


These routines provide high resolution graphics output facilities.

GG: General Graphics


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

GS: Graphics Style Selection


Control is provided over color, line-type and fill style.

GD: Graphics Drawing/Movement


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

GC: Graphics Character Output


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

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

Introduction

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

OS: Operating System


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

MI: Miscellaneous
The most important routine in this group is WInitialise, the Winteracter initialisation routine.

CH: Character Manipulation


These routines provide string manipulation facilities which are useful in interactive applications.

vi

Winteracter Starter Kit

Supplied Files

This chapter describes the files which you receive with your Winteracter Starter Kit. These are installed as part of the compiler installation procedure. Refer to Building a WiSK Program on page 3 for information on how to use and set up Winteracter once it has been installed. The Winteracter Starter Kit files are organized as follows under LF90s installation directory:
bin\dialoged.exe bin\dialoged.hlp bin\dialoged.cnt bin\menued.exe bin\menued.hlp bin\menued.cnt wisk\charsets\standard.chr wisk\charsets\duplexr.chr wisk\charsets\triplexr.chr wisk\charsets\fixed.chr wisk\charsets\swiss.chr wisk\demos\* src\winparam.h lib\winter.lib lib\wintera0.mod lib\modtable.txt

Dialog resource editor Dialog resource editor help file Dialog resource editor help contents file Menu resource editor Menu resource editor help file Menu resource editor help contents file Standard vector-based software character set Duplex Roman vector-based software character set Triplex Roman vector-based software character set Courier-like outline character set Helvetica-like outline character set Various demo programs (one per sub-directory) Resource compiler parameter definitions Winteracter Starter Kit library WINTERACTER module (file #1) WINTERACTER module (file #2)
Winteracter Starter Kit

Chapter 1

Supplied Files
The demos directory contains several demos which illustrate various aspects of Winteracter user interface and graphics programming. Each sub-directory contains a single demo consisting of a source file (with a .f90 extension), a resource script (resource.rc) and a program icon (winter.ico). Some directories will contain additional files dependent on the purpose of the demo.

Winteracter Starter Kit

Building a WiSK Program


A Winteracter program will consist of Fortran source code and a resource script. The latter describes menus, dialogs, etc. required by that program. Building a Winteracter program therefore consists of four distinct tasks: (1) Compiling the calling Fortran application source code to create .obj files. (2) Compiling the resource script (.rc) to get a .res file. (3) Converting the .res file to an object (.obj) file. (4) Linking the resulting object files from steps (1) and (3) with the Winteracter library.

Command Line
The LF90 driver will handle these four tasks automatically if you specifiy the -wisk switch on the LF90 command line, along with the Fortran 90 source file name(s) and the resource script name. For example, in the wisk\demos\example directory try typing:
lf90 example.f90 resource.rc -wisk

This is equivalent to the following four commands:


lf90 example.f90 -win -c -mod .;\<lf90>\lib rc /i \<LF90>\src resource.rc res2obj resource.res resource.obj lf90 example.obj resource.obj -win -lib \<LF90>\lib\winter.lib

These commands would compile and link the supplied EXAMPLE demonstration program, along with the accompanying RESOURCE.RC resource file. Both are simply examples. There is no special significance to the choice of these file names. The EXAMPLE program is discussed in some detail in the next chapter.
Winteracter Starter Kit

Chapter 2

Building a WiSK Program


The Winteracter library is called WINTER.LIB and is installed in the LIB sub-directory. This directory will also contain the WINTERACTER module, which defines data types, interface definitions and symbolic names. All Winteracter based programs USE this module. Resource scripts which define menus or dialogs will contain an include statement of the form:
#include "winparam.h"

The file winparam.h contains Windows parameter declarations and is installed in LF90s SRC directory. If you are not using the -wisk switch, then a command line argument should be used to identify this directory to the RC resource compilerc. Alternatively, RC will search the include path specified by the INCLUDE environment variable. Winteracter programs will need to reference identifiers in the resource script. These identifiers will normally be declared as PARAMETER values in a Fortran 90 module or in an include file. DialogEd and MenuEd, the Winteracter resource editors, can generate both file types. Where this file is saved as a module it should be compiled before the Winteracter program which USEs it. Executables built with the Winteracter Starter Kit will run on Intel systems under Windows NT 3.51 or later or under Windows 95. They will also run under Windows 3.1x provided Win32s is installed. A Win32 operating system (i.e. 95 or NT) is required for development.

ED for Windows
ED4W can be used to build W interacter programs too. The main issue here is that ED4W normally assumes that your program has only a single source file. However Winteracter programs consist of two source files, a Fortran program and a resource script, which must both be compiled and linked together. If you use a hardwired name for your resource script (specifically resource.rc as used in the WiSK demo directories) here's one solution. Install the following batch file somewhere on your system :
lf90 %1.f90 resource.rc -wisk

Then, in ED use Tool|Programs|Add to add a new program. The command line should specify the full path of the above batch file, followed by <name>. This tells ED4W to substitute the name of the current program as argument number 1 of the batch file. If you want to have the convenience of having this accessible via a toolbar button then one possibility is to modify the ELF90 button to run the above batch file. This leaves the LF90 button unchanged for use when building non-Winteracter programs.

Winteracter Starter Kit

Writing Winteracter Programs


This chapter aims to introduce you to writing software using Winteracter. It assumes that you are already familiar with how to compile and link Winteracter programs, as described in the previous chapter. The first section summarizes some basic rules. Later in this chapter you will find a worked example which provides a gentle introduction to writing a Winteracter application.

Basics
Certain basic principles apply regardless of which Winteracter features you use.

Initialization
All Winteracter programs must call WInitialise before opening a window.

Fortran I/O
All screen I/O should be performed via Winteracter. While WRITE(*,...) and READ(*,...) work, they will cause an extra output window to be opened over which the program has no direct control. This will look untidy, at the very least. Fortran I/O is freely available on all other channels.

The WINTERACTER Module


A Fortran 90 module called WINTERACTER is supplied which provides three facilities: Type definitions for Winteracter specific data structures. Interface definitions for Winteracter routines. PARAMETER definitions for numerous symbolic names.
Winteracter Starter Kit

Chapter 3

Writing Winteracter Programs


Use of the WINTERACTER module is required in any program unit which calls Winteracter routines. i.e. add the following statement at the beginning of every program unit which uses Winteracter:
USE WINTERACTER

Type Definitions Various Winteracter specific data types are defined in the WINTERACTER module. A typical example is the WIN_STYLE structure used by WindowOpen. Interface Definitions As an aid to checking the number and type of arguments supplied to Winteracter routines, the WINTERACTER module contains an extensive set of interface block definitions. These define the type and intent of all Winteracter subroutine arguments and functions. They will cause the compiler to check the number and type of arguments in each Winteracter call, potentially saving many hours of debugging. Symbolic Names The WINTERACTER module also contains a number of PARAMETER declarations which define symbolic names for Winteracter subroutine arguments and function results. These symbolic names can be used in place of numeric subroutine arguments/results and are designed to be meaningful, aiding program readability. A handful of Microsoft-recommended push-button identifiers (e.g. IDOK) are also defined here. All of the PARAMETER statements contain type declarations, so no further definition is required outside of the module. While use of the symbolic names defined in these files is not obligatory, their use is recommended. They are documented in the subroutine reference section of this manual and form part of the formal definition of Winteracter.

Subroutine Arguments
All subroutine arguments of type CHARACTER may be of any length, except where explicitly documented otherwise. All subroutine arguments of type INTEGER are 4-byte integers. Similarly, all REAL arguments are single precision 4-byte variables

Subroutine and Common Block Names


All externally callable routines in Winteracter start with the letter W or I. Winteracter-specific routines begin with the letter W. Routines which are common to both Winteracter and INTERACTER begin with an I.

Winteracter Starter Kit

Error Reporting
Various internal subroutines and COMMON blocks are used. All internal subroutines have names starting with the letters XX or YY (e.g. XXGDRV). Internal COMMON blocks are named INTRnn or WINTERnn where nn is a 2 digit number (e.g. INTR01). Avoid using subroutines or COMMON blocks with similar names.

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

Winteracter Under Windows 3.1x


Winteracter programs must be developed under a true Win32 operating system. Compiled Winteracter programs built with a Win32s-compatible compiler will run under Windows 3.1x subject to the following: Microsoft's Win32s sub-system must be installed. Bitmaps/icons cannot be used in dialogs (e.g. on push-buttons, check-boxes, etc.). Whilst programs which use bitmaps in dialogs are still valid under Win32s, the associated fields simply display their text caption instead. The height of enterable fields in dialogs must be at least 14. 'Flat' buttons are not supported for push-buttons/check-boxes/radio-buttons. The 'push-like' style is not supported by check-boxes/radio-buttons. The 3D effect is not available in dialogs. Certain resource types are limited (e.g. fewer dialogs can be loaded simultaneously than under Win32).

Winteracter Starter Kit

Chapter 3

Writing Winteracter Programs

Elements of a Winteracter Program


A Winteracter program consists of two main elements: A resource file describing menu structures and dialogs. Fortran 90 source code which calls routines in the Winteracter library.

Resource Files
Each Winteracter program requires a resource script to describe its menus and dialogs, along with miscellaneous information such as the program icon. This script will normally be created and maintained via the supplied visual development tools, namely MenuEd and DialogEd. These tools allow menus and dialogs to be created interactively. The resulting menu/dialog descriptions are saved as standard Windows resource (.RC) files which must be compiled using RC and RES2OBJ as described in the previous chapter. The resulting .OBJ file can then be linked with a program which calls Winteracter routines to produce a true Windows application program. The -wisk compiler command line argument will handle resource compilation automatically. Normally, there is no need to know about the format of a resource file, since this is handled automatically by the supplied resource editors. However, their format is documented later for the benefit of those who feel the need to delve further. A Windows executable may only contain one compiled resource file. Whilst it is feasible for multiple resource scripts to be #included into a parent resource script, this will prevent Winteracters visual tools from properly maintaining the identifiers associated with that resource. It is therefore recommended that the resource script be maintained as a single file.

Identifiers
Every menu, dialog, menu-item and dialog element has a numeric identifier associated with it. These are defined in the resource file. Many Winteracter routines require such an identifier to be specified as an argument. It is therefore important to maintain a separate Fortran module or include file which defines these identifiers (as INTEGER PARAMETER values) to allow the Winteracter program to refer to menu and dialog resources via symbolic names. This file is generated and updated automatically by MenuEd and DialogEd. It must be USE'd or INCLUDE'd by the calling program to enable access to menus/dialogs held in the program resource. This file will be referred to as the Symbol Header file. Several commonly used push-button identifiers (e.g. IDOK and IDCANCEL for OK/Cancel buttons) are defined in the WINTERACTER module (see WMessage). As a general rule, identifier values should be non-zero unsigned 16-bit integers, i.e. they should be in the range 1-65535. The exception is dialog identifiers which should be in the range 1-32767. Note that this limitation to 16-bit values does not affect the integer type of identifier variables or parameters, which should still be four byte integers.

Winteracter Starter Kit

Message Loop
Remember that identifiers must be valid Fortran parameter names. Hence, they should not include characters such as ! , + - * ( ) > < etc. Both MenuEd and DialogEd will reject attempts to use such characters in identifier names. Avoid using such characters if you amend resource files manually.

Message Loop
Most program input is reported via a message queue (also known as an event queue in some other windowing systems; events and messages are the same thing). Windows itself reports huge numbers of messages. Winteracter only passes a much reduced subset of these messages up to the calling program, greatly simplifying the volume and type of messages which must be processed. Messages are reported via the WMessage routine. Typical messages are 'a key was pressed', 'a menu item was selected', 'a window changed size' and so on. The calling program will usually revolve around a DO loop which calls WMessage then checks the resulting message in a SELECT CASE statement. The following is a simplified example of such a loop:
USE WINTERACTER TYPE (WIN_MESSAGE) :: MESSAGE ! DO ! loop until termination CALL WMessage(ITYPE,WMESSAGE) SELECT CASE (ITYPE) CASE (KeyDown) CASE (MenuSelect) CASE (Resize) ! A key was pressed ! A menu item was selected ! The window size changed KEY = MESSAGE%VALUE1 ITEM = MESSAGE%VALUE1 IWIN = MESSAGE%WIN CALL DrawMyGraph(IWIN) CASE (CloseRequest) ! The user closed the program EXIT END SELECT END DO

The location of the message loop is a matter of program choice. In a small program, it will make sense to place the message loop in the main program. However, this can rapidly lead to a 'top heavy' program in larger applications. It is therefore perfectly allowable to have multiple message loops in a program, provided they are capable of processing all the possible messages which can be reported at a given point in the programs execution. See the MH group in the subroutine reference section for more information.
Winteracter Starter Kit

Chapter 3

Writing Winteracter Programs

Windows
A Winteracter application consists of a root window and up to 20 child windows. The latter exclude any dialog windows (see the following Dialogs section). In this context a 'window' is a standard Windows output window which can have any text or graphics written into it. Effectively they are free format output windows. A root window is always opened first using WindowOpen. Child windows can then be opened using WindowOpenChild. The routines in the TX/FS groups can be used to write text in various styles to these windows. Equally, the graphics routines in the GG/GS/GD/GC groups can be used to draw in these windows. Every window has a handle which is allocated automatically by Winteracter when the window is opened. Use this to select the window to receive output in a call to WindowSelect. Text output to a window uses an arbitrary co-ordinate system which is independent of window size. Every window is assumed to to be 10000x10000 units square. Text co- ordinates are measured from the top left corner of the window. Graphics output uses a separate REAL user-defined cartesian co-ordinate system (see the following Graphics section).

Menus
The contents and structure of program menus are defined in resource files. Normally, these are created using MenuEd, the Winteracter menu resource editor. Use WindowOpen and/or WMenuRoot to activate these menus. Root menus remain visible at all times. Windows manages these menus automatically and reports menu selections via WMessage. The contents and state of individual menu items can be modified at run-time. For example, menu items can be greyed to prevent them from being selected, by calling WMenuSetState.

Dialogs
Dialogs are collections of fields (or 'controls') which are displayed in a dedicated child window. (In other development systems dialogs are also known as 'panels' or 'forms'.) The layout and initial contents of a dialog must be defined in resource files. These should be created using DialogEd, the Winteracter dialog resource editor. Two basic types of dialogs are allowed under Windows: modal and modeless. Their resource file definitions are identical, but their behaviour when activated is different. A modal dialog will block all other program input until the user terminates the dialog. This makes for simpler program development, at the expense of a slightly less friendly user interface. Modeless dialogs do not block program execution and allow interaction with other windows/dialogs belonging to the same program. A third dialog type is supported by Winteracter, known is 'semi-modeless'. These are a useful hybrid dialog type which appears modeless to the calling program but modal to the user.

10

Winteracter Starter Kit

Graphics
All dialogs are either 'pop-up' dialogs or 'child' dialogs. A pop-up dialog can be moved to any position on the screen either inside or outside of the application window. Child dialogs are restricted to the root window. Child dialogs must be modeless. To activate a dialog call WDialogLoad and WDialogShow. Multiple simultaneous dialogs are allowed. See the introduction to the DM(1) group for more details. Dialogs consist of various field types including strings, four styles of menu, push-buttons, radio buttons and check boxes. The contents of these fields can be assigned and retrieved using the various 'put/get' routines in the DM(2) group. Winteracter dialogs use standard Windows controls so all the normal behaviour is available. Notably clipboard cut/paste is supported via the mouse or the usual keyboard shortcuts (Ctrl/ C, Ctrl/V, etc.) Under Windows 4, the usual shortcuts menu is available via the right mouse button. Winteracter dialogs also implement Ctrl/A as a shortcut for Select All in string fields. In addition to application-specific dialogs, Windows also provides some pre-packaged modal dialogs. The most useful of these (file selection and message box) are supported via the routines in the CD group.

Graphics
Winteracter's graphics routines are compatible with the platform independent INTERACTER library. The introduction to the GG group describes the basic principles of Winteracter graphics programming. Graphics can appear in any window opened via WindowOpen or WindowOpenChild. The graphics co-ordinate system in each window is fully user definable and is controlled by the IGrUnits routine. This co-ordinate system is completely independent of the text coordinate system used by the text output routines in the TX group.

A Worked Example
This section explains how to write a simple Winteracter program which uses a small but typical selection of the facilities available, including message handling, common dialogs and graphics. The short program is built up step by step, with newly introduced statements highlighted at each stage by an '*' in the right hand margin. A copy of the complete program can be found in WISK\DEMOS\EXAMPLE, along with its associated resource script. The first thing to do in any Winteracter program is to initialize the library by calling WInitialise. This must be followed by a call to WindowOpen to open a root window and initialize the graphics routines. To terminate screen processing, WindowClose must be called. A minimal Winteracter program therefore looks like this:
Winteracter Starter Kit

11

Chapter 3

Writing Winteracter Programs


PROGRAM WISK_EXAMPLE * USE WINTERACTER * IMPLICIT NONE * TYPE(WIN_STYLE) :: WINDOW * CALL WInitialise(' ') ! Initialize Winteracter * WINDOW%FLAGS = SysMenuOn + MinButton + MaxButton * WINDOW%X = -1 ! Center window horizontally * WINDOW%Y = -1 ! Center window vertically * WINDOW%WIDTH = 0 ! Use default window size * WINDOW%HEIGHT = 0 ! (80% of screen size) * WINDOW%MENUID = 0 ! Menu identifier (none) * WINDOW%TITLE = 'Example Program' ! Root window title * CALL WindowOpen(WINDOW) ! Open root window * CALL WindowClose() ! Remove program window * END PROGRAM WISK_EXAMPLE *

The program initializes the library then fills a data structure with a description of the root window which is to be opened. WindowOpen is then called to open that window. Note that the program USE's the WINTERACTER module. In this particular example it will define the WIN_STYLE data type, the symbolic names assigned to the FLAGS element of the window type argument and the interface blocks for each of the called routines. As noted earlier in this chapter, use of this module is required. So far, all this program will do is open a root window with no menu then immediately close it again. Let's assume we want the program to read some time series data from a file and plot it as a simple line graph. The first task is to introduce some message handling so we can add 'Open' and 'Exit' options to the program. This will allow the user to select the data file to plot and to exit via a program menu option (though the System menu can be used for the same purpose, where enabled). The following expanded example assumes that a resource file is supplied which defines a menu consisting of 'Open' and 'Exit' options.

12

Winteracter Starter Kit

A Worked Example
PROGRAM WISK_EXAMPLE USE WINTERACTER IMPLICIT NONE INTEGER, PARAMETER :: IDR_MENU1 = 30001 * INTEGER, PARAMETER :: ID_OPEN = 40001 * INTEGER, PARAMETER :: ID_EXIT = 40002 * TYPE(WIN_STYLE) :: WINDOW TYPE(WIN_MESSAGE) :: MESSAGE * INTEGER :: ITYPE * CALL WInitialise(' ') ! Initialize Winteracter WINDOW%FLAGS = SysMenuOn + MinButton + MaxButton WINDOW%X = -1 ! Center window horizontally WINDOW%Y = -1 ! Center window vertically WINDOW%WIDTH = 0 ! Use default window size WINDOW%HEIGHT = 0 ! (80% of screen size) WINDOW%MENUID = IDR_MENU1 ! Menu identifier * WINDOW%TITLE = 'Example Program' ! Root window title CALL WindowOpen(WINDOW) ! Open root window DO WHILE (.TRUE.) ! Loop until user terminates * CALL WMessage(ITYPE, MESSAGE) * SELECT CASE (ITYPE) * CASE (MenuSelect) ! Menu item selected * SELECT CASE (MESSAGE%VALUE1) * CASE (ID_OPEN) ! Select file to plot * CONTINUE ! We will load file here * CASE (ID_EXIT) ! Exit program (menu option) * EXIT * END SELECT * CASE (CloseRequest) ! Exit program (e.g. Alt/F4) * EXIT * END SELECT * END DO * CALL WindowClose() ! Remove program window END PROGRAM WISK_EXAMPLE

Three parameters are now defined which identify the root menu and the two options which it will contain. Normally such PARAMETER statements would be stored in a module, but they are shown as part of this program for the sake of clarity. The identifier of the root menu is now specified as part of the root window description, ensuring that Windows will automatically attach that menu to the window. The main addition to the example program is the introduction of the DO WHILE loop which processes Windows messages. It loops continuously until the user selects Exit from the program menu or closes the window via the title bar controls. The message loop also allows for the user having selected the 'Open' option from the root menu. We will now expand the program to allow a data file to be selected via a common dialog. Data will then be read from the file ready for plotting.
Winteracter Starter Kit

13

Chapter 3

Writing Winteracter Programs


PROGRAM WISK_EXAMPLE USE WINTERACTER IMPLICIT NONE INTEGER, PARAMETER :: IDR_MENU1 = 30001 INTEGER, PARAMETER :: ID_OPEN = 40001 INTEGER, PARAMETER :: ID_EXIT = 40002 INTEGER, PARAMETER :: ID_STRING1 = 50001 * TYPE(WIN_STYLE) :: WINDOW TYPE(WIN_MESSAGE) :: MESSAGE INTEGER :: ITYPE, NVALUE, I * CHARACTER(LEN=255) :: FNAME * REAL, DIMENSION(50) :: VALUES * CALL WInitialise(' ') ! Initialize Winteracter WINDOW%FLAGS = SysMenuOn + MinButton + MaxButton WINDOW%X = -1 ! Center window horizontally WINDOW%Y = -1 ! Center window vertically WINDOW%WIDTH = 0 ! Use default window size WINDOW%HEIGHT = 0 ! (80% of screen size) WINDOW%MENUID = IDR_MENU1 ! Menu identifier WINDOW%TITLE = 'Example Program' ! Root window title CALL WindowOpen(WINDOW) ! Open root window FNAME = 'example.dat' * NVALUE = 0 * DO WHILE (.TRUE.) ! Loop until user terminates CALL WMessage(ITYPE, MESSAGE) SELECT CASE (ITYPE) CASE (MenuSelect) ! Menu item selected SELECT CASE (MESSAGE%VALUE1) CASE (ID_OPEN) ! Select file to plot CALL WSelectFile(ID_STRING1,PromptOn, & * FNAME,'Load Data') * IF (WInfoDialog(ExitButtonCommon).EQ.CommonOpen) THEN * OPEN(20,FILE=FNAME,STATUS='OLD') * READ(20,*) NVALUE * READ(20,*) (VALUES(I),I=1,NVALUE) * CLOSE(20) * ENDIF * CASE (ID_EXIT) ! Exit program (menu option) EXIT END SELECT CASE (CloseRequest) ! Exit program (e.g. Alt/F4) EXIT END SELECT END DO CALL WindowClose() ! Remove program window END PROGRAM WISK_EXAMPLE

14

Winteracter Starter Kit

A Worked Example
Our program now defines a values array and a filename variable. A common dialog is used to select the input file (a suitable example.dat file is supplied in the WISK\DEMOS\EXAMPLE directory). The ID_STRING1 identifier refers to a string table in the program's resource file which specifies the file types which the file selector dialog will offer. In the example supplied on the distribution media this will be '*.dat'. If the user confirms their file selection (i.e. they don't click on Cancel or press Escape) the name of the selected file is returned in the FNAME variable. Data is then read from the chosen file. Note that the file handling contains no error processing, to keep the example simple. We are now ready to plot the data. A separate routine will be introduced which uses Winteracter's graphics routines.

Winteracter Starter Kit

15

Chapter 3

Writing Winteracter Programs


PROGRAM WISK_EXAMPLE USE WINTERACTER IMPLICIT NONE INTERFACE * SUBROUTINE DrawGraph(VALUES,NVALUE) * IMPLICIT NONE * REAL , INTENT (IN), DIMENSION(:) :: VALUES * INTEGER, INTENT (IN) :: NVALUE * END SUBROUTINE DrawGraph * END INTERFACE * INTEGER, PARAMETER :: IDR_MENU1 = 30001 INTEGER, PARAMETER :: ID_OPEN = 40001 INTEGER, PARAMETER :: ID_EXIT = 40002 INTEGER, PARAMETER :: ID_STRING1 = 50001 TYPE(WIN_STYLE) :: WINDOW TYPE(WIN_MESSAGE) :: MESSAGE INTEGER :: ITYPE, NVALUE, I CHARACTER(LEN=255) :: FNAME REAL, DIMENSION(50) :: VALUES CALL WInitialise(' ') ! Initialize Winteracter WINDOW%FLAGS = SysMenuOn + MinButton + MaxButton WINDOW%X = -1 ! Center window horizontally WINDOW%Y = -1 ! Center window vertically WINDOW%WIDTH = 0 ! Use default window size WINDOW%HEIGHT = 0 ! (80% of screen size) WINDOW%MENUID = IDR_MENU1 ! Menu identifier WINDOW%TITLE = 'Example Program' ! Root window title CALL WindowOpen(WINDOW) ! Open root window FNAME = 'example.dat' NVALUE = 0 DO WHILE (.TRUE.) ! Loop until user terminates CALL WMessage(ITYPE, MESSAGE) SELECT CASE (ITYPE) CASE (MenuSelect) ! Menu item selected SELECT CASE (MESSAGE%VALUE1) CASE (ID_OPEN) ! Select file to plot CALL WSelectFile(ID_STRING1,PromptOn,FNAME,'Load Data') IF (WInfoDialog(ExitButtonCommon).EQ.CommonOpen) THEN OPEN(20,FILE=FNAME,STATUS='OLD') READ(20,*) NVALUE READ(20,*) (VALUES(I),I=1,NVALUE) CLOSE(20) CALL DrawGraph(VALUES,NVALUE) * ENDIF CASE (ID_EXIT) ! Exit program (menu option) EXIT END SELECT CASE (Expose,Resize) ! Need to redraw picture *

16

Winteracter Starter Kit

A Worked Example
CALL DrawGraph(VALUES,NVALUE) * CASE (CloseRequest) ! Exit program (e.g. Alt/F4) EXIT END SELECT END DO CALL WindowClose() ! Remove program window END PROGRAM WISK_EXAMPLE SUBROUTINE DrawGraph(YVALUE,NVALUE) ! Draw graph * USE WINTERACTER * 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 = MINVAL(YVALUE) * YMAX = MAXVAL(YVALUE) * 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,YMAX) * DO IX = 2,NVALUE * XPOS = XMIN + XLEN*REAL(IX-1)/REAL(NVALUE-1) * CALL IGrLineTo(XPOS,YVALUE(IX)) * END DO * RETURN * END SUBROUTINE DrawGraph *

Minimum X and Y values are assigned. IGrUnits is then used to define a co-ordinate system which leaves a border around the area in which the graph will be plotted. A simple Lshaped axis is plotted, followed by the data itself. IGrLineTo is effectively a Pen-Down and draw operation, so the DO loop creates a connected line graph. The graph will also be redrawn if the window size changes or the window becomes partly or wholly exposed. And finally, to add some annotation to the x axis:
Winteracter Starter Kit

17

Chapter 3

Writing Winteracter Programs


SUBROUTINE DrawGraph(YVALUE,NVALUE) ! Draw graph USE WINTERACTER 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 = MINVAL(YVALUE) YMAX = MAXVAL(YVALUE) 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,YMAX) 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 RETURN

* *

* * * * * * * * *

END SUBROUTINE DrawGraph Labels and tick marks are added to the x axis using center justified text. For more examples of how to use Winteracter see the various demonstration programs supplied in WISK\DEMOS.

18

Winteracter Starter Kit

MenuEd - Menu Resource Editor


A program called MenuEd is supplied which allows you to interactively create menu resource scripts. These describe one or more menu structures for a given application. They should be compiled using the RC resource compiler and the Lahey resource to object converter RES2OBJ. The resulting .OBJ file can then be incorporated into Winteracter based Windows applications using the linker. MenuEd also saves a Fortran source file which contains PARAMETER statements defining identifiers for each item in the menu resource file. This file can be USE'd or INCLUDE'd by a Winteracter program to enable it to refer to items in the menu by means of meaningful identifiers. The name of the resource file to edit can be specified via the 'File' menu option or on the MenuEd command line. The latter option ensures that MenuEd supports invocation via dragand-drop or via a file-type association (see 'View->Options->File Types' in Explorer). MenuEd displays a mimic of your menu structure in its main window. The following section describes the mouse and keyboard controls which are available to navigate and edit the menu. This is followed by a description of the various menu options and dialogs which MenuEd provides to allow you to edit your menu. Finally, a short example is provided illustrating the creation of a simple menu using MenuEd.

Mouse And Keyboard Input


Mouse Input
The left mouse button is used to select the currently editable object. If the pointer is currently over a valid item, it will be highlighted and selected. The right mouse button is used to display the Edit menu as a floating menu at the current cursor position. If the cursor is positioned over a valid item, that item will be highlighted and selected as the current item.
Winteracter Starter Kit

19

Chapter 4

MenuEd - Menu Resource Editor

Keyboard Input
As well as the menu shortcut keys there are some special keys to help simplify construction of your menu resources. The cursor keys can be used to move around the menu. The highlight will be updated at each key press. The Alt/1 to Alt/0 keys can be used to switch between the first 10 menu structures. Page Up/Down can also be used to move between menus.

File Options
The File option on the main menu leads to various sub-options: New This option clears all menu structures from memory, following a warning prompt. All current resource data will be deleted by this option. Open This option will load a resource script. The file is selected via the standard Windows file selection dialog. If the file was previously saved by MenuEd then the load function will read user preferences from the file too (as set in the File Settings box in the View->Preferences dialog) and set them for use by the current menu. Once the file has been successfully loaded it will be displayed with the first option highlighted. Up to 20 different menu structures can be loaded and edited at one time. If a resource script contains more than this, the extra menu structures will be ignored. Any other resource data in the file (such as icons and dialogs) will be retained when the file is saved. Save This option saves the menu resource in a Microsoft RC compatible format. The Save option will also produce a Fortran 90 include/module file depending on the current preference settings. See View Options for more information. The include or module file will be saved in the same directory as the resource file. If you have not already specified a file name then you will be prompted to choose one via the standard Windows file selector. The resultant resource file can then be compiled (using RC and RES2OBJ) and linked with your Winteracter program. Save As This option performs the same task as the Save option except that it will always prompt for a file name. Exit Leave the program. If there are unsaved menu resources, a warning will be displayed.

20

Winteracter Starter Kit

Edit Options

Edit Options
This menu can be accessed via the main menu or by pressing the right mouse button anywhere within the MenuEd window. Properties This option allows you to change the appearance of the menu items. When you select this item, via the Edit menu or by pressing the Enter key, the Properties dialog is displayed. The Caption field is used to specify the text that actually appears on the menu. A single character in the string can be underlined using the ampersand (&) character. This key can then be used in combination with the Alt key as a keyboard short cut to that menu item. The Item ID field is used to give the item a symbolic name to be referenced by in your Winteracter program. If the item is not at the end of the menu chain (i.e. it has a child/popup menu attached to it) or it is a separator, then this field can be left blank. However, if you wish to alter a popup item using Winteracter's menu handling routines then you will need to give the item an identifier (or use the default assigned by MenuEd). If an item is an end of chain option and this field is blank, a default value of ID_NONE will be assigned in the resource file. Click-on the drop-down button to select from the full list of currently defined menu item identifiers. The Popup check box is used to add or remove a child menu from the current item. If you uncheck an item that has child menu data then this data will be lost. If this box is checked for an item that has no children then the new child will be created with the Caption text of 'Empty'. The Separator check box is used to set the current item as a vertical or horizontal line. The values for the Item ID and Caption fields are ignored. Separators are used to break up lists of menu items into sub-sections. The Checked check box is used to specify whether the current menu item will have a tick by the side of it. MenuEd does not display ticks for ticked items. The Grayed check box is used to specify whether the current menu item will be grayed (and therefore not available) when the menu is displayed. MenuEd does not gray out grayed items. Accelerators This option allows the assignment of a key or combination of keys to a particular item. MenuEd allows up to 2 different key combinations to be used per item. The keys are split into two groups, ASCII key accelerators (alphanumeric characters and some symbols) and Virtual keys (Functions keys, keypad plus tab, enter etc.). Virtual keys can be used in combination with the Shift, Alt and Control keys. ASCII keys can be used in combination with the Control and Alt keys.
Winteracter Starter Kit

21

Chapter 4

MenuEd - Menu Resource Editor


The tab key can be used as a shortcut to this dialog. If the currently highlighted option is a popup then no accelerator can be assigned to it, so the option will be greyed out. Selecting this option will display a two part dialog: The Virtual Key Code list box field allows a choice of forty different virtual keys that can be used as menu accelerators. The check box fields Shift, Ctrl and Alt allow various key combinations to be used. To un-select or clear the current Virtual accelerator key select No Virtual Key from the Virtual Key Code list box. The ASCII Key Value field allows the user to enter a single ASCII key that will be used to select the option. The check box fields Ctrl and Alt allow various key combinations to be used. For example, to select the item associated with the above settings Alt-X could be used. To un-select or clear the current ASCII accelerator key delete the contents of the ASCII Key Value field. Any changes made to these fields will update the information embedded within the caption field in the Properties dialog. A short description of the selected key combination(s) will be added and right justified within the menu. See the Caption field in the Properties dialog for more information on simple assignment of keyboard short cuts using the ampersand symbol. Insert After This option allows you to add a new item to the menu structure. The item will be inserted after the current item on the same menu level. The caption of the new field will be Empty and the highlight will be moved to this new item. Insert Before This option allows you to add a new item to the menu structure. The item will be inserted before the current item on the same menu level. The caption of the new field will be 'Empty' and the highlight will be moved to this new item. Delete This option will delete the currently selected item in the menu chain. The highlight will then move to the next or previous item on the current menu level. If the item has a child item then all the data relating to the child item will be lost. If the item is the sole child item then the highlight will move to the parent item and its popup field will be cleared. Cut This option will remove the current menu item in the same way as Delete but a copy of the data will be stored in the paste buffer. Copy This option will copy the current item characteristics into the paste buffer.

22

Winteracter Starter Kit

Menu Options
Paste This option will insert the current contents of the paste buffer after the currently selected menu item.

Menu Options
Add Menu This option adds a new menu structure to the resource. Up to 20 menu structures can be edited by MenuEd at one time. The new menu will be displayed with the first item caption set to Empty and highlighted. The new menu will be given an identifier of IDR_MENUXX where XX is the next free menu structure value. Delete Menu This option removes a complete menu structure from the resource. A confirmation prompt will be displayed to make sure you really want to clear the menu structure. All the data associated with the menu structure will be lost and the next valid menu structure will be displayed. Choose Menu This option displays a dialog that will list all the currently editable menu structures by their identifiers. When a different menu structure is selected, it will be displayed. The keyboard keys Alt/1 - Alt/0 can be used to switch between the first 10 menu structures. Identifier This option allows you to change the symbolic name assigned to the current menu structure. This value can be any valid string but must not contain spaces. It will be used by the resource script to identify the structure and can be used by the Winteracter routines WindowOpen and WMenuRoot.

View Options
Used Identifiers This option displays a dialog that lists all of the identifier names used in the current menu structure.
Winteracter Starter Kit

23

Chapter 4

MenuEd - Menu Resource Editor


Preferences This option selects various information about how MenuEd saves data and how editable menus are displayed. The Preference dialog will be displayed. The dialog is divided into 'File Settings' and 'Display Settings'. The 'File Settings' preferences will be saved into the resource script and re-used when the script is next loaded by MenuEd or DialogEd. File Settings : The Symbol Header File field is used to select the file name of the Fortran 90 module or include file that the Save option will produce. This file lists all the symbolic identifiers for menu structures and menu items as Fortran 90 INTEGER PARAMETER statements. If this field is left blank then the Fortran file will have the same name as the resource script but with a .F90 or .INC extension. The Symbol Header File Type radio buttons are used to set whether Save produces a Fortran 90 module or a Fortran include file. The F90 Module Name field is used to set the module name of the Fortran 90 module created by Save. This can be any valid Fortran 90 module name up to 31 characters long and must not contain spaces. If the Symbol Header File Type is set to a Fortran include file this value is ignored. The Base Menu Value field is used to set the numeric value to start assigning menu structure identifier values from. We recommend that Winteracter developers use symbolic identifiers to reference their menu structures and that this value should only be changed if it causes clashes with values in other resource scripts used by your program. The Base Item Value field is used to set the numeric value to start assigning item identifier values from. We recommend that Winteracter developers use symbolic identifiers to reference their item values and that this value should only be changed if it causes clashes with values in other resource scripts used by your program.

Display Settings : The Font Style field allows you to alter the font that the current display uses to output menu text. There are five fonts to choose from: System Proportional (default), System Fixed, Times New Roman, Swiss and Courier New. The first two fonts are fixed in size and do not change when the window is re-scaled. The other fonts will adjust in size when the window is re-scaled and can be resized using the Font Size list box. The Font Size field allows you to select from eight fixed font sizes. These sizes only affect the Times New Roman, Swiss and Courier New fonts. This option allows you to adjust the amount of data that can be displayed in the MenuEd window depending on your screen size and configuration. The Menu Colour field allows the color of the editable menu display to be specified. The Highlight Colour field allows the color of the item highlight bar to be specified.

24

Winteracter Starter Kit

Creating Your First Menu Resource.

Creating Your First Menu Resource.


This brief tutorial is intended to help you to construct and use your first MenuEd menu resource: 1. Initially, MenuEd presents you with a grey menu strip just inside the main window. This menu is a simple emulation of a Windows menu to allow you to visualize how the menu will appear in your Winteracter program. Initially it has one item on it (labelled Empty) which is highlighted in blue. Click on this item with the left mouse button to display its properties. 2. The properties dialog is used to alter the settings for each individual item. First, set the text that actually appears on the menu bar. This is done via the caption box. Delete the current contents of the field and then type &File into the box. The ampersand (&) character is used to set which character within the string is underlined. This key can then be combined with the Alt key to select the menu item via the keyboard. 3. Click on the Popup check box (so that a tick appears). This will attach a pull down menu (or child menu) to the current item. Now click on the OK button. You should notice two things. First the highlighted item will now say File. Secondly, underneath it is a child menu with a single option (labelled Empty). 4. Double click on the new child item with the left mouse button. This will display the Properties dialog. Type &Option 1 into the caption box. As this item will be used to input a user action we must give it an identifier. This identifier will be reported via the Winteracter message loop when the item is selected. By default an identifier of ID_ITEM2 is given to this object but let's change this to something more meaningful. Type ID_OPTION1 into the item ID field. Now click on the OK button. 5. The display will now be updated. To add another item to the child menu use the Insert After option. This can be accessed by pressing the right mouse button which will display the edit menu at the current mouse position. You should now have a new item at the bottom of the child menu (labelled 'Empty') which will be highlighted. 6. Click on the new item with the left mouse button. Type E&xit into the caption box. Type ID_EXIT into the item ID box. Click the OK button. Your first menu resource is now finished. 7. To save your menu, click on the File option on the main menu and then the Save option. This will display the standard Windows file selector. Enter a file name (e.g. menu.rc) and click OK. You now have a resource script which can be compiled and linked with your Winteracter program code, as described in the "Building a WiSK Program" chapter. The resource file format is described in detail in the Resource File Format chapter. See the MN group in the subroutine reference for more information about using menu resources within Winteracter programs.
Winteracter Starter Kit

25

Chapter 4

MenuEd - Menu Resource Editor

26

Winteracter Starter Kit

DialogEd - Dialog Resource Editor


A program called DialogEd is supplied which allows you to interactively create dialog resource scripts. These describe one or more dialogs for a given application. They should be compiled using the RC resource compiler and the Lahey resource to object converter RES2OBJ. The resulting .OBJ file can then be incorporated into Winteracter based Windows applications using the linker DialogEd also saves a Fortran source file which contains PARAMETER statements defining identifiers for each dialog field/control in the dialog resource. This file can be USE'd or INCLUDE'd by a Winteracter program to enable it to refer to dialog elements by means of meaningful identifiers. The name of the resource file to edit can be specified via the 'File' menu option or on the DialogEd command line. The latter option ensures that DialogEd supports invocation via drag-and-drop or via a file-type association (see 'View->Options->File Types' in Explorer). DialogEd displays a mimic of your dialog in a sub-window. The following section describes the mouse and keyboard controls which are available to manipulate the dialog. This is followed by a description of the various menu options and dialogs which DialogEd provides to allow you to edit your dialog. Finally, a short example is provided illustrating the creation of a simple dialog using DialogEd.

Mouse and Keyboard Input


Mouse Input
The left mouse button is used to select the current field. This field will be marked by a surrounding border. Multiple fields can be selected by holding down the Shift key. When multiple fields are selected the last field selected will have a different colour border. To select a Group Box click on or near its border.
Winteracter Starter Kit

27

Chapter 5

DialogEd - Dialog Resource Editor


Once fields are selected they can be moved by dragging within any selected field. If a single field is selected, it can be resized by dragging the border. The mouse cursor will change to a double headed arrow when positioned over the border. Similarly, the cursor changes to a four headed arrow when positioned to move a field. Clicking the right mouse button on the dialog window title displays the Dialog Properties dialog. A right mouse button click anywhere else in the DialogEd window displays the Field Properties menu as a floating menu at the current cursor position. If the cursor is positioned over a field then it will be highlighted and selected as the current field. Double clicking on a field displays the General Properties dialog for that field.

Keyboard Input
Various menu options have keyboard shortcuts available (as well as the usual Alt+underlined letter). These are shown next to the menu items. Additionally, Alt/1 through Alt/0 select between the first ten dialogs in the resource.

File Options
The File option on the main menu leads to various sub-options: New This option clears all dialogs from memory, after prompting you to save any unsaved changes. All resource data will be deleted by this option. You will then be prompted for the properties of the first dialog in the new resource script. Open This option will load in a resource script. The file is selected via the standard Windows file selection dialog. If the file was previously saved by DialogEd then the load function will read user preferences from the file (as set in the File Settings box in the View->Preferences dialog) and set them for use by the current dialog. Once the file has been successfully loaded the first dialog in the resource will be displayed. Up to 50 different dialogs can be loaded and edited at one time. If a resource script contains more than this amount the extra dialogs will be ignored. Any other resource data in the file (such as icons and menus) will be retained when the file is saved. The identifiers of any bitmap or icon resources will also be loaded. Save This option saves the dialog resource in a Microsoft RC compatible format. The save routine will also produce a Fortran 90 include/module file depending on the current preference settings. See View Options for more information. The include or module file will be saved in the same directory as the resource file.

28

Winteracter Starter Kit

Edit Options
If you have not already specified a file name then you will be prompted to choose one via the standard Windows file selector. The resultant resource file can then be compiled (using RC and RES2OBJ) and linked with your Winteracter program. Save As This option performs the same task as the Save option except that it will always prompt for a file name. Import Picture This option adds a bitmap or icon to the resource script. After selecting the file containing the bitmap or icon, you will be prompted for an identifier. You should specify the same identifier as the field which will display the picture. Alternatively, any identifier can be used if you intend to assign the picture to a field at run time using WDialogPutImage. Exit Leave the program. You will be given the opportunity to save any unsaved changes.

Edit Options
Cut This option will remove the currently selected field(s) and copy them to the paste buffer. Copy This option will copy the current field(s) into the paste buffer. Paste This option will insert the current contents of the paste buffer. A new identifier will be generated for each pasted field. Delete This option will delete the currently selected fields. If the identifier of a deleted field is not used elsewhere in the resource, it will be deleted when the resource is next saved.
Winteracter Starter Kit

29

Chapter 5

DialogEd - Dialog Resource Editor

Dialog Options
Test This displays the current dialog in test mode, allowing you to see how it will appear in your program. However the following should be noted: 1) The dialog will always be displayed as a modal popup. 2) Any or icon bitmap fields will not have their specified bitmaps displayed. Instead a dummy bitmap will be used for test purposes. Any changes made to field contents in test mode are not saved. Add This option adds a new dialog to the resource script. Up to 50 dialogs can be edited by DialogEd at one time. The properties dialog will displayed, enabling you to specify the new dialog's initial properties. The dialog will be given an identifier of IDD_DIALOGXX where XX is the number of the next unused dialog. Delete This option displays a list of of the identifiers of all the dialogs in the current resource. Select the dialog to be deleted. If you delete the current dialog, you will be asked to choose a new dialog to edit, unless there are no other dialogs. Choose This option displays a list of all the dialogs in the current resource script, using their identifier names. Select the dialog you wish to edit. Properties This displays the properties of the current dialog (or the dialog that is being created if displayed from Add or File New). The available properties are: ID The identifier which will be used to refer to the dialog in your program. To change the identifier either enter a new name or select an existing name from the list. If the old name is not used elsewhere in the resource, it will be removed next time the resource is saved. Title Text to be displayed in the dialog's title bar. Clear the check box if you do not want the dialog to have a title bar.

30

Winteracter Starter Kit

Field Options
System Menu When checked, indicates that the dialog will have a system menu. It is not possible for a dialog to have a system menu unless it also has a title bar. Type Choose how the dialog will be displayed in your program - Popup or Child. Note: Do not choose Child if you intend to use the dialog as a modal or semi-modeless dialog in your program. Size Specify the height and width in dialog units. (Windows defines these as as a quarter of the average character width and an eighth of the character height.) Alternatively the dialog can be sized simply by stretching its window when in edit mode. Re-Order Fields This option allows the order in which the cursor will move through the fields to be changed. Simply click on the fields in the order in which you wish the cursor to move through them. As each field is clicked it will be disabled to indicate that it has been chosen. Take any other action (for example selecting Test) to finish ordering your fields.

Field Options
Add This leads to a sub-menu of available field types. Select the type of field which you wish to add then click in the dialog window to create it. Alternatively use the field insertion toolbar. Note that Windows imposes a limit of 255 fields in any one dialog. Properties This leads to a sub-menu of property types, followed by a dialog. This in turn depends on the type of property chosen and the type of the currently selected field. Alternatively this submenu can be displayed using the right mouse button. Some of the Properties dialogs contain options which are only available in combination with certain other options. These will be enabled/disabled as appropriate.
Winteracter Starter Kit

31

Chapter 5

DialogEd - Dialog Resource Editor


Alignment This leads to a submenu of alignment options (the same options are available via the Field Alignment Toolbar) : Align Left Align Right Align Top Align Bottom Centre Horizontally Centre Vertically Aligns the left hand edges of the selected fields with the last field selected. Aligns the right hand edges of the selected fields with the last field selected. Aligns the top edges of the selected fields with the last field selected. Aligns the bottom edges of the selected fields with the last field selected Horizontally centres the selected fields. Vertically centres the selected fields.

Label Fields
These simply display fixed text and are generally used to label other fields. The available properties are: General ID The identifier which will be used to refer to the field in your program. To change the identifier either enter a new name or select an existing name from the list. It is not possible for two fields in the same dialog to have the same identifier. The list of identifier names will not show identifiers that have already been used in the current dialog. Caption The text that is displayed in the field. It is possible to underline a character within the text by prefixing it with an & symbol. Pressing Alt and the underlined character can then be used to move to the next entry field after the label. X Pos The position of the left-hand edge of the field in dialog units. Y Pos The position of the top edit of the field in dialog units. Width The width of the field in dialog units.

32

Winteracter Starter Kit

Picture/Frame Fields
Height The height of the field in dialog units. Disabled Causes the field to be displayed greyed-out. This also disables any Alt+letter combination (see Caption, above). Note: It is not possible to move into label fields even when they are not disabled. Group Indicates that the field is the start of a new group. Style Alignment Determines the alignment of text within the field. Available options are: Left, Centre and Right. No Prefix Causes any & characters to be displayed, instead of being used to underline the next character. No Wrap Prevents word-wrap. Normally any text which did not fit into the width of a label field would be wrapped onto the next line (assuming the field was tall enough). See also Border properties.

Picture/Frame Fields
These are rectangular regions used to display a bitmap, icon, frame or solid rectangle. They are purely decorative. General ID The identifier of the field. If the field is to display a bitmap or icon, then the field and bitmap/icon must have the same identifier. To change the identifier either enter a new name or select an existing name from the list. It is not possible for two fields in the same dialog to have the same identifier. The list of identifier names will not show identifiers that have already been used in the current dialog. X Pos The position of the left-hand edge of the field in dialog units.
Winteracter Starter Kit

33

Chapter 5

DialogEd - Dialog Resource Editor


Y Pos The position of the top edge of the field in dialog units. Width The width of the field in dialog units. Height The height of the field in dialog units. Group Indicates that the field is the start of a new group. Style Type Choose what the field is used to display, available choices are Bitmap, Icon, Frame (outline) and Rectangle (solid). Note: Bitmap and Icon do not work with Win32s. Colour Chooses the color for frames and rectangles, available choices are Black, White, Grey and Etched. Note: The actual color used for grey' depends on what has been chosen in Control Panel. It will always be a darker shade of the color used for the dialog background. See also Border properties.

Group Box Fields


These are an etched rectangle which also displays a label. They are typically used to visually group fields together within a dialog. General ID The identifier which will be used to refer to the field in your program. To change the identifier either enter a new name or select an existing name from the list. It is not possible for two fields in the same dialog to have the same identifier. The list of identifier names will not show identifiers that have already been used in the current dialog. Caption The text that is displayed at the top of the group box. It is possible to underline a character within the text by prefixing it with an &. Pressing Alt and the underlined character can then be used to move to the next entry field after the group box.

34

Winteracter Starter Kit

Group Box Fields


X Pos The position of the left-hand edge of the field in dialog units. Y Pos The position of the top edge of the field in dialog units. Width The width of the field in dialog units. Height The height of the field in dialog units. Disabled Causes the field to be displayed greyed-out This also disables any Alt+letter combination (see Caption, above).. Note: It is not possible to move into group box fields even when they are not disabled. Group Indicates that the field is the start of a new group. Style Alignment Determines the positioning of the label part of the field. Available options are: Left, Centre and Right. Picture Specifies whether a bitmap/icon is displayed in the label part of the field instead of text. For this to work the field should be given the same identifier as the bitmap or icon. This feature is not available under Win32s, where the text caption will be displayed instead. Flat Causes the field to have a flat, rather than 3D, appearance. See also Border properties.
Winteracter Starter Kit

35

Chapter 5

DialogEd - Dialog Resource Editor

String Fields
General ID The identifier which will be used to refer to the field in your program. To change the identifier either enter a new name or select an existing name from the list. It is not possible for two fields in the same dialog to have the same identifier. The list of identifier names will not show identifiers that have already been used in the current dialog. Contents The default value for the field (if any). X Pos The position of the left-hand edge of the field in dialog units. Y Pos The position of the top edge of the field in dialog units. Width The width of the field in dialog units. Height The height of the field in dialog units. Disabled Causes the field to be displayed greyed-out. It will not be possible to move into the field. Group Indicates that the field is the start of a new group. Tabstop Indicates that the user can move the cursor into this field using the Tab key. Style Alignment Controls the justification of text within the field. Available options are Left, Centre and Right. Centre/Right alignment requires Multi-Line to be selected. This is applied automatically and the multi-line field is then greyed out. Where Multi- Line is enabled, the field can still be restricted to a single line by ensuring that it is only tall enough to accept a single line and that vertical scrolling is not enabled.

36

Winteracter Starter Kit

Push Button Fields


Password Displays * characters instead of the contents. This can only be used on fields which do not have a the Multiline style enabled. Since center and right alignment require the Multiline style, the password style can only be used with left aligned non-multiline fields. DialogEd will automatically disable the password style if center/right alignment and/or multiline styles are selected. Read Only Prevents modification of the field contents by the user. This should not be confused with disabled. It is possible to enter and scroll a read-only field. This is not possible with a disabled field. Multiline Specifies that more than one line of text can be entered into the field. Note the field must be tall enough or have vertical scrolling capabitlities. As noted above, this style is also required for center/right alignment. Enabling this style will also disable a password style, if enabled. Want Return Specifies that pressing Return starts a new line in a multiline field. Normally pressing Return would select the default push-button. Scrolling Auto Horizontal Scroll: Causes the field to scroll automatically when the field reaches the edge of the visible field. Horizontal Scrollbar: Displays a scrollbar at the bottom of the field which the user can use to scroll the field horizontally. Auto Vertical Scroll: Causes a multiline field to scroll vertically when the cursor reaches the top or bottom of the visible field. Vertical Scrollbar: Displays a scrollbar at the right of the field which the user can use to scroll the field vertically. Case Conversion Controls conversion of the text to upper/lower case. Available options are: None, Uppercase, Lowercase. See also Border properties.

Push Button Fields


These are buttons which can be pressed by clicking them with the mouse. They are generally used to close the dialog and/or select further options.
Winteracter Starter Kit

37

Chapter 5

DialogEd - Dialog Resource Editor


General ID The identifier which will be used to refer to the field in your program. To change the identifier either enter a new name or select an existing name from the list. It is not possible for two fields in the same dialog to have the same identifier. The list of identifier names will not show identifiers that have already been used in the current dialog. It is recommended that the pre-defined identifiers IDOK and IDCANCEL are used with the corresponding buttons. These are automatically assigned to the first two buttons created in a dialog by DialogEd. Other common button identifiers are also defined in WINPARAM.H and the WINTERACTER module (e.g. IDABORT). Caption The text used to label the button. It is possible to underline a character within the text by prefixing it with an & symbol. Pressing Alt and the underlined character will then have the same effect as selecting the push-button. X Pos The position of the left-hand edge of the field in dialog units. Y Pos The position of the top edge of the field in dialog units. Width The width of the field in dialog units. Height The height of the field in dialog units. Disabled The button will be displayed greyed-out. It will not be selectable. Group Indicates that the field is the start of a new group. Tabstop Indicates that the user can move the cursor into this field using the Tab key. Style Horizontal Alignment Controls how the button's caption is positioned horizontally. Available options are: Default, Left, Centre, Right.

38

Winteracter Starter Kit

Check Box Fields


Vertical Alignment Controls how the button's caption is positioned vertically. Available options are: Default, Top, Centre, Bottom. Default Makes the push button the default, i.e. the button that will be chosen if the user presses Enter. Picture Specifies whether a bitmap/icon is displayed instead of a text caption. The field should be given the same identifier as the bitmap or icon. This feature is not available under Win32s, where the text caption will be displayed instead. Multi-Line Allows the text caption to wrap onto more than one line if it does not fit horizontally and the button is tall enough. Flat Causes the button to be drawn as 2D, rather than 3D. See also Border properties.

Check Box Fields


These are a labelled box which can either be empty or checked. They are good for entering yes/no choices. General ID The identifier which will be used to refer to the field in your program. To change the identifier either enter a new name or select an existing name from the list. It is not possible for two fields in the same dialog to have the same identifier. The list of identifier names will not show identifiers that have already been used in the current dialog. Caption The text used to label the check box. It is possible to underline a character within the text by prefixing it with an & symbol. Pressing Alt and the underlined character can then be used to toggle the check box. Initial State Indicates the initial state for the check box, either cleared or checked.
Winteracter Starter Kit

39

Chapter 5

DialogEd - Dialog Resource Editor


X Pos The position of the left-hand edge of the field in dialog units. Y Pos The position of the top edge of the field in dialog units. Width The width of the field in dialog units. Height The height of the field in dialog units. Disabled Causes the check box to be displayed greyed-out. It will not be possible to change the state of the check box. Group Indicates that the field is the start of a new group. Tabstop Indicates that the user can move the cursor into this field using the Tab key. Style Horizontal Alignment Controls how the check box's caption is positioned horizontally within the caption area. Available options are: Default, Left, Centre, Right. Vertical Alignment Controls how the checkbox's caption is positioned vertically. Available options are: Default, Top, Centre, Bottom. Picture Specifies whether a bitmap/icon is displayed instead of a text caption. For this to work the field should be given the same identifier as the bitmap or icon. This feature is not available under Win32s, where the text caption will be displayed instead. Multi-Line Allows the text caption to wrap onto more than one line if it does not fit horizontally and the button is tall enough.

40

Winteracter Starter Kit

Radio Button Fields


Push-Like Causes the check-box to resemble a push button. It becomes recessed instead of displaying a check mark. Note: This only works with Windows 4. The check box will appear normal with Windows 3.x. Flat Causes the check box to be drawn as 2D, rather than 3D. Text Left Causes the field's caption to appear to the left of the checkbox, rather than to the right. This is separate from the horizontal alignment. See also Border properties.

Radio Button Fields


These are similar to check-boxes, but once a radio button is selected it remains selected until another radio button in the same group is selected. They are useful for choosing between a small number of mutually exclusive options. General ID The identifier to be used to refer to the field in your program. To change the identifier enter a new name or select an existing name from the list. Two fields in the same dialog may not have the same identifier. The list of identifier names will not show identifiers that have already been used in the current dialog. Caption The text used to label the radio button. It is possible to underline a character within the text by prefixing it with an & symbol. Pressing Alt and the underlined character can then be used to select the radio button. Initial State Indicates the initial state for the radio button, either cleared or checked. X Pos The position of the left-hand edge of the field in dialog units. Y Pos The position of the top edge of the field in dialog units. Width The width of the field in dialog units.
Winteracter Starter Kit

41

Chapter 5

DialogEd - Dialog Resource Editor


Height The height of the field in dialog units. Disabled Causes the radio button to be displayed greyed-out, it will not be possible to select the button. Group Indicates that the field is the start of a new group. This is used to create a set of mutually exclusive radio buttons. This should be checked for the first radio button in the group, cleared for all other radio buttons in the same group and checked for the first field (of whatever type) after the radio buttons. DialogEd will check this option by default if the previously created field was not a radiobutton and clear it if the previous field was a radio button. Tabstop Indicates that the user can move the cursor into this field using the Tab key. Style Horizontal Alignment Controls how the radio button's caption is positioned horizontally within the caption area. Available options are: Default, Left, Centre, Right. Vertical Alignment Controls how the radio button's caption is positioned vertically. Available options are: Default, Top, Centre, Bottom. Picture Specifies whether a bitmap/icon is displayed instead of a text caption. The field should be given the same identifier as the bitmap or icon. This feature is not available under Win32s, where the text caption will be displayed instead. Multi-Line Allows the text caption to wrap onto more than one line if it does not fit horizontally and the button is tall enough. Push-Like Causes the radio button to resemble a push button, it becomes recessed instead of displaying a check mark. Note : this only works with Windows 4. The radio button will appear normal with Windows 3.x. Flat Causes the radio button to be drawn as 2D, rather than 3D.

42

Winteracter Starter Kit

Menu Fields
Text Left Causes the field's caption to appear to the left of the radio button, rather than to the right. This is separate from the horizontal alignment. See also Border properties.

Menu Fields
Menu fields allow a user to choose from a number of options. They should not be confused with the menu resources created by MenuEd. General ID The identifier to be used to refer to the field in your program. To change the identifier enter a new name or select an existing name from the list. Two fields in the same dialog may not have the same identifier. The list of identifier names will not show identifiers that have already been used in the current dialog. X Pos The position of the left-hand edge of the field in dialog units. Y Pos The position of the top edge of the field in dialog units. Width The width of the field in dialog units. Height The height of the field in dialog units. For drop down and drop down list combo boxes this specifies the height when the list of options is made visible by the user, the non-dropped height is fixed. Selection The number of the initially selected option. For drop down and simple combo boxes this may be zero to indicate none. For these field types a second field is available in which to enter an initial value which will be used when the numeric selection is zero. Options Enter the text string for each option, one option per line.
Winteracter Starter Kit

43

Chapter 5

DialogEd - Dialog Resource Editor


Style Type Simple Combo Box : This consists of a string field (into which any value may be typed by the user) and a list of pre-set options. Drop Down Combo Box : This also consists of a string field and list of options, except that the list is hidden until the user displays it using the button at the right of the string field. Drop Down List Combo Box : This is similar to the Drop Down Combo Box except that only the listed options may be chosen. List box: This is a simple, permanently visible list. Scrolling Vertical Scrollbar: Indicates that a vertical scrollbar will be displayed when the field is not tall enough to display all the options at once. Disabled Scrollbar: Indicates that the vertical scrollbar will appear (but disabled) even when the field is tall enough to display all the options. See also Border properties.

Border Properites
This controls the style of border drawn around a field. In general it is recommended that you accept the default border style for fields. This will result in an appearance that is consistent with other Windows applications. However changing the border style is a good way to make a particular field stand out. It is best to just experiment with the border style combinations until you find an effect that you like. The sunken style is only available for Label and Picture/ Frame fields. Note: Some field types are always drawn with a border that cannot be removed.

View Options
Docked Field Insertion Toolbar This displays the Field Insertion Toolbar docked at the top of the main window. Floating Field Insertion Toolbar This displays the Field Insertion Toolbar as a moveable dialog. Field Alignment Toolbar This displays the Field Alignment Toolbar docked at the top of the main window.

44

Winteracter Starter Kit

View Options
Identifier Names This option displays a list of all of the identifier names defined in the current resource script. Picture List This option displays a list of the identifiers of all bitmap and icon resources in the current resource script. Preferences This option selects various information about how DialogEd saves data and the numeric values used to identify fields. The Preference dialog will be displayed. The preferences displayed in this dialog will be saved in the resource script and re-used when the script is next loaded by DialogEd or MenuEd. The Symbol Header File field selects the name of the Fortran 90 module or include file that the Save option produces. This file lists the symbolic identifiers for dialogs and fields as PARAMETER statements. If this field is left blank then the Fortran file will have the same name as the resource script but with a .F90 or .INC extension. The Symbol Header File Type radio buttons are used to determine whether the save option produces a Fortran 90 module file or a Fortran include file. The F90 Module Name field is used to set the module name of the Fortran 90 module created by Save. This can be any valid Fortran 90 module name up to 31 characters long and must not contain spaces. If the Symbol Header File Type is set to a Fortran include file this value is ignored. The Base Dialog Value is used to set the numeric value to start assigning dialog identifier values from. We recommend that Winteracter programmers use the symbolic identifiers to reference their dialogs and that this value should only be changed if it causes clashes with values in other resource scripts that your program uses. The Base Field Value is used to set the numeric value to start assigning field identifiers from. We recommend use of symbolic identifiers to reference fields and that this value should only be changed if it causes clashes with values in other resource scripts that a program uses. Grid This option toggles the grid on and off. When the grid is visible, moving and resizing fields using the mouse will snap to the grid. The size of the grid is 2x4 dialog units. By default the grid is on.
Winteracter Starter Kit

45

Chapter 5

DialogEd - Dialog Resource Editor

Using Bitmaps and Icons in Dialogs


Both bitmaps and icons can be added to a resource script. It is then possible for these pictures to be used by Picture/Frame, Group Box, Push Button, Checkbox and Radio Button fields. Once incorporated into your resource script a single picture can be used in any number of dialogs. Because bitmaps and icons are built into your executable, as for other resource types, there is no need to distribute the .BMP/.ICO file with your application. (Note that bitmaps and icons cannot be displayed in dialogs under Win32s.) Bitmaps and icons are added to a resource using File->Import Picture. After a file has been selected, you will be prompted for an identifier for the picture. This identifier is used to link the picture to a field. In general you should give the picture the same identifier as the field that will display it. However if you intend to assign the picture to the field at run time (using WDialogPutImage) then any identifier may be used. The type of picture, if any, to display is set using the field's Style Properties dialog. Note that DialogEd does not display the actual picture. Instead it uses a dummy bitmap/icon. The actual bitmap/icon will only be used at run time. If you intend to use the same picture in more than one dialog then it is recommended that you use the same field identifier in each dialog. This will avoid having multiple copies of the picture file built into your executable.

Creating Your First Dialog Resource.


This brief tutorial is intended to help you construct and use your first DialogEd dialog resource. For more information about individual options see the earlier sections in this chapter. 1. Initially, DialogEd presents you with an empty main window. To start a new resource file select New from the File menu. You will then be prompted for the properties of the first dialog in the resource. For now just accept the defaults, they can be changed later if necessary. Once you click OK an empty window will appear inside the main window. This represents your new dialog. The buttons at the top of the main window are now enabled. These buttons constitute the Field Insertion Toolbar and are used to add new fields to your dialog. 2. Now that we have a dialog we can create some fields inside it. First we will create the simplest type of field - a label. Click on the 'Label' button then click inside the window representing your dialog - don't worry too much about exact positioning just yet. The field is created with the default contents 'label'. Let's change this to something more meaningful. Right click on the field to bring up a small floating menu.

46

Winteracter Starter Kit

Creating Your First Dialog Resource.


Select General from this menu. This will display a dialog showing the general properties of the field. For now just move to the caption field and enter something more meaningful, then click OK. 3. Now that you have changed the caption of the label field it is likely that it is no longer big enough to display the text. To fix this, change the field's size by dragging the border of the field just as if it was a program window. Dragging within the field will move the field to a new position. Notice that the field's size and position snaps to the grid. 4. If the next field we wanted to create was a label then we could simply click in an empty region of the dialog again. However we will now create an entry field. Select the 'String' button from the toolbar and click somewhere to the right of your label. Notice that the thick border is removed from the label and placed around the string field, indicating that this is currently selected. 5. At this point we can test the dialog by selecting Test from the Dialog menu. This will allow you to type into your newly created string field. Press Esc or Enter when done. 6. While this dialog worked, having to use the keyboard to close it was not very Windows-like. Let's create OK and Cancel buttons. Do this by selecting the 'Push Button' button and clicking twice in the dialog window where you wish the buttons to appear. Notice that the captions on the buttons are automatically set to 'OK' and 'Cancel'. They are also assigned the standard identifiers IDOK and IDCANCEL. This is done for the first two buttons in every dialog. Also note that the first button (OK) was automatically made the default push button (as indicated by its different frame style). You may now wish to test your dialog again to see the improved effect 7. To save your dialog, click on the File option on the main menu and then the Save option. This will display the standard Windows file selector. Enter a file name (e.g. dialog.rc) and click OK. You now have a resource script which can be compiled and linked with your Winteracter program code, as described earlier. The resource file format is described in detail in the next chapter. See the Dialog Management chapter for more information about using dialog resources within Winteracter programs.

Winteracter Starter Kit

47

Chapter 5

DialogEd - Dialog Resource Editor

48

Winteracter Starter Kit

Resource File Format

Winteracter uses standard Windows resource files to define menus, dialogs, icons and string tables. The format of these resource files are defined by Microsoft. However, as with most aspects of Windows programming they represent a moving target. The precise definition of a 'standard' resource file is therefore ambiguous. This chapter attempts to define the resource format which MenuEd and DialogEd generate along with any limitations which Winteracter imposes on resource file contents. In general there should be little need to edit resource files directly, but this information is provided for the benefit of more advanced users. Resource files which define accelerators or dialogs must #include a header file called winparam.h which is installed in the \wint\include directory. This location can be specified on the resource compiler command line or via the INCLUDE environment variable. The Winteracter visual editors, MenuEd and DialogEd save resources in a common order, as listed below. Whilst this is not a requirement, it ensures consistent resource file layout. Header comment #include statements #define statements Dialogs Dialog RCDATA Menus Menu RCDATA Accelerators Bitmaps Icons String table Preferences (stored as comments)
Winteracter Starter Kit

49

Chapter 6

Resource File Format


When the visual editors load and save a manually edited resource or a resource created in another environment, they will automatically remove any data which is not supported by Winteracter.

Menus
A MENU resource structure is a collection of information that defines the appearance and function of an application menu. The MENU statement

Syntax
menuID MENU BEGIN item definitions list END

Where, menuID is a value that identifies the menu. This can be a string or a positive integer value. Commonly this value is assigned a symbolic name. This is the value that needs to be passed to WindowOpen to identify the menu you wish to use. The item definitions list contains the actual data that will be used to display/report back information to/from your application menus. The data must be enclosed within a pair of BEGIN and END statements. This data is split into 2 types, MENUITEM's and POPUP's. The MENUITEM statement

Syntax
MENUITEM text, itemID, [optionlist]

or
MENUITEM SEPARATOR

Where text is a string that contains the actual information that will be placed onto the application menu. The string must be contained within a pair of double quotes. The ampersand (&) character can be used to underline and determine the character used as a shortcut (using the Alt keys) to the menu item. There are also two special escape characters, \a and \t. The \a character aligns all following text to the right of the menu bar. The \t character inserts a tab character into the menu. The itemID is a value that identifies the menu item. This must be an integer value. Commonly this value is assigned a symbolic name. This is the value that will be returned by WMessage to identify a selected item.

50

Winteracter Starter Kit

Menus
The optionlist parameter is a set of characteristics that alter the appearance of the menu item. There are several options available, but Winteracter and the MenuEd resource editor only use the CHECKED and GRAYED options. The CHECKED option puts a tick mark next to the item and the GRAYED item displays the item in a grey or lighter color and disables the item. See WMenuGetState/WMenuSetState for more information. The special keyword SEPARATOR can also be used to place a horizontal or vertical bar on the menu. This item cannot be selected by the user, so no identifier is required. The POPUP statement

Syntax
POPUP text, [optionlist] BEGIN item definitions list END

Where text is a string that contains the actual information that will be placed onto the application menu. The string must be contained within a pair of double quotes. The ampersand (&) character can be used to underline and determine the character used as a shortcut (using the Alt keys) to the menu item. The optionlist parameter is a set of characteristics that alter the appearance of the menu item. There are several options available but Winteracter and the MenuEd resource editor only use the CHECKED and GRAYED options. The CHECKED option puts a tick mark next to the item and the GRAYED item displays the item in a grey or lighter color and disables the item. The item definitions list contains more data that will be displayed in a popup submenu related to the POPUP item. This must be enclosed in a pair of BEGIN and END statements. Numerous POPUP items can be nested within each other. The following is an example of a complete menu resource structure using MENU, MENUITEM and POPUP statements:

Winteracter Starter Kit

51

Chapter 6

Resource File Format


#define my_menu 30001 #define id_file_new 40001 #define id_file_open 40002 #define id_save_old 40003 #define id_save_new 40004 #define id_file_exit 40005 #define id_about 40006 my_menu MENU BEGIN POPUP "&File" BEGIN MENUITEM "&New", id_file_new MENUITEM SEPERATOR MENUITEM "&Open", id_file_open, GRAYED POPUP "&Save" BEGIN MENUITEM "&Old File", id_save_old MENUITEM "&New File", id_save_new, CHECKED END MENUITEM SEPERATOR MENUITEM "E&xit", id_file_exit END MENUITEM "&About", id_about END

Accelerators
Accelerators are keyboard codes which provide immediate access to a specfied menu option.

Syntax
menuID ACCELERATORS BEGIN event, itemID, [type] [options] END

Where, menuID is the name or integer value that identifies the resource. This should be the same as the menu which the accelerator table belongs to. Commonly this value is assigned a symbolic name. The event parameter is a keystroke to be used as the accelerator. It can either be a single ASCII character enclosed in quotes or a integer/symbolic value that represents a virtual key. The itemID parameter is an integer id/symbolic name that can be used to identify the accelerator. This will be reported back via WMessage when the key is selected. This will normally be associated with a menu item id so that the key can be used as a shortcut to a particular menu item.

52

Winteracter Starter Kit

Dialogs
The type parameter is used to specify the type of accelerator. It can either be ASCII for characters or VIRTKEY for virtual keys. The options list can be one or more of the following values: ALT, SHIFT and CONTROL can be used alone or in combination to select which modifier keys to use with the accelerator key. The following is an example of an accelerator table. Notice how it associates various keys with items from the previous menu resource.
my_menu ACCELERATORS BEGIN VK_F1 ,id_file_new ,VIRTKEY,ALT ; VK_F2 ,id_file_open,VIRTKEY,SHIFT ; "X" ,id_file_exit,VIRTKEY,CONTROL; "S" ,id_save_old ,ASCII ,ALT ; VK_TAB,key_select ,VIRTKEY ; "L" ,id_file_open,ASCII ; END

Alt/F1 selects File-New Shift/F2 selects File-Open Control/X selects File-Exit Alt/S selects File-Save-Old Non menu item accelerator L also selects id_file_open

Dialogs
A DIALOG resource is a collection of information that defines the appearance and fields of a dialog box.

Dialog Description
A dialog definition begins with a DIALOG statement:

Syntax
dialogID DIALOG xpos, ypos, width, height STYLE styles FONT font CAPTION "Title for dialog" BEGIN Field Defintions END

Where dialogID is a value that identifies the dialog. This is a positive integer value. Commonly this value is assigned a symbolic name. This is the value that needs to be passed to WDialogLoad or WDialogSelect to identify the dialog. xpos and ypos are ignored by Winteracter. Simply specify 0 for these values. width and height specify the size of the dialog in 'dialog units'. These are defined by Windows as a quarter of the average character width and an eighth of the height.
Winteracter Starter Kit

53

Chapter 6

Resource File Format


The style statement specifies the dialog's appearance, using one or more symbolic names (defined in winparam.h) separated by the | character. Allowable names are: WS_POPUP WS_CHILD WS_CLIPSIBLINGS WS_CAPTION WS_BORDER WS_SYSMENU WS_THICKFRAME WS_MINIMIZEBOX DS_MODALFRAME DS_3DLOOK Creates a popup dialog Creates a child dialog ) Specify only ) one of these

Should always be used when WS_CHILD is specified Specifies that the dialog has a title bar Draws a thin border around the dialog Specifies that the dialog has a system menu in its title bar Allows resizing of the dialog - not recommended Allows the dialog to be minimized Draws a 'normal' dialog frame Gives a 3D look under Windows 4 - strongly recommended

The FONT statement specifies the font to be used for the dialog, if this statement is omitted then the system proportional font will be used. In general, use of the following font statement is recommended:
FONT 8, "MS Sans Serif"

The caption statement specifies the text that will be displayed in the dialog's title bar. This is only applicable if the WS_CAPTION style is specified.

Field Descriptions
A field definition consists of a CONTROL statement. A complete dialog description consists of up to 255 of these statements.

Syntax
CONTROL text, fieldID, class, style, xpos, ypos, width, height[, extended-style]

This should be entered on a single line. text is a string that specifies the actual information that will be displayed in appropriate field types. It should be enclosed in double quotes. fieldID is a positive integer value that identifies the field. This will usually be a symbolic name rather than a number.

54

Winteracter Starter Kit

Supported Field Types


class specifies the Windows control class on which the field is based. In some cases this is combined with the style to determine the exact field type created. See the next section for details of how to specify each of the supported field types. The class name should be enclosed in double quotes. Supported classes are:
STATIC EDIT BUTTON COMBOBOX LISTBOX

style controls the cosmetic appearance of the field and also subdivides some of the basic control classes into different field types. The style parameter consists of one or more symbolic names (defined in winparam.h) separated by the | character.The following styles must be applied to all field types : WS_CHILD WS_VISIBLE The field belongs to this dialog. The field is visible.

The following styles can optionally be applied to all field types (other field-type specific styles are described in the next section): WS_DISABLED WS_BORDER WS_GROUP WS_TABSTOP Disables the field. Greys it out and prevents modification Gives the field a border Specifies that the field is the start of a new group Allows the user to reach the field using the Tab key. Recommended for all editable fields

The position of the top left of the field, in dialog units, is determined by xpos and ypos, and the size by width and height. As noted earlier, dialog units are defined by Windows as a quarter of the average character width and an eighth of the height. extended-style specifies additional style information. For the purposes of Winteracter it specifies special border styles for the field. Any or none of the following values may be specified: WS_EX_CLIENTEDGE WS_EX_STATICEDGE WS_EX_DLGMODALFRAME Gives a sunken effect Gives a less pronounced sunken effect Gives a raised effect.

Supported Field Types


The type of field created by a CONTROL statement is determined by the class and style elements. This section describes the combinations needed to create each of the field types supported by Winteracter.
Winteracter Starter Kit

55

Chapter 6

Resource File Format


Label This field type is created using a class value of STATIC. One of the following should be used in the style parameter: SS_LEFT SS_CENTER SS_RIGHT Left aligns the text within the label. Centers the text within the label. Right aligns the text within the label.

In addition any or none of the following style settings can also be applied: SS_NOPREFIX SS_SIMPLE SS_SUNKEN Displays & characters, rather than underlining the next character. Disables word wrap. Gives a sunken appearance to the field.

Example
CONTROL "Label Text",IDF_LABEL1,"STATIC", WS_CHILD | WS_VISIBLE | SS_LEFT, 10,10,80,12

Picture/Frame This field type is created using a class value of STATIC. One of the following should be specified in the style parameter: SS_BITMAP SS_ICON SS_BLACKRECT SS_GRAYRECT Specifies that the field displays the bitmap that has the same identifier as the field. Specifies that the field displays the icon that has the same identifier as the field. Displays a solid black rectangle. Displays a solid rectangle, in a darker shade of the same color that is used by the dialog background, normally grey. Displays a solid white rectangle. Displays a black outline frame. Displays a grey outline frame. Displays a white outline frame. Displays an etched outline frame.

SS_WHITERECT SS_BLACKFRAME SS_GRAYFRAME SS_WHITEFRAME SS_ETCHEDFRAME

In addition any or none of the following style settings can also be applied:

56

Winteracter Starter Kit

Supported Field Types


SS_CENTERIMAGE SS_SUNKEN Centers the bitmap/icon (if any) within the field.Without this the field is resized to fit the image. Gives a sunken appearance to the field.

Example
CONTROL " ",IDF_PICTURE1,"STATIC", WS_CHILD | WS_VISIBLE | SS_BITMAP | SS_CENTERIMAGE, 10,10,80,40 IDF_PICTURE1 BITMAP DISCARDABLE "picture.bmp"

Group Box This field type is created using a class value of BUTTON in combination with a style value of BS_GROUPBOX. One of the following styles should also be used: BS_LEFT BS_RIGHT BS_CENTER Displays the text label at the left of the top edge. Displays the text label at the right of the top edge. Displays the text label in the center of the top edge.

In addition any or none ot the following style settings can also be applied: BS_FLAT BS_BITMAP BS_ICON Gives a 2D, rather than etched, appearance Displays the bitmap that has the same identifier as the field, instead of the specified text. Displays the icon that has the same identifier as the field, instead of the specified text.

Note that BS_BITMAP and BS_ICON are mutually exclusive. Only one of these may be applied.

Example
CONTROL "Group Description",IDF_GROUP1,"BUTTON", WS_CHILD | WS_VISIBLE | BS_GROUPBOX | BS_LEFT, 10,10,80,40

String This field type is created using a class value of EDIT. The following style values can be applied: WS_VSCROLL WS_HSCROLL ES_LEFT ES_CENTER Vertical scrollbar Horizontal scroll bar Left justifies text Centers text ) ) ) Multiline strings only )
Winteracter Starter Kit

57

Chapter 6

Resource File Format


ES_RIGHT ES_MULTILINE ES_UPPERCASE ES_LOWERCASE ES_PASSWORD ES_AUTOVSCROLL ES_AUTOHSCROLL ES_READONLY ES_WANTRETURN Right justifies text )

Allows the entry of more than one line of text Converts entered text to uppercase Converts entered text to lowercase. Hides entered text and displays * characters instead. Automatically scroll vertically - multiline strings only. Automatically scroll horizontally. Allow entry to the field, but don't allow modification. Allows Enter to start a new line, rather than closing the dialog.

ES_MULTILINE must be specified if one of the alignment styles (ES_LEFT, ES_CENTER or ES_RIGHT) is specified. ES_PASSWORD can only be used if ES_MULTILINE is not specified. If alignment is not specified, fields are left justified.

Example
CONTROL "Initial Value",IDF_STRING1,"EDIT", WS_CHILD | WS_VISIBLE | WS_TABSTOP, 10,10,40,14

Push Button This field type is created using a class value of BUTTON, together with one of the following in the style parameter: BS_PUSHBUTTON BS_DEFPUSHBUTTON Creates a normal push button Creates a default push button, i.e. one that is selected when Enter is pressed.

In addition any or none of the following style settings can also be applied: BS_BITMAP BS_ICON BS_LEFT BS_RIGHT BS_CENTER BS_TOP Specifies that the button displays the bitmap that has the same identifier, rather than the specified text. Displays the icon that has the same identifier as the field, the same identifier, rather than the specified text. Left justifies the button's text. Right justifies the button's text. Centers the button's text horizontally. Displays the button's text at the top.

58

Winteracter Starter Kit

Supported Field Types


BS_BOTTOM BS_VCENTER BS_MULTILINE BS_FLAT Displays the button's text at the bottom. Centers the button's text vertically. Specifies that more than one line of text is displayed by the button. Displays a 2D, rather than 3D, button.

Note that BS_BITMAP and BS_ICON are mutually exclusive. Only one of these may be applied.

Example
CONTROL "OK",IDOK,"BUTTON", WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_DEFPUSHBUTTON, 10,10,20,14

Check Box This field type is created using a class value of BUTTON, together with the BS_AUTOCHECKBOX style. The following style values can be applied: BS_LEFTTEXT BS_BITMAP BS_ICON BS_LEFT BS_RIGHT BS_CENTER BS_TOP BS_BOTTOM BS_VCENTER BS_PUSHLIKE BS_MULTILINE BS_FLAT Displays the checkbox's text to the left of the box instead of to the right. Displays the bitmap that has the same identifier as the field, instead of the specified text. Displays the icon that has the same identifier as the field, the same identifier, rather than the specified text. Left justifies text within the label part. Right justifies text within the label part. Horizontally centers text within the label part. Displays the label text at the top of the label part. Displays the label text at the bottom of the label part. Vertically centers text within the label part. Draws the checkbox as a button that stays pushed. Specifies that the text can wrap onto more than one line. Gives the checkbox a 2D, rather than 3D, appearance.

Note that BS_BITMAP and BS_ICON are mutually exclusive. Only one of these may be applied.

Winteracter Starter Kit

59

Chapter 6

Resource File Format


Example
CONTROL "Checkbox Label",IDF_CHECK1,"BUTTON", WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_AUTOCHECKBOX, 10,10,20,14

Radio Button This field type is created using a class value of BUTTON, together with the BS_AUTORADIOBUTTON style. The first radio button in each group must specify WS_GROUP in it's style. Other radio buttons in the group must not specify WS_GROUP. Other styles are as for check boxes.

Example
CONTROL "Option 1",IDF_RADIO1,"BUTTON", WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_AUTORADIOBUTTON | WS_GROUP, 10,10,20,14 CONTROL "Option 2",IDF_RADIO1,"BUTTON", WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_AUTORADIOBUTTON, 10,20,20,14 CONTROL "Option 3",IDF_RADIO1,"BUTTON", WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_AUTORADIOBUTTON, 10,30,20,14

Menu This field type groups together two Windows control classes, COMBOBOX and LISTBOX. List-boxes should always have the LBS_HASSTRINGS style. Combo-boxes should always have the CBS_HASSTRINGS style, together with one of the following styles: CBS_SIMPLE CBS_DROPDOWN CBS_DROPDOWNLIST Allows entry of any value and always displays the list of defined options. Only allows selection of defined options. The list must be displayed by the user. Allows entry of any value. The list of defined options must be displayed by the user.

For list-boxes the following style values also apply: WS_VSCROLL LBS_DISABLENOSCROLL LBS_NOTIFY LBS_USETABSTOPS Displays vertical scrollbar when required. Displays a vertical scrollbar even when all options are visible. Report value change immediately when FieldChanged message reporting is enabled. Allow tab characters to place sub-strings at tab-stops

60

Winteracter Starter Kit

User-defined Dialog Data


For combo-boxes the following style values also apply: WS_VSCROLL CBS_AUTOHSCROLL CBS_DISABLENOSCROLL CBS_UPPERCASE CBS_LOWERCASE Displays vertical scrollbar when required. Automatically scrolls the editable part horizontally. Displays a vertical scrollbar even when all options are visible. Converts option strings and entered text to uppercase. Converts option strings and entered text to lowercase.

See also the following section on User-defined Dialog Data, where menu field contents can optionally be defined.

Example
CONTROL " ",IDF_MENU1,"LISTBOX", WS_CHILD | WS_VISIBLE | WS_TABSTOP | WS_VSCROLL, 10,10,20,30

User-defined Dialog Data


The standard Windows format for field definitions does not allow for all types of field to be fully initialized. This information must therefore be provided to Winteracter via the userdefined data section of a resource file, known as an RCDATA resource. If a dialog contains fields which cannot be fully initialized as part of the corresponding CONTROL statement then an RCDATA resource should be created with the same identifier. Field identifiers must be specified as numbers, not symbolic names within the RCDATA resource.

Syntax
dialogID RCDATA BEGIN data END

Each line of the data section should be followed by <space>\n and enclosed in double quotes, the last line should be followed by ,0 e.g.:
"This is a normal line \n" "This is the last line ",0

The RCDATA resource is divided into the following sections:


[Checks]

Winteracter Starter Kit

61

Chapter 6

Resource File Format


This section is used to specify the initial state of check-boxes and radio buttons. Each line has the following format:
fieldID onoff

where fieldID is the identifier of the field and onoff is 0 for unchecked and 1 for checked.
[Menus]

This section is used to specify the option strings and initial selection of menu fields, each menu has a header of the following format:
fieldID noptions ioption

followed by an appropriate number of lines for the option strings. The number of options is specified by noptions and the initial selection by ioption. This may be 0 for comboboxes. Example RCDATA resource
IDD_DIALOG01 RCDATA BEGIN "[Checks] \n" "1001 1 \n" "1002 0 \n" "1003 1 \n" "[Menus] \n" "1021 4 1 \n" "Option 1 \n" "Option 2 \n" "Option 3 \n" "Option 4 ",0 END

Bitmaps
The BITMAP resource statement specifies a bitmap (.bmp) file.

Syntax
name BITMAP DISCARDABLE filename

Where name specifies a unique name or integer value identifying the resource. The filename specifies the name of the bitmap file that contains the resource. The name must be a valid filename. It must be a full path if the file is not in the current working directory. The path can either be a quoted or non-quoted string.

62

Winteracter Starter Kit

Icons
The following is an example BITMAP resource:
IBMP1 BITMAP DISCARDABLE "c:\\resource\\mybitmap.bmp"

Icons
The ICON resource statement specifies an icon file which defines the shape of an icon.

Syntax
name ICON DISCARDABLE filename

Where name specifies a unique name or integer value identifying the resource. The program icon must always be called ICON1. The filename specifies the name of the bitmap file that contains the resource. The name must be a valid filename. It must be a full path if the file is not in the current working directory. The path can either be a quoted or non-quoted string. Icon resources can contain more than one image. The following is an example ICON resource:
ICON1 ICON DISCARDABLE "c:\\resource\\myicon.ico"

String Table
The STRINGTABLE resource statement defines strings to be used by the file selector.

Syntax
STRINGTABLE BEGIN stringID "string" END

Where stringID specifies either a unique name or integer value identifying the string. This is followed by the string itself in double quotes. The following is an example STRINGTABLE resource for a file selector :
STRINGTABLE BEGIN 1001 "Windows bitmap|*.bmp|Paintbrush image|*.pcx|" 1002 "Data file|*.dat|" END

Winteracter Starter Kit

63

Chapter 6

Resource File Format

64

Winteracter Starter Kit

Error Codes

The following error values are set by various Winteracter routines and are returned by the error information function InfoError. The listed symbolic names are all defined in the WINTERACTER module. Table 1: Winteracter Error Codes
Name ErrFileOpen ErrFileIO ErrFileClose ErrLargeNum ErrNoSubstring ErrBadChar ErrBadUnits No. 1 2 3 4 10 12 16 Description

Error opening a file. Error reading from a file. Error closing a file or device. Number too large in string-to-numeric conversion. No substring found. Invalid character detected.
X or Y graphics unit range is invalid. Default of 0-1 used.

ErrNumToStr ErrBadRadius ErrBadColor

18 20 42

Numeric to string conversion error. String filled with *'s. Radius of a circle is <= zero. Unknown color name or number specified to IGrColourN. Current color remains unchanged. Invalid X and/or Y range specified to IGrArea. reset to 0-1. Fill too complex in IGrPolygonComplex. Range

ErrBadArea ErrFillComplex

44 49

Winteracter Starter Kit

65

Chapter 7

Error Codes
Table 1: Winteracter Error Codes
Name ErrNoSoftFont ErrMenuItem ErrLoadMenu ErrWinHandle ErrCommonDlg ErrCurDialog ErrFieldNum ErrLoadDialog ErrSelDialog ErrFieldUndefined ErrOptionNum ErrDialogType ErrImageNum ErrRootHidden No. Description

53 1001 1002 1003 1004 1005 1006 1007 1008 1010 1011 1014 1015 1016

Unable to find software font file in IGrCharOut to substitute for unavailable hardware font Invalid menu item Unable to load menu from resource Invalid window handle General error in common dialog No dialogs currently loaded Invalid field identifier Unable to load dialog from resource Unable to select specified dialog Field value undefined Option number out of range Invalid dialog type Invalid bitmap/icon identifier Attempt to open an 'inside-root' child window or show a child dialog when the root window is hidden

66

Winteracter Starter Kit

Subroutine Summary

Group WM: Window Management


WindowOpen WindowOpenChild WindowClose WindowCloseChild WindowSelect

Create root window with various style options Open a child window with various style options Close root window Close a child window Select window which all output is sent to

Group TX: Text Output


WindowOutString

Output string at XY co-ordinate

WindowStringLength Return the unit length of a string

Group CL: Area Clearing


WindowClear WindowClearArea

Clear window to background color Clear area to background color

Group FS: Font Selection


WindowFont

Set all text attributes

Group MH: Message Handling


WMessage WMessageEnable WMessagePeek

Wait until valid message arrives Enable/disable reporting of individual messages Get next message or return immediately
Winteracter Starter Kit

67

Chapter 8

Subroutine Summary

Group MN: Menu Handling


WMenuGetState WMenuRoot WMenuSetState WMenuSetString

Get a menu item state (checked/greyed) Activate/remove root menu Set a menu item state (checked/greyed) Change text for a given menu item

Group DM(1): General Dialog Management


WDialogHide WDialogLoad WDialogSelect WDialogShow WDialogUnload

Remove a dialog from the screen Load a dialog from resource Select current dialog Display a dialog Free dialog resource from memory

Group DM(2): Dialog Field Assignment/Retrieval


WDialogGetCheckBox Get check box value WDialogGetMenu Get menu field value WDialogGetRadioButton

Get radio-button group value


WDialogGetString Get string value WDialogPutCheckBox Enable/disable a check-box WDialogPutImage Change bitmap/icon displayed in a field WDialogPutMenu Change menu field contents WDialogPutOption Change menu field option number WDialogPutRadioButton WDialogPutString

Change radio-button group value Change a string field value

Group CD: Common Dialog Management


WMessageBox WSelectFile

Display standard message box with various options Get a load or save filename from a common dialog

Group GG: General Graphics


IGrArea IGrAreaClear IGrGetPixelRGB IGrInit IGrPause IGrUnits

Define size of graphics area Clear the current graphics screen area Get the a screen pixel value as an (r,g,b) triplet Re-initialize graphics output Start a new picture Define plotting units to be used

68

Winteracter Starter Kit

Group GS: Graphics Style Selection

Group GS: Graphics Style Selection


IGrColourN IGrFillPattern IGrLineType IGrPaletteInit IGrPaletteRGB

Select graphics color using a color number Define fill pattern (solid/stippled/hatched) Select line type (solid, dashes, etc.) Reinitialize graphics palette Redefine color palette using RGB color scheme

Group GD: Graphics Drawing Primitives


IGrCircle IGrLineTo IGrMoveTo IGrPoint IGrPolygonComplex

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

Group GC: Graphics Character Output


IGrCharJustify IGrCharLength IGrCharOut IGrCharSet IGrCharSize IGrCharSpacing

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

Group IF: Information


InfoError InfoGraphics InfoGrScreen WInfoDialog WInfoFont WInfoScreen WInfoWindow

Return error information Return real graphics mode information Return graphics facilities information (screen) Return dialog information Return information about current font Return screen size & available colors Return information about the current window

Group OS: Operating System Interface


IOsExitProgram IOsVariable

Abort program with an error message & error code Return the value of an environment variable

Group MI: Miscellaneous


WindowBell WInitialise

Sound the bell Initialize Winteracter


Winteracter Starter Kit

69

Chapter 8

Subroutine Summary

Group CH: Character Manipulation Routines


IActualLength IFillString IJustifyString ILocateChar ILocateString ILowerCase IntegerToString IStringToInteger IUpperCase

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

70

Winteracter Starter Kit

Window Handling

Group WM: Window Management


This group provides routines to open, select and close windows. Two types of windows are controlled by the routines in the group. The root (or 'parent') window should be opened first, using WindowOpen. Multiple child windows can then be opened/closed using WindowOpenChild and WindowCloseChild. When window processing is complete, the root window and all its child windows can be removed using WindowClose. After the initial call to WInitialise, multiple calls to WindowOpen/ WindowClose are allowed, provided these calls are paired. Windows opened by the routines in this group can be written to using the text output functions in the TX group. Graphics output is written to the same windows using the routines in the GG/GS/GD/GC groups. In both cases, WindowSelect determines which window has the output focus. This routine takes a window handle as an argument, which is obtained from the WindowOpen or WindowOpenChild routines. The same handle is used by WindowCloseChild, allowing child windows to be opened and closed in any sequence.

WindowClose Subroutine
Description
Close root window.

Syntax
WindowClose()
Winteracter Starter Kit

71

Chapter 9

Window Handling
Effect
Closes all opened windows, including the root window, freeing all resources and memory allocations. Winteracter internals remain initialized however, allowing WindowOpen to be called again without reinitialization via WInitialise.

Example
TYPE(WIN_STYLE):: MYWIN ! ! Set root window style in here ! CALL WInitialise(' ') CALL WindowOpen(MYWIN) CALL WindowClose CALL WindowOpen(MYWIN) CALL WindowClose ! Initialize Winteracter ! Open root window ! Close root window ! Re-open root window ! Close root window

WindowCloseChild Subroutine
Description
Close a child window

Syntax
WindowCloseChild(ihandle)

Arguments
INTEGER ihandle = Winteracter child window handle (1-20)

Effect
Closes the specified child window. The window handle must have been obtained by a call to WindowOpenChild. If the specified window handle is invalid, no action is taken. If the closed child window is also the current window (as set by WindowSelect or WindowOpenChild) the Winteracter output focus returns to the root window. If a child window is closed by the user, via the system menu, a message is sent to the program via WMessage/WMessagePeek. This message (type 9) returns the handle in the win member of the WIN_MESSAGE structure. The calling program is then responsible for closing the window by calling this routine.

72

Winteracter Starter Kit

WindowOpen Subroutine
Example
TYPE(WIN_STYLE) :: MYWIN : ! Set child window style in here : CALL WindowOpenChild(MYWIN,ICHILD1) CALL WindowOpenChild(MYWIN,ICHILD2) CALL WindowOpenChild(MYWIN,ICHILD3) : CALL WindowCloseChild(ICHILD2) CALL WindowCloseChild(ICHILD1) CALL WindowCloseChild(ICHILD3)

! Open child window 1 ! Open child window 2 ! Open child window 3 ! Close child window 2 ! Close child window 1 ! Close child window 3

Errors
ErrWinHandle (1003) Invalid window handle

WindowOpen Subroutine
Description
Open root window

Syntax
WindowOpen(wstyle)

Arguments
WIN_STYLE wstyle = Structure describing window style TYPE WIN_STYLE INTEGER flagsTitle bar buttons, etc. Sum of: SysMenuOn MinButton MaxButton MaxWindow InsideRoot (1) (2) (4) (8) (16) = System menu on title bar = Minimize button = Maximize button = Maximize window = Window inside root = Fixed size window (child windows only)

FixedSizeWin (64) HideRoot INTEGER x INTEGER y

(128) = Hidden root window Horizontal top corner of window in pixels (-1=center) Vertical top corner of window in pixels (-1=center)

Winteracter Starter Kit

73

Chapter 9

Window Handling
INTEGER width INTEGER height Width of window in pixels(<=0: 80% of screen width) Height of window in pixels(<=0: 80% of screen height)

INTEGER menuid Main horizontal menu ID (root window only) (0=none) CHAR(LEN=80) titleWindow title END TYPE WIN_STYLE

Effect
Opens the root window, with the specified style. Each call to WindowOpen must be paired with a call to WindowClose and cannot be nested. WindowOpen will: Create a new root window using the user supplied styles in wstyle. Terminate with a message box if a fatal error occurs. Display a menu given a valid menu id. Initialize any menu accelerators in the resource file. Initialize graphics output.

The flags element of the wstyle structure determines various window attributes: Presence of a system menu. Maximize/minimize buttons on the title bar. Maximize the window on open. Should the window be fixed in size. Window visibility

To assign values to wstyle%flags, sum the appropriate SysMenu, MinButton, MaxButton etc. parameters as defined in the WINTERACTER module. The InsideRoot parameter is only used when opening child windows (see WindowOpenChild). The HideRoot option causes the window to be created but not displayed, allowing applications to open floating child windows or pop-up dialogs without a visible root window. Child dialogs and 'inside-root' child windows are not available in this case. Hidden windows still exist, so they must be closed using WindowClose as normal. To center the window, specify a position of (-1,-1). If the width or height is less than or equal to 0, the approriate dimension is set to 80% of the screen size. Alternatively, WInfoScreen can be used to interrogate the total screen size to allow screen-specific position and size values to be calculated. If wstyle%menuid specifies a valid menu in the program resource, this will appear as the root window menu. Set this to zero if no root menu is required (e.g. for a program which relies solely on dialogs).

74

Winteracter Starter Kit

WindowOpenChild Subroutine
The window is given the specified title. Winteracter graphics routines are also initialized by calling IGrInit(' '). See the documentation for IGrInit for details of the initial state of the graphics system. Screen graphics become available to any output window, including child windows opened subsequently by WindowOpenChild. The actual size of the root window and the associated flags value can be obtained at any time after it has been opened via WInfoWindow. Note that this requires that the root window should have the current output focus (see WindowSelect).

Example
TYPE(WIN_STYLE) :: MYWIN INTEGER, PARAMETER :: ID_MENU : CALL WInitialise(' ') ! Window open settings MYWIN%FLAGS = SysMenuOn + & MinButton + & MaxButton MYWIN%X = -1 MYWIN%Y = 100 MYWIN%WIDTH = 0 MYWIN%HEIGHT = 250 MYWIN%MENUID = ID_MENU MYWIN%TITLE = 'Hello World' CALL WindowOpen(MYWIN) = 30001 ! Initialize Winteracter once ! ! ! ! ! ! ! ! ! ! Turn on system menu Minimize button on title bar Maximize button on title bar Center horizontally in the screen Put window 100 pixels down Make window 80% of screen width Make window 250 pixels deep Assign menu resource ID_MENU Window title Create root window

Sample resource script :


#define ID_FILE_EXIT 40001 #define ID_MENU 30001 ID_MENU MENU BEGIN POPUP "&File" BEGIN MENUITEM "E&xit", ID_FILE_EXIT END END

WindowOpenChild Subroutine
Description
Open child window
Winteracter Starter Kit

75

Chapter 9

Window Handling
Syntax
WindowOpen(wstyle,ihandle)

Arguments
WIN_STYLE wstyle = Structure describing window style (See WindowOpen) INTEGER ihandle = Returned window handle (1-20)

Effect
Opens a child window using the same structure as WindowOpen. This allows a standard style to be used for all program windows, if required. The menuid element is not used for child windows. A maximum of 20 child windows can be open at one time. A window handle is returned in ihandle which should be used in subsequent calls to WindowCloseChild or WindowSelect. If a window could not be created then ihandle will be returned as -1. The first child window to be opened receives handle 1. All subsequently opened windows have incremental values. Closing windows out of sequence will cause Winteracter to reuse the freed handles for subsequently opened windows. (Note: ihandle is a Winteracter handle, not a Windows API window handle.) wstyle has the same meaning as for WindowOpen, except that: a) InsideRoot is available as one of the wstyle%flags options. This determines the style of the child window. When InsideRoot is not specified, a child window can move anywhere on the screen. Its size and position should then be specified in screen (pixel) units, as for the root window. If InsideRoot is specified, the child window will be restricted to the root window. The window size and position are then specified in Winteracter window units (0-9999). b) HideRoot has no meaning when opening a child window and will be ignored. When a child window is opened it receives the current output focus and all subsequent output will go to this window until WindowSelect, WindowOpenChild or WindowCloseChild are called. As for the root window, the actual size of a child window and the specified flags value can be obtained at any time after it has been opened via WInfoWindow, provided it has the current output focus. If the root window is hidden (i.e. HideRoot was specified when the root window was opened), child windows must not specify InsideRoot as one of the wstyle%flags options. No window will be opened if InsideRoot is specified when the root window is hidden and an error code will be generated. The window handle will also be returned as -1.

76

Winteracter Starter Kit

WindowSelect Subroutine
Example
TYPE(WIN_STYLE) :: MYWIN : MYWIN%FLAGS = SysMenuOn + MinButton + MaxButton MYWIN%X = -1 MYWIN%Y = 100 MYWIN%WIDTH = 0 MYWIN%HEIGHT = 250 MYWIN%TITLE = 'Child 1' & & ! Turn on system menu ! Show minimize button ! Show maximize button ! Put window 100 pixels down

! Make window 250 pixels deep ! Create child window that exists ! outside of the main window CALL WindowOpenChild(MYWIN, IHAND1) ! Create child window that ! exists inside of main window ! Notice how we can re-use some of the settings from previous open MYWIN%FLAGS = MYWIN%FLAGS + & ! Keep old flags InsideRoot ! Child window inside root MYWIN%Y = 1000 ! Put window 1000 units down MYWIN%HEIGHT = 2500 ! Make window 2500 units deep MYWIN%TITLE = 'Child 2' CALL WindowOpenChild(MYWIN, IHAND2)

Errors
ErrRootHidden (1016) InsideRoot specified when root window is hidden

WindowSelect Subroutine
Description
Select a window

Syntax
WindowSelect(ihandle)

Arguments
INTEGER ihandle = Winteracter window handle (1-20 or 0 for root window)

Effect
Selects the window for all Winteracter text and graphics output. Handle 0 specifies the root window, otherwise, ihandle must have been returned by an earlier WindowOpenChild call. If ihandle specifies a non-existent window, no action is taken. Do not confuse the Winteracter output focus with the Windows input focus (i.e. the front window). Winteracter allows output to background windows while receiving input from whichever window has the input focus.
Winteracter Starter Kit

77

Chapter 9

Window Handling
This routine will also update the internal window size values used by the text output and graphics routines .

Example
TYPE(WIN_STYLE) :: MYWIN : MYWIN%X = 10 MYWIN%Y = 10 MYWIN%WIDTH = 250 MYWIN%HEIGHT = 250 MYWIN%TITLE = 'Root Window' CALL WindowOpen(MYWIN) ! Create root window MYWIN%Y = 300 MYWIN%TITLE = 'Child 1' CALL WindowOpenChild(MYWIN, IHAND1) ! Open child window 1 MYWIN%Y = 600 MYWIN%TITLE = 'Child 2' CALL WindowOpenChild(MYWIN, IHAND2) ! Open child window 2 CALL WindowSelect(0) ! Select root window CALL WindowOutString(1000,5000,'Root Window') CALL WindowSelect(IHAND2) ! Select child window 2 CALL WindowOutString(1000,5000,'Child Window 2') CALL WindowSelect(IHAND1) ! Select child window 1 CALL WindowOutString(1000,5000,'Child Window 1')

Errors
ErrWinHandle (1003) Invalid window handle

Group TX: Text Output


The routines in this group are used to write text to the currently selected output window. After calling WindowOpen, the root window has the initial output focus. When child windows have also been opened, the output window is determined by WindowOpenChild and WindowSelect. WindowOutString writes text at any position in a window. A co-ordinate system is used which is independent of window size. A window is treated as measuring 10000 units in width and height. All text (x,y) co-ordinates should therefore be in the range 0-9999 and are relative to the top left of the window. The length of a string can be measured in these units using the WindowStringLength function. [Note: Winteracter graphics use their own separate user defined co-ordinate system.] The style of text written here is determined by the Font Selection (FS) group.

78

Winteracter Starter Kit

WindowOutString Subroutine

WindowOutString Subroutine
Description
Write text to a window

Syntax
WindowOutString(ix,iy,string)

Arguments
INTEGER ix = Horizontal start position (0-9999) INTEGER iy = Vertical start position (0-9999) CHARACTER string = String to write

Effect
Outputs string to the currently selected window, starting at the specified window co-ordinate. Text which extends beyond the right edge of the window will be truncated.

Example
CALL WindowOutString(3000,5000,Mid window)

WindowStringLength Function
Description
Measure a string in window units

Syntax
INTEGER WindowStringLength(string)

Arguments
CHARACTER string = String to measure

Effect
Returns the length of the supplied string using the current font characteristics, in terms of Winteracter units for the current window.
Winteracter Starter Kit

79

Chapter 9

Window Handling
Example
CHARACTER(LEN=18) :: MESSAGE MESSAGE = 'Center this string' LENSTR = WindowStringLength(MESSAGE) IX = (10000-LENSTR)/2 CALL WindowOutString(IX,5000,STRING)

Group CL: Area Clearing


These routines allow all or part of the window to be cleared. In either case, the window area is cleared to the current background color as set by WindowFont. The default background color at initialization is TextWhiteBold (15).

WindowClear Subroutine
Description
Clear a window

Syntax
WindowClear()

Effect
Clears the whole of the current window to the currently selected background color.

Example
FONT%IBCOL = TextBlue CALL WindowFont(FONT) CALL WindowClear ! Clear to dark blue

WindowClearArea Subroutine
Description
Clear part of a window

Syntax
WindowClearArea(ixtopl,iytopl,ixbotr,iybotr)

80

Winteracter Starter Kit

Group FS: Font Selection


Arguments
INTEGER ixtopl = Top left corner x co-ordinate INTEGER iytopl = Top left corner y co-ordinate INTEGER ixbotr = Bottom right corner x co-ordinate INTEGER iybotr = Bottom right corner y co-ordinate

Effect
Clears the specified area of the current window to the currently selected background color.

Example
FONT%IBCOL = TextBlue CALL WindowFont(FONT) CALL WindowClearArea(0,5001,9999,9999) ! half window blue

Group FS: Font Selection


Displayed text can be modified using this group. Color can be selected as well as supporting highlights such as underlining, bold text and italics. WInitialise sets all attributes to 'off' and text colors to black on bold-white. The default font is System Proportional.

WindowFont Subroutine
Description
Select font and font attributes

Syntax
WindowFont(font)

Arguments
WIN_FONT font = Structure describing font characteristics TYPE WIN_FONT INTEGER ifontnum= Font number (0-6) INTEGER iwidth = Average font width

INTEGER iheight = Font height INTEGER ibold = Bold (0=no 1=yes)


Winteracter Starter Kit

81

Chapter 9

Window Handling
INTEGER italic = Italics (0=no 1=yes)

INTEGER iunder = Underlined (0=no 1=yes) INTEGER ifcol INTEGER ibcol END TYPE WIN_FONT Table 2: Font Numbers
Name Number Font

= Foregound color = Background color

SystemProp SystemFixed TimesNewRoman Swiss CourierNew Symbols Windgings

0 1 2 3 4 5 6

System Proportional System Fixed Times New Roman Arial Courier New Symbols Wingdings

Table 3: Text Color Numbers


Name TextBlack TextRed TextYellow TextGreen TextCyan TextBlue TextMagenta TextWhite No. 0 1 2 3 4 5 6 7 Color Name TextBlackBold TextRedBold TextYellowBold TextGreenBold TextCyanBold TextBlueBold TextMagentaBold TextWhiteBold No. 8 9 10 11 12 13 14 15 Color

Black Red Yellow Green Cyan Blue Magenta Off-white Leave unchanged

Dark gray Bold Red Bold Yellow Bold Green Bold Cyan Bold Blue Bold Magenta Bold White User defined fore/back color

NotSet

-1

TextUserColour

16

82

Winteracter Starter Kit

WindowFont Subroutine
Effect
Sets the characteristics of the font to be used in future calls to WindowOutString.The selected fonts have been chosen so as to ensure availability on virtually any Win32 based system. The System Proportional font is used by default. The System Proportional and System Fixed fonts are both fixed in size. Neither supports italics or bold attributes. System Fixed and Courier New are both monospaced fonts. All others are proportionally spaced. The iwidth and iheight elements set the font size in Winteracter units. Due to the limitations of Windows font selection mechanism, the size of the returned font cannot be guaranteed to exactly match the requested size. On exit WInfoFont can therefore be called to interrogate the actual returned font size. In general, Windows gives much greater priority to the specified height when selecting a font size. The default colors at initialization are black (0) on bold/white (15). Colors 0-7 are normal intensity. Colors 8-15 select equivalent bold/bright shades. If only one color needs to be specified, the other color should be set to -1. The current selection will remain in force in this case. A special value of 16 allows programs to select the user-specified window colors as set via Control Panel. Invalid color numbers are ignored.

Example
TYPE (WIN_FONT) :: FONT FONT%IFONTNUM = Swiss FONT%IWIDTH = 1000 FONT%IHEIGHT = 1500 FONT%IBOLD = 0 FONT%ITALIC = 0 FONT%IUNDER = 0 FONT%IFCOL = TextGreenBold FONT%IBCOL = TextBlack CALL WindowFont(FONT) FONT%ITALIC = 1 FONT%IUNDER = 1 CALL WindowFont(FONT) ! Swiss font family ! ! ! ! Large font size No bold No italic No underline

! Green on black text ! Italic on ! Underline on

Winteracter Starter Kit

83

Chapter 9

Window Handling

84

Winteracter Starter Kit

10 Input Handling

Group MH: Message Handling


The WMessage routine will be at the core of most Winteracter programs, reporting all forms of user input. It reports the main events which a Windows based program needs to know about including menu selections, key presses, mouse clicks, and so on. In Windows terminology these events are reported as 'messages', with associated information being returned at each event (e.g. the location of the mouse cursor when the user clicked a button). A typical Winteracter program will operate around a DO loop containing a WMessage call and a SELECT CASE statement which processes each type of message. WMessage is complemented by the alternative routine WMessagePeek. This performs exactly the same task, but does not block program execution if no messages are waiting to be processed. Since some message types may only be needed in certain applications or in particular parts of an application, reporting of specific message types can be individually enabled or disabled via WMessageSelect. This is a useful concept, borrowed from X-Windows, which is not normally available under Windows.

WMessage Subroutine
Description
Get next message.

Syntax
WMessage(itype,value)
Winteracter Starter Kit

85

Chapter 10

Input Handling
Arguments
INTEGER itype = The type of message that is returned: Table 4: Message types
Name no. Message type

KeyDown MenuSelect PushButton MouseButDown MouseButUp MouseMove Expose Resize CloseRequest FieldChanged BorderSelect

1 2 3 4 5 6 7 8 9 10 12

Key press Menu item selected Push Button pressed Mouse button down Mouse button up Mouse moved Window expose Window resize Window close requested Changed to a new dialog field Window selected via border/ title-bar

WIN_MESSAGE value = Structure containing additional message information TYPE WIN_MESSAGE INTEGER win INTEGER value1 INTEGER value2 INTEGER value3 INTEGER value4 INTEGER x INTEGER y REAL REAL REAL REAL Window or Dialog the message came from Message-type dependent parameter #1 Message-type dependent parameter #2 Message-type dependent parameter #3 Message-type dependent parameter #4 X co-ordinate in Winteracter window units (0-9999) Y co-ordinate in Winteracter window units (0-9999)

gvalue1 value1 expressed in graphics units gvalue2 value2 expressed in graphics units gx gy X co-ordinate in graphics units (see IGrUnits) Y co-ordinate in graphics units (see IGrUnits)

END TYPE WIN_MESSAGE

86

Winteracter Starter Kit

WMessage Subroutine
Effect
Returns the next message from the input queue and returns any parameters associated with that message. If no message is available, WMessage waits for the next event to occur. Use the altenative WMessagePeek to continue processing if no messages are waiting. Only those messages enabled via WMessageEnable are reported. Initially reporting of all messages is enabled, except for MouseButUp, MouseMove, FieldChanged. and BorderSelect. For all message types (except 3 and 10), value%win identifies the window which generated the message. For PushButton and FieldChanged messages, value%win specifies the unique identifier of the dialog which generated the message. The other information returned in value is message-type dependent: itype = KeyDown If the user presses a key which is not processed as a keystroke in a dialog or a menu selection, the key code will be returned in value%value1. The (x,y) co-ordinate of the mouse cursor when the key was pressed will also be returned. The possible key codes which can be returned are summarized in the following table: Table 5: Key codes
Name Code Key Name Code Key

KeyBackSpace KeyTab Return KeyEscape KeyDelete KeyCursorUp KeyCursorDown KeyCursorRight KeyCursorLeft KeyPageUp KeyPageDown

32-255 8 9 13 27 127 258 259 260 261 262 263

Printable characters Backspace Tab Return Escape Delete left Cursor Up Cursor Down Cursor Right Cursor Left Page Up Page Down KeyInsert KeyDeleteUnder KeyShiftTab Keypad0 Keypad1 Keypad2 Keypad3 Keypad4 Keypad5 Keypad6 Keypad7 272 273 274 280 281 282 283 284 285 286 287 Insert Delete under cursor Key Shift/Tab Keypad 0 Keypad 1 Keypad 2 Keypad 3 Keypad 4 Keypad 5 Keypad 6 Keypad 7

Winteracter Starter Kit

87

Chapter 10

Input Handling
Table 5: Key codes
Name Code Key Name Code Key

KeyPageRight KeyPageLeft KeyUpExtreme KeyDownExtreme KeyRightExtreme KeyLeftExtreme KeyHome KeyEnd KeyF1-KeyF20 KeyShiftF1KeyShiftF20 KeyCtrlF1KeyCtrlF20

264 265 266 267 268 269 270 271 301320 321340 341360

Shift/cursor right Shift/cursor left Ctrl/cursor up Ctrlcursor down Ctrl/cursor right Ctrl/cursor left Home End F1-F20 Shift/F1 Shift/F20 Ctrl/F1-Ctrl/ F20

Keypad8 Keypad9 KeypadMinus KeypadPoint KeypadPlus KeypadDivide KeypadMultiply

288 289 290 291 292 293 294

Keypad 8 Keypad 9 Keypad Keypad . Keypad + Keypad / Keypad *

itype = MenuSelect When a menu item is selected, its unique identifier is returned in value%value1. This will correspond to the identifier defined in the program's resource file.This message will also be generated when the user presses an accelerator key. itype = PushButton When a dialog push button is pressed in a modeless or semi-modeless dialog, the unique identifier of that button is returned in value%value1. This will correspond to the identifier defined in the program's resource file. value%value2 will be set to the identifier of the currently selected field in the corresponding dialog when the button was pressed.

88

Winteracter Starter Kit

WMessage Subroutine
Certain Microsoft-recommended push-button identifiers are pre-defined in the WINTERACTER module :
INTEGER, INTEGER, INTEGER, INTEGER, INTEGER, INTEGER, INTEGER, INTEGER, INTEGER, PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER :: :: :: :: :: :: :: :: :: IDOK IDCANCEL IDABORT IDRETRY IDIGNORE IDYES IDNO IDCLOSE IDHELP = = = = = = = = = 1 2 3 4 5 6 7 8 9

Attempting to close a dialog (via the button, via Close on the system menu or by pressing Alt/F4) will also generate a PushButton message, with a button identifier value of IDCANCEL (2). itype = MouseButDown/MouseButUp When a button down or up event occurs, value%value1 will contain the button number: LeftButton MiddleButton RightButton (1) (2) (3) Left button pressed Middle button pressed (where available) Right button pressed

The (x,y) co-ordinate of the mouse cursor when the event occurred is returned. value%value2 will contain a time stamp. This is the elapsed time in centiseconds since the system start time. itype = MouseMove When a mouse moves, the new mouse (x,y) co-ordinate is returned. A time stamp is available in value%value2. This message is only reported if specifically enabled via WMessageEnable. Programs which enable this message must be prepared to process large numbers of movement messages. itype = Expose If all or part of a window becomes exposed, that window area will need to be repainted. The returned (x,y) co-ordinate identifies the top left corner of the exposed area. value%value1 and value%value2 define the width and height of the exposed area. itype = Resize When the user resizes a root or child window, value%value1 and value%value2 return the new window width/height in screen pixels. itype = CloseRequest
Winteracter Starter Kit

89

Chapter 10

Input Handling
If a user selects Close on the system menu (or clicks on the Close button under Windows 4) a CloseRequest message is returned. The handle of the window which originated the request is returned in value%win. This will be zero for the root window. It is then the responsibility of the calling program to close that window (via WindowCloseChild or WindowClose), if the close request is to be allowed. Typically, a CloseRequest message from the root window should result in program termination. However, the calling program may wish to ask for the user's confirmation (e.g. via WMessageBox) and close any data files, before terminating. itype = FieldChanged When a user changes a field value or moves between fields in a dialog, value%value1 will be set to the identifier of the previous field and value%value2 will be set to the 'moved to' or current field. If the current field number has not changed (e.g. the user has just changed their selection in a menu field), value%value1 will be the same as value%value2. field This allows the calling program to perform field-by-field validation without having to wait for a dialog to terminate via a PushButton event. itype = BorderSelect When the user selects a window by clicking on the title bar or border controls, a BorderSelect message reports the selected window in the value%win parameter. The mouse button number is returned in value%value1 as for a MouseButDown message The BorderSelect message is not reported by default since most programs need not be concerned about which window currently has the focus. Note that a focus change via a mouse click in a window's client area will be reported separately as a MouseButDown message.

Example
TYPE (WIN_MESSAGE) :: MESG DO CALL WMessage(ITYPE,MESG) SELECT CASE (ITYPE) CASE (MenuSelect) ! Check for 'Exit' menu option SELECT CASE (MESG%VALUE1) CASE (IDM_OPEN) ! Open option on the menu CALL OpenMyFile CASE (ID_EXIT) ! Was Exit selected from menu EXIT END SELECT CASE (Resize, Expose) ! Redraw graph CALL Draw_My_Graph CASE (CloseRequest) ! Close button or System menu option EXIT END SELECT END DO CALL WindowClose ! Close root window and all children

90

Winteracter Starter Kit

WMessageEnable Subroutine

WMessageEnable Subroutine
Description
Enable/disable message reporting.

Syntax
WMessageEnable(itype,ionoff)

Arguments
INTEGER itype = Message type, as for WMessage INTEGER ionoff = Turn message on/off (Disabled (0) = off, Enabled (1) = on)

Effect
Enables or disables reporting of the specified message type via WMessage and WMessagePeek. See WMessage for details of the message types which are reported by default. Note that disabling a particular message type does not prevent that event from occurring. It simply determines whether the event is reported to the calling program.

Example
CALL WMessageEnable(KeyDown,Disabled) ! keystroke messages off CALL WMessageEnable(MouseMove,Enabled) ! mouse move messages on

WMessagePeek Subroutine
Description
Get next message. Return if none waiting.

Syntax
WMessagePeek(itype,ivalue)

Arguments
See WMessage

Effect
This routine is identical to WMessage except that it will not 'block' if no message is waiting. If the input queue contains no messages, itype will be returned as NoMessage (-1). Use WMessagePeek where a program wishes to poll for messages but needs to continue processing if no events have occurred.
Winteracter Starter Kit

91

Chapter 10

Input Handling
Example
TYPE (WIN_MESSAGE) :: MESG DO Iteration = 1, 100000 CALL WMessagePeek(ITYPE, MESG) IF (ITYPE/=NoMessage) THEN ! Process message(s) here END IF ! Next iteration of number cruncher CALL Number_Cruncher(Iteration) END DO

Group MN: Menu Handling


Menu structures are defined externally via a resource file, which will normally have been created via MenuEd, the Winteracter menu resource editor. Menu selections are reported via WMessage in the MH group. The routines in this group provide the remaining menu handling capabilities, namely: Activation and removal of root menus via WMenuRoot Setting and retrieving the state (i.e. checked and/or greyed) of individual menu items via WMenuSetState/WMenuGetState Updating the strings associated with a given menu item via WMenuSetString (initial strings can be assigned in the resource file)

All the routines in this group use unique menu or menu-item identifiers as defined in the program resource file(s).

WMenuGetState Function
Description
Get grayed/checked state of a menu item.

Syntax
INTEGER WMenuGetState(menuitem,iprop)

Arguments
INTEGER menuitem = Menu item identifier as specified in resource file INTEGER iprop = Property to retrieve: ItemEnabled (1): Is item enabled ?

92

Winteracter Starter Kit

WMenuRoot Subroutine
Returns : Disabled Enabled (0) Item is greyed out (1) Item is selectable

ItemChecked (2): Is item checked ? Returns : Unchecked Checked (0) No check mark (1) Check mark is present

Effect
Retrieves the state of the specified menu item property. Only one property can be interrogated at one time. An INTEGER binary flag is returned to indicate the state of the specified property. See also WMenuSetState.

Example
see WMenuSetState

Errors
ErrMenuItem (1001) Invalid menu item

WMenuRoot Subroutine
Description
Activate or remove a root menu structure.

Syntax
WMenuRoot(menuid)

Arguments
INTEGER menuid = Identifier of root menu to activate (0 to remove current root menu)

Effect
Activates the specified root menu structure, which will be attached to the top of the root window. Multiple root menus are allowed in a single program as a result, though only one can be active at one time. To remove the current root menu, specify a zero menu identifier. Item selections are reported via WMessage in a MenuSelect message. WMenuRoot also loads and activates an accelerator table from the program resource, if such a table exists with the same identifier. An accelerator table identifies keystrokes which can be used to directly select a menu item from the keyboard, without having to navigate the menu.
Winteracter Starter Kit

93

Chapter 10

Input Handling
Depending on the number and length of the menu items and the current window size, calling this routine may cause a change in the size of the useable window area. This is will be reported via WMessage as a Resize message. The state of individual menu items (greyed/checked) can be set via WMenuSetState. Menu item strings can be updated via WMenuSetString.

Example
CALL WMenuRoot(0) ! Remove root menu

Errors
ErrLoadMenu (1002) Unable to load menu from resource

WMenuSetState Subroutine
Description
Set grayed/checked state of a menu item.

Syntax
WMenuSetState(menuitem,iprop,ivalue)

Arguments
INTEGER menuitem = Menu item identifier as specified in resource file. INTEGER iprop = Property to set: ItemEnabled (1) Enable item ItemChecked (2) Check item INTEGER ivalue = New state for menu item property (WintOff (0): Off, WintOn (1): On)

Effect
Sets the state of the specified menu item property. The specified menu item must exist on the current root menu. iprop = ItemEnabled When an item is enabled, it is selectable in the normal manner. When it is disabled, it will be greyed out. iprop = ItemChecked A checked item has a tick mark against it.This is used to indicate that a particular program option is currently enabled. It is not possible to add checks to top level root menu items.

94

Winteracter Starter Kit

WMenuSetString Subroutine
Example
IPROP = WMenuGetState(ID_OPTION,MenuChecked) ! Toggle check mark ! next to an option IPROP = 1 - IPROP CALL WMenuSetState(ID_OPTION,MenuChecked,IPROP)

Errors
ErrMenuItem (1001) Invalid menu item

WMenuSetString Subroutine
Description
Change the text of a menu item

Syntax
WMenuSetString(menuitem,string)

Arguments
INTEGER menuitem = Menu item identifier as specified in resource file. CHARACTER string = New text for the specified menu item.

Effect
Changes the text of the specified root menu item.

Example
IF (FIRSTTIME) THEN CALL WMenuSetString(ID_OPTION,'New data') ELSE CALL WMenuSetString(ID_OPTION,'Old data') END IF

Errors
ErrMenuItem (1001) Invalid menu item
Winteracter Starter Kit

95

Chapter 10

Input Handling

96

Winteracter Starter Kit

11 Dialog Manager

A dialog is a set of associated data entry fields, the layout of which will have been defined in a resource script using DialogEd, the Winteracter dialog editor. Any number of dialog descriptions can be built into a program executable, as part of the program resources. The Dialog Manager operates by selectively loading one or more of these dialogs from the program resource (see WDialogLoad), possibly modifying the dialog, then displaying it (see WDialogShow). When no longer required, a dialog can be unloaded (see WDialogUnload). The same dialog can be loaded and unloaded as many times as required. Alternatively, it can be loaded just once then repeatedly displayed and hidden (see WDialogHide). Three types of dialog are supported:

Modal
A modal dialog blocks data entry or option selection via other dialogs or menus belonging to the current program. Such dialogs are easier to manage from a programming viewpoint because display, user-entry and termination all occur as a single operation (in a call to WDialogShow). They also eliminate any need to process Resize or Expose messages while the dialog is displayed.

Modeless
A modeless dialog remains on screen while a program continues to run. Button presses are reported via WMessage, as PushButton messages. The dialog remains visible until explicitly removed by the calling program. Several modeless dialogs can be active simultaneously.

Semi-Modeless
A semi-modeless dialog is a useful hybrid of the previous two types. Such a dialog appears modeless to the program, but modal to the user. In other words, control returns to the program as soon as the dialog is displayed by WDialogShow (allowing message processing via WMessage, for example), but input to other dialogs or program menus is blocked. Like a modeless dialog, a semi-modeless dialog remains onWinteracter Starter Kit

97

Chapter 11

Dialog Manager
screen until explicitly removed by the calling program. Multiple semi-modeless dialogs can be stacked, allowing the use of 'Options' or 'Advanced' buttons to activate sub-dialogs. All dialogs are either 'pop-up' or 'child' dialogs. This is determined by a setting in the resource file. (See Dialog Properties in DialogEd.) A pop-up dialog can be moved to any position on the screen either inside or outside of the application window. Child dialogs are restricted to the root window. Child dialogs must be modeless While more than one dialog is loaded, the Dialog Manager uses the concept of the 'current' dialog. This is simply the dialog which most of the other dialog management routines will operate on. This can be set explicitly via WDialogSelect, but is also set implicitly by WDialogLoad. Whichever dialog type is used, it can consist of the following standard Windows field/control types: Strings Menus (simple character fields or multi-line edit controls) (list boxes and three styles of combo boxes)

Check boxes (simple on/off option selectors) Radio buttons (a group of check boxes, with at most one selected) Push buttons (dialog termination buttons such as OK, Cancel, etc.)

In addition a dialog can also include various 'decorations' (e.g. bitmaps and frames), which are defined within the resource script, but are not manipulated directly from within a program. The initial contents of each field can be defined in the program resource. These will be the initial values each time WDialogLoad is called. While loaded, the contents of the dialog can be updated via the various WDialogPutXXX routines in the DM(2) group. The values of dialog fields can be interrogated, (both before and after user data entry) via the corresponding WDialogGetXXX routines in the same group. For example, the contents of a string field can be assigned via WDialogPutString and retrieved via WDialogGetString. Dialog validation can be performed at the calling level by checking the values returned by the 'get' routines in group DM(2). On-the-fly validation can be performed in modeless and semi-modeless dialogs by checking for FieldChange messages in the message loop. When a user has finished entering data in a dialog they will normally press a termination button (e.g. OK, Cancel, etc.). This will cause a modal dialog to be terminated immediately, with termination information reported via WInfoDialog. However, a modeless or semi-modeless dialog will remain on-screen, with the button presses reported via WMessage. The dialog remains on screen till explicitly removed by WDialogHide or WDialogUnload.

98

Winteracter Starter Kit

Group DM(1): General Dialog Management


Every dialog and field used in a given program must have a unique identifier, as set in the resource file. A Fortran module or include file should normally be used to specify PARAMETER values for these dialog/field identifiers. DialogEd will create such a module or include file automatically.

Group DM(1): General Dialog Management


The main routines in this group are those which load a dialog from a resource and then display it on the screen (WDialogLoad and WDialogShow). Modeless and semi-modeless dialogs can be hidden while not required to be visible, by WDialogHide. When a dialog is no longer needed in memory it can be unloaded completely by WDialogUnload. Up to 50 dialogs can be loaded simultaneously. The majority of the routines in this group and in the DM(2) group operate on the 'current' dialog. This can be set by WDialogSelect. It is also set by WDialogLoad.

WDialogHide Subroutine
Description
Remove current dialog from screen.

Syntax
WDialogHide()

Effect
Remove the current dialog from the screen, but keep it in memory so that its contents can still be accessed. It is only necessary to call this routine for modeless or semi-modeless dialogs. Modal dialogs are automatically removed from the screen when WDialogShow terminates. If the current dialog is semi-modeless and there are no other semi-modeless dialogs active, then all program windows and modeless dialogs are re-enabled. A dialog can be removed from memory subsequently by calling WDialogUnload.

Winteracter Starter Kit

99

Chapter 11

Dialog Manager
Example
CALL WMessage(ITYPE,MESSAGE) SELECT CASE (ITYPE) CASE (MenuSelect) : CASE (PushButton) CALL WDialogHide() ! Remove dialog from display ! when a push-button is pressed CASE (MouseButDown) : END SELECT

Errors
ErrCurDialog (1005) No current dialog

WDialogLoad Subroutine
Description
Load a dialog definition from program resource.

Syntax
WDialogLoad(idialog)

Arguments
INTEGER idialog = Identifier of dialog to load, as defined in the resource script.

Effect
Loads the specified dialog from the program resource. The dialog contents are initialized to the settings specified in the program's resource script. To make the dialog appear on screen, call WDialogShow. Optionally, the contents of the dialog can be modified using the various WDialogPutXXX routines in the DM(2) group, before the WDialogShow call. WDialogLoad implicitly selects idialog as the current dialog for use by other Winteracter routines. A dialog can be reselected after loading other dialogs by calling WDialogSelect. If the dialog specified by idialog is already loaded, it will simply be re-selected as the current dialog. To completely reinitialize a dialog, unload it (via WDialogUnload) and reload it.

Example
CALL WDialogLoad(IDD_ABOUT) CALL WDialogShow(-1,-1,0,Modal) CALL WDialogUnload()

100

Winteracter Starter Kit

WDialogSelect Subroutine
Errors
ErrLoadDialog (1007) Unable to load dialog from resource

WDialogSelect Subroutine
Description
Select the current dialog.

Syntax
WDialogSelect(idialog)

Arguments
INTEGER idialog = Identifier of dialog to select

Effect
Selects the current dialog. This is the dialog which all Winteracter field manipulation routines subsequently operate on. Calling this routine does not cause the dialog to appear (see WDialogShow). The specified dialog must already be loaded (see WDialogLoad).

Example
CALL WDialogLoad(IDD_DIALOG1) CALL WDialogLoad(IDD_DIALOG2) CALL WDialogLoad(IDD_DIALOG3) CALL WDialogSelect(IDD_DIALOG2) CALL WDialogShow(-1,-1,0,Modal) ! Will show 2nd dialog ! Load several dialogs

Errors
ErrSelDialog (1008) Unable to select specified dialog

WDialogShow Subroutine
Description
Display the currently selected dialog.
Winteracter Starter Kit

101

Chapter 11

Dialog Manager
Syntax
WDialogShow(ixpos,iypos,ifield,itype)

Arguments
INTEGER ixpos = X Co-ordinate of top left corner of dialog (-1 to center) (Child dialogs: Winteracter units, Floating dialogs: Pixels) INTEGER iypos = Y Co-ordinate of top left corner of dialog (-1 to center) (Child dialogs: Winteracter units, Floating dialogs: Pixels) INTEGER, OPTIONAL ifield = Identifier of initial field to edit (0 for default: 1st field with WS_TABSTOP style) INTEGER, OPTIONAL itype = Dialog type for floating dialogs Modal Modeless Semi-modeless (1) : Modal dialog (2) : Modeless dialog (default) (3) : Semi-modeless dialog

Effect
Displays the currently selected dialog, allowing the user to edit its contents. The dialog must have been loaded previously using WDialogLoad. If the current dialog selection has changed since the dialog was loaded, the dialog to be displayed must be reselected by calling WDialogSelect. If the specified dialog is already active, the position and type parameters will be ignored. Instead the dialog will simply be brought to the front and made active. Both child and floating dialogs are supported (this is determined by a setting in the resource file). Child dialogs are restricted to the programs root window. Floating dialogs can be moved anywhere on screen. The initial position of a child dialog is determined in Winteracter units (i.e. 0-9999), relative to the top corner of the root window. Floating dialog positions are specified in pixels relative to the top corner of the screen. Only floating dialogs (also known as pop-up dialogs) can be displayed if the root window is hidden (i.e. if HideRoot was specified in the call to WindowOpen). Attempting to show a child dialog will fail and generate an error code. ifield specifies the initially highlighted data entry field. This argument has the OPTIONAL attribute. If it is zero or omitted, the initial field will be the first editable field in the dialog (i.e. the first control in the dialog with the WS_TABSTOP style).

102

Winteracter Starter Kit

WDialogShow Subroutine
itype specifies the dialog type: Modal : A modal dialog is one which blocks all other input to the program until the user terminates the dialog (e.g. by clicking on OK). WDialogShow will not return until the user has terminated the dialog at which point the dialog window is automatically removed from the screen. The exit field and terminating button identifiers are available via WinfoDialog. Modeless: A modeless dialog does not block input. WDialogShow returns as soon as the dialog has been displayed. The dialog remains on screen until WDialogHide or WDialogUnload is called. Any push-button clicks in the dialog will be reported via WMessage as a PushButton message. The current field number when the button was pressed will be returned via the associated value argument. It is not possible to display a modeless dialog while a semi-modeless dialog is already active. If any semi-modeless dialogs are active and modeless is requested then the dialog will be displayed as semi-modeless and an error code set. SemiModeless : A semi-modeless dialog is a hybrid of the other two dialog types. It appears modeless to the program but modal to the user. It blocks user input to all other dialogs and windows, but WDialogShow returns as soon as the dialog has been displayed. The dialog remains on screen until WDialogHide or WDialogShow is called. Any push-button clicks in the dialog will be reported via WMessage as a PushButton message. The current field number when the button was pressed will be returned via the associated value argument. Child dialogs are always modeless (Windows does not allow modal or semi-modeless child dialogs). The itype argument is therefore OPTIONAL and need only be specified for floating dialogs. If not specified, the default type is Modeless. Further dialogs may be activated whilst a semi-modeless dialog is in use. However, these dialogs must be modal or semi-modeless. If a modeless dialog is requested, then a semimodeless dialog will be displayed instead. Error code 1014 will be set in this case.

Example
CALL CALL CALL CALL WDialogLoad(IDD_DIALOG1) WDialogShow(-1,-1,0,Modeless) WDialogLoad(IDD_DIALOG2) WDialogShow(-1,-1,0,Modal) ! ! ! ! ! Display dialog1 as a modeless dialog Display dialog2 as a modal dialog Both are centered.

Errors
ErrCurDialog ErrFieldNum ErrDialogType ErrRootHidden (1005) No current dialog (1006) Invalid field identifier (1014) Invalid dialog type (1016) Child dialogs cannot be shown when root window hidden
Winteracter Starter Kit

103

Chapter 11

Dialog Manager

WDialogUnload Subroutine
Description
Remove dialog from screen and memory.

Syntax
WDialogUnload(iaction)

Arguments
INTEGER, OPTIONAL iaction = Not used in Starter Kit

Effect
Removes the currently selected dialog from the screen, if it is currently visible. It then removes the dialog and its associated data from memory, releasing all associated resources. The same dialog can be reloaded later using WDialogLoad, though this will reset all the dialog parameters to their initial values as set in the program resource.

Example
CALL WDialogLoad(IDD_ABOUT) CALL WDialogShow(-1,-1,2,0) CALL WDialogUnload()

Errors
ErrCurDialog ErrFieldNum (1005) No current dialog (1006) Invalid field identifier

Group DM(2): Assign/Retrieve Fields


The routines in this group assign and retrieve the contents of individual dialog fields via a set of WDialogPutXXX and WDialogGetXXX routines. The 'Put' routines would normally be called before WDialogShow. The resulting field contents can then be retrieved from a dialog using the 'Get' equivalents after WDialogShow. Where a field is part of an already visible modeless dialog, the various 'Put' routines update the on-screen contents of the dialog immediately. All routines in this group affect the currently selected dialog, as set by WDialogLoad or WDialogSelect. The error flag is therefore set to ErrCurDialog if an attempt is made to assign or retrieve the contents of a field when no dialog is currently selected. Bear in mind that WDialogUnload causes the current dialog to become undefined. WDialogSelect must be called in this case to reselect the current dialog.

104

Winteracter Starter Kit

WDialogGetCheckBox Subroutine

WDialogGetCheckBox Subroutine
Description
Get state of a dialog check box.

Syntax
WDialogGetCheckBox(ifield,istate)

Arguments
INTEGER ifield = Field identifier as set in resource file INTEGER istate = Returned check box state (Unchecked (0): Clear, Checked (1): Set)

Effect
Gets the state of a check box field in the current dialog.

Example
LOGICAL :: UseColor CALL WDialogGetCheckBox(IDF_COLOR,ICHECKED) UseColor = ICHECKED.EQ.1

Errors
ErrCurDialog ErrFieldNum (1005) No current dialog (1006) Invalid field identifier

WDialogGetMenu Subroutine
Description
Get a value from a dialog menu field.

Syntax
WDialogGetMenu(ifield,ioption,cvalue)

Arguments
INTEGER ifield = Field identifier as set in resource file INTEGER ioption = Number of selected option CHARACTER, OPTIONAL cvalue = Entered string
Winteracter Starter Kit

105

Chapter 11

Dialog Manager
Effect
Gets a value from a menu field in the current dialog. ioption returns the currently selected item number from the pre-defined list held in this field. If this returns 0, the user entered a non-matching string in the enterable field of a combo box menu field. This will then be returned via cvalue. Since cvalue has the OPTIONAL attribute, it can be omitted if the menu is known not to have an enterable field. If the menu field contents are undefined ioption is returned as -999 and an error code is set.

Example
CHARACTER (LEN=80) :: USERSTRING CALL WDialogGetMenu(IDF_COMBO1,IOPTION,USERSTRING) SELECT CASE(IOPTION) CASE(0) ! Process supplied string ! CASE(1) ...

Errors
ErrCurDialog ErrFieldNum (1005) No current dialog (1006) Invalid field identifier

ErrFieldUndefined (1010) Field value is undefined

WDialogGetRadioButton Subroutine
Description
Gets a radio-button group value

Syntax
WDialogGetRadioButton(ifield,iset)

Arguments
INTEGER ifield = Field identifier of a radio button as set in resource file INTEGER iset = Position of currently set radio button within the group which contains button ifield. (-999 if none set) Gets the position of the currently selected item in the group of radio buttons in the current dialog which contains button ifield. In other words, rather than returning the state of the specified individual radio button, this routine identifies which radio button is on in the group which ifield belongs to. Note that iset is a positional value. So, for example, if there are 5 radio buttons in a group, iset will normally be in the range 1 to 5.

106

Winteracter Starter Kit

WDialogGetString Subroutine
If all the radio buttons are clear (because the initial button state was not defined in the resource file) iset is returned as -999 and an error code is set.

Example
CALL WDialogGetRadioButton(IDF_RADIO1,IPOSITION) SELECT CASE (IPOSITION) ! END SELECT

Errors
ErrCurDialog ErrFieldNum (1005) No current dialog (1006) Invalid field identifier

ErrFieldUndefined (1010) Field value is undefined

WDialogGetString Subroutine
Description
Get a string from a dialog string field.

Syntax
WDialogGetString(ifield,cvalue)

Arguments
INTEGER ifield = Field identifier as set in resource file CHARACTER cvalue = Returned character value (blank if undefined)

Effect
Gets a string from a field of almost any type. While this routine will normally just be used to retrieve the contents of ordinary string fields, it also provides access to the contents of just about any field which has an associated string value. This includes push buttons, check-boxes and radio-buttons. If ifield specifies a multi- line edit control, the returned string will contain embedded carriage return/line-feed pairs (i.e. CHAR(13)//CHAR(10)) indicating line ends.

Example
CHARACTER (LEN=20) :: TEXT,BUT CALL WDialogGetString(IDF_STRING,TEXT) ! Contents of string field CALL WDialogGetString(IDF_BUTTON,BUT) ! Caption of a push-button

Winteracter Starter Kit

107

Chapter 11

Dialog Manager
Errors
ErrCurDialog ErrFieldNum (1005) No current dialog (1006) Invalid field identifier

WDialogPutCheckBox Subroutine
Description
Set the state of a dialog check box.

Syntax
WDialogPutCheckBox(ifield,istate)

Arguments
INTEGER ifield = Field identifier as set in resource file INTEGER istate = Check box field state (Unchecked (0): Clear, Checked (1): Set)

Effect
Sets the state of a check box in the current dialog. To set the associated check box string, call WDialogPutString.

Example
CALL WDialogPutCheckBox(IDF_CHECK,Checked)

Errors
ErrCurDialog ErrFieldNum (1005) No current dialog (1006) Invalid field identifier

WDialogPutImage Subroutine
Description
Change the bitmap/icon displayed in a field.

Syntax
WDialogPutImage(ifield,imageid,itype)

Arguments
INTEGER ifield = Field identifier as set in resource file

108

Winteracter Starter Kit

WDialogPutMenu Subroutine
INTEGER imageid = Bitmap or icon identifier as set in resource file INTEGER, OPTIONAL itype = Image type 1 : Bitmap (default) 2 : Icon Changes the bitmap or icon which is displayed in the specified field in the current dialog. The bitmap or icon must exist in the program resource and the field specified by ifield must be one of the following types : Picture/frame Push-button Group-box Check-box Radio button If itype is omitted, a bitmap resource is assumed. The significant difference between a bitmap and an icon is that the latter allows for transparent pixels. This routine has no effect under Windows 3.xx.

Example
CALL WDialogPutImage(IDF_PICTURE,ID_BITMAP)

Errors
ErrCurDialog ErrFieldNum ErrImageNum (1005) No dialogs currently loaded (1006) Invalid field identifier (1015) Invalid bitmap/icon identifier

WDialogPutMenu Subroutine
Description
Set the contents of a dialog menu field.

Syntax
WDialogPutMenu(ifield,option,maxopt, ioption,cvalue)

Arguments
INTEGER ifield = Field identifier as set in resource file CHARACTER option(:) = Array of menu options
Winteracter Starter Kit

109

Chapter 11

Dialog Manager
INTEGER maxopt = Number of menu options INTEGER ioption = Number of initially highlighted option CHARACTER, OPTIONAL cvalue = User modifiable string

Effect
Sets the contents of the specified menu field in the current dialog. An array of maxopt option strings should be supplied. ioption specifies the item number which should be highlighted initially. This will normally be in the range 1 to maxopt. If ifield specifies a combo box with a user enterable field, cvalue can contain the initial user modifiable value. In this case, ivalue should be specified as zero. Otherwise, cvalue can be omitted since it has the OPTIONAL attribute.

Example
INTEGER, PARAMETER :: NFRUIT = 4 CHARACTER (LEN=7), DIMENSION (NFRUIT) :: FRUIT & (/'Apples','Oranges','Pears','Bananas'/) IFRUIT = 1 CALL WDialogPutMenu(IDF_FRUIT,FRUIT,NFRUIT,IFRUIT)

Errors
ErrCurDialog ErrFieldNum ErrOptionNum (1005) No dialogs currently loaded (1006) Invalid field identifier (1011) Option number out of range

WDialogPutOption Subroutine
Description
Set the selected option in a dialog menu field.

Syntax
WDialogPutOption(ifield,ioption)

Arguments
INTEGER ifield = Field identifier as set in resource file INTEGER ioption = Menu option number to highlight

110

Winteracter Starter Kit

WDialogPutRadioButton Subroutine
Effect
Sets the currently selected option in a menu field in the current dialog. This is the same as the ioption argument to WDialogPutMenu. The option number can be zero if ifield specifies a combo box, in which case none of the predefined menu items will be highlighted.

Example
CALL WDialogPutOption(IDF_FRUIT,IFRUIT)

Errors
ErrCurDialog ErrFieldNum ErrOptionNum (1005) No dialogs currently loaded (1006) Invalid field identifier (1011) Option number out of range

WDialogPutRadioButton Subroutine
Description
Set the state of a radio button group.

Syntax
WDialogPutRadioButton(ifield)

Arguments
INTEGER ifield = Field identifier as set in resource file Enables the specified radio button. All other radio buttons in the group to which it belongs are automatically disabled.

Example
! Set Radio button number 2, clear all others in the same group CALL WDialogPutRadioButton(IDF_RADIO2)

Errors
ErrCurDialog ErrFieldNum (1005) No dialogs currently loaded (1006) Invalid field identifier
Winteracter Starter Kit

111

Chapter 11

Dialog Manager

WDialogPutString Subroutine
Description
Set the value of a dialog string.

Syntax
WDialogPutString(ifield,cvalue)

Arguments
INTEGER ifield = Field identifier as set in resource file CHARACTER cvalue = Character string to be placed in field

Effect
Sets the string of a field of almost any type. This routine can be used to set the contents of ordinary string fields or any field which has an associated string value. This includes push buttons, check boxes, radio-buttons and multi-line edit controls. If ifield specifies a multi-line edit control, the supplied string should contain embedded carriage return/line-feed pairs (i.e. CHAR(13)//CHAR(10)) to indicate line ends. Tabcharacters (CHAR(9)) can also be embedded to vertically align text at tab stops in such fields.

Example
CALL WDialogPutString(IDF_STRING,'Some Text') ! now a push button field CALL WDialogPutString(IDF_BUTTON,'Press Me')

Errors
ErrCurDialog ErrFieldNum (1005) No dialogs currently loaded (1006) Invalid field identifier

Group CD: Common Dialogs


Windows provides a handful of predefined dialogs which meet common requirements. The file-selector and message-box common dialogs' are supported via the routines in this group. All the dialogs displayed by these routines are modal.

112

Winteracter Starter Kit

WMessageBox Subroutine

WMessageBox Subroutine
Description
Display a standard Windows message box.

Syntax
WMessageBox(ibutton,icon,idefbut,message,title)

Arguments
INTEGER ibutton = The type of buttons to be displayed Table 6: Common Dialog Buttons
Name No. Button(s)

OKOnly OKCancel RetryCancel YesNo YesNoCancel RetryAbortIgnore

0 1 2 3 4 5

OK button OK and Cancel buttons Retry and Cancel buttons Yes and No buttons Yes, No and Cancel buttons Retry/Abort/Ignore buttons

INTEGER icon = The type of icon to be displayed Table 7: Common Dialog Icons
Name No. Icon

NoIcon StopIcon QuestionIcon ExclamationIcon InformationIcon

0 1 2 3 4

No icon Stop icon Question mark icon Exclamation mark icon Information icon

Winteracter Starter Kit

113

Chapter 11

Dialog Manager
INTEGER idefbut = Default highlighted button: Table 8: Common Dialog Button Numbers
Name No. Highlighted Button

CommonCancel CommonIgnore CommonOK CommonOpen CommonYes CommonRetry CommonAbort CommonNo

0 0 1 1 1 1 2 2

Cancel Ignore OK Open Yes Retry Abort No

CHARACTER message = Message box text CHARACTER title = Message box title

Effect
Displays a standard message box consisting of a message and up to three push buttons. Since many programs require only simple confirmations from the user this routine can help reduce the number of required dialog resources. ibutton selects the number and type of buttons the message box will contain. icon selects the pre-defined icon that appears in the message box beside the text. idefbut specifies which button will be highlighted when the message box is first opened. This value follows the same numbering scheme as the exit button code returned by WInfoDialog. message should contain the text to be displayed in the message box. Windows limits the length of the message box text to three lines. Windows does not automatically break the lines to fit in the message box, so the message string must contain carriage returns (i.e. CHAR(13)) to break the lines at the appropriate places. The message can be blank if required. title should contain the message box title. Again, this can be blank. The button pressed to exit from this routine is available via WInfoDialog(4). This uses the same numbering scheme as idefbut.

114

Winteracter Starter Kit

WSelectFile Subroutine
Example
CALL WMessageBox(YesNo, QuestionIcon, 1, & 'Another message box ?', 'Question') IF (WInfoDialog(4).EQ.1) THEN CALL WMessageBox(OKOnly, InformationIcon, 1, & 'This is how to split your text'//CHAR(13)// & 'over several lines.','Information') END IF

Errors
ErrCommonDlg (1004) Common dialog function returned an error. Actual system error code available via InfoError(3)

WSelectFile Subroutine
Description
Select a file using a standard Windows Open/Save dialog.

Syntax
WSelectFile(filterid,iflags,filedir,title)

Arguments
INTEGER filterid = Filter strings identifier or CHARACTER filterid = Filter strings INTEGER iflags = Dialog settings. Sum of: LoadDialog or SaveDialog PromptOn NonExPath DirChange (0) (1) (2) (4) (8) ) Load or ) Save dialog Enable prompting Allow non existent paths Allow directory change

CHARACTER filedir = Entry : Initial directory path + filename Exit : Final directory path + filename CHARACTER title = Dialog title
Winteracter Starter Kit

115

Chapter 11

Dialog Manager
Effect
Prompts for a filename using the standard Windows file selector. The dialog allows the user to enter a new file name or path. It is the responsibility of the caller to create these if necessary. The dialog is displayed slightly below the top left corner of the window or dialog which currently has the input focus. If the file selector is displayed relative to the root window and the root window is hidden, you can still specify the window position to WindowOpen to determine where the file selector dialog will appear. filterid identifies a list of filter pairs. This can either be an integer identifier of a string value in the resource script string-table or a program-supplied character variable/string. In either case, the list of filter pairs is a string containing program type descriptions and corresponding file name match strings. They are used by the file selector to restrict the file types which are offered in the dialog. An example of a resource script filter string table is as follows :
STRINGTABLE BEGIN 1000 "Windows Bitmap|*.bmp|Paintbrush Image|*.pcx|" END

In this example, a filter id of 1000 would add the filters *.bmp and *.pcx to the file type combo box. The first filter in the list is used initially. Note that the final "|" in the filter string is required. Multiple filters can be attached to one filter string by separating them with semicolons, e.g.
1000 "Fortran files|*.f90;*.for;*.f|"

Set filterid to 0 if no filters are required (i.e. match all files). iflags provides control over the exact behaviour of the file selector, by summing together the following settings: LoadDialog selects a standard open-file (i.e. load) dialog. SaveDialog selects a save file dialog. Add PromptOn to iflags to enable prompting. When prompts are enabled, the setting of bit 0 determines the actual type of warning prompts displayed. For load dialogs the user will be prompted if they specify a file or directory that does not exist. For save dialogs the user will be prompted if they try to save to a file that already exists. Add NonExPath to iflags, if non-existent directoriy paths are to be allowed. Otherwise, only file names with valid directory names can be returned from the dialog. Add DirChange to iflags to allow the current directory to be updated. Enabling this option causes the current directory to be updated dependent on which directories the user browses in the file selector. If this option is not selected, WSelectFile saves and restores the current directory across the call to the file selector dialog.

116

Winteracter Starter Kit

WSelectFile Subroutine
On entry filedir will contain the directory path and/or filename to use as the initial default. If this is blank the current directory path is used with no default file name. On exit the final path and file name will be returned in filedir. This will be left unchanged if the user clicked on Cancel or closed the dialog window. title specifies the dialog window title. If this is blank, a default title of 'Select File' is used. The exit button/result from this routine will be available via WInfoDialog(4).

Example
CHARACTER (LEN=255) FILENAME INTEGER, PARAMETER :: ID_FILTER = 40001 : FILENAME = 'C:\DATAFILE' ! Default file path IFLAGS = LoadDialog + PromptOn ! Select load dialog CALL WSelectFile(ID_FILTER, IFLAGS, FILENAME, 'Load data file.') ! Load data if user clicked OK IF (WInfoDialog(4)==1) CALL LoadMyData(FILENAME)

Example Resource script


#define ID_FILTER 40001 STRINGTABLE BEGIN ID_FILTER "Data file|*.dat|Text file|*.txt|" END

Errors
ErrCommonDlg (1004) Common dialog function returned an error. Actual system error code available via InfoError(3)

Winteracter Starter Kit

117

Chapter 11

Dialog Manager

118

Winteracter Starter Kit

12 High Resolution Graphics


The routines described in this chapter are divided into 4 groups: GG General Graphics GS Graphics Style selection (Housekeeping, etc.) (color, line type, fill style)

GD Graphics Drawing and Movement (Line/fill primitives) GC Graphics Character Output (Text primitives)

In addition, graphics related information functions are provided in the IF group.

Group GG: General Graphics


Starting and Finishing

Winteracter's graphics are automatically initialized by WindowOpen. Graphics are always directed to the currently selected root or child window as set by WindowOpen, WindowOpenChild or WindowSelect. Graphics remain available until WindowClose is called.
Co-ordinate System

The Winteracter graphics co-ordinate system is user-definable and is not related to the physical resolution of the output device, making graphics based programs device independent. The area of the output window to be used for the graphics display can also be defined. The IGrArea and IGrUnits routines control the main graphics area and coordinate system respectively. Calls to routines in other groups, such as IGrLineTo, IGrCharOut, etc. all use (x,y) co-ordinates defined in terms of the range set by the call to IGrUnits. So if IGrUnits sets the min and max X values as 0-1000 and the min and max Y values as 0-500, all co-ordinate values should be in these ranges too. Attempts to draw outside this area will be clipped at the edge of the graphics area. By default (0,0) is the bottom left corner of the graphics area. Initially, the main graphics area is set to the full window.
Winteracter Starter Kit

119

Chapter 12

High Resolution Graphics

IGrArea Subroutine
Description
Define size of graphics area.

Syntax
IGrArea(xleft,ylower,xright,yupper)

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

Effect
Defines the area of the current window to be used by all following graphics commands. The full window is defined as being 1 unit high and 1 unit wide, so you should describe your area in values in the range 0.0 - 1.0 as shown above. When you call IGrUnits, that then defines the 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 changing

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

Errors:
ErrBadArea (44)

Invalid X and/or Y range. Range reset to 0-1.

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

120

Winteracter Starter Kit

IGrAreaClear Subroutine

IGrAreaClear Subroutine
Description
Clear the current graphics screen area.

Syntax
IGrAreaClear()

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

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

IGrGetPixelRGB Subroutine
Description
Read a screen pixel color value

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

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

121

Chapter 12

High Resolution Graphics


Effect
Returns the color of the specified screen co-ordinate, as an (r,g,b) triplet. The (x,y) co-ordinate should be expressed in the normal user units as set via IGrUnits. The returned 24-bit color value uses the same color range as the corresponding IGrPaletteRGB routine. If the specified co-ordinate lies outside the graphics area the RGB value is returned as (11,1). On a monochrome screen the returned values will always be (0,0,0) or (255,255,255).

IGrInit Subroutine
Description
Re-initialize graphics output.

Syntax
IGrInit(type,nx,ny,nc)

Arguments
CHARACTER type = Type of output. Leave blank in Starter Kit implementation. INTEGER, OPTIONAL nx = INTERACTER compatibility argument INTEGER, OPTIONAL ny = INTERACTER compatibility argument INTEGER, OPTIONAL nc = INTERACTER compatibility argument

Effect
Re-initializes graphics output. This routine is called by WindowOpen, so it should not normally be necessary to call it again unless the whole of the graphics system needs to be reset to its default state.

122

Winteracter Starter Kit

IGrPause Subroutine
Winteracter's internal graphics are reinitialized to the following defaults: 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 none Sets plotting color to 223 (black) Sets secondary color for mixed-color fills to 0 (white) Sets line type to solid Selects hardware character set and fixed spacing Sets character size to width and height of 1.0

The nx, ny and nc arguments are provided for compatibility with codes written for INTERACTER. They are not used in Winteracter and have the OPTIONAL atrribute. They can be safely omitted in Winteracter-specific code.The type argument should be specified as a blank in Winteracter Starter Kit programs (this argument has meaning in the full version of Winteracter).

IGrPause Subroutine
Description
End of picture.

Syntax
IGrPause(action)

Arguments
CHARACTER action = String describing required action (default is clear window) = 'P': Preserve contents of graphics window

Effect
Sounds the bell and optionally clears the graphics window. This routine is included for INTERACTER-compatibility. There is little benefit in using it in new Winteracter applications.
Winteracter Starter Kit

123

Chapter 12

High Resolution Graphics

IGrUnits Subroutine
Description
Define plotting units to be used.

Syntax
IGrUnits(xleft,ylower,xright,yupper)

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

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

Errors
ErrBadUnits (16)

Lower X or Y value is greater than or equal to upper X or Y

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

Group GS: Graphics Style Selection


The subroutines in this group affect the appearance of output from other graphics routines. The current graphics color is selected using IGrColourN. The number of available colors is device dependent, so Winteracter uses the same color numbering scheme regardless of screen mode or output device, based on 256 nominal colors. When less than 256 colors are available, a near equivalent is always selected. Hence, programs can be written to use color without having to be too concerned with the details of which colors are actually available on the current device. On monochrome devices, the color handling routines can still be called but their effect will be limited to selecting either background/foreground color.

124

Winteracter Starter Kit

IGrColourN Subroutine
Color 0 is treated as the background color and all others as foreground. However, color 0 can still be selected as the current color for graphics operations, though it will obviously only be visible if the operation takes place on top of some non-background color. The color palette (the relationship between color numbers and actual colors displayed) can be redefined on many displays using IGrPaletteRGB. By default the background color is white. The palette can be reinitialized by calling IGrPaletteInit. In addition to color control, line type and fill style are selectable via IGrLineType and IGrFillPattern.

IGrColourN Subroutine
Description
Select graphics color using a color number.

Syntax
IGrColourN(ncolor)

Arguments
INTEGER ncolor = color number (0-255)

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

Winteracter Starter Kit

125

Chapter 12

High Resolution Graphics


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

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

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

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

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

(195, (131,

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

( 60, 60, 60) -> (

(124,124,124) -> ( 64, 64, 64) (191,191,191) -> (131,131,131)

126

Winteracter Starter Kit

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

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

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

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

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

(255, (191, ( 0,

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

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

(255,255,255)

On monochrome screens color zero selects the background color and any non-zero color number is treated as a foreground color. Normally, the default monochrome palette is blackon-white. Whatever color number is used, IGrColourN has no effect on the actual color which is associated with that number. It simply sets the logical color number to be used by any following graphics operations. To redefine the association of displayed colors with logical colors you should use IGrPaletteRGB. Two consecutive calls to IGrColourN will select the colors to be used by mixed-color area fills (see IGrFillPattern). The default graphics color at initialization is black. The actual number of colors available can be checked using InfoGrScreen(30).
Winteracter Starter Kit

127

Chapter 12

High Resolution Graphics


Requesting a color number outside the range 0-255 is ignored and an error code is set. The two most recently requested colors are available via InfoGrScreen(34) and (35). See the COL256 demo program. This illustrates all of the available colors in the default palette. The number of colors supported by Winteracter is related to the number of colors provided by the Windows video driver:, as follows: Table 11: Windows colors
Windows Video Driver Colors 2 16 256 32k/65k/16m Number of colors used by Winteracter 2 8 16 256

Example
DO ICOL = 31,255,32 CALL IGrColourN(ICOL) CALL IGrMoveTo(0.0,0.0) CALL IGrLineTo(0.5,REAL(ICOL)) END DO

Errors
ErrBadcolor (42)

Unknown color number. Current color unchanged

IGrFillPattern Subroutine
Description
Define fill pattern (solid/mixed-colors/hatched).

Syntax
IGrFillPattern(istyle,idense,iangle)

128

Winteracter Starter Kit

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

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

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

Sparse Medium (default) Dense Very dense Very very dense

INTEGER, OPTIONAL iangle = Hatched line angle: Table 14: Hatched Line Angle
Name FillHoriz FillVertic No. 3 4 Information

Horizontal lines (default) Vertical lines

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

Winteracter Starter Kit

129

Chapter 12

High Resolution Graphics


The default fill style is zero which gives outlines only. In this case, the density and angle parameters are ignored. idense and iangle have the OPTIONAL attribute. They can be omitted when not required. If they are omitted when a value is expected, (e.g. for hatched fills) the indicated defaults are assumed. Hatched fills draw lines at intervals across the area to be filled. If a hatched fill is selected, the density and angle parameters define the precise style of the fill. A dense fill uses roughly twice as many lines to fill the area as a sparse fill. The angle parameter controls the direction of the fill lines. Type 1 hatched fills draw lines in one direction only, according to the selected iangle value. Type 2 (cross-hatched) fills draw lines in both directions. Hatched fills are normally drawn with an outline. Specify a negative istyle value to suppress this outline. Type 4 (solid) fills use a pure color, as most recently defined by a call to IGrColourN. Type 3 (mixed) fills are similar to solid ones, except that the two colors as defined by the last two calls to IGrColourN are mixed. Hence if two successive calls to IGrColourN specify Yellow then Red, a type 3 fill will mix these colors. This will either use a stippled fill (where alternate pixels are plotted in each color) or a (r,g,b) value will be selected which is exactly half way between the two specified colors.This can give the appearance of many more shades than some devices actually support. Selecting the same color twice in succession gives a solid fill. In monochrome modes, the foreground/background colors are automatically mixed in stippled fills, regardless of the last two colors specified, unless those colors were identical in which case a solid fill is selected. When solid/stippled fills are requested, angle and density are ignored. If an invalid style, density or angle is specified, then the indicated defaults are used.

Example
CALL CALL CALL CALL IGrColourN(48) ! select first mixed-fill color IGrColourN(144) ! select 2nd mixed-fill color IGrFillPattern(3) ! density and angle omitted IGrCircle(150.,500.,30.)

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

Syntax
IGrLineType(ltype)

130

Winteracter Starter Kit

IGrPaletteInit Subroutine
Arguments
INTEGER ltype = Line type: Table 15: Line Types
Name SolidLine Dotted Dashed DotDash DotDotDash No. 0 1 2 3 4 Information

Solid (default) Dots Dashes Dot/dash Dot/dot/dash

Effect
Selects the line type for subsequent drawing operations. The currently requested line type is available via InfoGrScreen(36). Windows only supports 5 line styles. The line type which is supposed to be dotted is more like short dashes on most displays.

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

IGrPaletteInit Subroutine
Description
Reinitialize graphics color palette.

Syntax
IGrPaletteInit()

Effect
Reinitializes the Winteracter graphics palette to the default settings. See IGrColourN.
Winteracter Starter Kit

131

Chapter 12

High Resolution Graphics

IGrPaletteRGB Subroutine
Description
Redefine color palette using RGB color scheme.

Syntax
IGrPaletteRGB(ncolor,ired,igreen,iblue)

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

INTEGER igreen = Amount of green to assign to displayed color (0-255) INTEGER iblue = Amount of blue to assign to displayed color (0-255)

Effect
Controls the graphics color palette, using the red, green, blue (RGB) color scheme. An actual color combination is assigned to a logical color number. Under Windows, redefinition of the palette only affects subsequent plotting. Note that the whole of the background color can be reset by calling IGrPaletteRGB with an ncolor value of 0. The displayed color is specified in terms of its RGB (red/green/blue) components. Since the number of colors available on different devices varies widely, the RGB components are expressed in an arbitrary range of 0-255. In theory this allows for up 16 million different colors. Where a screen supports fewer colors, the nearest approximation to the requested color is selected. The logical color number specifies the color which would be selected by supplying exactly the same value to IGrColourN. Hence the logical color should lie in the range 0 to 255 and will be converted to an appropriate actual color number for the current video driver, using the same rules as IGrColourN. See IGrColourN for a description of the colors available in the default palettes.

Example
CALL IGrPaletteRGB(200,255,200,200) ! Pale pink

132

Winteracter Starter Kit

Group GD: Graphics Drawing/Movement

Group GD: Graphics Drawing/Movement


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

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

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

Syntax
IGrCircle(xpos,ypos,radius)

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

Effect
Draws a circle of a given radius centered at the specified absolute plotting position, in the current graphics color as selected by IGrColourN. 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.

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

Errors
ErrBadRadius (20)

radius <= zero. Nothing will be drawn.


Winteracter Starter Kit

133

Chapter 12

High Resolution Graphics

IGrLineTo Subroutine
Description
Draw line to a new absolute position.

Syntax
IGrLineTo(xpos,ypos)

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

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

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

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

Syntax
IGrMoveTo(xpos,ypos)

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

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

134

Winteracter Starter Kit

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

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

Syntax
IGrPoint(xpos,ypos)

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

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

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

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

Syntax
IGrPolygonComplex(x,y,nvert)

Arguments
REAL x(:) REAL y(:) = Array of X co-ordinates = Array of Y co-ordinates

INTEGER nvert = Number of vertices in supplied x/y arrays (<=4095)


Winteracter Starter Kit

135

Chapter 12

High Resolution Graphics


Draws an irregular polygon defined by the specified absolute plotting positions, with possibly intersecting borders. The polygon is drawn in the current graphics color as selected by IGrColourN. The polygon will be filled, if required, using the pattern set by IGrFillPattern. The polygon will be closed, i.e., the last point will be joined to the first. Up to 4095 vertices are allowed.
IGrPolygonComplex uses a Windows GDI primitive for solid and mixed-color fills. A generic scan-line search method is used for hatch fills. In very rare situations, a polygon may be too complex for IGrPolygonComplex's generic algorithm, in which case the routine will exit with error code 49. This is only likely to occur in very extreme cases.

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

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

Errors
ErrFillComplex (49)

Fill too complex. Unable to fill polygon.

Group GC: Graphics Character Output


This group provides routines to control graphics text output. The routine which actually writes graphics text strings is IGrCharOut. Hardware-dependent (i.e. TrueType) fonts are used by default. Alternatively, software defined character sets (outline or vector fonts) can be loaded from disk using IGrCharSet. The former look better, but the latter guarantee accuracy. The justification of graphics mode text can be controlled using IGrCharJustify. The size of text is set using IGrCharSize. By default text is monospaced, but proportional spacing is selectable via IGrCharSpacing. The relative length of a graphics text string (taking account of proportional spacing if enabled) is returned by the IGrCharLength function.

136

Winteracter Starter Kit

IGrCharJustify Subroutine

IGrCharJustify Subroutine
Description
Select graphics text justification.

Syntax
IGrCharJustify(justif)

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

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

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

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

Syntax
REAL IGrCharLength(string)

Arguments
CHARACTER string = String or character to measure
Winteracter Starter Kit

137

Chapter 12

High Resolution Graphics


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

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

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

Syntax
IGrCharOut(xpos,ypos,string)

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

Effect
Outputs string at the graphics co-ordinate (xpos,ypos). Color is as previously defined by IGrColourN. If a vector-based software character set has been selected, characters are drawn using a solid line style.

138

Winteracter Starter Kit

IGrCharSet Subroutine
The position of the text relative to (xpos,ypos) is determined by the most recent call to IGrCharJustify, and can be centered or left/right justified. The default is centered. Text is written horizontally. ypos specifies a position half-way up a character. In left/right justification mode the other coordinate specifies an extreme end of the string. On exit the current plotting position is updated to a point within the next character cell after the string which has been written. The exact position within the cell will depend on the current justification mode. The font/character set used by IGrCharOut is determined by IGrCharSet and IGrCharSpacing. The default is fixed space hardware (i.e. Courier New) characters. Text size is governed by IGrCharSize. Whichever justification or character set is used, text which would extend beyond the limits of the main graphics area (as defined by IGrArea) is clipped at the edge of that area. Text which would be completely outside the graphics area is not printed. Text written by this routine can contain both 7-bit and 8-bit characters, as defined in the ISO Latin-1 standard (i.e. character codes in the range 32-126 and 161-255).

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

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

Syntax
IGrCharSet(filnam)

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

Effect
Selects the character set to be used by future calls to IGrCharOut to output graphics text.
Winteracter Starter Kit

139

Chapter 12

High Resolution Graphics


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

Equivalent to PostScript Helvetica Equivalent to PostScript Courier

140

Winteracter Starter Kit

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

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

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

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

char set file') character set')

char set file')

Errors
ErrFileOpen (1)

Error opening file. The current character set selection remains in force. Error reading from file or unexpected end-of-file. Hardware-dependent text is selected and any in-memory character set is lost.
Winteracter Starter Kit

ErrFileIO

(2)

141

Chapter 12

High Resolution Graphics


ErrFileClose (3)

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

IGrCharSize Subroutine
Description
Select graphics text size.

Syntax
IGrCharSize(xsize,ysize)

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

Effect
Sets the size of characters printed by IGrCharOut. Width/height values of 1.0 give standard size text, corresponding to 75 columns by 25 rows. This character size is completely independent of window size, ensuring a consistent character size, regardless of the resolution of the display. Character sizes of 2.0, for example, would give text which is twice as wide and high as the default, but the X and Y sizes need not be the same. Text size is dependent on the size of the main graphics area as set by IGrArea. If IGrArea is called to rescale the size of this area, the size of graphics text is rescaled automatically. Hence, setting the width of the main graphics area to say 0.25 - 0.75, would give text which by default was half as wide, i.e., equivalent to 150 characters per line. This ensures that the size of text relative to other graphics in the main graphics area remains consistent regardless of the size of that area. However, text can quickly become unreadable in this situation, so it may be appropriate to call IGrCharSize to increase the character size when changing the main graphics area in this way. Hardware text is resizable, since TrueType Courier New or Arial fonts are used. However, Windows will not always give the exact font size requested. The default character size at initialization is 1.0 for both height and width. Attempting to select a size which is less than or equal to zero resets that size to 1.0. Text is written using fixed spacing by default, but proportionally spaced text is selectable via IGrCharSpacing('P'). When proportional spacing is enabled the exact number of characters which will fit in a given window width will vary according to what characters are

142

Winteracter Starter Kit

IGrCharSpacing Subroutine
actually printed. All proportional spacing is measured in terms of the equivalent fixed character spacing, so the size factor specified here is equally applicable to both fixed and proportionally spaced text.

Example
CALL 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
Description
Select fixed or proportional spacing for graphics text.

Syntax
IGrCharSpacing(fixprop)

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

Effect
Selects fixed or proportional character spacing. By default, fixed spacing is selected which causes all characters to occupy equally sized character cells. This makes text string lengths and individual character positions easy to calculate. When proportional spacing is selected, characters are spaced according to the width of a character (e.g., a W occupies nearly 3 times the width of an I). The length of a proportionally spaced string can be measured using IGrCharLength. All software character sets support proportional spacing. When hardware text is selected the effect of selecting fixed or proportional spacing is as follows: Proportional spacing A TrueType Arial font will be selected. Fixed spacing A Courier New font will be selected.
Winteracter Starter Kit

143

Chapter 12

High Resolution Graphics


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

144

Winteracter Starter Kit

13 General Functions

Group IF: Information


To help you find out exactly what facilities are available on the current system or to simply interrogate the state of Winteracter variables, a number of functions and subroutines are provided to return information to the calling program. In all cases one call to an IF group routine returns one item of information. The routines in this group fall into two categories: INTERACTER compatible Info functions Winteracter specific WInfo routines

Logically there is no particular difference between these two sets of routines. Their names simply differ to reflect the above separation. In all cases, specifying an invalid information item number to an IF group routine returns an undefined result.

InfoError Function
Description
Return error information.

Syntax
INTEGER InfoError(item)
Winteracter Starter Kit

145

Chapter 13

General Functions
Arguments
INTEGER item = Number of information item required: Table 18: Error Information items
Name LastError No. 1 Information

Last error set by Winteracter (0 if no errors since last call to InfoError(1)) I/O code for last type 1 or 2 error (file open or read/write error), otherwise undefined Operating system error code

IOErrorCode OsErrorCode

2 3

Effect
Returns information about the last error to be detected. If no errors have occurred since startup or since the last call to InfoError, the last error is returned as zero. If several errors have occurred since the last call to InfoError, only the most recent error is returned. A call to InfoError also resets the corresponding error flag (depending on the value of item) to zero. This feature can be used to clear the error flags, when your program is uncertain of what errors may already have occurred. If a type 1 or type 2 error occurs (error on file/device open, read or write), a call with an item value of 2 returns the associated Fortran OPEN/READ/WRITE statement IOSTAT value or Windows I/O routine error code. This IOSTAT value will still be available if further I/O is performed or other non I/O errors occur. i.e., The error code for an I/O error remains available until it is cleared by interrogating InfoError(2) or until another I/O error occurs. item 3 returns the error code set by internal operating system interface routines, such as those used by WSelectFile. Typically this value will only be set when item 1 returns a value of 13 (Operating system command error). This will be an internal Windows error code.As for the IOSTAT value described above, this return code remains available until it is cleared by interrogating InfoError(3) or until another o.s. error occurs.

Example
CHARACTER (LEN=6) :: STR ! clear error flag first IErrorOld = InfoError(1) IStatOld = InfoError(2) CALL IGrCharSet('badname.chr') IError = InfoError(1) IF (IError==1.OR.IError==2) THEN CALL WindowOutString(IX,IY,'Load error') IStat = InfoError(2)

146

Winteracter Starter Kit

InfoGraphics Function

InfoGraphics Function
Description
Return real graphics mode information.

Syntax
REAL InfoGraphics(item)

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

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

GraphicsY

GraphicsChWidth

GraphicsChHeight GraphicsAreaMinX GraphicsAreaMinY GraphicsAreaMaxX GraphicsAreaMaxY GraphicsUnitMinX GraphicsUnitMinY GraphicsUnitMaxX GraphicsUnitMaxY

4 7 8 9 10 11 12 13 14

Effect
Returns certain REAL graphics mode parameters. These are generally dynamic values which change depending on calls to other graphics routines. See also InfoGrScreen which returns INTEGER data, mainly describing the capabilities of the current display.
Winteracter Starter Kit

147

Chapter 13

General Functions
The current plotting position, as set by IGrMoveTo and other routines, is accessible using item values 1 and 2. The current graphics text character size (item's 3 and 4) is derived from the size set using IGrCharSize and converted to user plotting units. This can be useful in calculating the extent of a graphics string to be output by IGrCharOut. item's 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.

Example
! 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(Solid) CALL RECTANGLE(WIDTH,HEIGHT) CALL IGrCharSet(' ') CALL IGrCharJustify('L') CALL IGrColourN(159) CALL IGrCharOut(X,Y+HEIGHT/2.0,STRING)

InfoGrScreen Function
Description
Return graphics facilities information (screen).

Syntax
INTEGER InfoGrScreen(item)

Arguments
INTEGER item = Number of information item required: Table 20: Graphics Screen Information items
Name ColNumAvailable AspectRatio No. 30 32 Information

Number of colors availablee Aspect ratio as a percentage

148

Winteracter Starter Kit

WInfoDialog Function
Table 20: Graphics Screen Information items
Name PrevColReq ColorReq LineTypeReq No. 34 35 36 Information

Last but one requested graphics color Most recently requested color Most recently requested line type

Effect
Returns information about the graphics facilities available on the current display in the current mode. The value returned is an INTEGER. item number 30 return the number of selectable colors (see IGrColourN for details of how this is determined). item 32 returns the aspect ratio of the current window is returned as a percentage. For example, in a window with an aspect ratio of 1.4, a value of 140 would be returned. This aspect ratio is used internally by Winteracter when drawing circles, but can also be useful in applications which require a shape to be rotated without distortion. item's 34 and 35 return the last two color numbers which have been requested. The color returned by item 34 is only used in mixed-color fills. item 36 returns the last line type requested via IGrLineType.

WInfoDialog Function
Description
Return dialog information.

Syntax
INTEGER WInfoDialog(item)

Arguments
INTEGER item = Number of information item required. Table 21: Dialog Information items
Name No. Information

ExitButton ExitField

1 2

Identifier of button used to terminate program-supplied modal dialog Current field when modal dialog terminated

Winteracter Starter Kit

149

Chapter 13

General Functions
Table 21: Dialog Information items
Name No. Information

CurrentDialog ExitButtonCommon DialogXPos DialogYPos DialogWidth DialogHeight

3 4 6 7 8 9

Identifier of current dialog, 0 = none Button used to terminate common dialog (0-2) Current dialog X position Current dialog Y position Current dialog width Current dialog height

Effect
Returns dialog information. This routine can be called after a modal or common dialog function call has terminated. item 1 returns the identifier of the push button used to exit a program supplied modal dialog. If an error occurred in the dialog, -1 is returned. Commonly used identifiers (e.g. IDOK and IDCANCEL which are typically attached to the OK and Cancel buttons) are defined in the WINTERACTER module. See the PushButton message under WMessage for a list. The actual button codes will depend on the definition of the particular dialog. item 2 returns the identifier of the last active field before a dialog terminated. This can be useful if a Help button is pressed, to provide context sensitive help. This return value is not available for common dialogs. item 3 returns the current dialog identifier, as set by WDialogLoad or WDialogSelect. Note, this is not necessarily the same as the dialog that has the current input focus. item 4 returns a code which indicates which button was used to terminate a common dialog in the CD group: Table 22: Common Dialog Termination Codes
Name No. Button

CommonCancel CommonIgnore CommonOK CommonOpen CommonYes

0 0 1 1 1

Cancel Ignore OK Open Yes

150

Winteracter Starter Kit

WInfoFont Function
Table 22: Common Dialog Termination Codes
Name No. Button

CommonRetry CommonAbort CommonNo

1 2 2

Retry Abort No

item's 6 and 7 return the position of the current dialog as selected by WDialogLoad or WDialogSelect. The returned values are in pixels relative to the top left corner of the screen for a popup dialog. For a child dialog, the returned values are in W interacter window units, relative to the top left corner of the root window. item's 8 and 9 return the width and height of the current dialog, in the same units as items 6 and 7.

Example
CALL WDialogLoad(ID_DIALOG1) CALL WDialogShow(-1,-1,Modal,0) IF (WinfoDialog(ExitButton).EQ.IDOK) THEN CALL WDialogGetString (IDC_STRING1,CVALUE) END IF CALL WDialogUnload()

WInfoFont Function
Description
Return font information.

Syntax
INTEGER WInfoFont(item)

Arguments
INTEGER item = Number of information item required. Table 23: Font Information items
Name No. Information

FontXPos FontYPos

1 2

Output cursor X position Output cursor Y position

Winteracter Starter Kit

151

Chapter 13

General Functions
Table 23: Font Information items
Name No. Information

FontBold FontItalic FontUnderline FontForeCol FontBackCol FontStyleNum FontWidth FontHeight

3 4 5 6 7 8 9 10

Bold (0=off 1=on) Italic (0=off 1=on) Underline (0=off 1=on) Foreground color index Background color index Currently selected font number Current font width Current font height

Effect
Returns information about the routines in the TX/FS groups. items 1 and 2 return the current output cursor X/Y position, i.e the end of the string most recently output via the routines in the TX group. The initial position is (0,0). The values are returned in Winteracter window units. item's 3, 4 and 5 return binary flags to indicate the currently requested states of the bold, italic and underlined attributes. All will be off by default. item's 6 and 7 return the current foreground/background color index numbers (i.e. 0- 16). item 8 returns the most recently requested font number, as set by WindowFont. This will be zero (SystemProportional) initially. item's 9 and 10 return the current font width and height as reported by the Windows API, expressed in Winteracter window units. This may be different to the requested font size. For proportionally spaced fonts the width value will be the average character width.

Example
CALL WindowFont(FONT) IXWID = WInfoFont(FontWidth) ! Get the actual font width IYWID = WInfoFont(FontHeight) ! Get the actual font height

152

Winteracter Starter Kit

WInfoScreen Function

WInfoScreen Function
Description
Return screen information.

Syntax
INTEGER WInfoScreen(item)

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

ScreenWidth ScreenHeight ScreenColours

1 2 3

Screen Width Screen Height Number of screen colors

Effect
Returns information about the current screen. This information is available immediately after WInitialise has been called, allowing the results of this function to be used to determine the required root window size. item's 1 and 2 return the screen resolution, in pixels, for the video mode which was selected when WInitialise was called. If a dynamic video mode changer (e.g. QuickRes) is used subsequently, the new screen dimensions will not be updated. item 3 returns the total number of screen colors available in the current screen mode when WInitialise was called. Note this is different to the number of colors used by Winteracter graphics. See IGrColourN.

Example
TYPE (WIN_STYLE) :: WIN CALL WInitialise(' ') ISCRWID = WInfoScreen(1) ! Get screen width ISCRHGT = WInfoScreen(2) ! Get screen height WIN%WIDTH = ISCRWID / 2 ! Set window to half screen width WIN%HEIGHT = ISCRHGT / 3 ! Set window to third screen height ! set up rest of WIN structure here ... CALL WindowOpen(WIN) ! Open window

Winteracter Starter Kit

153

Chapter 13

General Functions

WInfoWindow Function
Description
Return window information.

Syntax
INTEGER WInfoWindow(item)

Arguments
INTEGER item = Number of information item required. Table 25: Window Information items
Name No. Information

WindowWidth WindowHeight OpenFlags WindowHandle WindowXPos WindowYPos ClientXPos ClientYPos

1 2 3 4 5 6 7 8

Current window width Current window height Window style flags Current window handle Current window X position Current window Y position Current window client-area X position Current window client-area y position Current window state : WinMinimised (0) : minimised WinNormal (1) : normal size WinMaximised (2) : maximised

WindowState

Effect
Returns window related information. item's 1 and 2 return the dimensions of the current root or child window as selected by WindowSelect, WindowOpen or WindowOpenChild. The returned values are in pixels. item 3 returns the flags value specified in the original WindowOpen or WindowOpenChild call.

154

Winteracter Starter Kit

Group OS: Operating System Interface


item 4 returns the Winteracter handle of the current window. This will be zero for the root window or 1-20 for a child window. item's 5 and 6 return the position of the current root or child window as selected by WindowSelect, WindowOpen or WindowOpenChild. The returned values are in pixels relative to the top left corner of the screen for a root or floating child window. For an inside root child window, the returned values are in Winteracter window units, relative to the top left corner of the root window. item's 7 and 8 return the position of the top left corner of the 'client' area of the current window (i.e. the drawable area within the frame). This is always expressed in pixels relative to the corner of the screen. item 9 returns the minimised/normal/maximised state of the currently selected window.

Example
TYPE (WIN_STYLE) :: WIN IWINWID = WInfoWindow(1) ! Get IWINHGT = WInfoWindow(2) ! Get WIN%WIDTH = IWINWID / 2 ! Set WIN%HEIGHT = IWINHGT / 2 ! Set CALL WindowOpenChild(WIN,IHANDLE) parent window parent window child to half child to half width height width of parent height of parent

Group OS: Operating System Interface


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

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

Syntax
IOsExitProgram(errmes,iexcod)

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

155

Chapter 13

General Functions
Effect
Aborts the current program, using a standard message box with the message string Abnormal exit (code nn) followed by the supplied error message. This routine is designed to be used when an unexpected fatal error is encountered. If the error message is blank, the program terminates without a message box. The supplied exit code is returned to Windows via the API ExitProcess function. In general, it is recommended that exit codes greater than 20 are used. Codes 1-20 are reserved for use by Winteracter. If you wish to leave a program immediately, but without issuing either an error message or a non-zero exit code, simply supply a blank error message and an IEXCOD value of zero.

Example
INQUIRE(FILE=MYDATA.DAT,EXIST=EXISTS) IF (.NOT.EXISTS) CALL IOsExitProgram('Data file not found,21)

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

Syntax
IOsVariable(vname,value)

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

Effect
Returns the value of the specified environment variable. If the specified variable name has not been initialized or has no value, value will be returned blank. Windows converts all variable names to upper case, so the supplied variable name must also be in upper case. IOsVariable strips trailing blanks from the supplied variable name.

156

Winteracter Starter Kit

Group MI: Miscellaneous


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

Group MI: Miscellaneous


This group is for routines which have no obvious home elsewhere. The important routine in this group is WInitialise. It must be called in every Winteracter program before opening a window. WindowBell is provided to ring the bell and to control whether other routines ring the bell.

WindowBell Subroutine
Description
Ring/enable/disable the bell.

Syntax
WindowBell(onoff)

Arguments
CHARACTER onoff = 'ON'or OFF to enable/disable the bell Any other value to ring bell if currently enabled

Effect
By default the bell is enabled so a call to WindowBell with a blank argument would ring the bell. However, in some environments the bell can become irritating if used frequently. To stop WindowBell producing any sound, the on/off option is provided. This simply controls the action taken by WindowBell when an argument other than 'ON' or 'OFF' is supplied.
Winteracter Starter Kit

157

Chapter 13

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

WInitialise Subroutine
Description
Initialize Winteracter.

Syntax
WInitialise(initfile)

Arguments
CHARACTER initfile = Initialization file name (not used in Starter Kit)

Effect
WInitialise must be called to initialize the library before calling any other Winteracter screen i/o routines. initfile should be specified as a blank when linking with the Starter Kit version of Winteracter. WInitialise identifies the current screen dimensions and number of available screen colors. This information then becomes available via WInfoScreen. This information may prove useful when selecting the initial window size/position in the subsequent call to WindowOpen. Bear in mind that WInitialise performs no screen output and does not open a window. That is the task of WindowOpen and the other Winteracter routines. This routine should only called once per program run. Subsequent calls to WInitialise will therefore be ignored and no values will be altered.

158

Winteracter Starter Kit

Group CH: Character Manipulation


Example
PROGRAM ! Variables, modules, etc. here CALL WInitialise(' ') ! Initialize : ! Winteracter program code : STOP END PROGRAM

Group CH: Character Manipulation


The routines in this group are not strictly user interface functions. However, since any UI code involves considerable manipulation of textual information, they provide useful basic facilities such as string to numeric conversion, sub-string location, case conversion and so on. Some duplicate Fortran 90 intrinsics, but are required internally by Winteracter.

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

Syntax
INTEGER IActualLength(string)

Arguments
CHARACTER string = String to search

Effect
Returns an INTEGER with the actual length of the character string held in string, excluding any trailing spaces or nulls. If the string is completely blank, (i.e., only contains spaces and/ or nulls) zero is returned. IActualLength is a replacement for the standard LEN function which simply returns the length of a character variable not the length of the string which is held in it. It also provides an alternative to the Fortran 90 LEN_TRIM intrinsic which treats nulls as significant characters.

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

Winteracter Starter Kit

159

Chapter 13

General Functions

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

Syntax
IFillString(string,chr)

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

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

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

IJustifyString Subroutine
Description
Justify a string within a character variable.

Syntax
IJustifyString(string,lcr)

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

Effect
Justifies a string within the character variable which holds it.

160

Winteracter Starter Kit

ILocateChar Function
Note that in the sense used here, a "string" is defined as all characters from the first non-blank character to the last non-blank character within the character variable string. Since IJustifyString justifies the string within the supplied variable itself, string must be passed as a variable rather than as a literal string. If string is blank, IJustifyString takes no action.

Example
CHARACTER (LEN=14) :: TITLE TITLE = ' Test Results ' CALL IJustifyString(TITLE,'L') ! variable TITLE will now contain: 'Test Results ' CALL IJustifyString(TITLE,'C') ! variable TITLE will now contain: ' Test Results ' CALL IJustifyString(TITLE,'R') ! variable TITLE will now contain: ' Test Results'

ILocateChar Function
Description
Locate position of first non blank character.

Syntax
INTEGER ILocateChar(string)

Arguments
CHARACTER string = String to search

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

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

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

161

Chapter 13

General Functions
Syntax
ILocateString(string,istart,iend)

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

Example
CHARACTER (LEN=80) :: STRING READ(LFN,'(A80)') STRING CALL ILocateString(STRING,ISTART,IEND) IF (ISTART>0) & CALL WindowOutString(100,300, & 'First substring is '//STRING(ISTART:IEND))

ILowerCase Subroutine
Description
Convert a string to lower case.

Syntax
ILowerCase(string)

Arguments
CHARACTER string = String to be converted to lower case

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

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

162

Winteracter Starter Kit

IntegerToString Subroutine

IntegerToString Subroutine
Description
Convert an integer value to a string.

Syntax
IntegerToString(ivalue,string,frmat)

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

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

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

Errors
ErrNumToStr (18)

Numeric-to-string conversion error.

IStringToInteger Subroutine
Description
Convert a string to an integer value.

Syntax
IStringToInteger(string,ivalue)

Arguments
CHARACTER string = String containing number to be converted. INTEGER ivalue = Value to be returned
Winteracter Starter Kit

163

Chapter 13

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

Example
CHARACTER (LEN=80) :: LINE CHARACTER (LEN=10) :: VALSTR CALL WDialogGetString(IFIELD,LINE) CALL IStringToInteger(LINE,IVALUE) IF (InfoError(1)>0) THEN CALL WindowOutString(IX,IY,'Wrong !!') ELSE CALL IntegerToString(IVALUE,VALSTR,'(I10)') CALL WindowOutString(IX,IY,'Value = '//VALSTR) END IF

Errors
ErrLargeNum ErrNoSubstring ErrBadChar (4) (10) (12)

Number too large (exceeds 4-byte INTEGER limits) No substring found (string is blank) Invalid character detected (i.e. not 0123456789 or leading +/-)

IUpperCase Subroutine
Description
Convert a string to upper case.

Syntax
IUpperCase(string)

Arguments
CHARACTER string = String to be converted to upper case

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

164

Winteracter Starter Kit

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

Winteracter Starter Kit

165

Chapter 13

General Functions

166

Winteracter Starter Kit

14 Glossary

Accelerators: A keyboard short cut to a menu item. Defined via MenuEd and stored in the resource file. BMP or Windows Bitmaps: A pixel based graphics format for storing and retrieving image data, developed for the Windows operating system. BMP files can be read or written by numerous third party packages. Winteracter can display BMP files in several different dialog field types. Check Box Fields: A small square field ( with a 3D edge in Windows 4 ) which contains a cross or tick which can be toggled off and on by the user. They are usually associated with a description label. Child Dialog: A dialog that cannot be moved outside of its parent window. Child Windows: These are windows created after the root window has been opened. They can be made to be moveable anywhere on-screen or restricted to inside of the root window. Winteracter allows up to 20 child windows to be created. Combo Box: See Menu Fields. Dialogs: Dialogs are the main Windows method of obtaining information from the user. Other development systems refer to them as forms or panels. Dialogs can contain various field types and styles. They are created and managed using DialogEd, the Winteracter dialog resource editor. Environment Variables: These are operating system variables with an associated string value, which are defined in your AUTOEXEC.BAT (Windows 3.1 & 95) or Registry (Windows 95/NT) or they can be defined via the DOS prompt. Expose Messages: When a window that is overlapped by another window or dialog is moved to the front of the screen the overlapped, or exposed, areas need to be redrawn. This action causes a Expose message to be sent to the program (via WMessage) reporting which area needs redrawing. Fixed Spaced Text: See Mono Spaced Text.
Winteracter Starter Kit

167

Chapter 14

Glossary
Fixed Window Size: This is a special window attribute that stops a root or child window from being resized by the user. Group Box: A square box outline usually used to visually group fields within a dialog. An optional title can be specified. Hardware Text: In the context of WiSK graphics text output, these are TrueType fonts. (In the full version of Winteracter they refer more generally to hardware-specific fonts.) Hidden Root Window: The root window need not be visible. The initial WindowOpen call allows it to be hidden. Data input via dialogs and and output to child windows can still be performed. Icon: A pixel based bitmap, like a BMP file except that the background is transparent. Icon files usually have a .ico extension. Typically icons come in standard sizes (e.g. 16x16, 32x32, etc.) Icons can be displayed in dialogs. Each program has its own icon which is displayed by Explorer (or Program Manager), which should always be referenced as icon1 in the resource script. Inside-Root Child Window: A child window that cannot be moved outside of its parent (or root) window. List Box: See Menu Fields. Maximised Window: A window that is opened or resized to fill the entire parent window (in the case of an inside-root child window) or the entire screen (root windows and other child windows). Maximise Button: A button on the right hand corner of the window title bar that makes the window fill the entire screen or root window, depending on the type of window which the button is attached to. Pressing this button for inside-root child windows will make the child window fill the entire drawable area of the root window. Menu Fields: There are four types of menu which can appear in a dialog: Simple Combo Box: This consists of a string field (into which any value may be typed by the user) and a list of pre-set options. Drop Down Combo Box: This also consists of a string field and a list of options, except that the list is hidden until the user displays it using the button at the right of the string field. Drop Down List Combo Box: This is similar to the Drop Down Combo Box except that only the listed options may be chosen. List Box: This is a simple, permanently visible list.

168

Winteracter Starter Kit

Messages: These are Windows (and therefore Winteracters) method of passing data from the system to a program. Messages include key pressed, mouse button clicked, menu item selected etc. Each message consists of several items of information passed in a Fortran 90 data structure (e.g. Which mouse button was pressed? Where was the mouse cursor at the time? etc.) Minimise Button: A button on the right hand corner of the window title bar. It causes the window to be hidden. The Windows becomes an icon (Windows 3.x) or button (Windows 4). The location of the icon/button depends on what type of window the Minimise button is attached to. Inside-root child windows minimise within the root window. Other types of window minimise to the bottom of the screen (Win 3.x) or task bar (Win 4). Modal Dialogs: These are dialogs which block program execution. A program only continues when the user has completed their input and closed the dialog. Modal dialogs cannot have the child dialog style. Other dialogs or windows belonging to the same program cannot be selected while a modal dialog is active. Modal dialogs are removed from the screen once a push-button (or equivalent, e.g. Escape) is pressed. Modeless Dialogs: These are types of dialog that do not block program execution. The dialog is displayed and the program continues. When the user changes fields or presses buttons messages are sent back to the main program. Modeless dialogs can have popup or child dialog styles. Other dialogs and windows can be selected. See also Semi-Modeless dialogs which provide a hybrid between modal and modeless dialogs. Mono Spaced Text: Each character within the text font is given the same width value so text is evenly spaced across the screen. A common mono spaced font is Courier (the Windows-specific variant is known as Courier New). Outline Fonts: Fonts that are defined as a set of points that describe the outline of the font. When output, the outline is filled to give a solid text character. The Windows implementation of such fonts are called TrueType fonts. Winteracters graphics text routines support our own software based outline fonts and TrueType fonts. Pixel: A single addressable unique point on the screen with its own RGB value. The number of pixels on a screen is device dependant. Winteracter uses pixel units for certain types of window/dialog placement and dimensions. Popup Dialog: A dialog that can be moved anywhere on-screen. Proportional Spacing: Each character in a font is given its own spacing value. For example an i occupies a narrower space than a W. This gives text a more realistic appearance. Most text output (such as this document) is formatted using proportionally spaced fonts. A typical proportional font is Times New Roman. Push Button Fields: These are raised buttons on a dialog that are used to confirm an action. They can have an attached string description or even an icon or bitmap image (under Windows 4). When a button is pressed a dialog will either terminate (modal) or return a PushButton message (modeless or semi-modeless).
Winteracter Starter Kit

169

Chapter 14

Glossary
Radio Button Fields: These are a group of check-boxes within a dialog, only one of which may be selected at one time. Selecting one member of a radio button group turns off all other members of the group. Resize Messages: When the user resizes a window, the new size information is passed back to the calling program via a Resize message. This tells the program the new window dimensions. The window contents usually need to be redrawn to match the new window size. Winteracter automatically adjusts its internal scaling factors to match the new window size. Window resizing can be disabled by specifying FixedSizeWin as part of the window style when calling WindowOpen or WindowOpenChild. Resource Scripts: This is an ASCII based format that describes dialogs, menus, icons, bitmaps, etc. These scripts are compiled using the resource compiler supplied with your Fortran compiler (usually RC.EXE). The resulting file is then linked into the executable using the linker. The resource data is then automatically available to Winteracter at run-time. The main advantage of resource scripts is that your user-interface look and feel can usually be adjusted without the need to alter your source code. This should normally be done via DialogEd and MenuEd.. RGB: Red Green Blue colour encoding. Each element of an RGB triplet is given a value of 0 to 255. So an RGB value of (255, 0, 0) is pure red and (255, 255, 255) is pure white. The RGB colour model allows for up to 16.8 million different colours to be described. Root Menu: This is the horizontal menu that is attached to the root window. This includes the drop-down menus which form part of the root menu structure. Root menus are created via MenuEd and stored in the resource script.. Each menu structure has a unique identifier which can be specified when the window is opened or during program execution. Only root windows may have a root menu. Root Window: This is the first window opened in a Winteracter program using the WindowOpen routine. Root windows contain the program menu, where selected. They can optionally be hidden from view. Only one root window may be open at any time. Semi-Modeless Dialogs: These are hybrid dialogs that appear modal to the user but modeless to the programmer. This means that when a semi-modeless dialog is opened, user input to other dialogs or windows belonging to the current program are blocked but the program code continues to run. Software Text: Graphics text can be written using Winteracter-specific software fonts, via the IGrCharOut routine. Both outline and vector based software fonts are provided. They were designed to be highly portable across all types of output device. In the specific context of WiSK, hardware text is normally preferable (i.e. TrueType fonts). Software character sets mainly provide compatibility with codes written for the DOS version of LISK (The Lahey INTERACTER Starter Kit). String Fields: These fields allow the input of character data. They can be single or multiline and can scroll horizontally or vertically.

170

Winteracter Starter Kit

System Menu: This is accessed by clicking on the icon at the far left of the window or dialog title bar. It is also accessible via a right-click on the title bar under Windows 4. The System Menu contains various window related options such as Maximise, Restore, etc. Winteracter allows the developer to turn this menu off to prevent windows and dialogs being closed unintentionally. Window Handle: This is a value that identifies a window uniquely. No two Winteracter windows will be given the same handle. The root window always has a handle of zero. Window handles for child windows are obtained via WindowOpenChild. Windows API: This is the Application Programming Interface supplied by Microsoft to program software for its Windows platforms. The API is a complex set of interacting subroutines, structures and functions that can be used to manipulate all aspects of Windows. Winteracter uses many API functions internally. Winteracter is designed to hide many of the complexities of the Windows API. Windows Input Focus: This is the current window or dialog that all mouse and keyboard messages get sent to. This is usually displayed at the front of the screen. Winteracter Output Focus: This is the window that Winteracter text and graphics are sent to. When output is sent to a window it need not be at the top of the window stack (i.e. it need not be fully visible). The output focus is determined by WindowSelect or the most recent call to WindowOpen or WindowOpenChild. Winteracter Graphics Units: These are program-definable, device independent units which determine the co-ordinate range for Winteracter graphics output. They are set via IGrUnits and default to 0-1 in both X and Y. They are mainly used by routines in the GD/GC subroutine groups. Winteracter Text Units: These are screen independent units for Winteracter text output. Each window is assigned a width and height of 10000 units, regardless of its size. These units are used to place text and child windows/dialogs within a window. Mainly used by routines in the TX and CL subroutine groups.

Winteracter Starter Kit

171

Chapter 14

Glossary

172

Winteracter Starter Kit

Index
A
Accelerators 21, 52, 167 Area Clearing 80 Assign/Retrieve Fields 104 ErrNoSubstring 65 ErrNumToStr 65 Error Codes 65 Error Reporting 7 Events 9 Expose Messages 167 IGrCharSpacing Subroutine 143 IGrCircle Subroutine 133 IGrColorN Subroutine 125 IGrFillPattern Subroutine 128 IGrGetPixelRGB 121 IGrGetPixelRGB Subroutine 121 IGrInit Subroutine 122 IGrLineTo Subroutine 17, 134 IGrLineType Subroutine 130 IGrMoveTo Subroutine 134 IGrPaletteInit Subroutine 131 IGrPaletteRGB Subroutine 132 IGrPause Subroutine 123 IGrPoint Subroutine 135 IGrPolygonComplex Subroutine 135 IGrUnits Subroutine 11, 124 IJustifyString Subroutine 160 ILocateChar Function 161 ILocateString Subroutine 161 ILowerCase Subroutine 162 INCLUDE Environment Variable 4 InfoError Function 7, 65, 145 InfoGraphics Function 147 InfoGrScreen Function 148 Information 145 Input Handling 85 Inside-Root Child Windows 168 IntegerToString Subroutine 163 IOsExitProgram Subroutine 155 IOsVariable Subroutine 156 IStringToInteger Subroutine 163 IUpperCase Subroutine 164

B
Base Item Value 24 Base Menu Value 24 Bitmap Files 62 Bitmaps 46, 62 BMP or Windows Bitmaps 167 Border Properties 44

F
F90 Module Name Field 24 Field Types 55 Fixed Spaced Text 167 Fixed Window Size 168 Font Selection 81 FONT Statement 54 Font Style 24

C
Character Manipulation 159 Check Box Fields 39, 167 Child Dialogs 167 Child Windows 167 Combo Box 167 Common Dialogs 112 CONTROL Statement 54 Coordinate System 10

G
General Dialog Management 99 General Functions 145 General Graphics 119 Graphics Character Output 136 Graphics Drawing/Movement 133 Graphics Style Selection 124 Group Box 168 Group Box Fields 34

D
Dialog Definition 53 Dialog Manager 97 DIALOG Statement 53 DialogEd 8, 10, 27, 49 Dialogs 10, 167 Drop Down Combo Box 168 Drop Down List Combo Box 168

H
Hardware Text 168 Hidden Root Window 168 High Resolution Graphics 119 Highlight Colour 24

E
ED for Windows 4 Environment Variables 167 ErrBadArea 65 ErrBadChar 65 ErrBadColor 65 ErrBadRadius 65 ErrBadUnits 65 ErrFileClose 65 ErrFileIO 65 ErrFillComplex 65 ErrLargeNum 65

I
IActualLength Function 159 Icons 46, 63, 168 Identifiers 8 IFillString Subroutine 160 IGrArea Subroutine 120 IGrAreaClear Subroutine 121 IGrCharJustify Subroutine 137 IGrCharLength Function 137 IGrCharOut Subroutine 138 IGrCharSet Subroutine 139 IGrCharSize Subroutine 142

K
Keyboard Input 20, 28

L
Label Fields 32 List Box 168

M
Maximise Button 168 Maximised Window 168 Menu Colour 24

Winteracter Starter Kit

173

Index

Menu Fields 43, 168 Menu Handling 92 MENU Statement 50 MenuEd 8, 10, 19, 25, 49 MENUITEM 50 Menus 10 Message 9 Message Handling 85 Message Queue 9 Messages 169 Minimise Button 169 Modal Dialogs 169 Modeless Dialogs 169 Mono Spaced Text 169 Mouse Input 19, 27

String Fields 36, 170 String Table 63 Subroutine Arguments 6 Symbol Header File 8 Symbol Header File Type 24 System Menu 171

T
Text Output 78

W
WDialogGetCheckBox Subroutine 105 WDialogGetMenu Subroutine 105 WDialogGetString Subroutine 106, 107 WDialogHide Subroutine 99 WDialogLoad Subroutine 11, 100 WDialogPutCheckBox Subroutine 108 WDialogPutMenu Subroutine 109 WDialogPutOption Subroutine 110, 111 WDialogPutString Subroutine 112 WDialogSelect Subroutine 101 WDialogShow Subroutine 11, 101 WDialogUnload Subroutine 104 WIN_STYLE 12 WIN_STYLE Structure 6 Window Handle 171 Window Management 71 WindowBell Subroutine 157 WindowClear Subroutine 80 WindowClearArea Subroutine 80 WindowClose Subroutine 11, 71 WindowCloseChild Subroutine 72 WindowFont Subroutine 81 WindowOpen Subroutine 10, 11, 12, 73 WindowOpenChild Subroutine 10, 11, 75 WindowOutString Subroutine 79 Windows 10 Windows API 171 Windows Input Focus 171 WindowSelect Subroutine 10, 77 WindowStringLength Function 79 WInfoDialog Function 149 WInfoFont Function 151 WInfoScreen Function 153

N
Names 6

WInfoWindow Function 154 WInitialise Subroutine 11, 158 WINPARAM.H 4, 49 WINTER.LIB 4 Winteracter Graphics Units 171 WINTERACTER Module 4, 6 Winteracter Output Focus 171 Winteracter Text Units 171 WMenuGetState Function 92 WMenuRoot Subroutine 10, 93 WMenuSetState Subroutine 10, 94 WMenuSetString Subroutine 95 WMessage Subroutine 9, 10, 85 WMessageBox Subroutine 113 WMessageEnable Subroutine 91 WMessagePeek Subroutine 91 WSelectFile Subroutine 115

O
Operating System Interface 155 Outline Fonts 169

P
Picture/Frame fields 33 Pixel 169 Popup Dialog 169 POPUP Statement 51 Proportional Spacing 169 Push Button Fields 37, 169

R
Radio Button Fields 41, 170 RC Resource Compiler 19, 27 RCDATA Resource 61 RES2OBJ 8, 19, 27 Resize Messages 170 Resource Compiler 4 Resource Script 8, 19, 49, 170 RESOURCE.RC 3 RGB 170 Root Menu 170 Root Window 170

S
Screen I/O 5 Semi-Modeless Dialogs 170 Simple Combo Box 168 Software Text 170

174

Winteracter Starter Kit

Potrebbero piacerti anche