0% found this document useful (0 votes)

149 views452 pages

Clear Win

The ClearWin+ User's Guide provides comprehensive instructions for using the ClearWin+ library with Salford Fortran compilers to develop Windows applications. It covers various topics including getting started, format windows, input/output, and graphics, while emphasizing the ease of use compared to the Windows API. The guide also includes tutorials, programming tips, and a library overview to assist developers in creating professional and user-friendly applications efficiently.

Uploaded by

carlos fernando castillo espinoza

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

149 views452 pages

Clear Win

Uploaded by

carlos fernando castillo espinoza

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

&OHDU:LQ

Fortran Edition
Table of Contents

1. Introduction ............................................................................................................ 1
Windows applications............................................................................................................................................................... 1
The ClearWin+ library ............................................................................................................................................................. 1
How to use this guide................................................................................................................................................................ 2

2. Getting started ........................................................................................................ 5

3. ClearWin+ tutorial................................................................................................... 7

4. Format windows ................................................................................................... 19

5. Input and output ................................................................................................... 37

Interactive I/O .........................................................................................................................................................................37
Data output .............................................................................................................................................................................45

6. Button controls..................................................................................................... 51

7. Controls other than buttons................................................................................. 61

8. Bitmaps, Cursors, Icons....................................................................................... 75

9. Menus and accelerator keys................................................................................. 81

Contents-1
ClearWin+ User’s Guide Fortran

10. Layout and positioning ........................................................................................ 89

11. Displaying text ...................................................................................................... 97

Displaying text........................................................................................................................................................................ 97
Edit boxes.............................................................................................................................................................................. 103
File selection and filter.......................................................................................................................................................... 105

12. Edit box (%eb)..................................................................................................... 107

13. Help...................................................................................................................... 119

14. Window attributes............................................................................................... 121

15. Graphics .............................................................................................................. 135

Introduction........................................................................................................................................................................... 135
Graphics format %gr[options] ............................................................................................................................................. 136
Basic graphics primitives...................................................................................................................................................... 138
Drawing text ......................................................................................................................................................................... 138
Re-sizing a graphics surface ................................................................................................................................................. 141
The %gr call-back function .................................................................................................................................................. 142
Graphics selections ............................................................................................................................................................... 143
Drawing device independent bitmaps................................................................................................................................... 145
Direct manipulation of the graphics surface......................................................................................................................... 148
Off-screen graphics ............................................................................................................................................................... 150
Graphics icons....................................................................................................................................................................... 152
Windows graphic modes....................................................................................................................................................... 154
Owner draw box format - %dw[options] ............................................................................................................................. 157
Updating the screen............................................................................................................................................................... 159

16. OpenGL ............................................................................................................... 161

Contents-2
Table of Contents

17. SIMPLEPLOT....................................................................................................... 181

18. Using the printer ................................................................................................. 189

19. Hypertext windows ............................................................................................. 199

Hypertext %N.Mht ................................................................................................................................................................199
Conditional Hypertext...........................................................................................................................................................203
Linking to the web ................................................................................................................................................................204

20. Standard call-back functions ............................................................................. 205

A simple text editor...............................................................................................................................................................212

21. Format code reference ....................................................................................... 215

22. Compiling and linking ........................................................................................ 293

Compiler options and directives for Windows .....................................................................................................................293
SLINK commands ................................................................................................................................................................295
Using the Salford Resource Compiler ..................................................................................................................................296
FTN95...................................................................................................................................................................................297

23. ClearWin windows .............................................................................................. 299

24. Using the Windows API...................................................................................... 305

Calling Windows API routines from Fortran .......................................................................................................................305
The Fortran STDCALL statement........................................................................................................................................306

Contents-3
ClearWin+ User’s Guide Fortran

The Fortran STOP and PAUSE statements.......................................................................................................................... 309

Using Windows API structures from Fortran....................................................................................................................... 310

25. Programming tips ............................................................................................... 311

Tricks with boxes.................................................................................................................................................................. 311
Debugging with an auxiliary terminal ................................................................................................................................. 312
Recording mouse and keyboard events ................................................................................................................................ 313
Breaking into the debugger .................................................................................................................................................. 314

26. Library overview ................................................................................................. 315

ClearWin window functions................................................................................................................................................. 315
Clipboard functions .............................................................................................................................................................. 316
File mapping functions ......................................................................................................................................................... 317
Format window functions ..................................................................................................................................................... 317
General functions.................................................................................................................................................................. 318
Graphics functions (bitmaps,cursors,icons).......................................................................................................................... 318
Graphics functions (device context) ..................................................................................................................................... 319
Graphics functions (device independent bitmap) ................................................................................................................. 319
Graphics functions (font,text)............................................................................................................................................... 320
Graphics functions (lines,fill) ............................................................................................................................................... 321
Graphics functions (metafiles).............................................................................................................................................. 322
Graphics functions (palette).................................................................................................................................................. 322
Graphics functions (printer,files).......................................................................................................................................... 323
Graphics functions (screen,regions) ..................................................................................................................................... 324
Hypertext functions............................................................................................................................................................... 324
Information functions ........................................................................................................................................................... 325
Mouse functions.................................................................................................................................................................... 325
Movie functions ................................................................................................................ .................................................... 325
Standard dialog functions ..................................................................................................................................................... 326
Sound functions .................................................................................................................................................................... 326
Useful API functions............................................................................................................................................................. 327

27. Library reference................................................................................................. 329

28. Glossary .............................................................................................................. 421

Appendix A. Functions ported from DBOS..................................................................... 429

Graphics................................................................................................................................................................................ 429
Graphics plotter/screen ........................................................................................................ ................................................. 431
Graphics printer .................................................................................................................................................................... 432
Mouse.................................................................................................................................................................................... 432
Table of alternative routines................................................................................................................................................. 433

Contents-4
IMPORTANT NOTICE
Salford Software Ltd gives no warranty that all errors have been eliminated from this
manual or from the software or programs to which it relates and neither the Company
nor any of its employees, contractors or agents nor the authors of this manual give any
warranty or representation as to the fitness of such software or any such program for
any particular purpose or use or shall be liable for direct, indirect or consequential
losses, damages, costs, expenses, claims or fee of any nature or kind resulting from any
deficiency defect or error in this manual or such software or programs.
Further, the user of such software and this manual is expected to satisfy himself/herself
that he/she is familiar with and has mastered each step described in this manual before
the user progresses further.
The information in this document is subject to change without notice.

17 February, 2000

© Salford Software Ltd 2000

All copyright and rights of reproduction are reserved. No part of this document may be
reproduced or used in any form or by any means including photocopying, recording, taping
or in any storage or retrieval system, nor by graphic, mechanical or electronic means without
the prior written consent of the Salford Software Ltd.

FTN77 is a registered trademark of Salford Software Ltd.

FTN95, DBOS, Salford C++, and ClearWin+ are trademarks of Salford Software Ltd.
MS-DOS, Visual Basic, Windows, Windows 95 and Windows NT are all trademarks of
Microsoft Corporation.

ii
PREFACE

This user’s guide discusses the binding from Salford Fortran compilers to the Microsoft
Windows Applications Programming Interface (API). It also describes the Salford
ClearWin+ library. ClearWin+ offers an easy-to-use interface to the Windows API.
ClearWin+ is used together with a Salford Win32 compiler in order to develop Windows
(Win32) applications that will run under Windows 95 and Windows NT. This guide
describes how to write Win32 applications.
Details of how to use ClearWin+ to develop Win16 applications will be found in the
ClearWin+ User’s Supplement. An electronic copy of this supplement can be found on the
Salford Tools CD. The supplement also includes details of functions that are considered to
be obsolete together with details of functions that can be ported from old DBOS programs
but which do not add any extra functionality those that are described in this guide.
Programmers who are familiar with the older functions and who prefer to use them should
refer to the supplement.
The guide does not try to describe or to document the Windows API, which is a subject too
extensive to be covered here. Full documentation of the Windows API is provided with the
Microsoft Windows Software Development Kit (SDK).
The Salford Tools CD contains example programs that illustrate some of the more common
operations that developers will need in order to produce Windows applications. It also
provides an HTML version of this manual that can be used to extract the sample code that
appears thoughout the text.
This guide is for version 6.0 of ClearWin+. It also includes details of the new branch-view
format (%bv). Enhancements to ClearWin+ that have been added after the preparation of
this guide are described in a README and .ENH enhancement files on the CD and also in
the BROWSE example program.

iii
The chapter headings in this guide are as follows:
page
1. Introduction ............................................................................. 1
2. Getting started ........................................................................ 5
3. ClearWin+ tutorial.................................................................... 7
4. Format windows .................................................................... 19
5. Input and output .................................................................... 37
6. Button controls ...................................................................... 51
7. Controls other than buttons ................................................... 61
8. Bitmaps, Cursors, Icons ........................................................ 75
9. Menus and accelerator keys.................................................. 81
10. Layout and positioning......................................................... 89
11. Displaying text..................................................................... 97
12. Edit box (%eb)................................................................... 107
13. Help .................................................................................. 119
14. Window attributes.............................................................. 121
15. Graphics............................................................................ 135
16. OpenGL ............................................................................ 161
17. SIMPLEPLOT ................................................................... 181
18. Using the printer ................................................................ 189
19. Hypertext windows ............................................................ 199
20. Standard call-back functions.............................................. 205
21. Format code reference ...................................................... 215
22. Compiling and linking......................................................... 293
23. ClearWin windows ............................................................. 299
24. Using the Windows API ..................................................... 305
25. Programming tips .............................................................. 311
26. Library overview ................................................................ 315
27. Library reference ............................................................... 329
28. Glossary............................................................................ 421
Appendix A. Functions ported from DBOS............................... 429

iv
1.

Introduction

Windows applications
ClearWin+ is a library of functions and subroutines that enables developers to
produce Windows applications very quickly. It can be used together with a Salford
Win32 compiler (FTN77, FTN95 or SCC) in order to produce Windows (Win32)
applications for Windows 95 and Windows NT.
Many developers will see the need to take advantage of the graphics user interface
(GUI) that is now available in Windows environments in order to produce applications
that are simple to use and professional in their appearance. At the same time there
will be very few developers who have the time and interest to work through the long
learning curve that is required in order to get to grips with the Windows API - a
Microsoft library that can be used to write Windows applications. Salford’s solution
to this dilemma is ClearWin+. ClearWin+ is designed to be used in a way that
closely emulates traditional programming techniques. The complexities of the
Windows API are avoided by using the ClearWin+ interface with the result that
Windows applications can be developed in a very small fraction of the time that
otherwise would be needed. The resulting programs are much shorter than equivalent
Windows programs produced in other ways.

The ClearWin+ library

The ClearWin+ interface may be used at three levels:
At the first and simplest level, DOS programs that interact with the user via standard
Fortran input and output statements (for example A403, FA8C4 and ?A8=C) may be
recompiled to produce simple Windows applications with little or no modification to

1
ClearWin+ User’s Guide Fortran

the source code. ClearWin+ will automatically create a window (called a ClearWin
window) complete with scroll bars and manage it for the developer.
At an intermediate level, ClearWin+ can be used to provide a professional graphics
interface, without incurring the burden of directly using the full Windows API. In
particular, the F8=8>/ function can be used to produce one or more fully featured
GUI windows (called format windows) both quickly and easily. This function
dispenses with the need to provide detailed resource scripts for menus, dialog boxes,
etc.. It also largely eliminates the requirement for the user to provide complex call-
back functions in order to control the interface. The effect is that much of the
complexity of using the full API becomes transparent to the programmer. At this
level, Windows API functions are rarely needed.
Finally at the lowest level, it is possible for the developer to use ClearWin+ to write
programs that use Windows API functions. However, even those who are familiar
with the Windows API will probably find it quicker and easier to work at the
intermediate level using the ClearWin+ library.
ClearWin+ is supplied with a full Windows debugger. Detailed information on how
to use the debugger is given the user guides for each of the Salford compilers.
A convention has been adopted in this guide of using mixed case names for the
routines present in the Windows API (for example, CreateWindow, GetDC,
GetTextMetrics). Routines in the ClearWin+ library do not use mixed case names.

How to use this guide

All integer constants and variables in this guide that are declared as INTEGER are
assumed to be 32 bits long (i.e. INTEGER(KIND=3) or INTEGER*4). Real values
are usually declared as DOUBLE PRECISION and assumed to be 64 bits long (i.e.
REAL(KIND=2) or REAL*8).
This guide distinguishes between three types of window.
1) An API window is produced using only Windows API functions. The term does
not imply any added functionality from the ClearWin+ library.
2) A ClearWin window is a window that has the added ability to make direct use of
standard Fortran I/O (A403 FA8C4 and ?A8=C). The ClearWin window was the
central feature of ClearWin versions 3.0 and 3.1 and is still of interest in the
current version of ClearWin+. A ClearWin window example is used in the
“getting started” section of Chapter 2.
3) A format window is a window that has been created using the ClearWin+ F8=8>/
function. This function is the distinguishing feature of ClearWin+ (it is, to all
intents and purposes, the “+” in ClearWin+). Like a ClearWin window, a format

2
Chapter 1 Introduction

window also has added functionality which provides all of the standard GUI
facilities in an easily programmed form - enabling the programmer to bypass the
complexities of the Windows API. Chapter 3 provides a tutorial to get you started
with format windows whilst chapters 4 to 21 provide detailed information.
The guide includes a Glossary. Words that have a special meaning in the context of
Windows and ClearWin+ are often presented in italic font and included in the
Glossary.
Please note that Windows 95 has been used to create the illustrations in this user
guide. Other versions of Windows may produce a slightly different appearance.

3
ClearWin+ User’s Guide Fortran

4
2.

Getting started

Introduction
The Salford Tools CD includes a number of programs that illustrate the use of
ClearWin+. Particular attention should be given to the demonstration programs that
illustrate the use of the ClearWin+ function fX]X^/ and to the ‘Browse’ example.
The following instructions explain how to compile, link and execute a very simple
Windows application without using fX]X^/.
Consider a program to calculate the squares of a sequence of numbers and print them
out.
In Fortran this takes the form1:
F8=0??
8=C464A XSg
3> XSg,
?A8=C XSg B`dPaTS Xb XSgXSg
4=33>
4=3
Using your editor, type in the above program and save it as (say) test.for.
Open a DOS box and enter a command line of the form:
5C=&& C4BC ;8=:
This will produce an executable file called test.exe that can be run from the Program
Manager in the normal way or by entering:

1 Throughout this guide INTEGER values are assumed to be 32 bits long unless otherwise stated.

5
ClearWin+ User’s Guide Fortran

C4BC
at the DOS box command line.
Tip Under Windows 95 or Windows NT 4.0 (or later) you may wish to create a shortcut
icon on your desktop to run your program. To do this simply right click on an empty
part of the screen and select New and Shortcut. Then supply the full path name of
your executable program. If you change the program this will not destroy the
shortcut, which will continue to reference the latest version of your program

The above procedure will run your test program and display a window that presents
the output. This program illustrates how ClearWin+ can be used to convert a simple
DOS application without the need to attend to any Windows programming features. It
automatically generates what is called a ClearWin window that handles the input and
output in a Windows environment.
Further information about compiling and linking is given in Chapter 22 whilst
Chapter 23 gives detailed information about using ClearWin windows. The
intervening chapters deal with what are called format windows using fX]X^/.
Format windows provide a quick and easy method for developing fully featured
Windows applications.

Using FTN77 and FTN95

Salford Win32 compilers use 32 bit integers (unless configured otherwise). This
guide assumes that integers are 32 bits long unless otherwise stated.
The examples in this manual have been written using Salford Fortran 77 syntax.
Since this syntax is a subset of Fortran 90/95, the programs can be used for the
FTN95 compiler with little or no change. However, users of FTN95 may wish to use
ClearWin+ modules instead of an include file called windows.ins. The relevant
module is called mswin.mod which is accessed via the Fortran 90/95 statement:
DB4 <BF8=
mswin.mod makes reference to the following modules which can be used separately.
mswin32.mod Windows API functions and parameters.
clrwin.mod ClearWin+ functions and parameters.
msw32prm.mod Windows API printer functions and parameters.

6
3.

ClearWin+ tutorial

This tutorial shows you how to develop a simple Windows application using a Salford
Fortran compiler and ClearWin+. It takes you through a step-by-step process leading
to an interactive program that produces the factors of a user-supplied integer. This
“Number Factoriser” is one of the demonstration programs that is supplied with
ClearWin+. The full source code can be found in the file called factor.for.
The tutorial is based on a number of files called factor1.for, factor2.for, etc. that can
be found in the ClearWin+ demonstration directory installed on your hard disk.
These files present stages in the development of the full program. The files are listed
in the tutorial together with a detailed line-by-line explanation of the purpose and
effect of the code. The idea is that you should compile, link and run factor1.for and
then read the explanation for this file. Then proceed to factor2.for and so on.

Step 1
Begin by loading Windows and opening a DOS box.
Now use your text editor to list factor1.for.
Here is the text of factor1.for. Line numbers have been added so that each line can be
referenced in the explanation below1.
F8=0?? 2F?N82>A2
!
" ?A>6A0< UPRc^a
# 8<?;828C =>=4
$ 8=2;D34 +fX]S^fbX]b-
% 8=C464A P]b

1 Throughout this guide INTEGER values are assumed to be 32 bits long unless otherwise stated.

7
ClearWin+ User’s Guide Fortran

& P]b,fX]X^/RPJ=d\QTa 5PRc^aXbTaL

' 4=3
You can compile and link this program with a command line of the form:
5C=&& 502C>A ;8=:
This produces a Windows executable factor1.exe that can be run by typing
502C>A
from the DOS box command line.
Alternatively you can run the executable from the Program Manager.
factor1.for simply opens a format window with a caption like this:

The illustrations throughout this manual have been produced using Windows 95. If
you are using another version of Windows then the output will differ slightly in its
appearance.
The quickest way to terminate the application is to press Alt-F4.
Now that you have seen the application running, have a look at the code. Before
looking at line 7, which is the key line in this program, let’s get some preliminaries
out of the way first.
Line 1 provides information for the linker that is called when you use /LINK on the
compiler command line. It causes the linker to produce a Windows executable. For a
Win32 application, the zero values on this line are redundant. (Some later compilers
allow you to omit these values.)

cwp_ico.rc is the name of what is called a resource script that can be found in the
same directory as factor1.for. This particular resource script
provides information about an icon that is embedded in the
application. In the program this “Window” icon is not used in the
application itself but is simply available as a icon that identifies
the application when it is installed in the Program Manager or its
equivalent.
WINAPP must be the first compiler directive in the file and must appear before the
main program.
Line 4 is recommended as a standard line for all programs and routines that use the
file windows.ins. This line is a compiler directive that ensures that all variables are

8
Chapter 3 ClearWin+ tutorial

given an explicit type. It is included because the names of many of the Windows
parameters are very long and consequently they are easy to misspell. Without this
directive, such bugs are very hard to find. The file factor.for is too short for this to
matter, but never-the-less we adopt the practice here as a matter of routine.
Line 5 is a call to include the file windows.ins. The diamond brackets indicate that the
file is located within the Salford compiler directory. This file contains type
declarations for many of the ClearWin+ and Windows API routines and parameters.
The only information of relevance to this particular main program is that fX]X^/
returns an 8=C464A result (in this guide, all integers are 32 bits long unless
otherwise stated). Note that, if you are only using fX]X^/ from the ClearWin+
library, then you will reduce the compilation time by replacing the 8=2;D34 line by
8=C464A fX]X^/
This brings us to line 7 and the heart of this and most ClearWin+ applications.
fX]X^/ is a ClearWin+ function that allows you to create a format window that
displays all manner of graphical user interface (GUI) objects such as menus, buttons,
pictures, formatted text, list boxes and icons. It also allows you to specify what action
is to be taken in response to the options that you present to the user. This means that
this one function can be used to avoid the complexities of writing a GUI application
based on calls to the standard API library combined with a detailed resource script and
complex call-back functions.
The first (and in this case only) argument of fX]X^/ is called a format string. In the
present case the format string starts with %ca and this is an example of what is called
a format code. The format code %ca stands for ‘caption’ and it supplies a title for the
format window. The title itself appears in square brackets after the format code.
There are many format codes available and all of them are represented by a % sign
and a two letter format code. Additional information is often supplied (as here) by
adding text enclosed in square brackets. This text is called a standard character
string. We shall see later that sometimes extra information is placed between the %
sign and the two letters. In other cases the format code is allowed to collect
information from additional arguments that are presented after the initial format
string argument of fX]X^/.
This brings us to the end of step 1 in our development process.

Step 2
Here is the text of factor2.for.
F8=0?? 2F?N82>A2
!

9
ClearWin+ User’s Guide Fortran

" ?A>6A0< UPRc^a!

# 8<?;828C =>=4
$ 8=2;D34 +fX]S^fbX]b-
% 8=C464A P]b]d\QTa
& ]d\QTa,
' P]b,fX]X^/RPJ=d\QTa 5PRc^aXbTaL
( P]b,fX]X^/X[ ! #&#'"%#&
P]b,fX]X^/=d\QTa c^ QT UPRc^aXbTS) aS]d\QTa
4=3
Note that ]d\QTa has been added to line 6 and & has been inserted towards the end of
line 8. Lines 7, 9 and 10 have also been included.
If you compile, link and run this program the output looks like this.

A flashing text cursor appears in the inner box and the user is able to enter any integer
in the range from 1 to 2147483647. As before Alt-F4 terminates the application.
The “&” character in line 8 is simply a device to allow the description of the format
window to continue in the next call to fX]X^/ (on line 9 in this case). Using this
device avoids long format strings with long lists of associated arguments.
Line 9 contains the format code %il. This specifies the integer limit for the input on
line 10. %il takes two (8=C464A) values that are provided as extra arguments to
fX]X^/. The lower limit is 1 and the upper limit (2147483647) is the largest possible
32 bit integer. The “&” character allows continuation in the next fX]X^/ call.
In line 9 the format string begins with some text that comes before the next format
code which is %rd. This text is simply copied to the window. The text includes the
space before %rd. Without the %il, the user would be able to enter negative or zero
values which would not make sense in this application.
The %rd format code is used for user integer input. It creates an edit box and displays
the value of the 8=C464A variable (in this case ]d\QTa) that is provided as the next
argument of fX]X^/. The initial value of ]d\QTa in line 7 has been chosen to be in
the permitted range. Users will find that they are only able to type in integers in this
range. Each time a single digit is typed, ]d\QTa is updated so that it always holds the
value that is visible on the screen.
Now we are ready for step 3.

10
Chapter 3 ClearWin+ tutorial

Step 3
Now that we have a window and the user is able to input an integer, the next stage is
to add a button to initiate the factorising process. factor3.for includes code for such a
button. Here is the text:
F8=0?? 2F?N82>A2
!
" ?A>6A0< UPRcâ"
# 8<?;828C =>=4
$ 8=2;D34 +fX]S^fbX]b-
% 4GC4A=0; UPRcâXbTa
& 8=C464A P]b]d\QTa
' ]d\QTa,
( P]b,fX]X^/RPJ=d\QTa 5PRcâXbTaL
P]b,fX]X^/X[ ! #&#'"%#&
P]b,fX]X^/=d\QTa c^ QT UPRcâXbTS) aS]d\QTa
! P]b,fX]X^/cPOMQcJ5PRcâXbTLUPRcâXbTa
" 4=3
#
$ 8=C464A 5D=2C8>= UPRcâXbTa
% UPRcâXbTa,
& 4=3
Note that lines 6, 12 and 15 to 17 have been added to factor2.for. Also an “&”
character has been inserted after %rd on line 11. We need to look at line 12 in detail.
The other new lines simply declare an external function which for the moment merely
returns the value 1.
When you compile, link and run this program the output looks like this.

But at the moment nothing happens when you click on the button.
Line 12 of the program uses the format code %bt to provide the button. The text on
the button is given as a standard character string (in square brackets) The “&”
character in “Fac&torise” has the visual effect of producing an underscore on the next
letter (‘t’ in this case). The result is that ‘t’ on the keyboard can be used as an

11
ClearWin+ User’s Guide Fortran

alternative to clicking on the button when used in combination with the Alt key i.e.
Alt-T.
Note that two special characters, a grave accent (`) and a caret character (^), have
been included after the % sign. These are two out of a set of four characters called
format modifiers (the others are the tilde (~) and the question mark (?)). As it
happens, all four modifiers may be used with %bt, but the number of modifiers that a
format code can take and the effect each modifier has varies from one format code to
another.
In the present case of the button format %bt, the grave accent means that this button is
the default button. The default button has a slightly different appearance and is the
one that is selected when the Enter key is pressed.
The caret means that a call-back function (called UPRc^aXbTa in this case) is
provided as the next argument of fX]X^/. This is the function that is to be called
when the user clicks on the button. Call-back functions that are used with fX]X^/
must have no arguments and must return an integer value. It is advisable that this
function be declared 4GC4A=0;.
Finally we note that a tab (represented by %ta) has been placed before the %bt format
code. This has been used to separate the button from the text before it. Alternatively,
you could simply use spaces.
A call-back function must return one of the following values:

0 or negative Closes the format window.

1 The window remains open and the whole window is refreshed to
allow any changes to be displayed.
2 The window is left open with no refresh. If anything needs to be
updated before the call-back returns, a call to fX]S^fNd_SPcT/ is
used to refresh individual components.
3 Used only with %mg.

Step 4
The next thing we need is a child window in order to present the results of the
factorising process. factor4.for includes the code for such a window but we shall leave
out the code that calculates the results until the end. Here is the text of factor4.for:
F8=0?? 2F?N82>A2
!
" ?A>6A0< UPRc^a#
# 8<?;828C =>=4

12
Chapter 3 ClearWin+ tutorial

$ 8=2;D34 +fX]S^fbX]b-
% 4GC4A=0; UPRcâXbTa
& 8=C464A P]b]d\QTa
' 270A02C4A$ bca
( 2><<>= ]d\QTabca
]d\QTa,
bca,
! P]b,fX]X^/RPJ=d\QTa 5PRcâXbTaL
" P]b,fX]X^/X[ ! #&#'"%#&
# P]b,fX]X^/=d\QTa c^ QT UPRcâXbTS) aS]d\QTa
$ P]b,fX]X^/cPOMQcJ5PRcâXbTLUPRcâXbTa
% P]b,fX]X^/!][^Q#!bcRQbca
& 4=3
'
( 8=C464A 5D=2C8>= UPRcâXbTa
! 8=C464A ]d\QTa
! 270A02C4A$ bca
!! 2><<>= ]d\QTabca
!" FA8C4bca]d\QTa
!# 20;; fX]S^fNd_SPcT/bca
!$ UPRcâXbTa,
!% 4=3
Lines 8, 9, 11, 16 and 19 to 26 have been added and as before an “&” character has
been placed at the end of the format string on line 15.
When the program is compiled the result looks like this:

At the current state of development, when you click on the “Factorise” button, the
number that has been entered is simply copied to the new child window.
The allocation of the variable ]d\QTa to a common block in lines 9, and 22, provides
a method for passing this variable to the UPRc^aXbTa function. You will recall that
call-back functions like UPRc^aXbTa do not have any arguments. Line 23 stores the
value of ]d\QTa as a character string in bca. bca is also held in common because it
is used for output on line 16:

13
ClearWin+ User’s Guide Fortran

P]b,fX]X^/!][^Q#!bcRQbca
On line 16, %2nl provides two line feeds so that the child window that follows is
placed below the existing controls.
The %ob format code is used to open a box at the current position. It automatically
marks the position of the top left-hand corner of a box that will be drawn when a
corresponding %cb (close box) is encountered. %cb automatically marks the position
of the bottom right-hand corner of the box. The box is simply provided as a border.
The enclosed area has no special attributes. In the present case the box is used to
enclose a string that is produced by the %st format. The string is located in bca and
the width of the associated area is 42 characters. However, the standard width of a
character in this context will be the maximum width of all the characters of the
proportionally spaced font.
Finally, line 24 has the effect of updating the string on the screen in order to reflect a
change in the contents of bca.

Step 5
Now we shall add a menu bar with an associated “About” dialog box in order to create
factor5.for. Here is the text, but to make it easier to understand, only those parts of
facror4.for that have changed are listed in full.
% 4GC4A=0; UPRcâXbTaPQ^dc
! P]b,fX]X^/RPJ=d\QTa 5PRcâXbTaL
" P]b,fX]X^/\]J5X[TJ4gXcLL4G8C
# P]b,fX]X^/\]J7T[_J0Q^dc =d\QTa 5PRcâXbTaLLPQ^dc
$ P]b,fX]X^/X[ ! #&#'"%#&
( 4=3
!
! 8=C464A 5D=2C8>= UPRcâXbTa
!' 4=3
!(
" 8=C464A 5D=2C8>= PQ^dc
" 8<?;828C =>=4
"! 8=2;D34 +fX]S^fbX]b-
"" 8=C464A P]b
"# P]b,fX]X^/RPJ0Q^dc =d\QTa 5PRcâXbTaL
"$ P]b,fX]X^/U]JCX\Tb =Tf A^\P]LcbQUR]CdcâXP[!3
"% P]b,fX]X^/cb#][ 3
"& P]b,fX]X^/R]?a^VaP\ faXccT] c^ ST\^]bcaPcT!][
"' P]b,fX]X^/cbcRR]QU2[TPaFX] $3A61/!$$
"( P]b,fX]X^/cRbU!][R]Qh

14
Chapter 3 ClearWin+ tutorial

# P]b,fX]X^/!][R]BP[U^aS B^UcfPaT
# P]b,fX]X^/!][R](OQcJ>:L
#! PQ^dc,
#" 4=3
A new call-back function called PQ^dc has been added to line 6 and the code for this
function has been added to the end of factor4.for in lines 30 to 43. The new menu bar
has been included as lines 13 and 14 after the caption in line 12.
This is what the compiled program displays on the screen.

When you click on the “Help” menu and then on the “About Number Factoriser” item,
you get the dialog box below.
Now for the details of how this effect is created. First look at lines 13 and 14 for the
menu bar.
" P]b,fX]X^/\]J5X[TJ4gXcLL4G8C
# P]b,fX]X^/\]J7T[_J0Q^dc =d\QTa 5PRc^aXbTaLLPQ^dc
The menu format is provided by %mn. Square backets enclose a list of menu topics,
with each topic having an optional embedded list of associated menu items. There are
two menu topics here, “File” and “Help”. These provide for two drop down menus
each of which (in this example) has one item . The “&” character is used in the same
way as on a button in order to provide an accelerator key.

15
ClearWin+ User’s Guide Fortran

Each menu item requires a call-back function and these are provided as further
arguments to fX]X^/. The first one ('4G8C') refers to what is called a standard
ClearWin+ call-back function. When a standard call-back function is used, the code
for the function is supplied by ClearWin+ rather than by the programmer. In this
case the effect of calling the function is simply to close the application.
The second call-back function (PQ^dc) is supplied by the progammer. In this case the
PQ^dc function displays a dialog box that describes the application. When the user
clicks on the OK button, the dialog box closes but the application remains active. If
PQ^dc returned zero instead of a 2, the application would also close when the OK
button was used.
All we need to do now is look at the new call-back function for the “About” dialog.
Let’s concentrate on the format codes that we have not seen before in this tutorial.
%fn defines a new font for the text that follows. In this case the font is “Times New
Roman” and this font is used for the subsequent text up to the %sf format code on line
39. %sf stands for “standard font” and has the effect of resetting all text attributes
(font, size, colour, bold, italic, and underline) to the default settings.
%ts is used to set the text size. It takes one 3>D1;4 ?A428B8>= argument. The
value 2.0D0 on line 35 doubles the standard text size and then the standard size is
restored on line 36 with the value 1.0D0. Line 38 uses a text size of one and a half
times the standard and then the standard size is restored with %sf on line 39.
%bf on line 35 is used to provide bold faced font whilst %cn has the effect of centring
the line of text in the dialog box. In this example %cn is cancelled by the next

16
Chapter 3 ClearWin+ tutorial

newline format (%nl). On line 38, %tc changes the colour of the text to red. The
colour is provided by the call to the ClearWin+ function A61/. A61/ takes three
8=C464A arguments in the range 0 to 255. These provide the red, green and blue
intensities. Note that %ts comes before %tc and uses the 1.5D0 argument on line 38.
%tc is also used on line 39. In this case the argument (-1) restores the system text
colour. This is one of the screen colours that the user can set from the Control Panel
in the Program Manager.
Finally line 41 produces the OK button. As before the grave accent makes this the
default button, whilst the value 9 has the effect of widening the button to a 9 character
width. This button does not have a call-back function. As a result, when the user
clicks on the button, the format window closes. If there are a number of buttons like
this, then the value returned by fX]X^/ (P]b in this case) gives the number of the
button that was pressed.

Step 6
factor6.for contains the finished program. In this program the UPRcâXbTa function
has been developed to do the calculations needed to factorise the number that is
supplied by the user. The details of this simple Fortran code are not of direct interest
to us in this tutorial but here is the code for those who want to read it.
8=C464A 5D=2C8>= UPRcâXbTa
8=C464A ]d\QTa]Z
270A02C4A$ bcaeP[
2><<>= ]d\QTabca
FA8C4eP[X ]d\QTa
20;; caX\/eP[
bca,CWT UPRcâb Û eP[ );4=6eP[ PaT)
],]d\QTa
3> Z,!]
85]ZZ4@]C74=
FA8C4eP[X Z
20;; caX\/eP[
20;; P__T]SNbcaX]V/bca eP[
],]Z
85]6C 6>C>
4=385
4=3 3>
20;; fX]S^fNd_SPcT/bca
UPRcâXbTa,
4=3

17
ClearWin+ User’s Guide Fortran

This is what the final program displays on the screen:

This brings us to the end of the tutorial. In this one demonstration program you have
been introduced to some of the important format codes that come with fX]X^/. More
importantly you have been able to experience the ease with which it is possible to
develop a GUI application with ClearWin+.

18
4.

Format windows

Introduction
This chapter presents an overview of the ClearWin+ function fX]X^/ that was
introduced in Chapter 3. Further details are given in the following chapters up to
Chapter 21 which provides a detailed reference.
fX]X^/ is used to lay out and control a window in order to include a wide variety of
controls, child windows, toolbars, etc.. Of course, this task could be carried out by
making direct use of the Windows API. Although the direct method does provide
maximum flexibility, it also requires large amounts of complex coding in order to
control the interface. In contrast, the fX]X^/ function requires a bare minimum of
code to achieve elaborate window interfaces.
Windows applications typically have a great deal of “low level” functionality. For
example, a window with several input controls will let the user move between fields
using the tab key or the mouse. Likewise, buttons change their appearance slightly
when they acquire focus. Fortunately you do not need to write code to program this
functionality into your application, as it is already supplied by ClearWin+.
The following example illustrates the power and flexibility of fX]X^/. In this
example fX]X^/ is used to produce a window that includes a menu bar with
associated standard call-back functions. The window contains a so-called edit box
that is used to display and edit a file. The menu and edit box is fully functional.
Three buttons are also shown on the right hand side of the window. These are used to
illustrate how buttons are added to the window. As the example stands, clicking on
any of these buttons has no effect since code for the corresponding processes has been
omitted.
F8=0??
8=2;D34 +fX]S^fbX]b-

19
ClearWin+ User’s Guide Fortran

270A02C4A !( UX[T]TfNUX[TWT[_NUX[T
8=C464A R^\_X[T[X]Zad]X
4GC4A=0; R^\_X[T[X]Zad]
WT[_NUX[T,\hWT[_W[_
X,fX]X^/RPJ4gP\_[TL
X,fX]X^/\]J5X[TJ>_T]LL´438CN58;4N>?4=
UX[T
X,fX]X^/³\]JJBPeTLL´438CN58;4NB0E4
]TfNUX[T
X,fX]X^/³\]JJBPeT 0bLL´438CN58;4NB0E4N0B
]TfNUX[T
X,fX]X^/³\]JJ4gXcLL4G8C
X,fX]X^/\]J4SXcJ2^_hLL´2>?H
X,fX]X^/³\]JJ2dcLL´2DC
X,fX]X^/³\]JJ?PbcTLL ?0BC4
X,fX]X^/\]J7T[_J2^]cT]cbLL´74;?N2>=C4=CB
WT[_NUX[T
X,fX]X^/³\]JJ7T[_ ^] WT[_LL74;?N>=N74;?
WT[_NUX[T
R 3TUX]T P "g TSXc Q^g TQ
X,fX]X^/ff_e
X,fX]X^/" TQJebRa^[[QPaWbRa^[[QPaL
R 3TUX]T Qdcc^]b cWPc PaT c^ QT SXb_P[hTS
X,fX]X^/!][ M&QcJ2^\_X[TLR^\_X[T
X,fX]X^/!][ M&QcJ;X]ZL [X]Z
X,fX]X^/!][ M&QcJAd]L ad]
4=3
R 2P[[QPRZ Ud]RcX^]b cWPc S^ ]^cWX]V
8=C464A 5D=2C8>= R^\_X[T
R^\_X[T,
4=3
8=C464A 5D=2C8>= [X]Z
[X]Z,
4=3
8=C464A 5D=2C8>= ad]
ad],
4=3
This is what the window looks like on the screen:

20
Chapter 4 Format windows

The reminder of this chapter and the following chapters up to and including Chapter
21 provide a detailed explanation of how to set out the parameters of fX]X^/.

Call-back functions
A ClearWin+ call-back function takes no arguments and returns an integer result. As
a result, such functions may be coded in C, C++, or Fortran.
When a call-back function returns, it indicates what is to happen next by its return
value. A negative or zero value signals an exit and closes the parent format window.
The corresponding call to fX]X^/ will return the absolute value of this quantity. A
return value of 1 will cause a full update of the format window so that any changes are
made visible. This should be used sparingly because if a call-back is used repeatedly,
then the whole display area may flicker due to the frequent screen updates. A more
efficient approach is to use a return value of 2. This will not cause the format window
to close nor will it update the window. In order to refresh any part of the display that
needs to be refreshed, a call to fX]S^fNd_SPcT/ will suffice. This will also improve
the response since only small sections of the display will be redrawn.

21
ClearWin+ User’s Guide Fortran

In summary return values can be:

≤0 Closes associated window.
1 Returns from call-back with display refresh.
2 Returns from call-back with no refresh.
3 Used with %mg only.
4 Used with %lv and %bv only.
≥5 Reserved for future use.

Tip Returning a negative value can be very convenient. Consider a window with a list
box and OK and CANCEL buttons. Typically it is required that a double click on a
list box item will select that item and close the window as if the OK button had been
pressed. To achieve this the list box call-back function should return -1, so that
fX]X^/ will return 1 as if the OK button had been pressed - thus saving a flag and
more complex program logic.

It is often convenient to use one call-back function for a variety of reasons. Whenever
a call-back function is invoked, ClearWin+ defines a string that specifies the reason
for the call. This string is obtained by calling
R[TPafX]NbcaX]V/’20;;102:NA40B>=´. Testing the string makes it easy to
determine the reason for the call. See page 342 for further details.

Window formats
The ClearWin+ function fX]X^/ has the following form:
8=C464A fX]X^/Uâ\Pc
270A02C4A Uâ\Pc
where the ellipses ... represents a list of arguments whose length depends on what
appears in the character variable Uâ\Pc. The character string is called a format
string. The list must only contain arguments of type 8=C464A, 3>D1;4 ?A428B8>=,
270A02C4A or 4GC4A=0; functions.
At its very simplest, fX]X^/ may be used to display information:
F8=0??
8=2;D34 +fX]S^fbX]b-
3>D1;4 ?A428B8>= gh
g,
h,!$

22
Chapter 4 Format windows

R fU SXb_[Ph P U[^PcX]V _^X]c eP[dT

X,fX]X^/G , cPfU][H , cPfUgh
4=3

%wf is an example of a format code. The %wf format code displays a floating point
value with six decimal places as the default. New lines are represented by %nl, and
tabs %ta operate on a grid of 8-character intervals or by setting tab stops with the %tl
format (see page 90). %2nl (for example) is used for two new lines and %3ta (for
example) is used for three tabs. Form-feed (%ff) has a special meaning in a format
window. It moves the current position to the left margin, beneath any existing
controls. The window is automatically constructed with a size to suit its contents.
%wd, %wx, %ws, %wc, %we, and %wg are alternatives to %wd & %wf with the
following usage:

%wd Integer output.

%wx Hexadecimal integer output.
%ws String output.
%wc Character output.
%wf Floating point output in decimal form.
%we Floating point output in exponent form.
%wg Floating point output in decimal or exponent form.

Each of these output format codes can be modified in order to control the manner in
which the information is presented. Details are given on page 45.
By using the additional format codes described below and in the following chapters,
the resulting windows can prompt for and display a wide variety of information.
Each format code begins with the percent (%) character, followed by optional size
information of the form n or n.m where n and m are integer constants (e.g. %6.4wd).
n and/or m can be replaced by an asterisk “*” with the corresponding value(s) being
supplied as one or two 8=C464A arguments in the argument list. After the optional
size information, a two-letter code is used to define the format. This two letter code is
not case sensitive. Some format codes have mandatory size information. These sizes
are represented by uppercase N and M in the text.

23
ClearWin+ User’s Guide Fortran

Four special characters, known as format modifiers, are often inserted after the size
information and before the two-letter code. The first of these is the caret character (^)
which indicates that a call-back function is supplied in the argument list (after any
other arguments required by the format code). The tilde character (~) is used with
certain format codes to control the disabling (greying) of the control. The grave
accent character (`) is also used to modify the action of certain codes. These
characters may only be used with the codes that define them as detailed in Chapter 21.
The fourth character is the question mark (?) that is used with any format that defines
a control (as opposed to formats such as %ww that modify the appearance of the
window as a whole). The question mark signifies that a help string is supplied in the
format. This string is displayed at the bottom of the window or as a help “bubble”
whenever the user’s cursor lies over the corresponding control. The text is either
surrounded by square brackets, or a “@” character is placed in the format string to
indicate that the help string is supplied as an extra argument. The text string that is
supplied in either of these two forms is known as a standard character string.
Many format codes are supplied with a list of options. When used, these are placed in
a comma-separated list and set between square brackets after the two-letter format
code. For example
VaJQ[PRZaVQNR^[^dabL
If none of the options are used then the list, together with the square brackets, may be
omitted. However, if the option list is empty and a help string is required, then square
brackets must be inserted to represent the empty list. These brackets are followed by
the help string. For example:
! .TQJLJ4SXc Q^gL
Here is an example that uses a help string. It prompts the user for an integer (%rd)
and augments the window with an additional help string.
F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A ]NRW
]NRW,
X,fX]X^/=^ ^U RWX[SaT] .aS
J7^f \P]h RWX[SaT] WPeT h^d V^c.L]NRW
4=3
The following code would produce the same result:
270A02C4A' WT[_
WT[_,7^f \P]h RWX[SaT] WPeT h^d V^c.
]NRW,
X,fX]X^/=^ ^U RWX[SaT] .aS/]NRWWT[_
4=3

24
Chapter 4 Format windows

Help strings may include line feed characters (RWPa ) if necessary. The area to
contain the help text will be sized to fit the dimensions of the largest string. The help
text can be positioned at another location (e.g. inside a box) by using the %he format.
Alternatively, %bh provides for ‘bubble’ help and %th for ‘tooltip’ help (see page
119).

A toolbar requires a help string for each button (see the %tb example on page 56).
Calls to fX]X^/ may become quite complex. For this reason, a method is available to
continue a format over several calls to fX]X^/. If the last character in a format string
is an ampersand (&) character, this character is removed from the string and the
format information is joined seamlessly to the next call to fX]X^/.
For example:
X,fX]X^/4]cTa P] X]cTVTa cPaS][]
X,fX]X^/4]cTa P bTR^]S X]cTVTacPaS][\
X,fX]X^/R]OQcJ3^]TL
This creates a single window containing two integer edit boxes together with a button.
Note that, using this technique, it is possible to build a dialog box with a structure that
is controlled by your program logic. For example, if the user had already supplied a
file name you could omit a file open box, possibly replacing it with a suitable message.
If you choose to write some routines in Fortran and others in C++, then the
programming language that you use for the first call to fX]X^/ for a given format
window must be the same as that used in any continuation calls. However, it is
possible to create one format window using Fortran and another using C++.

Closing a window
ClearWin+ programs may create a number of windows, some of which might be open
at the same time. A ClearWin+ program terminates when both a) the END point of
the program (or its equivalent) is reached, and b) all windows created by the program
have been closed by the user.

25
ClearWin+ User’s Guide Fortran

Normally the user is provided with a number of ways to close a window. There is
usually a system menu with a ‘Close’ item (Alt+F4) at the top left of a window.
:
Selecting this item is equivalent to clicking on the box at the top right of a window.
The programmer can use %cc with a call-back function to trap this event.
The programmer can also add an ‘Exit’ item to a %mn menu. This item will either be
linked to a call-back function provided in the program or to the standard ‘4G8C’ call-
back.
Other exit routes can be provided via buttons (using for example %bt or %tt):
a) When you click on the button that has no call-back function attached, the parent
window will close. If there is only one window open, the effect is the same as if
the standard ‘4G8C´ call-back were attached to the button.
b) If there is no call-back function attached to a button and the associated window has
been created within a call-back function, then the window will close. The affect on
the window’s parent will depend on the value returned by the call-back (see page
22). A zero return will close the window’s parent. The same is true for any call-
back, not just those attached to buttons.
Another approach to window closure is to attach a control variable to a window.
When a window (or dialog) is created, by default it will be equivalent to a modal
dialog box. A modal dialog box is one that must be closed before other windows in
the same application can be accessed. Any code that follows the fX]X^/ calls for a
particular modal dialog box, will not be processed until the user closes the dialog.
If you want more than one window to be accessible (the equivalent of a modeless
dialog box) then you can use %lw (see page 122) to leave a window open and to attach
a control variable to the window. The presence of %lw causes any code that follows
the fX]X^/ calls for a particular window to be processed immediately. ClearWin+
sets the value of a %lw control variable to -1 (minus one). If the control variable is
subsequently set a non-negative value, the window will close when that variable is
updated (see below).
Notes
1. %lw is used together with %fr and %aw to create a multi-document interface.
2. %cv also provides a control variable for use with %aw but in this case the window
will be a child window and will not be left open.

Updating windows
Many of the format codes of the fX]X^/ function take pointers to data that may
change. For example, the bar control variable in the %br format will typically change

26
Chapter 4 Format windows

as some time consuming process proceeds. Likewise, consider the following partial
window definitions:
270A02C4A$ \hUâ\
\hUâ\,C4BC
X,fX]X^/RP/\hUâ\
The address of the variable \hUâ\ has been passed to fX]X^/, and if the contents of
the string \hUâ\ alter, it is desirable to update the window accordingly. In general,
if you alter data that is in use by a window, the window will be updated if it is
obscured and restored for any reason.
However, to obtain an immediate update, the subroutine
BD1A>DC8=4 fX]S^fNd_SPcT/ePaXPQ[T
should be called. The argument is the variable whose value has changed. In reality
the address of the variable is passed and this address must be the exact address
originally passed to fX]X^/. For example, in the above example, the address of the
first character in the string would be passed to fX]S^fNd_SPcT/ using
20;; fX]S^fNd_SPcT/\hUâ\
The update would not work if the address of the second character (i.e. \hUâ\!)!)
where passed, even though this address points to part of the caption. The
fX]S^fNd_SPcT/ function will update all controls, captions, etc. that depend on the
variable. It may also be used with a grey-control variable (see for example %bt, page
51), or the control variable associated with the %lw format. In the latter case, setting
the control variable to a non-negative value means that the window will close.
Note that, in general, fX]S^fNd_SPcT/ will only update those objects that depend on
the variable whose address is supplied. However, there is no guarantee that other
portions of the display will not become updated in the process.
It is desirable that fX]S^fNd_SPcT/ be called at a sensible rate. Perhaps no more
than once or twice per second for a given variable. Frequent updates may produce an
unpleasant flicker.

Advanced use of format windows

It is convenient at this point to mention a few advanced approaches to ClearWin+
programming. If you are still unfamiliar with how to program with fX]X^/, it would
be better to skip this section for the moment.

27
ClearWin+ User’s Guide Fortran

There are three ways in which the usage of fX]X^/ can be varied under program
control. First, you can use fX]X^/ statements within flow control constructs such as
DO and IF constructs. Here is a simple example.
F8=0??
8=C464A ]XfX]X^/
2><<>= ]
4GC4A=0; RQNUd]R
X,fX]X^/=d\QTa Û [X]Tb) #aS]
X,fX]X^/!][R]MccJBW^fLRQNUd]R
4=3
R
8=C464A Ud]RcX^] RQNUd]R
8=C464A ]XYfX]X^/
2><<>= ]
3> Y, ]
X,fX]X^/;X]T fS][Y
4=33>
X,fX]X^/
RQNUd]R,
4=3
The first dialog box allows you to enter a number. Clicking on the button then
produces another dialog box with the given number of lines of output. Notice that the
format string within the DO loop is terminated by an ampersand (&) to allow the
description of the dialog box to continue on the next loop. The final call to fX]X^/
acts as a terminator. It contains only a format string with a single space character.
The same idea can be used with other flow control constructs containing calls to
fX]X^/
A second method for varying the use of fX]X^/ under program control involves
changes to the format string. The next example illustrates the idea.
F8=0??
8=C464A ]XfX]X^/
2><<>= ]
4GC4A=0; RQNUd]R
],
X,fX]X^/5â\Pc â !) #aS]
X,fX]X^/!][R]MccJBW^fLRQNUd]R
4=3
R
8=C464A Ud]RcX^] RQNUd]R
8=C464A ]XYfX]X^/
2><<>= ]
270A02C4A U\c

28
Chapter 4 Format windows

U\c,8]eP[XS eP[dT fS

85]T` C74=
U\c,5â\Pc fS
4;B4 XU]T`! C74=
U\c,5>A<0C fS
4=385
X,fX]X^/U\c]
RQNUd]R,
4=3
In this example, the choice of format string for the output depends on the value
entered into the edit box. The illustration is not very useful in itself but it does point
the way to the idea that it is possible to construct format strings dynamically under
program control.
The third and final approach to the dynamic use of fX]X^/ takes the last idea one
stage further. As it is we cannot easily change the format codes within a format string
because different format codes take different arguments in the fX]X^/ call. For
example, if %wd were changed to %wf in the above example, then the call to fX]X^/
would require a real valued argument rather than an integer after the format string.
Although you could solve this problem by using complex IF or CASE constructs,
ClearWin+ provides an alternative and potentially more powerful approach via the
following routines:
BD1A>DC8=4 033NF8=8>N8=C464A/8
8=C464A 8
BD1A>DC8=4 033NF8=8>N5;>0C/G
3>D1;4 ?A428B8>= G
BD1A>DC8=4 033NF8=8>N270A02C4A/B
270A02C4A B
BD1A>DC8=4 033NF8=8>N5D=2C8>=/5
4GC4A=0; 5
Using these routines, you create the argument list before calling fX]X^/ After
creating the list, you then call fX]X^/ with the format string as its only argument.
Here is a simple example.
F8=0??
8=C464A ]XfX]X^/
2><<>= ]
4GC4A=0; RQNUd]R
],
X,fX]X^/5â\Pc â !) #aS]
X,fX]X^/!][R]MccJBW^fLRQNUd]R

29
ClearWin+ User’s Guide Fortran

4=3
R
8=C464A Ud]RcX^] RQNUd]R
8=2;D34 +fX]S^fbX]b-
8=C464A ]X
2><<>= ]
270A02C4A! U\c
3>D1;4 ?A428B8>= g
g,]
85]T` C74=
U\c,8]cTVTa fS
20;; PSSNfX]X^NX]cTVTa/]
4;B4
U\c,ATP[ fU
20;; PSSNfX]X^NU[^Pc/g
4=385
X,fX]X^/U\c
RQNUd]R,
4=3
This example is too simple to do justice to the concept but it is sufficient to point the
way.

Format codes grouped by function

The following table presents the format codes under various headings. Details are
given in chapters 5 to 18. A reference guide is presented in Chapter 21. An index
and summary of the format codes appears in the next section, in addition to the index
at the end of this user’s guide.

1) Interactive I/O: %co, %dd, %df, %dl, %dr, %fl, %il, %rd, %rf,
%rs
2) Controls: %bc, %br, %bt, %bv, %bx, %el, %ga, %hx,
%ib, %ld, %ls, %lv, %ms, %rb, %sl, %tb, %tt,
%tv, %vx
3) Bitmaps, Cursors, Icons: %bi, %bm, %cu, %dc, %gi, %ic, %mi, %si
4) Menus and accelerator keys: %ac, %es, %mn, %pm, %sm
5) Layout and positioning: %ap, %bd, %cn, %dy, %ff, %gd, %gp, %nd,
%nl, %nr, %pv, %rj, %rp, %ta
6) Boxes: %cb, %ob
7) Displaying text: %bf, %eq, %fn, %gf, %ht, %it, %pd, %sd, %sf,
%st, %su, %tc, %ts, %tl, %ul

30
Chapter 4 Format windows

8) Help: %bh, %he, %ht

9) Graphics: %dw, %gr, %og, %pl
10) Main window attributes: %ca, %cv, %de, %lw, %mv, %nc, %ns, %sp,
%sv, %sy, %sz, %wp, %ww
11) Background colour %bg
12) Child windows: %aw, %ch, %cl, %cw, %fr, %hw, %if, %lc,
%ps, %sh, %uw
13) Formats for call-back %cc, %fs, %ft, %mg, %rm, %sc
functions:
14) Edit boxes: %eb, %pb, %re, %tx
15) Data output: %ss, %wc, %wd, %we, %wf, %wg, %ws, %wx

Alphabetical index of format codes

The following table provides a list and summary of the special format codes. Details
are given in chapters 5 to 19. A reference guide is presented in Chapter 21.
page

%ac Accelerator key format. 88

%ap Absolute positioning of next control 95
%aw Attach window format. 123
%bc Button colour format - specifies the colour of the next %bt button. 217
%bd Specifies all four window borders individually. 218
%bf Switch to bold font. 97
%bg Background colour format. 127
%bh Bubble help format. 119
%bi Supply an icon for the next button. 54
%bk Allow a right mouse click to be used on the next %bt button. 220
%bm Bitmap format draws a bitmap. 75
%br Bar format - draws a horizontal or vertical bar which is partially filled 61
with a user-selected colour.
%bt Button format - defines a button with text. 51
%bv Hierarchical tree-view, alternative to %tv. 222
%bx Adds a raised grey bar to a tool bar. 59
%ca Caption format - defines the title of a dialog box. 121
%cb Box close format - closes a box opened by %ob. 82

31
ClearWin+ User’s Guide Fortran

%cc Closure control format - provides a link to a call-back function by which 130
the user controls the action to be taken when a window is closed.
%ch Child window format - inserts a child window. 123
%cl Displays a colour palette. 73
%cn Centring format - forces everything which follows it, up to the next new 89
line or form-feed character, to be centred in the window.
%co Control option format - used to modify subsequent %rd, %rf, and %rs 40
boxes.
%cu Establishes a cursor for the next control in a format. 76
%cv Control variable format. 123
%cw Embeds a ClearWin window. 128
%dc Establishes a default cursor for the window. 76
%dd Increase/decrease button for an integer. 41
%de Disables some other window while the current window is active. 232
%df Increase/decrease button for a floating point value. 41
%dl Allows a call-back function to be called at regular intervals via a timer. 130
%dp Parameter box format. 263
%dr Drag and drop. 125
%dw Owner draw box format - provides owner draw boxes. 157
%dy Provides a vertical displacement by a non-integral number of character 235
depth units.
%eb Edit box format - presents a edit box in which a text file is displayed 107
and modified.
%el Inserts an editable combo box. 236
%ep Parameter box format. 263
%eq Equation format - inserts a mathematical equation in a window. 100
%es Escape format - causes the program to exit when the 4bRP_T key is 237
pressed.
%ew Exit Windows format - provides a call-back function which is called 238
when the user shuts down.
%fb Remember current font for subsequent buttons. 238
%ff Form feed. Move down to below any existing controls. 239
%fh Font handle - use a font created by the API function CreateFont. 239
%fl Floating point limit format - specifies the lower and upper limits for 41
subsequent %rf formats.
%fn Font name format - selects a font for subsequent text. 97
%fp Parameter box format. 263

32
Chapter 4 Format windows

%fr MDI frame format - defines a frame to contain child windows attached 123
by %aw.
%fs File selection format - specifies the working directory and file filter for 105
subsequent file open call-backs.
%ft File filter format - specifies filter information for subsequent file open 106
call-backs.
%ga Gang format - enables radio buttons and/or bitmap buttons to be ganged 59
together so that if one is switched on the others are switched off.
%gd Programmer's grid format - supplies a temporary grid to help with the 95
positioning of controls.
%gf Get font handle format. 97
%gi Draws a (possibly animated/transparent) GIF image. 243
%gp Get window position format - used to get the current co-ordinates of the 94
window position.
%gr Graphics format - provides a rectangular area for Salford graphics ch 15
routines.
%he Help format - specifies the location of help information. 119
%ht Hypertext document attachment. ch 19
%hw Obtains the window handle of the format window. 121
%hx Attaches a horizontal scroll bar to the next control. 247
%ib Image bar - a replacement format for %tb. 247
%ic Icon format - draws an icon. 77
%if Initial focus format - specifies that the next control will have the initial 249
focus.
%il Integer limit format - specifies the lower and upper limits for 42
subsequent %rd formats.
%it Switch to italic font. 97
%lc Obtain the control handle. 249
%ld LED format - displays a round LED (a coloured disk with a black 251
border).
%ls List box format 62
%lv Listview format 252
%lw Leave window open format - allows fX]X^/ to return without closing 122
the window that it creates.
%mg Message format - provides a call-back function for a given Windows 257
message.
%mi Minimise icon format - supplies the name of an icon resource to be used 77
if the window is minimised.
%mn Menu format - used to attach a menu to the window. 81

33
ClearWin+ User’s Guide Fortran

%ms Defines a multi-selection box that stores its settings in an array. Similar 64
to %ls
%mv Move format - provides a call-back function that is to be called when 259
the user moves or resizes the window.
%nc New class name format - provides a specified class name for the 260
application.
%nd Never-down format - prevents controls from sliding down when sizing a 260
window.
%nl New line 260
%nr Never-right format - prevents controls from sliding to the right when 261
sizing a window.
%ns Disable screen saver. 133
%ob Box open format - defines the top left hand corner of a rectangular box 91
into which subsequent objects are to be placed until a corresponding
%cb format is encountered.
%og Graphics format - provides a rectangular area for OpenGL graphics ch 16
routines
%pb Parameter box format. 263
%pd Is used to insert a Sterling pound symbol ‘£’ regardless of editor mode. 100
%pm Supplies a popup menu so that when the right mouse button is pressed 84
in the main window a menu appears.
%ps Property sheet - layer windows to produce a card index style. 129
%pv Pivot format - used to create a pivotal point for any subsequent re-sizing 93
of the window.
%rb Radio button format - defines a radio button or check box with text 55
supplied directly.
%rd Integer input format - creates an edit box and displays an integer that 37
can be updated.
%re Creates an multi-line edit box. 268
%rf Floating point input format - creates an edit box and displays a floating 37
point value that can be updated.
%rj Right justifying format - forces everything which follows it, up to the 90
next new line or form-feed character, to be right justified in the window.
A window margin, if any, is still applied.
%rm Read message format - Provides the name of a call-back function to 270
handle messages from another ClearWin+ application.
%rp Relative position format - Sets the position of the next control relative to 270
the current position.
%rs Character string input format - creates an edit box and displays a 40
character variable (i.e. a string) that can be updated.

34
Chapter 4 Format windows

%sc Start-up call-back. Causes a call-back to be called once when a window 123
is opened - useful for drawing initial %gr data.
%sd Subscript text format. 272
%sf Standard font format - resets to default text attributes after use of any 98
combination of %bf, %it, %ul, %fn, and %ts.
%sh Used with property sheet format. 130
%si Standard icon format - defines a standard icon that is to be placed to the 78
left of the block of text that follows the descriptor.
%sl Produces a slider control using a floating point variable to determine its 44
position.
%sm System menu format. 86
%sp Set window position format - used to initialise the position of the 94
window on the screen.
%ss Allows the settings of selected controls to be auto saved and loaded 48
from an INI file.
%st Variable string format - lays a string out in a field of n characters. The 100
string is re-drawn each time the window is renewed.
%su Superscript text format. 277
%sv Allows the program to become a screen saver executable. 132
%sy Style format - changes the style of a window. 277
%sz Size window format. 126
%ta Insert tab 8-character intervals or to predefined tab stops. See %tl. 279
%tb Bitmap button and toolbar format - defines a bit mapped button or a 56
whole tool-bar.
%tc Sets the colour of subsequent text. 99
%th Bubble help in the form of a ‘Tool tip’. 281
%tl Sets up tab locations for use with %ta. 90
%tp Parameter box format. 263
%ts Text size format - used to scale the text font size either up or down. 99
%tt Textual toolbar format. 54
%tv Hierarchical tree-view 68
%tx Displays an array of text in a rectangular region, defined by its 103
parameters.
%ul Underline text. 97
%up Parameter box format. 263
%uw User window allows windows code to be interfaced to ClearWin+. 131
%vx Attaches a vertical scroll bar to the next control. 286
%wc Character output. 45
%wd Integer output. 45

35
ClearWin+ User’s Guide Fortran

%we Floating point output in exponent form. 46

%wf Floating point output in decimal form. 47
%wg Floating point output in decimal or exponent form. 47
%wp Supplies the name of a wallpaper bitmap which is used as a back drop 131
to its contents.
%ws Character string output. 48
%ww Window control format - causes the resultant window to look like a 126
normal application window, rather than a dialog window.
%wx Hexadecimal integer output. 48

36
5.

Input and output

Interactive I/O
Reading numbers or character strings from a window under ClearWin+ is very
similar to reading data in a traditional program using A403. However, it is important
to remember that each variable must be given an initial value before the window is
created since a default value will appear as soon as the window is displayed.
Tip Checkmate can be used to flag an error when a variable that has not been given a
value is used.
Those controls that allow the user to edit text in a box (such as %rd) can also transfer
text to/from the clipboard using the special ClearWin+ call-back functions 2DC
2>?H ?0BC4, defined in the standard call-back functions described in Chapter
20.

Integer input - %nrd

%rd creates an edit box and displays the value of the corresponding (8=C464A)
argument. The integer will be updated whenever the edit field is adjusted. The user
will be prevented from creating an invalid or out of range integer (see %il below). By
default the edit box will be made large enough to hold integers of the current range,
although the integer parameter n can be used to override this.
For example:
8=C464A _
X,fX]X^/bX4]cTa P] X]cTVTa) "aS_

37
ClearWin+ User’s Guide Fortran

A call-back function is supplied using the caret (^) modifier. This function is called
whenever a change is made.
A grave accent format modifier (`) may be used to make the control read-only. In this
form no surrounding box is supplied, and the value displayed can only be changed by
the program, using fX]S^fNd_SPcT/ to reflect the changes.

Floating point input - %nrf

%rf creates an edit box and displays the value of the corresponding (3>D1;4
?A428B8>=) argument. The number will be updated whenever the edit field is
adjusted. The user will be prevented from creating an invalid or out of range number
(see %fl below). Numbers are entered in decimal or exponent form. For example: -
0.0748 or -7.48e-2.
By default the edit box will be made large enough to hold values in the current range,
although the integer parameter n can be used to override this.
A call-back function is supplied using the caret (^) modifier. This function is called
immediately a change is made.
For example, suppose you wanted to prompt for a complex number, and the user is
allowed to supply this as an (x, y) pair or as an (r,θ) pair. The box should show the
current number in both formats and any change in one format should be reflected in
the other. Here is some sample code that has the desired effect.
F8=0??
3>D1;4 ?A428B8>= ghacWTcP
2><<>= ghacWTcP
8=C464A XfX]X^/
4GC4A=0; R^]eTacNc^NghR^]eTacNc^N_^[Pa
g, 3
h,3
a, 3
cWTcP,3
X,fX]X^/RPJ?^[Pa R^^aSX]PcTbLQVJVaThL
X,fX]X^/"c[$ $!
X,fX]X^/ XcgOXc,cP
X,fX]X^/MaUgR^]eTacNc^N_^[Pa
X,fX]X^/ XchOXc,cP

38
Chapter 5 Input and output

X,fX]X^/MaUhR^]eTacNc^N_^[Pa
X,fX]X^/UU XcaOXc,cP
X,fX]X^/MaUaR^]eTacNc^Ngh
X,fX]X^/ U]JBh\Q^[LXc`bU ,cP
X,fX]X^/MaUcWTcPR^]eTacNc^Ngh
4=3
R
8=C464A 5D=2C8>= R^]eTacNc^N_^[Pa
3>D1;4 ?A428B8>= ghacWTcPcX]h
2><<>= ghacWTcP
cX]h, 3%
a,B@ACgghh
85g;CcX]h0=3h;CcX]hC74=
cWTcP,
4;B4
cWTcP,0C0=!hg
4=385
R^]eTacNc^N_^[Pa,
4=3
R
8=C464A 5D=2C8>= R^]eTacNc^Ngh
3>D1;4 ?A428B8>= ghacWTcP
2><<>= ghacWTcP
g,a2>BcWTcP
h,aB8=cWTcP
R^]eTacNc^Ngh,
4=3

A grave accent format modifier (`) is used to make the control read-only. In this form
no surrounding box is supplied, and the value displayed can only be changed by the
program, using fX]S^fNd_SPcT/ to reflect the changes.
The %co format (see page 40) is used to modify the way that %rf and %rd call-back
functions behave.

39
ClearWin+ User’s Guide Fortran

Character string input format - %nrs

This format takes one character variable and displays it in a single line edit box so
that the user can change it. Optionally, it can be modified with an integer n that sets
the width of the box in characters. The edit box will then scroll horizontally when
necessary. For multiple line edit boxes see %re (page 268) and %eb (page 107).
For example:
270A02C4A' bca
bca,8]XcXP[ bcaX]V _PSSTS fXcW b_PRTb XU ]TTSTS
X,fX]X^/ abbca
It is important to note that because there is an obvious difference between the widths
of characters e.g. ‘i’ and ‘W’, the width is specified in ‘average characters’.
A grave accent format modifier (`) is used to make the control read-only. In this form
no surrounding box is displayed, and the string can only be changed by the program,
using fX]S^fNd_SPcT/ to reflect the changes. This should be used in place of %ws
when it is necessary to display a string which needs to be updated. A similar effect is
produced with %st. (see page 100). The caret is added to provide a call-back function
that will be called on every change to the edit window.

Control option format - %co[option-list]

This format is used to modify the form of subsequent edit boxes associated with %rd,
%rf, and %rs. Currently, four options are available:

RWTRZN^]NU^RdbN[^bb Perform checks and call-back (and update the

corresponding data item) with %rd, %rf, and %rs on
loss of focus only. This is particularly valuable if
numeric limits have been imposed by %il or %fl (see
the Glossary for a definition of the focus).
SPcPNQ^aSTa Put a border round %rd, %rf, and %rs boxes
(default).
Ud[[NRWTRZ Perform checks and call-back on %rd, %rf, and %rs
for every change (default).
]^NSPcPNQ^aSTa Omit border round %rd, %rf, and %rs boxes.

For example:
X,fX]X^/³R^J]^NSPcPNQ^aSTaLX[aS´ Y
X,fX]X^/³][R^JSPcPNQ^aSTaLaS´Z
places a box around the second data area but not the first.

40
Chapter 5 Input and output

Integer increase/decrease format - %dd

Supplies an spin control button to go with an %rd edit box. %dd takes one integer
argument that specifies the amount the value in the edit box is to be increased or
decreased when the user clicks on the control. The resulting value is always a
multiple of the increase. A call-back function can be supplied with the corresponding
%rd format. %dd may also be used with %rs.
For example:
8=C464A eP[X
eP[,
R OaS SXb_[Phb P] X]cTVTa ]^c dbTa RWP]VTPQ[T
X,fX]X^/RPJB_X]LSSOaS$eP[
4=3

Floating point increase/decrease format - %df

Supplies an spin control button to go with a %rf edit box. %df takes one 3>D1;4
?A428B8>= argument that specifies the amount the value in the edit box is to be
increased or decreased when the user clicks on the control. The resulting value is
always a multiple of the increase. A call-back function can be supplied with the
corresponding %rf format. For example
3>D1;4 ?A428B8>= g
8=C464A XfX]X^/
4GC4A=0; RQNUd]R
X,fX]X^/SUMaU 3gRQNUd]R

Floating point limit format - %fl

Specifies the lower and upper limits (as 3>D1;4 ?A428B8>= arguments) for
subsequent %rf formats. The lower and upper limits are supplied as arguments.
For example:
3>D1;4 ?A424B8>= g
X,fX]X^/U[aU3 3g
The lower limit should be specified with care unless R^J2742:N>=N5>2DBN;>BBL
is used. If, for example, the lower limit were 500.0 and the user desired to enter the

41
ClearWin+ User’s Guide Fortran

value 525.0, the number would be rejected as soon as the first digit 5 is entered. If
2742:N>=N5>2DBN;>BB is not used then the lower limit should be chosen to avoid
this problem.

Integer limit format - %il

Specifies the lower and upper limits (as 8=C464A arguments) for subsequent %rd
formats. As for %fl, the lower limit should be specified with care unless
R^J2742:N>=N5>2DBN;>BB] is used.
For example:
8=C464A _
_,
X,fX]X^/bX4]cTa P b\P[[ _^bXcXeT X]cTVTa)X[aS((_
4=3

Parameter box - %N.Mpb[options]

A parameter block is a control that has been designed for use in complex simulation
programs where you may wish to browse a large set of parameter names and values,
with the option to select a value and modify it. A parameter block is defined using
%N.Mpb where N is the width of the block in average characters, and M is the number
of lines in the control. The control will scroll if necessary to display all the
parameters. %pb takes the option b^acTS to cause the parameters to be
alphabetically sorted by name. After a parameter block has been defined, parameters
can be attached by subsequent format codes as follows:
%dp - Integer parameter
%fp - Floating point parameter
%tp - Text parameter
%ep - Enumerated parameter (a set of named alternatives)
%up - User parameter (just activates a call-back)
Each of these format codes is followed by a standard character string that gives the
text to appear in the box. The question mark (?) modifier can be used with any of the
additional format codes as illustrated below but %pb itself takes no modifiers. If a
question mark is used with a parameter, the associated help string is displayed when
the cursor is positioned above that parameter. One use for the user parameter (%up) is
to activate another parameter block to achieve a hierarchical effect.
The various parameter types are illustrated by the following example:
F8=0??

42
Chapter 5 Input and output

8=2;D34 +fX]S^fbX]b-
4GC4A=0; PRcX^]
8=C464A XcTgcdaTNch_T
3>D1;4 ?A428B8>= e_P
270A02C4A' cTgcdaTb%
270A02C4A! ]P\T
30C0 cTgcdaTbBcXRZh<Tbbh3Xach6aTPbhB[X\h
ETah b[X__Tah
30C0 Z Z!Z#Z$ecTgcdaTNch_TP !#$#$#"$#
_, !%
]P\T,1[PRZ ] BcXRZh !"
X,fX]X^/ffJRPbcbNbWPSS^fLRPJ?PaP\TcTa bTccX]VL
X,fX]X^/3^dQ[T R[XRZ ^] cWT _PaP\TcTa h^d fXbW c^´
´RWP]VT)!][
X,fX]X^/"'_QJbâcTSL
X,fX]X^/S_JcTbc LZ
X,fX]X^/S_JcTbc!LZ!
X,fX]X^/T_J>X[ cTgcdaTLcTgcdaTb%cTgcdaTNch_T
X,fX]X^/S_JCT\_TaPcdaT 3TV 2LZ#
X,fX]X^/S_J2PaQ^] \^]^gXST LZ$
X,fX]X^/U_J2daT]c 0\_bcTbc%LP
X,fX]X^/ "U_JE^[cPVTLe
X,fX]X^/U_J>X[ _aTbbdaT ?B8L_
X,fX]X^/
.c_J>X[ ]P\TLJFWPc Xb cWT ÛUXRXP[ ]P\T Û cWXb ^X[.L
! ]P\T
X,fX]X^/d_JB_TRXP[ PRcX^]LPRcX^]
4=3

8=C464A 5D=2C8>= PRcX^]

8=2;D34 +fX]S^fbX]b-
X,fX]X^/=^ b_TRXP[ PRcX^] PePX[PQ[T´
³hTc!][R]QcJ2^]cX]dTL
PRcX^],!
4=3

43
ClearWin+ User’s Guide Fortran

Slider format - %nsl[options]

This format produces a vertical or horizontal (default) slider control n average
characters wide. It takes three arguments which are all floating point values. The
first is a variable to hold the current value, the second its lower limit and the third is
the upper limit.
For example:
F8=0??
8=C464A XfX]X^/
3>D1;4 ?A428B8>= \Pg\X]eP[dTSTU
30C0 \Pg\X]STUeP[dT $
X,fX]X^/RPJB[XSTaLQVJVaThLOR]
X,fX]X^/!b[eP[dT\X]\Pg
X,fX]X^/!][ EP[dT Xb
X,fX]X^/SUU[%aUSTU\X]\PgeP[dT
4=3

44
Chapter 5 Input and output

Data output
Each of the format codes %wd, %wx, %wf, %we, %wg, %ws, and %wc, can be
modified in order to control the way in which the information is presented in the
dialog window. The modifiers are all optional and appear after the % sign with the
following general form:
%[flags][width][.precision] code
where code is one of wd, wf, etc.
[width] represents a positive integer that specifies the minimum number of characters
that are to be output. More characters will be output rather than truncate the result.
Where fewer than the minimum are needed, by default the field is padded with spaces
on the left. Note, however, that with a proportionally spaced font, padding may have
little apparent effect.
[.precision] represents a full stop followed by a positive integer that specifies the
precision of the output. For floating point values, this integer is usually the required
number of decimal places in the output.
Alternatively the [width] and [.precision] values may be replaced with an asterisk (*).
For example:
%[flags][*.*] code
Integer values must then be supplied as arguments, one for each asterisk.
[flags] represents one or more of the characters: minus “-”, zero “0”, plus “+”, and the
hash symbol “#”. These modifiers have various effects depending on the current
format code. For example they are used to force left justification, to pad with zeros
rather than spaces, and to force a plus sign for a non-negative result.
In the following examples ∇ is used to represent a space.

%wc
%wc is used for the output of a single character. The width modifier may be used to
pad out a field with spaces and the minus flag will cause the character to be left
justified in such a field.

%wd
%wd is used for the output of integer values.

45
ClearWin+ User’s Guide Fortran

format output for i=123 comment

%wd 123 minimum width
%6wd ∇∇∇123 minimum of 6 characters, right justified
%6.4wd ∇∇0123 shows 4 digits, with a leading zero
%-6wd 123∇∇∇ left justify
%06wd 000123 pad with zeros on the left
%+6wd ∇∇+123 force a + sign when not negative

Use this format only for displaying formatted text output that does not need to be
refreshed when a variable is modified. Otherwise use %`rd in conjunction with the
fX]S^fNd_SPcT/ call. The grave accent makes the %rd format a read-only text
display box.

%we
%we is used for the output of floating point values in exponent form. The exponent
part (following the letter ‘e’) always contains a sign and two digits.
format output for x=0.0126 comment
%we 1.2607000e-02 6 decimal places, otherwise minimum
width
%14we ∇∇1.260000e-02 minimum of 14 characters, right justified
%10.2we ∇∇1.26e-02 10 characters, 2 decimal places
%6.0we ∇1e-02 6 characters, no decimal point
%-9.1we 1.3e-02∇∇ 9 characters, 1 decimal place, left justified
%010.3we 01.260e-02 right justified, padded with zeros
%+10.2we ∇+1.26e-02 force a + sign when not negative
%#8.0we ∇∇1.e-02 forces a decimal point when the precision
modifier is zero

46
Chapter 5 Input and output

%wf
%wf is used for the output of floating point values in decimal form.

format output for x=1.26 comment

%wf 1.260000 6 decimal places, otherwise minimum width
%10wf ∇∇1.260000 minimum of 10 characters, right justified
%6.2wf ∇∇1.26 6 characters, 2 decimal places
%2.0wf ∇1 2 characters, no decimal point
%-6.1wf 1.3∇∇∇ 6 characters, 1 decimal place, left justified
%07.3wf 001.260 right justified, padded with zeros
%+6.2wf ∇+1.26 force a + sign when not negative
%#4.0wf ∇∇1. forces a decimal point when the precision
modifier is zero

%wg
%wg is used for floating point values and has essentially the same effect as %wf
unless the supplied value cannot adequately be represented in %wf form; in which
case %wg has the same effect as %we. To be specific, the %we form is only used if
the exponent is less than -4 or greater than or equal the precision value. Note,
however, that with %wg, trailing zeros after a decimal point are removed. Where
appropriate, the decimal point is also removed.
format value output comment
%wg 0.0126 0.0126
%10wg 1.26e-4 ∇∇0.000126 exponent is -4
%.3wg 126.7 126.7 exponent is less than the
precision
%9.2wg 1.267e-5 ∇1.27e-05 exponent is less than -4
%7.2wg 100.0 ∇∇1e+02 exponent is equal to the
precision

47
ClearWin+ User’s Guide Fortran

%ws
%ws is used for the output of character strings.

format string output

'Mr %ws Bloggs' 'Frederick' Mr Frederick Bloggs (1)
'Mr %9ws Bloggs' 'Fred' Mr Fred Bloggs (2)
'Mr %`9ws Bloggs' 'Fred' Mr Fred Bloggs (3)
'Mr %.4ws Bloggs' 'Frederick' Mr Fred Bloggs (4)
'Mr %-9ws Bloggs 'Fred' Mr Fred Bloggs (5)

(1) minimum field width,

(2) minimum of 9 characters, right justified,
(3) right justified in a space the width of 9 characters
(4) maximum of 4 characters,
(5) minimum of 9 characters, left justified.

%wx
%wx is similar to %wd but is used to output hexadecimal values. A grave accent (`)
modifier is used to specify an upper case letter hexadecimal output.

Save settings to .INI file - %ss[filename/section]

Saves the supplied variables to an .INI file that is automatically located in the
Windows directory, not the current working directory (the format of an .INI file is
illustrated below). When the program is rerun the variables stored in the .INI file will
automatically be restored (whenever the windows containing the %rs, %rd or %rf
controls are displayed). The file name string (without the extension .INI) must be
supplied in square brackets followed by a (/) character and the section name that will
be used in the .INI file. The item name (within the section) is formed automatically
from the text that appears immediately before the (%rd, %rf, %rs) format code.
A control argument of type 8=C464A must also be supplied. This is a ‘save’ control
flag that prevents the automatic saving of values when set to zero. This is useful when
an abort/abandon path is taken rather than a clean exit, thus preventing erroneous or
incomplete data from being stored. %ss should be placed before the first (%rd, %rf,
%rs) format code.
For example:
8=C464A ]d\bPeTNR^]ca^[X
270A02C4A! SXaTRc^ah
bPeTNR^]ca^[,

48
Chapter 5 Input and output

]d\,
SXaTRc^ah,³ ³
X,fX]X^/³bbJUX[TbTRcX^]L´bPeTNR^]ca^[
X,fX]X^/³DbTab) aS][´]d\
X,fX]X^/³?PcW) ab´SXaTRc^ah
If the user enters ‘12’ and ‘c:\temp’ into the two edit boxes, this creates a file called
file.ini in the Windows directory containing:
JbTRcX^]L
DbTab, !
?PcW,R)KcT\_

49
ClearWin+ User’s Guide Fortran

50
6.

Button controls

Button format - %nbt[button_text]

This format defines a button where button_text represents a standard character string
consisting of the text that is dsiplayed on the button. The text must either be enclosed
in square brackets, or an @ symbol is used to indicate that the text is supplied as an
argument. The buttons of a dialog box are numbered from 1. The fX]X^/ function
returns the number of a button used to close a window or zero if it was closed in some
other way (this assumes the button does not have a call-back). Button names may
include the “&” character in order to provide accelerator keys.
For example:
X,fX]X^/8SX^ccPQcJB^aahL

A grave accent (`) is used to indicate that the button is the default when the Enter key
is pressed. A default button has a slightly different appearance.
The caret character (^) may be used to define a call-back function that is called when
the user clicks on the button (or, if the button is the default button, when the user
presses the Enter key).
For example:
8=C464A XfX]X^/
4GC4A=0; Ud]R
X,fX]X^/?aTbb cWXb c^ bTT fWPc WP__T]b ³

51
ClearWin+ User’s Guide Fortran

X,fX]X^/³MQcJ?A4BBLUd]R
4=3
R5d]RcX^] c^ S^ b^\TcWX]V
8=C464A Ud]RcX^] Ud]R
Ud]R,
4=3

The buttons in a format window (both %bt and %tt) are numbered from 1 in the order
in which they are defined in the format string. When the user clicks on a button that
does not have a call-back function, the format window closes and the corresponding
fX]X^/ call returns the number of the button pressed. For example:
?A8=C fX]X^/QcJ>:LcPQcJ2P]RT[L
outputs the value 1 if ‘OK’ is pressed, 2 if ‘Cancel’ is pressed and zero if the window
is closed without clicking on a button.
Alternatively, if a button has a call-back function that returns a negative value, then
clicking on the button causes the format window to close and the corresponding
fX]X^/ call returns this value made positive. For example:
8=C464A fX]X^/XUd]R
4GC4A=0; Ud]R
X,fX]X^/MQcJ>:LcPQcJ2P]RT[LUd]R
?A8=C X
4=3
8=C464A 5D=2C8>= Ud]R
Ud]R,
4=3
displays the value +1 if ‘OK’ is pressed, 2 if ‘Cancel’ is pressed and zero if the
window is closed without clicking on a button.
Normally a button created with %bt is permanently enabled. However, if the tilde (~)
format modifier is used then an extra 8=C464A argument must be supplied (before any
call-back function). This argument provides an integer that controls the state of the
button. When this integer is zero the button is greyed and cannot be used. When this
integer is 1 the button is enabled. Typically this control integer would be altered by
code responding to another control. For example, after a successful file-opening, a

52
Chapter 6 Button controls

number of options might be enabled. Note that there is no reason why the same
control integer should not control several buttons and/or menu items.
For example:
F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A VaThNR]ca[
4GC4A=0; ^_T]NUbPeTNUbPeTNPbNU
2><<>= VaThNR]ca[
R>][h cWT >?4= Qdcc^] Xb X]XcXP[[h PePX[PQ[T
VaThNR]ca[,
X,fX]X^/ MQcJ>_T]L ³^_T]NU
X,fX]X^/³mMQcJBPeTL ´VaThNR]ca[bPeTNU
X,fX]X^/³mMQcJBPeT PbLVaThNR]ca[bPeTNPbNU
4=3
R
8=C464A Ud]RcX^] ^_T]NU
8=C464A VaThNR]ca[
2><<>= VaThNR]ca[
VaThNR]ca[,
^_T]NU,!
4=3

The width of the button, in average characters, can be supplied using the parameter n
(e.g. QcJBPeTL) rather than this being determined by the width of its text. A
button is created wide enough for at least n characters (possibly more, if the font is not
mono-spaced). This enables a number of buttons of the same size to be created. %fn
and %ts can be used before %bt in order to modify the button text. %bi is used to add
an icon the a button whilst %bc is used to change its background colour.
The text on a button will be placed on more than one line if a line feed character
(270A ) is spliced into the text at the appropriate point.
For example:
Qdcc^]N]P\T,?aTbb270A WTaT
X,fX]X^/Qc/Qdcc^]N]P\T

53
ClearWin+ User’s Guide Fortran

Button colour - %bc[colour]

This format is used in order to specify the background colour for the next %bt button
only. The colour is specified in the same way as for %bg (see page 127). The grave
accent modifier is used to allow the colour to be changed dynamically after the button
has been formed (see page 217).
For example:
X,fX]X^/³RPJ1dcc^] 2^[^daL´
X,fX]X^/³QRJaTSL´
X,fX]X^/³QcJ1dcc^] 0L ´
X,fX]X^/³QR´A61/ !'!$$
X,fX]X^/³QcJ1dcc^] 1L´

Button icon - %bi[icon_name]

This format supplies the name of an icon resource (as a standard character string) for
the next %bt button. For example: QXJcTPNXR^]LQcJL where tea_icon is defined
in an associated resource script (see %ic on page 77). In this example no text would
appear on the button. However, in most cases you will probably want to supply button
text to go with the icon.
For example:
QXJcTPNXR^]LQcJCTPL

Textual toolbar - %tt[button_text]

This format code is much the same as %bt, except that the button is not as tall. Also
the width of the button is rounded up to one of a set of standard sizes. This makes it
possible to produce a textual toolbar (using a sequence of %tt formats) as used, for
example, in the standard Windows Help buttons “Contents”, “Search”, “Back”, etc.
When using this format you will probably want to remove the borders from the
window using the ]^NQ^aSTa option of the %ww format.

54
Chapter 6 Button controls

For example:
F8=0??
8=C464A XfX]X^/
X,fX]X^/ffJ]^NQ^aSTaLRPJCTgcdP[ c^^[QPaL
X,fX]X^/\]J4gXcL4G8C
X,fX]X^/ccJ2^\_X[TLccJ;X]ZLccJAd]L
X,fX]X^/Qg3
X,fX]X^/QVJVaThL
X,fX]X^/_eUa#
4=3

Radio button - %rb[button_text]

This format defines a radio button. The button text is a standard character string. It
takes a single 8=C464A argument that is set to 0 or 1 according to whether the
corresponding control is off or on. The grave accent (`) is used to change this control
to a check box. Radio buttons can be ganged together (see %ga page 59) so that only
one of a set is selected at any one time. Note that it is not “standard” Windows
programming practice to gang check boxes together.
For example:
F8=0??
8=C464A XfX]X^/a!R"
30C0 a R !
X,fX]X^/RPJAPSX^ Qdcc^]bLQVJVaThL
X,fX]X^/5^a\Pc)][
X,fX]X^/!OVPa a!
X,fX]X^/cPaQJ?2GL][a
X,fX]X^/cPaQJ1<?L!][a!
X,fX]X^/2^\_aTbbX^])][
X,fX]X^/"OVPR R!R"
X,fX]X^/cPOaQJ7XVWL][R

55
ClearWin+ User’s Guide Fortran

X,fX]X^/cPOaQJ<TSXd\L][R!
X,fX]X^/cPOaQJ;^fLR"
4=3

The caret character (^) is used in association with a call-back function and this will be
called whenever the item is selected.

Bitmap button and toolbar - %n.mtb

%tb has been superceded by %ib. For new code use %ib instead. See pages 58 and
247 for further details.
This format defines a bit mapped button or a whole toolbar. The names of three
bitmap resources representing the off state, on state, and depressed state should be
supplied as character string arguments, followed by an 8=C464A argument that
represents the state (0 = off, 1 = on). In the absence of a call-back function, pressing
the button toggles the state, but does not close the format window. The correct order
for the arguments is as follows:
³1<?^UU´ ³1<?^]´ ³1<?S^f]´ 2^]ca^[EPaXPQ[T 2P[[QPRZ
Any button on the toolbar can be set to an inactive/disabled state by using the (~) tilde
format modifier. An extra bitmap will be required to represent this state.
For example:
³1<?^UU´ ³1<?^]´ ³1<?S^f]´ ³1<?SXbPQ[TS´ 2^]ca^[EPaXPQ[T
6aTh2^]ca^[EPaXPQ[T 2P[[QPRZ
The caret character (^) is used in association with a call-back function and this will be
called whenever the user clicks on the button.
In order to obtain the effect of a non-toggling button, simply specify the same bitmap
for the on and off states, and supply a call-back function to respond to each button
press. Note that bitmaps may look different on screens of different resolutions.

56
Chapter 6 Button controls

Where necessary the program should supply the appropriate bitmaps for the resolution
in use. Bitmaps can be created using the standard Microsoft “Paint” accessory.
Here is a simple example of the use of bitmap buttons:
F8=0?? S!aR
8=2;D34 +fX]S^fbX]b-
8=C464A P]bfTa
X,fX]X^/7T[[^cPcQ1CN>551CN>=1CN3>F=P]bfTa
4=3
The file d20.rc contains:
1CN>55 18C<0? 1C 1<?
1CN>= 18C<0? 1C!1<?
1CN3>F= 18C<0? 1C"1<?
Using the optional parameters n and m it is possible to create a whole toolbar as a
rectangular array of buttons n items across by m deep. For example, a 1-deep
horizontal bar of 10 items would be represented by %10.1tb (or just %10tb) together
with 30 bitmap resources as the corresponding arguments.
If call-back functions are used, these follow each set of bitmaps thus: ³^UU ´,
³^] ´, ³S^f] ´, Ud]R , ³^UU!´, ³^]!´, ³S^f]!´, Ud]R!,... etc. If the “?”
modifier is used, then n × m help strings must be provided. It is particularly valuable
to provide such help in the case of toolbar buttons, since their meaning is not always
obvious. The following example creates a 3-element horizontal toolbar with help
information and call-back functions. The second button is initially set to the on state.
F8=0?? S! aR
8=2;D34 +fX]S^fbX]b-
8=C464A Q Q!Q"
4GC4A=0; Ud]R Ud]R!Ud]R"
30C0 Q Q!Q"
X,fX]X^/" .McQJ0__[TbLJ>aP]VTbLJ?TPabL
>55 >= 3F= Q Ud]R
! >55!>=!3F=!Q!Ud]R!
" >55">="3F="Q"Ud]R"
4=3
R
8=C464A Ud]RcX^] Ud]R
Ud]R ,
4=3

The file d21.rc contains:

57
ClearWin+ User’s Guide Fortran

>55 18C<0? 1C 1<?

>= 18C<0? 1C!1<?
3F= 18C<0? 1C"1<?
>55! 18C<0? 1C 1<?
>=! 18C<0? 1C!1<?
3F=! 18C<0? 1C"1<?
>55" 18C<0? 1C 1<?
>=" 18C<0? 1C!1<?
3F=" 18C<0? 1C"1<?
Bitmap buttons can be ganged together (see %ga below). A greyed bar can also be
drawn around the tool bar (see %bx below).

Image button and image bar - %n.mib

%ib provides an enhanced and simplified replacement for %tb. Like %tb, %ib can be
used to create toolbars or rectangular arrays of image buttons. However, only one flat
image is required for each button - all the variants are created automatically. Also,
text can be automatically added to the image. Here is some sample code that
illustrates the use of %ib.
F8=0??
8=C464A fX]X^/X
X,fX]X^/RPJ8\PVT QPaLbhJ"SL
X,fX]X^/QS33$3 3
X,fX]X^/\]J5X[TJ4gXcLL4G8C
X,fX]X^/"XQJU[PcLRdc2dc#2>=C8=D4
R^_h2^_h#2>=C8=D4 _PbcT?PbcT#2>=C8=D4
4=3

A4B>DA24B
Rdc 18C<0? RdcQ\_
R^_h 18C<0? R^_hQ\_
_PbcT 18C<0? _PbcTQ\_

The argument list for %ib consists of the following triplet repeated for each button in
turn: bitmap_name, stat_ctrl, cb_func.

58
Chapter 6 Button controls

The first part of the string bitmap_name gives the name of a bitmap resource. If you
want a string to be added to the bitmap then this must come next after an oblique (‘/’).
This string can include linefeed characters (char(10)).
The integer stat_ctrl is used to control the state of the button. The constant value 4 is
used to describe a button that does not toggle, i.e. it is in the down state only whilst
the mouse button is held down. For a button that toggles, use a variable that will take
the value 1 when it is in the up date and the value 2 when in the down state. The state
value 3 describes a button that is greyed and disabled. Every button has a call-back
function cb_func.
The option U[Pc gives a toolbar that is initially flat and grey. When the mouse cursor
is above a button, the image becomes coloured and the button is raised or depressed
depending on its state. When this option is not used the old style of button is
obtained.
%ib is designed for bitmaps that have a grey background. If the image has a one-pixel
border then the border colour is used as the background colour, otherwise the
background is assumed to be light grey (192,192,192). In the above example, the
image bitmaps are 48x24 pixels. This results in buttons of equal width when the
strings are added. See page 247 for further details.

Tool bar border - %bx

This format will add a raised grey bar effect to any tool bar (created using %bt, %tt,
%ib or %tb) set at the top of the window. It takes one floating point argument that
specifies the additional depth (in average characters) to be inserted above and below
the bar.

Gang format - %Nga

By using %ga, radio buttons (%rb) and/or toolbar buttons (%tb) can be ganged
together. At any time at most one control in a gang will be switched on. The addition
of a grave accent (`) makes sure that there is always one control switched on.
The parameter N must be present, and have a value greater than 1. N specifies the
number of controls to be ganged. The argument list must contain N 8=C464A
arguments, that contain the N controlling integers. For example, in the toolbar
example (see page 57), the three controls could be ganged together by modifying the
code thus:
X,fX]X^/"VP´Q Q!Q"
X,fX]X^/³" .McQJ0__[TbLJ>aP]VTbLJ?TPabL
! >55 >= 3F= Q Ud]R
" >55!>=!3F=!Q!Ud]R!
# >55">="3F="Q"Ud]R"

59
ClearWin+ User’s Guide Fortran

The ganging format code may be placed before or after the formats in which the
control variables are actually used. A given variable may be used in more than one
control. However, it is unusual for a variable to appear in more than one gang format
for a given window. If it does then there must only be one variable that is common
and the effect is to merge the two gang sets. If the grave accent is used on one of the
gangs then it must be used on both.

60
7.

Controls other than buttons

Bar format - %N br[options]

This format draws a horizontal or vertical bar which is partially filled with a given
colour. The first argument is a 3>D1;4 ?A428B8>= control variable that indicates
the extent of the fill. This variable should have a value between 0.0D0 and 1.0D0
inclusive. The second argument is an (r,g,b) colour value given by A61/. N is used to
specify the length of the bar, in average characters, when fully filled.
If options are supplied they should be placed in square brackets and separated by
commas. The following options are available:

[TUcNaXVWc Bar is drawn horizontally left to right (default).

aXVWcN[TUc Bar is drawn horizontally right to left.
c^_NQ^cc^\ Bar is drawn vertically from the top.
Q^cc^\Nc^_ Bar is drawn vertically from the bottom.
]^NQ^aSTa No bar border is drawn.

The bar is updated by using the fX]S^fNd_SPcT/ function. This should be called at
suitable intervals to provide a smooth progression. This is illustrated in the following
example:
F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A Rca[
3>D1;4 ?A428B8>= S
S,
X,fX]X^/RPJ1Pa U^a\PcL´
X,fX]X^/³?a^RTbbX]V !][´
X,fX]X^/³!Qa´SA61/!$$!$$

61
ClearWin+ User’s Guide Fortran

X,fX]X^/³[fRca[
3> F78;4S;C
3> X,
4=3 3>
S,S
R CWT SPcP WPb RWP]VTS b^ _a^\_c fX]S^fb c^
R d_SPcT cWT QPa SXb_[Ph
20;; fX]S^fNd_SPcT/S
4=3 3>
4=3

The above program will produce a horizontal bar which will extend to the right as the
task proceeds.

Horizontal and vertical scroll bars %hx and %vx

Both %hx and %vx have similar meaning and usage. %vx generates a vertical scroll
bar on the right-hand side of the next control and %hx a horizontal scroll bar along
the bottom of the next control. %hx and %vx should not be used with controls (like
%eb and %cw) that have their own scroll bar mechanism. Three arguments must be
supplied to both format codes. The first is an 8=C464A argument that determines the
‘page step’. This determines the amount the scroll box (also called the thumb) moves
each time the left mouse button is pressed inside the scroll bar region. You would
normally link this value to the effect of a ‘page change’ in the control. The second
argument is the maximum value (call this max say) that the scroll bar may generate.
The third argument holds the current value of the scroll bar. This is of type 8=C464A
and will be in the range 0 to (max - 1). A call-back function is provided when the
caret modifier is used. See also pages 247 and 286.

List box format - %n.mls[options]

This format supplies a simple list-box facility. The corresponding arguments are an
array of 270A02C4A strings, an 8=C464A argument giving the size of the array and
an 8=C464A argument that both sets the initial selection and returns the result.

62
Chapter 7 Controls other than buttons

For example:
8=C464A Z
270A02C4A VaTTZ#$
30C0 VaTTZXX, #P[_WPQTcPVP\\P´ST[cP´
Z,
X,fX]X^/BT[TRc P 6aTTZ [TccTa) &"[bVaTTZ#;Z
4=3
The characters “7.3” before “ls” specify the width of the list box (as the number of
characters) and the depth of the list box (as the number of lines). Pre-setting k to 1
would cause “alpha” to be already highlighted when the window is displayed. If the
user selects “beta”, then k set to 2. If k were pre-set to zero, none of the items would
be initially selected. If the user were to exit without making a selection, k would keep
its pre-set value.

The grave accent (`) may be used with %ls to produce a drop-down combo box rather
than a list box (for an editable combo box see %el on page 236). The caret (^)
character is used in association with a call-back function. This function will be called
whenever an item is selected.
For example:
4GC4A=0; [bNUd]RcX^]
X,fX]X^/M[bPaaPh%;][bNUd]RcX^]
(See also the ;8BC1>GN8C4<NB4;42C43 parameter in R[TPafX]NX]U^/ page 337).
For a list box (i.e. when a grave accent modifier is not used), the option WbRa^[[QPa
provides a horizontal scroll bar whilst the option \d[cXR^[d\] provides a multiple
column display. For example:
270A02C4A' UadXc&
30C0 UadXc0__[Tb1P]P]Pb2WTaaXTb6aP_Tb
>aP]VTb?TPab?[d\b
X,fX]X^/!##;BJ\d[cXR^[d\]LUadXc&Z

63
ClearWin+ User’s Guide Fortran

Combining WbRa^[[QPa with \d[cXR^[d\] gives a horizontal scroll bar that

selects one column at a time.

Multiple selection box - %n.mms

%ms creates a list box that allows the user to select more than one item at a time. It is
similar to %ls but the variable returning the result is replaced by an integer array.
The elements of this array should be initialised to a value of zero for initially de-
selected items and to a value of 1 for selected items. The array is updated as the user
changes the selection.
n and m are optional (m cannot be specified without n). n represents the width of the
multiple selection box (as a number of characters) and m the depth (as the number of
lines). %ms requires three arguments. The first is an array of 270A02C4A strings;
the second is the number of entries in the list; and the third is an array of type
8=C464A. The two arrays must have the same number of elements. If the number of
elements that are displayed is less than the number in the list then a vertical scroll bar
is provided. If a call-back function is supplied then it is called each time the user
selects an item.
The following program illustrates some typical cases:
F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A ZX
8=C464A XeTR&
270A02C4A cWX]Vb&
30C0 cWX]Vb0__[Tb1P]P]Pb2WTaaXTb6aP_Tb
>aP]VTb´ ³?TPab´ ³APb_QTaaXTb
R BTc cWT X]XcXP[ eP[dTb U^a cWT bT[TRcX^]b
30C0 XeTR
X,fX]X^/RPJBT[TRcX]V cWX]VbL´
X,fX]X^/³"c[ $"#$
X,fX]X^/cRJaTSLBX\_[TcP3a^_S^f]cPBRa^[[X]VcP
X,fX]X^/³<d[cX_[T bT[TRcX^]][cRJQ[PRZL

64
Chapter 7 Controls other than buttons

X,fX]X^/[bcPcWX]Vb&Z
X,fX]X^/O[bcPcWX]Vb&Z
X,fX]X^/ "[bcPcWX]Vb&Z
X,fX]X^/\bcWX]Vb&XeTR
X,fX]X^/UU][=^cT cWPc cWT UXabc cWaTT Q^gTb PaT
X,fX]X^/´R^d_[TS c^VTcWTa][
X,fX]X^/QTRPdbT cWTh bWPaT cWT aTbd[c ePaXPQ[T Z
4=3

List-view - %lv[options]
A list view control is a window that displays a collection of items, each item
consisting of an optional icon and a label. List view controls provide several ways of
arranging items and displaying individual items. One of the arguments for %lv is an
integer variable in the range 0..3 that represents the type of view: 0=Icon view;
1=Report view; 2=Small icon view; 3=List view. In the report view, additional
information about each item can be displayed in columns to the right of the icon and
label. The Microsoft Explorer uses a list view in order to display directory
information. Here is a Fortran 90 example that illustrates the concept. For further
details see page 252.
8=C464A =
?0A0<4C4A =,!
270A02C4A"% X]U^= 2^[^daXR^]b%
8=C464A aVQ=bT[=eXTfWf]SfX]X^/A61/
2><<>= X]U^aVQWf]S
4GC4A=0; RP[[NQPRZ

65
ClearWin+ User’s Guide Fortran

8=C464A RP[[NQPRZX
bT[,*aVQ,
aVQ ,A61/!$$
aVQ!,A61/!$$
aVQ",A61/!$$
aVQ#,A61/!$$!$$
aVQ$,A61/!$$!$$
aVQ%,A61/!$$!$$
X]U^ ,k2^[^daN(kATSk6aTT]k1[dT
X]U^!,2^[^dak0ATSk aVQ
X]U^",2^[^dak16aTT]k aVQ!
X]U^#,2^[^dak21[dTk aVQ"
X]U^$,2^[^dak32hP]k aVQ#
X]U^%,2^[^dak4<PVT]cPk aVQ$
X]U^&,2^[^dak5HT[[^fk aVQ%
eXTf,
XR^]b,aTSVaTT]Q[dTRhP]\PVT]cPhT[[^fQ[P]Z
X,fX]X^/ffbhJ"SLRPJ;XbceXTf bP\_[TL
X,fX]X^/\]JEXTfbJ8R^]LL B4CeXTf
X,fX]X^/\]JJAT_^acLL B4CeXTf
X,fX]X^/\]JJB\P[[ XR^]LLB4CeXTf!
X,fX]X^/\]JJ;XbcLL B4CeXTf"
X,fX]X^/_eOM[eJTSXcN[PQT[bbX]V[TNbT[TRcX^]L
!# !X]U^=bT[eXTfXR^]bRP[[NQPRZ
X,fX]X^/UUR] Oab[RBT[TRcTS R^[^daWf]S
4=3

270A02C4A"% 5D=2C8>= 2^[^da]P\TaVQ

270A02C4A ]P\T
8=C464A aVQaVQ
270A02C4A" aRVRQR
a,0=3!$$aVQ
V,0=3!$$ABaVQ'
Q,0=3!$$ABaVQ %
FA8C4aRX" a
FA8C4VRX" V
FA8C4QRX" Q
aR,039DBC;aR
VR,039DBC;VR
QR,039DBC;QR
FA8C42^[^da%P ]P\TaR );4=NCA8<aRk
VR );4=NCA8<VRkQR );4=NCA8<QR
4=3

66
Chapter 7 Controls other than buttons

8=C464A 5D=2C8>= RP[[NQPRZ

8=2;D34 +fX]S^fbX]b-
8=C464A =
?0A0<4C4A =,!
270A02C4A"% X]U^=
8=C464A aVQ=Wf]Sa^f
2><<>= X]U^aVQWf]S
270A02C4A"% 2^[^da]P\T
RP[[NQPRZ,!
B4;42C 20B4R[TPafX]NbcaX]V/20;;102:NA40B>=
20B4B4CNB4;42C8>=
a^f,R[TPafX]NX]U^/A>FN=D<14A
20;; bTcNR^]ca^[NcTgcNR^[^da/Wf]SaVQa^f
20B44=3N438C
]P\T,R[TPafX]NbcaX]V/438C43NC4GC
a^f,R[TPafX]NX]U^/A>FN=D<14A
X]U^a^f "),2^[^da]P\T );4=NCA8<]P\TkaVQa^f
20;; fX]S^fNd_SPcT/X]U^
4=3 B4;42C
4=3

A4B>DA24B
aTS 82>= aTSXR^
VaTT] 82>= VaTT]XR^
Q[dT 82>= Q[dTXR^
RhP] 82>= RhP]XR^
\PVT]cP 82>= \PVT]cPXR^
hT[[^f 82>= hT[[^fXR^
Q[P]Z 82>= Q[P]ZXR^
The fX]X^/ statement that generates the list-view is:
X,fX]X^/OM[eJTSXcN[PQT[bbX]V[TNbT[TRcX^]L
!# !X]U^=bT[eXTfXR^]bRP[[NQPRZ
Here is an outline of the meaning of the symbols and variables used in this statement:
grave accent a list of icons (called icons) is supplied
caret a call-back function (called call_back) is supplied
edit_lables an option that enables the names of the colours to be edited by
the user
single_selection an option that ensures that at most one colour can be selected at
a time
240 the initial width of the list-view in pixels

67
ClearWin+ User’s Guide Fortran

120 the initial height of the list-view in pixels

info an array of strings that defines each row; the first row defines
the column headings; the first character on subsequent rows is
an index (A, B, C,...) that selects an icon from the list of icons;
different fields are separated by a pipe ‘|’ symbol.
N a parameter defining the maximum number of rows
sel an integer array to mark the current selection
icons a string of icon resources
call_back a call-back function that is used when a selection is made and
when the end of label editing is detected.

Tree-view - %N.M tv[options]

The %tv format is used to construct a hierarchical list box that is analogous to the type
of control sometimes used to display a directory structure. %bv is a newer format that
is similar to %tv but has more options (see below). %tv takes a 270A02C4A array
followed by an 8=C464A argument giving the size of the array. The final argument is
an 8=C464A argument (call it sel) that is used to receive the index of the chosen item.
The format modifiers N and M set the width and depth of the tree-view in ‘average
characters’. The control operates in a manner that is similar to a listbox except that
the first two characters of each string have a special meaning. The first character
must be a capital letter (‘A’ - ‘Z’) indicating the level of the item within the hierarchy.
The second letter should be a ‘C’ if the item is to be displayed compactly (i.e. not

68
Chapter 7 Controls other than buttons

displaying any children) and ‘E’ if the item is to be displayed expanded. Consider the
following list of things:
AEFood
BEFruit
CCApples
CCPears
BCNuts
CCHazel nuts
CCBrazil nuts
AEDrink
BCAlcoholic
BCNon-alcoholic
The children of a node (together with any of their children, etc.) are placed
immediately beneath the parent node. In the example shown the types of nuts would
not immediately be shown because of the ‘C’ in ‘BCNuts’. Any node is expanded and
contracted by simply by clicking on it. Usually you would code ‘C’ for the second
character of each string. This would produce an initial display showing only the top
level. As nodes are expanded and contracted, the information is stored in the strings.
This means that, if the strings are used to display the hierarchy a second time, the
display will start from where it left off. You could even store the strings in a file so
that the expanded state would be the same from one run to another.
Items with a lower case letter or a blank in the first position are ignored and never
displayed. This provides a means to hide elements, or to provide space for the display
to grow dynamically. If a node has no children you can use ‘E’ or ‘C’ - there is no
difference.
Notice that it makes no sense for a level 2 item (say) to be followed immediately by a
level 4 item. An item may not be followed immediately by its ‘grandchildren’. This
condition will be detected as an error. Conversely, a level may decrease by any
amount.
%tv can take a call-back function. The call-back function may use the index of the
chosen item (i.e. the argument sel) and can also get the value of
R[TPafX]NX]U^/´CA44E84FN8C4<NB4;42C43´. This value will be equal to 1
if the call-back is responding to a double click mouse event.
By default, the tree-view displays bullet marks to the left of the nodes. By using a
grave accent with %tv, the bullet marks are replaced by icons. When the grave accent
is used, the third character in each string is interpreted as an index (‘A’ - ‘Z’) into a
list of icons. This icon list is supplied as an extra argument that consists of icon
resources separated by commas (e.g. 82>= 82>=!82>="). You should
construct the icons in such a way that the image is confined to the top left 16 x 16
corner. The remainder of the icon should be filled with the transparent colour. The
Salford icon editor SCION can be used for this purpose.

69
ClearWin+ User’s Guide Fortran

By providing a call-back that examines the expansion indicator (character two of each
string) it is possible to change the icon index to reflect whether or not the icon is
expanded. If you perform a change of this sort you should pass the main array to
fX]S^fNd_SPcT/ to force the control to be updated.
The following example illustrates the use of tree-view controls:
F8=0??
1;>2: 30C0
270A02C4A" R^]cT]cb$%
8=C464A XcT\
2><<>=2R^]cT]cb
2><<>=8XcT\
30C0 R^]cT]cb
0201^^Z 1202WP_cTa 220BTRcX^]
220BTRcX^] ! 220BTRcX^] " 220BTRcX^] #

220BTRcX^] " 220BTRcX^] #
4=3
R
8=C464A 5D=2C8>= cTbc
R
R 2P[[QPRZ Ud]RcX^] bTcb cWT XR^] Uâ
R TPRW ^QYTRc PRRâSX]V c^ fWTcWTa Xc Xb Tg_P]STS â ]^c
R
270A02C4A" R^]cT]cb$%
8=C464A XcT\
2><<>=2R^]cT]cb
2><<>=8XcT\
270A02C4A" bcaX]V
bcaX]V,R^]cT]cbXcT\
85bcaX]V!)!4@4C74=
bcaX]V")",1
4;B4
bcaX]V")",0
4=385
20;; fX]S^fNd_SPcT/R^]cT]cb
cTbc,!
4=3
R <PX] _a^VaP\ Ydbc RP[[ F8=8>/
4GC4A=0; cTbc

70
Chapter 7 Controls other than buttons

270A02C4A" R^]cT]cb$%
8=C464A XcT\fX]X^/P
2><<>=2R^]cT]cb
2><<>=8XcT\
P,fX]X^/ff^Q_e´
P,fX]X^/³MO! $ce´
R^]cT]cb$%XcT\2;>B43N1>>:>?4=N1>>:cTbc
P,fX]X^/³RQUU][R]OQcJ>:L
4=3
Link this with a resource file containing the following:
2;>B43N1>>: 82>= 1>>: 82>
>?4=N1>>: 82>= 1>>:!82>

Branch-view - %bv[options]
The %bv format is used to construct a hierarchical tree-view that is similar to %tv.
%bv gives a control with a slightly different appearance. %bv has more options and is

71
ClearWin+ User’s Guide Fortran

simpler to use because a call-back function is nolonger needed in order to change the
image when expanding a node. Here is some sample code like that for %tv:
F8=0??
270A02C4A" R^]cT]cb$%U\c !
8=C464A XcT\XfX]X^/
30C0 R^]cT]cb
0411^^Z 1202WP_cTa 220BTRcX^]

XcT\,
U\c,OQeJWPbNQdcc^]bWPbN[X]TbbW^fNbT[TRcX^]NP[fPhb
TSXcN[PQT[b[X]TbNPcNa^^c_PXaTSNQXc\P_bL
X,fX]X^/ffbhJ"SL_e
X,fX]X^/RPJ1aP]RWeXTfL
X,fX]X^/U\c! %R^]cT]cb$%XcT\2;>B43>?4=
4=3
A4B>DA24B
2;>B43 18C<0? R[^bTQQ\_
>?4= 18C<0? ^_T]QQ\_

%bv uses 16x16 bitmaps. The character array called contents is constructed in the
same way as for %tv. The option _PXaTSNQXc\P_b indicates that the list of bitmaps
³2;>B43 >?4=´ is ordered such that the bitmap for an expanded node (OPEN)
follows immediately after that for the corresponding collapsed node (CLOSE). For
further details see page 222.

72
Chapter 7 Controls other than buttons

Colour palette - %cl[options]

The %cl format code allows the user to select from a set colours presented in a palette.
The user can also change the palette. Note that the range of colours available depends
on the video display and currently selected display mode.
This format takes one array argument of type 8=C464A that holds the values of up to
three selected colours (for, respectively, the mouse left button, the right button and the
middle button - values that are not used return a shade of grey). These values are in
the same format as the result of the A61/ function.
F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A Xe"
X,fX]X^/³RPJR^[^da _P[TccTL R[´e
X,fX]X^/³RPJR^[^da \Xg aTbd[cL CWT R^[^da fPb fS´e
4=3

The options are:

b1 Right mouse button only
b2 Left and right buttons (the default)
b3 Left , right and middle buttons
title1 Title above button boxes
title2 Title above palette
iconic Transparent and inverse transparent selection

See page 227 for further details.

73
ClearWin+ User’s Guide Fortran

74
8.

Bitmaps, Cursors, Icons

Bitmap - %bm[bitmap_name]
This is similar to the icon format %ic (see page 77) but the picture is supplied as a
simple bitmap. For example we could write:
X,fX]X^/CWXb Xb P QXc\P_) Q\JcTPNQXc\P_L
and the resource script would include a line of the form:
cTPNQXc\P_ 18C<0? 1C 1<?
The grave accent is used to specify that the bitmap is supplied via a handle rather than
a name. A suitable handle is returned by \PZTNQXc\P_/ or by the Windows API
function LoadBitmap. If you want to use LoadBitmap to access one of the pre-
defined bitmaps then you will need to create your own binding to LoadBitmap. For
example:
8=C464A WNQXc\P_>1<N3=0AA>F
?0A0<4C4A >1<N3=0AA>F,I&55;
BC320;; <h;^PS1Xc\P_ ;^PS1Xc\P_0 E0;E0;)8=C464A
WNQXc\P_,<h;^PS1Xc\P_=D;;>1<N3=0AA>F
X,fX]X^/OQ\WNQXc\P_
A call-back function can be added to a bitmap by using the caret (^) format modifier.
The %gi format is also available and works in the same way as %bm except that it
uses a GIF resource created from an image file stored in GIF format. GIF files are
compressed and may be animated and/or partially transparent. They therefore make
ideal eye-catching features. See page 243 for further details.

75
ClearWin+ User’s Guide Fortran

Cursor - %cu[cursor_name]
By default the mouse cursor is represented by an arrow except in graphics regions
(such as %gr) where by default it is represented by a cross. Two formats are supplied
to change the mouse cursor representation. %dc sets the default cursor for the window
as a whole, and %cu sets the cursor for the next control in the window. Each is
followed by a standard character string (i.e. a string in square brackets or an @
character indicating that the required string is supplied as an argument). The string
should be the name of a 2DAB>A resource. By using a grave accent (`), you can use
constants representing the standard Windows cursors. These constants are defined in
windows.ins.
For example:
P,fX]X^/OSR´2DAB>AN8140<
P,fX]X^/³^QORd´2DAB>ANF08C
P,fX]X^/³Va´
P,fX]X^/³RQUU][R]OQcJ>:L
For further information see %dc below.
%cu and %dc also have a more complex form in which several alternative cursors are
supplied, together with an integer used to select the one to use. The integer should be
in the range from 1 to the number of different cursors supplied.
For example:
8=C464A Z
Z,
X,fX]X^/"SRJ2DAB>AN LJ2DAB>AN!LJ2DAB>AN"LZ
Whenever the cursor is in the main window, its shape will be governed by the current
value of Z. The %cu format is used in a similar way.

Default cursor - %dc[cursor_name]

By default, fX]X^/ supplies an arrow for the mouse cursor. The %dc format takes a
standard character string giving the name of the cursor resource or, if a grave accent
format modifier is used, it takes an argument that is one of the following constants
representing built-in Windows cursors:

2DAB>AN0AA>F Standard arrow cursor

2DAB>AN8140< Text I-beam cursor
2DAB>ANF08C Hourglass cursor
2DAB>AN2A>BB Cross hair cursor
2DAB>AND?0AA>F Vertical arrow cursor

76
Chapter 8 Bitmaps, Cursors, Icons

2DAB>ANB8I4 A square with a smaller square inside its lower-right

corner
2DAB>AN82>= Empty icon
2DAB>ANB8I4=FB4 Double-pointed cursor with arrows pointing Northwest and
Southeast
2DAB>ANB8I4=4BF Double-pointed cursor with arrows pointing Northeast and
Southwest
2DAB>ANB8I4F4 Double-pointed cursor with arrows pointing west and east
2DAB>ANB8I4=B Double-pointed cursor with arrows pointing North and
South

For example:
X,fX]X^/OSR2DAB>AN8140<
whilst for a user defined cursor:
X,fX]X^/SRJ\hNRdabâL
combined with a resource script that contains the line:
\hNRdabâ 2DAB>A RdabâRda
The file cursor.cur is created using an image editor.
See the description of %cu (page 76) for a further example of how %dc is used and
how several different cursors can be used for different parts of the format window.

Icon - %ic[icon_name]
This format supplies the name of an icon resource (as a standard character string). It
is drawn at the current position in the format window.
For example:
F8=0?? S!'aR
8=2;D34 +fX]S^fbX]b-
X,fX]X^/CWXb Xb P] XR^]) XRJfX]NXR^]L
4=3

In a separate file called d28.rc we have:

fX]NXR^] 82>= fX]S^fXR^

77
ClearWin+ User’s Guide Fortran

The caret (^) character is used to attach a call-back function to an icon. The function
is called each time the user clicks on the icon.
Icons differ in one respect from bitmaps in that they may have transparent regions that
make the image appear to sit on the background in the same way that text does.
If a grave accent (`) is used, the icon is supplied via an icon handle. A suitable handle
is returned by \PZTNXR^]/ (see page 377) or by the Windows API function
LoadIcon. If you want to use LoadIcon to access one of the pre-defined icons then
you will need to create your own binding to LoadIcon. For example:
BC320;; <h;^PS8R^] ;^PS8R^]0 eP[eP[)8=C464A
8=C464A WNXR^]
WNXR^],<h;^PS8R^]=D;;838N@D4BC8>=
X,fX]X^/OXRWNXR^]

Minimise icon - %mi[icon_name]

This format supplies the name of an icon resource (as a standard character string) to
be used if the window is minimised. The %ww format must be used in order for it to
be possible to minimise the window.
For example:
F8=0?? S aR
8=2;D34 +fX]S^fbX]b-
X,fX]X^/ff3^]c QT [PcT U^a cTP\XJcTPNXR^]L
4=3
The file d10.rc contains:
cTPNXR^] 82>= cTPXR^

Standard icon - %nsisymbol

Defines a standard icon that is to be placed to the left of the block of text that follows
the format code. symbol is one of “?”, “*”, “!”, and “#”. The icons given by these
symbols are illustrated below.
For example:
X,fX]X^/!bX.!bXM!bX!bXRQNXR^]
X,fX]X^/³!][CWTbT PaT P[[ cWT bcP]SPaS XR^]b´
X,fX]X^/³!][R]&QcJ>:L

78
Chapter 8 Bitmaps, Cursors, Icons

The symbol is vertically centred to the left of n lines of text (the parameter n defaults
to 1), and a half icon width is left blank to the right so as to leave an appropriate gap
between the icon and subsequent text. Sound is added by attaching the “144?” call-
back (see page 206). Alternatively, you can call the API function MessageBeep
before creating the format window.
The caret character (^) is used with %si in order to attach a call-back function. This
function is called each time the user clicks on the icon. In the above example the ‘!’
icon uses the call-back function cb_icon.

Using the handle of a resource

ClearWin+ controls that take the name of a bitmap, icon, or cursor resource, can be
given a string consisting of a decimal integer enclosed in curly brackets (with no
embedded spaces), for example {21542}. The number should be the decimal value of
a Windows handle to an object of the appropriate type. If the handle is invalid the
results will be unpredictable.
For example:
270A02C4A"! XR^]"!WP]S[T
XR^] ,

XR^]"!,
FA8C4WP]S[TX \PZTNXR^]/XR^]
X,fX]X^/XRJjWP]S[TlL
For %bm, %ic, %mi, %cu, and %dc it is easier to use a grave accent, supplying the
handle as an integer argument . However, the above technique is useful for other
format codes (e.g. %bi, %ti, %tb, %tv) and when format strings must be constructed
dynamically under program control.

79
ClearWin+ User’s Guide Fortran

80
9.

Menus and accelerator keys

Menu format - %mn[menu_specification]

%mn is used to attach a menu to the window. This is best illustrated by an example:
X,fX]X^/\]J0[_WP1TcPJ1TcP 1TcP!k1TcP"L6P\\PL
RQ RQ!RQ"RQ#RQ$

This format specifies five selectable items, three of which, 1TcP , 1TcP!, and 1TcP"
are contained in a drop-down menu. A bar symbol ( | ) between 1TcP! and 1TcP"
causes a separator to be drawn in the drop-down menu. The three top-level menu
items (0[_WP, 1TcP and 6P\\P) can be selected using accelerator keys Alt-A, Alt-B
and Alt-G that are specified by the inclusion of the ampersand character (&) placed to
the left of the character chosen to be the (unique) accelerator for this menu (a double
ampersand (&&) is required if you want an ampersand to appear in the text). Five
call-back functions are required as arguments corresponding to each selectable menu
item. A call-back function is called when the corresponding menu item is selected.
Individual menu items may also be greyed (so that they are visible, but not usable). In
order to grey an item, prefix its name with a tilde (~) and insert an 8=C464A
argument to provide a control integer. When the value of this integer is zero, the item
is greyed and disabled, otherwise it is enabled. Note that it is not necessary to use a
different control integer for every item. You can use one integer to control several

81
ClearWin+ User’s Guide Fortran

menu items and/or buttons. The following example illustrates a 3-item menu, in
which the middle item is greyed:
F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A SaX]ZTa
4GC4A=0; b`dPbWNUd]RQTTaNUd]RcTPNUd]R
SaX]ZTa,
X,fX]X^/\]JB`dPbWL´b`dPbWNUd]R
X,fX]X^/³\]Jm1TTaL´SaX]ZTaQTTaNUd]R
X,fX]X^/³\]JCTPLcTPNUd]R
4=3
R RP[[ QPRZ Ud]RcX^]
8=C464A 5D=2C8>= b`dPbWNUd]R
b`dPbWNUd]R,
4=3

The hash character (#) is used to control the placement of a check mark (tick) at the
front of a menu item. The corresponding control variable is set to the value 1 in order
to display a check mark otherwise it is set to zero. Top level menu items cannot be
checked.
As an alternative to using the ampersand (&) before a character, an accelerator key
may also be associated with a menu item and its corresponding call-back function as
illustrated in the following example.
X,fX]X^/\]J5X[TJ>_T]2ca[5 !LL^_T]NUd]R
The paragraph mark ¶ (270A!) is used here as an alias for the tab character
(270A() and is followed by the key name. Valid key names are illustrated with the
accelerator key format %ac below. The use of an accelerator key is is only permitted in
sub-menus and should not be used in top level menus.
In order to continue a menu in a new fX]X^/ statement, it is necessary to match
opening square brackets with closing brackets on the line to be continued. Then use
an appropriate number of opening square brackets on the next line. For example:
X,fX]X^/³\]JCTbc5X[TJ>_T]LL´U U!
X,fX]X^/³\]JJBPeTL7T[_L´U"U#
is equivalent to

82
Chapter 9 Menus and accelerator keys

X,fX]X^/³\]JCTbc5X[TJ>_T]BPeTL7T[_L´U U!U"U#
Help strings are provided by inserting a question mark (%?mn). All the strings are
placed in order at the end of the format description, one for each item that has a call-
back function. For example,
X,fX]X^/.\]J5X[TJ=TfLLJBcPac P ]Tf UX[TL´]TfU]
X,fX]X^/³.\]JJBPeTLLJBPeT cWXb UX[TLbPeTU]
Separators also require a help string but this is not used.

Dynamic Menus
If you wish to add or remove menu items whilst the program is running then this is
possible with the aid of a handle:
X,fX]X^/³\]JFX]S^fJLL ´ WP]S[T
The asterisk (*) causes %mn to provide a handle that is passed
to either PSSN\T]dNXcT\/ (see page 333) or
aT\^eTN\T]dNXcT\/ (see page 394). Note that items are
added to the end of the pop-down menu that contains the
handle. You may have a number of handles for various pop-
down menus.
Only one handle is required to create a menu with multiple
entries. To detect which menu entry has been selected use
R[TPafX]NbcaX]V/³2DAA4=CN<4=DN8C4<´ to obtain
the text of the menu item selected.
Here is some sample code that illustrates how to add a list of files to a file menu.
F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A XWP]S[TRca[RQRQ
270A02C4A !( U]P\T
4GC4A=0; RQRQ
2><<>= Rca[
X,fX]X^/\]J5X[TJ=TfLLRQ
X,fX]X^/\]JJ>_T]LL RQ
X,fX]X^/\]JJBPeTkLL RQ
X,fX]X^/\]JJLLWP]S[T
X,fX]X^/[fRca[
3> X, "
FA8C4U]P\TP8 5X[TX
20;; PSSN\T]dNXcT\/WP]S[TU]P\T RQ
4=33>
20;; PSSN\T]dNXcT\/WP]S[T270ARQ

83
ClearWin+ User’s Guide Fortran

20;; PSSN\T]dNXcT\/WP]S[T4gXc RQ

4=3
R
8=C464A 5D=2C8>= RQ
RQ,
4=3
R
8=C464A 5D=2C8>= RQ
8=2;D34 +fX]S^fbX]b-
8=C464A Rca[
2><<>= Rca[
Rca[,
20;; fX]S^fNd_SPcT/Rca[
RQ,
4=3

Popup menu - %pm[menu_specification]

This format code is almost identical to %mn but a popup menu is activated when the
right mouse button is pressed in the format window. Please refer to %mn above for
general information on how to contruct a menu.
In the example below a popup menu controls the mathematical operation carried out
on two values that are provided by slider controls. The divide option is greyed out
whenever the slider for the denominator gives zero. An attempt to divide by zero
would cause a processor exception. This has been included to show how to use the
tilde (~) character.
F8=0??
R2^_h c^ _\X]b
8=2;D34 +fX]S^fbX]b-
8=C464A T]PQ[T\^STR$
3>D1;4 ?A428B8>= ae e!
2><<>= T]PQ[T\^STRae e!
R4]S ^U _\X]b
3>D1;4 ?A428B8>= \X]\PgbcT_
4GC4A=0; RP[RbTc\^ST
8=C464A XRP[RbTc\^ST
3> X, $
RX,
4=33>
\X],3
\Pg, 3
bcT_, 3
T]PQ[T,
\^ST,"

84
Chapter 9 Menus and accelerator keys

R\^ST,
e ,3
e!, 3
X,fX]X^/ffJ]^NQ^aSTa]^N\PgQ^gLRPJ?^_d_L
X,fX]X^/!!^QJcWX]N_P]T[[TSL
X,fX]X^/M b[RQe \X]\PgRP[R
X,fX]X^/ Sh"3
X,fX]X^/SUM#aURQbcT_e RP[R
X,fX]X^/M b[RQe!\X]\PgRP[R
X,fX]X^/ Sh"3
X,fX]X^/SUM#aURQbcT_e!RP[R
X,fX]X^/UU^QJbcPcdbcWX]N_P]T[[TSL
X,fX]X^/cPShO&aURQ"3a
X,fX]X^/_\J<d[cX_[hL R bTc\^ST
X,fX]X^/_\Jm3XeXSTkLT]PQ[TR!bTc\^ST
X,fX]X^/_\J0SSL R"bTc\^ST
X,fX]X^/_\JBdQcaPRcL R#bTc\^ST
4=3
R
8=C464A 5D=2C8>= bTc\^ST
8=2;D34 _\X]b
270A02C4A XcT\
4GC4A=0; RP[R
8=C464A XRP[R
R\^ST,
XcT\,R[TPafX]NbcaX]V/2DAA4=CN<4=DN8C4<
85XcT\4@<d[cX_[h \^ST,
85XcT\4@3XeXST \^ST,!
85XcT\4@0SS \^ST,"
85XcT\4@BdQcaPRc \^ST,#
R\^ST,
X,RP[R
bTc\^ST,!
4=3
R
8=C464A 5D=2C8>= RP[R
8=2;D34 _\X]b
T]PQ[T,
85e!;C 3%C74=
T]PQ[T,
85\^ST4@! \^ST,$
4=385
85\^ST4@ a,e e!
85\^ST4@! a,e e!

85
ClearWin+ User’s Guide Fortran

85\^ST4@" a,e e!

85\^ST4@# a,e e!
85\^ST4@$ a,3
20;; fX]S^fNd_SPcT/a
RP[R,!
4=3

System menu - %sm[menu_specification]

This format code is used to augment the system menu and is constructed in a manner
similar to %mn. A grave accent modifier (`) is used in order to replace the menu
rather than to add to it.
For example:
X,fX]X^/b\J0[_WPm1TcPL0[_WPNUd]R1TcPNR]ca[1TcPNUd]R
will add the menu items 0[_WP and 1TcP to the end of the system menu. 1TcP will
be greyed when the control variable Beta_cntrl has a zero value. Alpha_func and
Beta_func are the associated call-back functions. If a grave accent is supplied in the
form %`sm, then the two menu items will replace the system menu.
The tab character 270A( (or 270A!) attaches an accelerator key to a particular
menu item and its associated call-back function. The syntax is the same as that for
%mn above.

Enhanced menus
A ClearWin+ window can have an enhanced standard menu (%`mn) as an alternative
to a standard (%mn) menu. Enhanced popup menus (%`pm) are also available. An
enhanced menu has more possibilities such as bitmap entries and is more flexible for

86
Chapter 9 Menus and accelerator keys

programs that update menus on the fly or read them from configuration files. Any
window can be given either a normal menu or an enhanced menu.
%`mn and %`pm each take one character argument, that describes the entire menu,
and one call-back function that is used for all menu events.
Example
8=C464A XfX]X^/RQUd]R
4GC4A=0; RQUd]R
270A02C4A!$% U\c
U\c,J5X[TJQ\J^_T]Q\_LbT4gXcL7T[_J0Q^dcLL
X,fX]X^/O\]U\cRQUd]R
4=3

8=C464A 5D=2C8>= RQUd]R
8=2;D34 +fX]S^fbX]b-
270A02C4A % \T]dXcT\
\T]dXcT\,R[TPafX]NbcaX]V/2DAA4=CN<4=DN8C4<
RQUd]R,
85\T]dXcT\4@5X[Tm4gXc RQUd]R,
4=3

A4B>DA24B
^_T]Q\_ 18C<0? ^_T]Q\_

The character string U\c illustrates a typical enhanced menu definition:

U\c,J5X[TJQ\J^_T]Q\_LbT4gXcL7T[_J0Q^dcLL
Here the ‘&’ character performs the same accelerator key function as for standard
menus. Special options preceded by a minus sign are available as follows:
-bm[xxx] Represents a bitmap (loaded from a resource named xxx). In the
example, the text ‘Open’ is part of the bitmap (the font is 8pt MS Sans
Serif).
-se Menu separator
-gr Subsequent item is greyed out
-ch Subsequent item is checked

87
ClearWin+ User’s Guide Fortran

-he[...] Subsequent item has help information given between square brackets.
This information can include newline characters.
-rc Subsequent item has a radio button placed in front of it.

Notice that sub-menus are specified using nested square brackets - just as they are for
standard menus.
The call-back function is invoked when the user selects a menu event. This function
uses 2;40AF8=NBCA8=6/2DAA4=CN<4=DN8C4< to determine which event is
required. In the given example, when the user selects ‘Exit’ the string ‘File~Exit’ is
returned. Strings are separated by a tilde ‘~’ character and any ‘&’ characters in the
menu names are left in place. In the given example, selecting ‘Open’ generates
‘File~openbmp’. (Menu items often represent recently opened files. File names might
contain tilde ‘~’ characters, however no ambiguity will occur because such items will
always appear in terminal positions in the menu tree structure.)
Newline and carriage return characters are ignored between menu items. This means
that a menu structure can conveniently be defined in a text file, read in and presented
as an enhanced menu.
If a menu is to be altered (whether it be to alter the grey/check status of an item, or to
add/remove entries etc.) the menu is simply replaced using one of the calls:
20;; A4?;024N4=70=243N<4=D/70=3;4 <4=D
20;; A4?;024N4=70=243N?>?D?N<4=D/70=3;4 <4=D
where 70=3;4 is an integer that is the (%hw) window handle of the parent window
and <4=D is the replacement character argument. 70=3;4 can be zero, in which case
the most recently created window is updated. It is an error to call these routines for a
window that does not use %`mn or %`pm.

Accelerator key format - %ac[key]

%ac is used to attach an accelerator key to a specified call-back function. The key
name is provided as a standard character string and the call-back function is an
argument associated with %ac.
For example:
4GC4A=0; RP[[NQPRZNUd]R
X,fX]X^/PRJ2ca[0[c?LRP[[NQPRZNUd]R
Other examples of valid key names are Alt+Esc, Ctrl+Shift+Del, Esc, Alt+Enter,
and Ctrl+F9. See page 215 for further details. See also PSSNPRRT[TaPc^a/.

88
10.

Layout and positioning

Format windows, created using fX]X^/, contain text and child windows called
controls. Text and controls are presented in the order in which they appear in the
format string. ClearWin+ automatically positions the text and controls in a window
and adjusts the size of the window to suit its contents. This automatic positioning
provides for a standard blank border within the window. This border surrounds all the
text and controls. It can be removed by using %ww together with its ]^NQ^aSTa
option.
Text and controls in a format string can be separated by one or more of the following
format codes.
%nl gives a new line
%ta advances to the next tab position
%ff advances to the left margin below any existing controls
%cn centres text and controls on the current line
%rj right justifies text and controls on the current line

%ta and %nl can be used with an integer modifier. For example, %2nl gives two new
lines. Further information about %cn and %rj is given below.
It is important to note that, if these codes appear within a %ob box, then the effect
relates to the box rather than the window as a whole. Moreover, %ob boxes can be
nested. As a result it is possible to exercise a fine control over the positioning of items
within a window. In extreme cases, there are other mechanisms for adjusting the
position of a given item. Details are given below.

Centre - %cn
%cn forces the text and controls that follow (up to the next %nl or %ff) to be centred
in the window (or box). It is often used in conjunction with buttons.

89
ClearWin+ User’s Guide Fortran

For example:
F8=0??
8=C464A XfX]X^/
X,fX]X^/RPJ2[TPaFX]LQVJVaThL
X,fX]X^/R]bXBPeT RdaaT]c RWP]VTb.!][
X,fX]X^/ccJHTbL ccJ=^L ccJ2P]RT[L
4=3

The %cn format code can take a grave accent format modifier. This causes centring
to apply to the remainder of the format window or box. Thus a whole window or a
box full of centred items may be created very easily.
For example:
X,fX]X^/OR]?a^VaP\ c^ cTbc _aX\T ]d\QTab
X,fX]X^/!][FaXccT] Qh 9^T 1[^VVb!][OQcJ>:L´

If %cn is used within a box then it centres objects within that box.

Right justify - %rj

%rj forces text and controls that follow (up to the next %nl or %ff) to be right
justified.

Tab location - %N tl
This format code allows you to change the default tab locations. Distances are
measured from the left-hand edge of the window or box using multiples of the width
of an average character. N is the number of tabs to set and an argument is supplied
for each location. For example, %4tl would take four integer arguments specifying
the first four tab locations. A complex window layout might contain several %tl
formats. Each %tl format takes effect for subsequent text and controls and cancels any
previous one. If you use the grave accent modifier with %tl, then the tab locations are
specified as 3>D1;4 ?A428B8>= values.

90
Chapter 10 Layout and positioning

Box format - %n.mob[options][title]

%ob is used to create boxes, to create a status bar, or to create a grid. Any of these
can be filled with text and controls. %ob defines the top left hand corner of a
rectangular box. Subsequent items are placed to the right and beneath this point until
the box is closed with %cb. Every open box must be closed before the format string
(plus any continuations) is complete. Boxes can be nested, one within another, in
order to provide a fine control over the positioning of items in a window. A grave
accent is used to indicate that the box and all items within it should have a darker
(shaded) background.
%ob can be followed by options enclosed in square brackets. The options are:

]P\TSNR Places a given title in the top line of the box (in the centre)
]P\TSN[ Places a given title in the top line of the box (on the left).
]P\TSNa Places a given title in the top line of the box (on the right)
]^NQâSTa Creates an invisible box which is useful for grouping controls.
_P]T[[TS Creates a three-dimensional panel.
bWPSTS Equivalent to %òb.
bcPcdb The box takes the form of a status bar.
cWX]N_P]T[[TS An alternative to _P]T[[TS.
bRâTS Double line, three-dimensional shade effect.
ST_aTbbTS Single line, three-dimensional shade effect.
aPXbTS Single line, three-dimensional shade effect

A status bar is a strip (with the same colour as the face of a standard button) that is
placed at the bottom of a window. A status bar is typically used to display help
information. The status bar format should be used at the beginning of the first
(normally the only) line of status information. For example, ^QJbcPcdbLWTRQ
would create a status bar and place help information in it. Although status bars can be
made to cover more than one line (for example by using %he in a window in which
some of the help strings extend over more than one line), the result tends to look ugly.
No further controls should be specified after the final %cb that closes a status bar,
unless they are positioned via a %ap format code (see page 95).
A name that is to be placed in the top line of the box is provided as a standard
character string. For example:
F8=0??
8=C464A XfX]X^/
X,fX]X^/RPJ=P\TS Q^gTbLQVJVaThL
X,fX]X^/^QJ]P\TSN[LJ;TUcL

91
ClearWin+ User’s Guide Fortran

X,fX]X^/][ 1^g RQ

X,fX]X^/^QJ]P\TSNRLJ2T]caTL
X,fX]X^/][ 1^g !RQ
X,fX]X^/^QJ]P\TSNaLJAXVWcL
X,fX]X^/][ 1^g "RQ
4=3

%ob can take integer modifiers in order to create a grid. For example, %2.3ob would
create a grid two items across and three down. The contents of each grid component
are terminated with %cb. Thus the above case would require six %cb format codes
following it to close each component of the grid.
Note that, if you place %rd (say) in the grid, you might also choose to use
R^J]^NSPcPNQâSTaL in order to remove the border from the %rd control.
Most of the %ob options may be uesd when %ob is used to create a grid. However, a
grid box cannot be named.
For example:
F8=0??
270A02C4A & bca
3>D1;4 ?A428B8>= eP[\X]\Pg
8=C464A XfX]X^/
eP[,
\X],
\Pg,
bca,BP[UâS BÛcfPaT
X,fX]X^/ffJ]^NUaP\TLRPJ\d[cX_[T aTVX^]bL
R3TUX]T P !g! Q^g
X,fX]X^/!!^QJ_P]T[[TSL &QcJ^]TL RQ
X,fX]X^/ &QcJcf^L RQ´
X,fX]X^/³ &QcJcWaTTL RQ
R3STUX]T P b[XSTa
X,fX]X^/ b[JWâXi^]cP[L RQ][eP[\X]\Pg
X,fX]X^/! ^QJbcPcdbcWX]N_P]T[[TSL´
X,fX]X^/³O#aURQéP[
X,fX]X^/³OabRQbca
4=3

92
Chapter 10 Layout and positioning

%ob can be used with the option ]^NQâSTa to divide a window into a rectangular
array of sub regions that are used to position text and controls within each region. As
a simple example, suppose we wish to place two buttons (one below the other) to the
right of some text. Here is some code that has the desired effect.
X,fX]X^/! ^QJ]^NQâSTaLSh$3
X,fX]X^/Cf^ Qdcc^]b _[PRTS ][c^ cWT aXVWc Û cTgcRQ
X,fX]X^/ccJ>:L][ShccJ2P]RT[LRQ"3

Notice that %dy has been used to provide vertical displacement. In this context, if the
single argument for %dy were given the value 1.0D0 then the use of %dy would be
equivalent to %nl.

Pivot - %pv
In the absence of a pivot (%pv) a window will not re-size (except to minimise). A
pivot may only be placed before a control that will re-size in response. It is an error to
attempt to pivot any other type of control. The following controls will accept the pivot
(more may be added later, but many controls are intrinsically fixed in size):

%bv Branch-view
%cw Embedded ClearWin windows

93
ClearWin+ User’s Guide Fortran

%dw Owner draw box

%eb Edit boxes
%fr Frame for MDI child windows
%gr Graphics box, must have \TcPUX[TNaTbXiT or dbTaNaTbXiT property.
%ht Hypertext
%ls List box controls (but not dropdown boxes using the grave accent)
%lv List-view
%ms Multiple selection boxes
%og OpenGL graphics box.
%tv Tree-view
%tx Text array
%uw User defined window

An alternative %pv mechanism is available but not recommended. The alternative is

is obtained by calling bTcN^[SNaTbXiTN\TRWP]Xb\/. In this case, the %pv format
code marks the position of a pivot point. Items to the right of this point move to the
right as the window is widened, whilst items below the pivot point move downwards
as the window is lengthened. %nr and %nd can be used in conjunction with this
mechanism.

Get and set window position formats - %gp, %sp

%gp takes two integers as arguments. When the window is created these integers are
set to the screen x, y co-ordinates of the point where the %gp format is used.
Typically these values are used to position other windows over appropriate parts of a
main window by using the %sp format. It is also used for child windows. Each time
the window is moved or re-sized the x, y pair is updated.
For example:
F8=0??
8=C464A ghfX]X^/
2><<>= gh
4GC4A=0; \hUd]R
X,fX]X^/?aTbb cWXb Qdcc^] c^ R^]RTP[ Xc ´
X,fX]X^/V_´gh
X,fX]X^/³MQcJ?aTbbL\hUd]R
4=3
R
8=C464A 5D=2C8>= \hUd]R
8=C464A ghfX]X^/

94
Chapter 10 Layout and positioning

2><<>= gh
R FX]S^f fX[[ QT _^bXcX^]TS aT[PcXeT c^ cWT Qdcc^]
R R^]ca^[ X] cWT \PX] fX]S^f
X,fX]X^/b_7XSST]g$h$
\hUd]R,
4=3

Absolute position format - %ap

This format code takes two integer arguments and positions the next control at the
given (x, y) point. The units are the same as those used in the %gd format code
described below. This format code is not recommended for general use. The
following points should be noted if %ap is used:
• Try to place all the absolute positioned objects at the end of a format, or follow a
%ap format with a %ff to enable the automatic control placement mechanism to
recover.
• It is possible to place controls on top of each other using this format. This is
usually undesirable unless all but one of the overlapping controls are given the
‘hidden’ attribute.
See also %rp and %dy.

Programmer grid format - %gd

%gd is for program development only. It overlays a grid over the window and any
items within it. This enables controls to be positioned using the %ap format. The
grid is marked in small intervals corresponding to the average character size of the
default font, with major divisions every 10 such units. The grid starts at the left and
top margins, but extends over the right and bottom margins, since this may help in the
placement of further controls.

95
ClearWin+ User’s Guide Fortran

96
11.

Displaying text

Font name - %fn[font_name]

%fn is used to select a font for subsequent text and controls.
For example:
fX]X^/³CWXb Xb P] TgP\_[T ^U U]JCX\TbLCX\TbbU U^]c´
This causes the word “Times” to appear in Times font with the remainder of the
sentence in system font. %sf is used to reset all text attributes to the system font.

Get font - %gf

%gf takes one 8=C464A variable that receives the current font handle. This handle
can then be used in any Windows API function that requires a font handle.
For example:
8=C464A WNU^]c
X,fX]X^/cbVU!3WNU^]c

Font attributes - %it, %bf, %ul

These format codes are used to begin italic, bold face, and underlined text
respectively. Each code takes the grave accent modifier (`) in order to terminate the
corresponding attribute.

97
ClearWin+ User’s Guide Fortran

For example:
X,fX]X^/DbTb QUQ^[S UPRTOQU U^a T\_WPbXb
%sf (system font) is used after any combination of these format codes in order to
restore the sytem font.

System font - %sf

%sf resets the text attributes and is used after any combination of %bf, %it, %ul, %fn,
and %ts.
%sf can also take a grave accent (`) but this only has effect if the program is running
under Windows 95. For Windows 95, %`sf selects the scaleable font that is used in
menus and controls. %ts (see below) can be used after %`sf in order to set the size of
the scaleable font. %`sf followed by %ts with a scale factor of about 1.15 will produce
readable text (see also dbTNfX]S^fb($NU^]c/).
The value returned by the function fX]S^fbN($NUd]RcX^]P[Xch/ will indicate if
Windows 95 is running. This function returns the value 1 if the program is running
under Windows 95, otherwise it returns zero.

Font default - %fd

%fd sets the font to the default Windows 95/98 font (Windows 95/98 only).

Subscript - %sd
A font must be selected using %fn, before %sd is used. All text following %sd will be
in subscript style. A grave accent (%`sd) is used to return to the previous font setting.
For example:
X,fX]X^/³U]JPaXP[L FPcTa Xb 7bS!ObS>´

Superscript - %su
A font must be selected using %fn, before %su is used. All text following %su will be
in superscript style. A grave accent (%`su) is used to return to the previous font
setting.
For example:
X,fX]X^/³U]JPaXP[L4X]bcTX] bPXS cb4,<2bd!Obd´ '3

98
Chapter 11 Displaying text

This is the result of the examples above for %su and %sd used together. In general,
scaled down fonts are undesirable as they may become unreadable in lower screen
resolutions.

Text size - %ts

%ts takes one 3>D1;4 ?A428B8>= argument that is used to scale the size of any text
that follows until the next %ts or %sf format code. The default value of this argument
is 1.0. Values of the argument in the range from 0 to 1.0 are used to scale down,
whilst values greater than 1.0 are used to scale up. Note that the system font cannot
be scaled, so %fn must always be used before %ts (see page 97).
For example:
X,fX]X^/U]J2^daXTa =TfLcbCWXb Xb [PaVTa $3

Text colour - %tc

By default, the text in a format window is coloured using the ‘window text’ colour that
the user can select from the Control Panel in the Program Manager. This colour is
returned by 6TcBhb2^[^a2>;>ANF8=3>FC4GC. %tc is used to specify the text
colour for subsequent text and controls (until another %tc overrides it). %tc takes one
integer argument which is typically created using A61/.
For example:
8=C464A A61/
X,fX]X^/ cRATS´ A61/!$$
X,fX]X^/³ cR6aTT]´A61/!$$
X,fX]X^/³ cR1[PRZ A61/
It is often desirable to base the new colour on the default set by calling GetSysColor
(see the description of %bg on page 127 for details of how to do this). An argument
value of -1 resets the colour to the ‘window text’ colour.

99
ClearWin+ User’s Guide Fortran

Alternatively one of the standard colours (Q[PRZ fWXcT VaTh aTS VaTT]
Q[dT and hT[[^f) can be specified by enclosing the colour name in square
brackets (for example: cRJaTSL).
Note that the text colour for a given control can be changed dynamically (after the
window has been created) by calling the subroutine B4CN2>=CA>;NC4GCN2>;>DA/.

Variable string - %N.mst

This format code takes one character string argument and lays out the string in a field
of N characters. The string is redrawn each time the window is renewed. For this
reason, the size N must be specified and must be the maximum number of characters
required. The number of lines m is optional and defaults to 1. For example, %20.2st
provides for 20 characters on each of two lines. Use the fX]S^fNd_SPcT/ function
(see page 26) in order to force a change to become visible. %st is similar to %`rs.

Sterling pound symbol - %pd

%pd will ensure that a pound ‘£’ symbol appears correctly on the chosen output
device. Note that the ‘£’ symbol is represented differently in the OEM and ANSI
character tables.

Mathematical equation - %eq[equation]

%eq is provided to enable mathematical equations to be drawn. It is followed by a
standard character string (i.e. a string in square brackets, or an ‘@’ symbol with a
string as an argument). It takes two integer arguments which are the width and depth
of the equation in pixels. If the contents of the equation are not going to change, then
the width and depth are set to zero, forcing the size of the region to be defined by the
equation. Equations may also be included in hypertext (see Chapter 19).
Equations are strings with the three characters {;} reserved. The following symbols
can be included in strings:
{alpha} α {beta} β
{gamma} γ {delta} δ
{epsilon} ε {phi} φ
{pi} π {zeta} ζ
{psi} ψ {sigma} σ
{theta} θ {kappa} κ
{lambda} λ {iota} ι

100
Chapter 11 Displaying text

{rho} ρ {mu} µ
{nu} ν {omega} ω
{chi} χ {tau} τ
{infinity} ∞ {plus_minus} ±
{ge} ≥ {proportional} ∝
{curly_d} ∂ {le} ≤
{ne} ≠ {identically_eq} ≡
{approximately_eq} ≈ {such_that} 
{vector_sum} ⊕ {empty_set} ∅
{set_intersection} ∩ {set_union} ∪
{proper_subset} ⊂ {subset} ⊆
{belongs_to} ∈ {not_belongs_to} ∉
{for_all} ∀ {there_exists} ∃
{del} ∇ {sqrt} √
{semicolon} ;

The names of these special symbols are case sensitive, and the Greek characters also
exist as upper case characters. For example, {Pi} will produce Π. In this context only
the first character is upper case.
In addition, a number of more complex constructions are supplied. In the list below ,
the asterisk “*” stands for any equation string:
{sup *} Superscript or exponent
{sub *} Subscript
{divide *;*} Division written with a horizontal bar
{sum *} Summation without upper limit
{sum *;*} Summation with both limits
{integral } Indefinite integral
{integral *} Integral with lower limit only
(integral *;*} Full definite integral.
{symbol nnn} Character number nnn (decimal) from the symbol font.

101
ClearWin+ User’s Guide Fortran

Note that the body of the sum or integral will be placed after the closing curly brace.
Spaces are important in the above constructions.
Badly formed equations will normally cause a Clearwin+ error. However, if a grave
accent modifier is specified (%`eq), the error will be suppressed.
Excessive nesting of constructs such as ‘sup’ or ‘sub’, that reduce the font size, may
result in unreadable equations.
Here are a few well known equations and chemical formulae as examples:
F8=0??
8=C464A XffX]X^/
270A02C4A' b#
b ,7jbdQ !lB>jbdQ #l
b!,4,\Rjbd_ !l
b",jST[l1,
b#,
jbd\ ], *jX]UX]XchlljSXeXST *]jbd_ !ll,jSXeXST j_Xljbd_ !l*%l
X,fX]X^/RPJ4`dPcX^]bLQVJVaThL
3> X, #
f,fX]X^/^QT`/RQbX
4=33>
f,fX]X^/
4=3

Equations are constructed using symbols from the Times New Roman and Symbol
fonts.
These same equation strings may be used in hypertext (%ht) embedded between
<equation> and </equation>. The string between these delimiters is treated as a pure
equation - no mark-up codes are recognised. So, for example, the ‘<’ symbol should
be written as it is.

102
Chapter 11 Displaying text

Edit boxes
Edit box - %eb
See Chapter 12.

Text array - %N.Mtx[options]

Text arrays provide a convenient way to display a grid of characters with ‘attributes’
to achieve an effect analogous to that achieved under DOS by writing to the screen
buffer. A text array can respond to keyboard and mouse input via its call-back
function by using R[TPafX]NX]U^/ (see below), updating the array as necessary.
The text array format takes two character strings and two integer modifiers N, and M.
For example:
F8=0??
270A02C4A' cTgcPcca
8=C464A ZfX]X^/
cTgc,CTbc R^[^da
20;; RWPaNUX[[/PccaRWPa
20;; RWPaNUX[[/Pcca )#RWPa
20;; RWPaNUX[[/Pcca%) RWPa!
Z,fX]X^/%'cgcTgcPcca'; ;
Z,fX]X^/cRJQ[dTLchJaTSLcRJhT[[^fLchJVaTT]L
4=3
In the above example, the text array cTgc is displayed in the box as an 80 x 10 array
of which initially only 60 x 8 is visible. The size of the control can be varied if it is
preceded by a pivot (%pv) in a variable sized window. The Pcca array contains
attribute numbers stored using 270AX where 0 < i < 255. Zero is the default
attribute (usually black on white), others are defined by subsequent
%tc[fgcolour]%ty[bgcolour] format pairs. The first %tc%ty pair defines colour index
1and so on. fcolour is the foreground colour of the text, and bgcolour is the
background. In the above example, the word ‘Test’ appears as blue on a red
background whilst the word ‘colour’ appears as yellow on a green background. The
colour can be specified as an A61/ value in the argument list if the colour in brackets
is omitted. Changes in font attributes (underlining, etc.) are not possible with %tx.
%tx may have a call-back functino that can use the following R[TPafX]NX]U^/
strings:

C4GCN0AA0HN270A value of key pressed

103
ClearWin+ User’s Guide Fortran

C4GCN0AA0HN34?C7 holds the new value on resizing

C4GCN0AA0HN<>DB4N5;06B mouse button press information

C4GCN0AA0HNA4B8I8=6 text array window dimension change

C4GCN0AA0HNF83C7 holds the new value on resizing

C4GCN0AA0HN74867C holds the new value on resizing

C4GCN0AA0HNG location x when the mouse is pressed in %tx

C4GCN0AA0HNH location y when the mouse is pressed in %tx

The C4GCN0AA0HNA4B8I8=6 parameter is set to one only in a call-back responding

to a re-sizing event. The next two parameters in the table only have meaning in this
context. They supply the new size of the control in average characters.
The C4GCN0AA0HNG and C4GCN0AA0HNH parameters give the mouse position in
characters from the top left corner, and are zero based. The mouse flags, that contain
information about which mouse button (if any) is depressed, can be obtained by a call
to VTcN\^dbTNX]U^/. The option 5D;;N<>DB4N8=?DC is specified in order to
force the call-back function to be called whenever the mouse moves over the control.
C4GCN0AA0HN<>DB4N5;06B uses bitwise flags as follows:
<:N;1DCC>= 1 Left mouse button depressed
<:N;1DCC>= 2 Right mouse button depressed
<:NB785C 4 Keyboard shift key depressed
<:N2>=CA>; 8 Keyboard control key depressed
<:N<1DCC>= 16 Middle mouse button depressed
By default, the call-back function is called when a keyboard character is received
while the control has the focus. The character is placed in the parameter
C4GCN0AA0HN270A. If the option 5D;;N270AN8=?DC is specified, the call-back
function receives each keystroke using the Microsoft VK_ parameters (defined in the
file windows.ins). The call-back is invoked for each key press and each key release.
In the latter case C4GCN0AA0HN270A parameter has the top bit set. The parameter
C4GCN0AA0HN270A will be zero when not in use. To respond to ALT key
combinations you should use the %ac facility rather than tracking the ALT key with
5D;;N270AN8=?DC. This is because messages associated with the release of the ALT
key might be delayed until the next key is pressed. The option DB4NC01B may be
used to cause the tab key to be passed to the call-back rather than performing its
normal Windows function of moving between controls.

104
Chapter 11 Displaying text

The system font is used in a %tx control, unless %fn appears before %tx. If %fn is
used then a mono-spaced font (such as Courrier New) should be selected because the
text array must be aligned both vertically and horizontally.
Note that the text array is not re-dimensioned if the control is re-sized. Re-sizing
simply changes the region that is visible.

File selection and filter

File selection - %fs[path]

%fs together with the related %ft format code (see below), changes the default file
selection used by a subsequent 58;4N>?4=A or 58;4N>?4=F call-back function (see
page 205). The information is used in the standard Windows dialog displayed by
these call-back functions. %fs is followed by a standard character string, that is
either:
a) the path name of a directory to be used rather than the current working directory
(e.g. 2)KC4BC), or
b) a complete file selection specification (e.g. 2)KC4BCK4G4).
In the latter case the file filter information, displayed at the bottom of the standard
‘file open’ dialog, is replaced by the specified filter.
F8=0??
270A02C4A !( UX[T]\
8=C464A XfX]X^/
2><<>= UX[T]\
4GC4A=0; SXb_N]P\T
UX[T]\,
X,fX]X^/UbJR)KSQ^bSXaKfaXL´
X,fX]X^/³\]J5X[TJ>_T]LL58;4N>?4=AUX[T]\SXb_N]P\T
X,fX]X^/³\]JJ4gXcLL´³4G8C
4=3

8=C464A 5D=2C8>= SXb_N]P\T

270A02C4A !( UX[T]\
8=C464A XfX]X^/
2><<>= UX[T]\
X,fX]X^/fb OQcJ>:LUX[T]\
SXb_N]P\T,
4=3

105
ClearWin+ User’s Guide Fortran

File filter - %ft[name][filter]

%ft is used to change the default filter for subsequent use of the 58;4N>?4=A and
58;4N>?4=F call-back functions (see page 205). The information is used in the
standard Windows dialog displayed by these call-back functions. Two standard
character strings are required after %ft. The first is the name of the filter (e.g.
'Executable files'). The second is the specification (e.g. 4G4).
For example:
X,fX]X^/Uc//4gTRdcPQ[T UX[Tb4G4
Alternatively,
X,fX]X^/UcJ4gTRdcPQ[T UX[TbLJ4G4L
If the grave accent modifier is used with %ft, the filter information replaces the
existing information, otherwise it is added at the front of any existing filter
information. The default filter selects all files.
You cannot change the name and filters dynamically by using %fs and %ft with
variable character strings. See VTcNUX[cTaTSNUX[T/.

106
12.

Edit box (%eb)

%N.Meb[options]
This format code provides a text editor and is by far the most complex format
available. However, many applications will not require any of the embellishments
detailed below. Note that %rs and %re are simpler to use but are limited to 32768
characters.
Two arguments are required, a pointer to the buffer containing the text to be edited,
and an integer specifying the maximum size of the buffer. The text should be
terminated by the null (270A) character, and new lines should consist of carriage
return/line feed pairs. This does not use the standard Windows edit control and as a
result there is no limit (other than the total available memory) to the size of the text
area. If the second argument (the length of the buffer) is set to zero, the edit box
allocates its own memory for the buffer, re-sizing it as required.
%60eb denotes an edit box that displays 60 characters on one line (which is the same
as %60.1eb). %60.20eb denotes an edit box that displays 60 characters by 20 lines.
The text itself has the format of a normal DOS text file (lines of text separated by a
carriage return/line feed character pair) with a closing a null terminator. The edit box
can also handle text lines separated by carriage return characters only, providing this
is used consistently.
In order to read/write data to a file in this format the file should be opened in binary
mode.
For example:
F8=0??
270A02C4A QdUUTa
270A02C4A' U]P\T
8=C464A WP]S[TTaaNR^STQhcTbNaTPS]QhcTbfX]X^/
U]P\T,\hUX[T

107
ClearWin+ User’s Guide Fortran

20;; ^_T]a/U]P\TWP]S[TTaaNR^ST
20;; aTPSU/QdUUTaWP]S[T QhcTbNaTPSTaaNR^ST
20;; R[^bTU/WP]S[TTaaNR^ST
X,fX]X^/%!TQQdUUTa
20;; ^_T]f/U]P\TWP]S[TTaaNR^ST
]QhcTb,8=34GQdUUTa270A
20;; faXcTU/QdUUTaWP]S[T]QhcTbTaaNR^ST
4=3
The only null character in the string must be at the end. You must include the null
character when calculating the length of a string. In the above example, the Fortran
8=34G intrinsic function has been used to obtain the size of the edit buffer. An
alternative method is given below. Note that ^_T]a/ etc. are Salford Fortran library
routines.
<option list> is a list of items surrounded by square brackets and separated by
commas. The entire (square-bracketed) list may be omitted if no options are required.

WbRa^[[QPa Supply and control a horizontal scroll bar.

[X\XcTSNWbRa^[[QPa Like WbRa^[[QPa but the user is prevented from
scrolling horizontally until all characters have
disappeared.
ebRa^[[QPa Supply and control a vertical scroll bar.
]^NWbRa^[[ Inhibit all horizontal scrolling.
]^NebRa^[[ Inhibit all vertical scrolling.
P[cNTSXc Changes the action of Del, Backspace, and Enter
keys so that they never split or join lines.
UXgTSNU^]c Uses a fixed font for the edit box, rather than the
default variable font. (However, it is preferable to use
%fn, with a monospaced font such as Courier New,
before %eb in the format string.)
W^^ZNU^Rdb Causes the call-back to be called every time the box
gains or loses the focus. Note that the over use of this
option can cause annoying effects for the user and more
importantly an infinite loop may be started if the result
of an object gaining a focus is the shift of that focus to
another object!
dbTNcPQb Uses tabs in the edit box in the normal way for an
editor. Otherwise tabs are used to cycle through the
various controls in the parent window.
]^NUaP\T Removes the line around the edit box without removing
the blank border (]^NQ^aSTa removes both). This

108
Chapter 12 Edit box (%eb)

option is particularly useful for edit boxes which fill a

window.
]^NQâSTa Omit the blank border that by default is placed between
the text and the surrounding box.
aTPSN^][h Prevents the user from changing the text. The cursor
can still be used to scroll through the text.
dbTaNR^[^dab The call-back function is invoked in such a way that
the colours used for text and its background can be
modified. This facility could be used, for example, to
produce an editor which highlighted certain keywords.
The use of this option is described further below.
TgcT]STS Allows 2;40AF8=NBCA8=6/³20;;102:NA40B>=´
to be used within a call-back function. For %eb the
possible returns include ³30C0N0;C4A0C8>=´.
d]S^ Causes the edit box to save information to enable
changes to be ‘undone’. By default all changes are
recorded and can be undone in reverse order. The
program can also restrict the amount of undo
information by calling a function. The standard call-
back function 438CND=3> is used to perform one
level of undo each time it is invoked. Menus or buttons
attached to this call-back will automatically become
grey when no more undo information is available. The
undo mechanism can reverse changes made using the
keyboard/ mouse or by calling any of the edit-box
related functions. However changes made by directly
altering the buffer and calling F8=3>FND?30C4/ will
not be recorded and cannot be reversed.
]^NRdabâNb]P_ By default if, when you move the cursor up or down,
you end up off the end of the line, the cursor will snap
back to the end of the line. For some purposes, such as
when you are using block marks (see below), this is
inconvenient. Use the ]^NRdabâNb]P_ option to
leave the cursor in free space on the end of the line.
aT_âcNS^dQ[TNR[XRZ Responds to a mouse (left) double click by calling the
call-back function rather than by marking a word.
aT_âcNaXVWcNR[XRZ Responds to a mouse right click by calling the call-
back function rather than by looking for a pop-up
menu.

109
ClearWin+ User’s Guide Fortran

The edit box maintains a set of variables in a structure (called an 438CN8=5>

structure) that controls the operation of the box. Normally these variables are hidden.
However, much more detailed control of the edit box can be obtained by using the
grave accent edit modifier and by supplying an array of the form:
8=C464A X]U^!#
If more than one edit box is open, each one must have its own 438CN8=5> structure.
The following example illustrates the use of this structure, making use of the
following identifiers:

Offset Label Description

1 WN_^bXcX^] Cursor horizontal character position.
2 eN_^bXcX^] Cursor vertical character position.
3 [PbcN[X]T Total number of lines in the buffer.
4 QdUUTa Address of edit buffer.
5 bXiT Size of buffer contents (excluding null
terminator).
6 \PgNQdUUTaNbXiT Size of memory block.
7 RdaaT]cN_^bXcX^] Address of the position corresponding to
TQNWN_^bXcX^]TQNeN_^bXcX^].
8 bT[TRcX^] Address of selected text if any.
9 ]NbT[TRcTS Number of selected characters.
10 eZNZTh Set to E:NC01 etc. if this handles a key press.
11 eZNbWXUc Shift state corresponding to key.
12 PRcXeT Set to the number of the edit box (1 if only one
edit box is open) when a call-back is invoked,
reset afterwards. This value is used to identify
which edit box is associated with the current
use of a call-back function.
13 \^SXUXTS Set to 1 each time the buffer is modified.
14 R[^bX]V Set when buffer is about to be closed.
15 ]NRWPabNc^NR^[^da Count of characters to colour.
16 cTgcNc^NR^[^da Address within buffer for region to colour.

110
Chapter 12 Edit box (%eb)

17 cTgcNR^[^dab Address of foreground colours.

18 QPRZVa^d]SNR^[^dab Address of background colours.
19-24 Reserved for future enhancements.

Users of FTN95 could define a TYPE corresponding to the 438CN8=5> array.

Although this structure is passed to most of the functions described below, you will not
normally need to know its contents nor should you normally need to manipulate the
buffer yourself. (You can do so it you wish, but you must remember to update the
contents consistently and to make use of fX]S^fNd_SPcT/ at appropriate intervals.)
The following example takes the last example above and adapts it so that a) the edit
box allocates its own buffer with address TQNQdUUTa and b) the TQN\^SXUXTS flag is
checked before a prompt to save the edited file.
F8=0??
8=C464A WP]S[TTaaNR^STXfX]X^/
8=C464A X]U^!#
TQNWN_^bXcX^] TQNeN_^bXcX^] TQN[PbcN[X]T
! TQNQdUUTa TQNQdUUTaNbXiT TQN\PgNQdUUTaNbXiT
" TQNRdaaT]cN_^bXcX^]TQNbT[TRcX^] TQN]NbT[TRcTS
# TQNeZNZTh TQNeZNbWXUc TQNPRcXeT
$ TQN\^SXUXTS TQNR[^bX]V TQNaTbTaeTS
4@D8E0;4=24
TQNWN_^bXcX^] X]U^ TQNeN_^bXcX^] X]U^!
! TQN[PbcN[X]T X]U^" TQNQdUUTa X]U^#
" TQNQdUUTaNbXiT X]U^$ TQN\PgNQdUUTaNbXiTX]U^%
# TQNRdaaT]cN_^bXcX^]X]U^& TQNbT[TRcX^] X]U^'
$ TQN]NbT[TRcTS X]U^( TQNeZNZTh X]U^
% TQNeZNbWXUc X]U^ TQNPRcXeT X]U^ !
& TQN\^SXUXTS X]U^ "TQNR[^bX]V X]U^ #
' TQNaTbTaeTS X]U^ $
X,fX]X^/%!OTQX]U^
85TQN\^SXUXTS4@ C74=
X,fX]X^/R]BPeT RWP]VTb.!][%QcJHTbL %QcJ=^L´
85X4@ C74=
20;; ^_T]f/\hUX[TWP]S[TTaaNR^ST
20;; faXcTU/22>A4 TQNQdUUTaWP]S[TTQNQdUUTaNbXiT
TaaNR^ST
4=385
4=385
4=3

111
ClearWin+ User’s Guide Fortran

Note the use of the Salford-supplied intrinsic function 22>A4 to return the character
string at the given address.
The Salford-supplied intrinsic function ;>2 can be used when the address of a
variable is required. For example, if an edit buffer is provided, the following fragment
of code would give the position of any selected text in the window relative to the
beginning of the file.
270A02C4A QdUUTa
8=C464A _^bXcX^]X]U^!#

X,fX]X^/%!OTQQdUUTa X]U^
_^bXcX^],TQNbT[TRcX^];>2QdUUTa
Note also that, if an edit buffer is provided, a call-back function can be used to
monitor the size of the text in the buffer and to make a call to VTcNbc^aPVT/ if it is
getting full. If the buffer overflows, the system will generate a fatal error.
%eb can take the caret (^) format modifier to indicate that a call-back function is
supplied (after the address of the 438CN8=5> structure if any). This function is called
whenever the contents of the box change, a key is pressed, or the cursor is moved. If
the call-back function does not handle the response to control keys such as Delete,
BackSpace, etc., then it should return a zero value.
This format code can also use the tilde (~) format modifier to indicate that a grey
control variable is supplied. This variable should precede the call-back function (if
any) in the argument list.
An edit box will almost certainly contain information that the user will not wish to
lose, so it is a good idea to use the %cc format to monitor the closure of the main
window.

Standard call-back functions

The following standard call-back functions (described in Chapter 20) can be used with
a %eb edit box.
2>=58A<N4G8C
2>?H 2DC ?0BC4
438CN58;4
438CN58;4N>?4=
438CN58;4NB0E4
438CN58;4NB0E4N0B
4G8C
58;4N>?4=A
58;4N>?4=F

112
Chapter 12 Edit box (%eb)

B4;42CN0;;

Colouring the text and background

The grave accent is used with %tc in order to provide the text colour for a %eb edit
box. %`tc then takes an integer argument which is the RGB value for the text colour.
This colour can be changed under program control. Here is some sample code that
illustrates the concept:
8=C464A R[a
R[a,A61/!$$!$$

X,fX]X^/OcR R[a
X,fX]X^/!!TQ QdUUTa

In order to update the colour of the whole text in the edit box, the following code
would appear in a call-back (obvously, you could use A61/ instead of GetSysColour):

R[a,6TcBhb2^[^a2>;>AN7867;867C
20;; fX]S^fNd_SPcT/R[a
In order to change the colours of selected parts of the text dynamically, you should
supply the dbTaNR^[^dab option to %eb (use %^`eb[user_colours] in a winio@ call)
together with an 438CN8=5> array and a call-back function.
Extra invocations of your call-back function will be made for each line of text when it
is about to be displayed. This call-back will be indicated by a non-zero value of the
]NRWPabNc^NR^[^da component of the 438CN8=5> array. In this case
cTgcNR^[^dab and QPRZVa^d]SNR^[^dab are the addresses of arrays of 4-byte
colour values, such as those created by using A61/ These values will have already
been initialised to the default values including colour changes associated with text
selection, but you are able to modify the values as required. Note that the colours may
be adjusted by display drivers using a limited number of colours.
It is very important to ensure that the function which alters the display colours does
not itself perform any screen I/O. At the point when the colouring request is made,
Windows has issued a WM_PAINT message, and Windows will become unstable if
this rule is not followed.
Since the colours are stored as 4-byte integers, this leaves the top byte of each colour
otherwise unused (it is set to zero by A61/). With %eb, you can set the following bits
in the foreground colour:
I# Force underline.

I! Force italic.

113
ClearWin+ User’s Guide Fortran

I Force bold.

I' Hide the character.

These bits only add attributes, so if the basic font for the edit box has been set bold
(say) the bold bit will have no effect. The ‘hide character’ bit removes the
corresponding character (and the space it occupies) from the screen. This is useful for
implementing magic text sequences to achieve special effects. For example, suppose
you were writing a program to display some text containing URL’s. If you surrounded
the URL’s with some special character sequences to identify them:
$$$http://www.salford.ac.uk/ssl-$$$
your program could recognise these sequences and make them invisible while
changing the colour/attributes of the characters comprising the URL.
The following functions have been added to help manipulate edit boxes:

Text search:
8=C464A 58=3N438CNBCA8=6/4BCA102:F0A3BF7>;4NF>A3
20B4NB4=B8C8E4
8=C464A 4!# 438CN8=5> Q[^RZ
270A02C4A BCA BcaX]V c^ bTTZ
;>6820; 102:F0A3B CadT c^ _TaU^a\ QPRZfPaS bTPaRW
;>6820; F7>;4NF>A3 BTTZ P fW^[T f^aS
;>6820; 20B4NB4=B8C8E4 2PbT \dbc \PcRW
;>6820; B4;42CNA4BD;C ;TPeT aTbd[c bT[TRcTS
This function searches for the specified string and returns 1 if successful and zero
otherwise. Typically you would supply a search menu item on a window containing
an edit box. In the call-back function associated with that menu you would display a
dialog box to obtain the string (%rs) and some of the various flags (%rb) and then call
UX]SNTSXcNbcaX]V/ Although designed for %eb, this function may also be
useful when searching for a sub-string in a string obtained from some other source.

Text search/replace:
8=C464A 58=3NA4?;024N438CNBCA8=6/4BCAA4?;024<4=C
102:F0A3BF7>;4NF>A320B4NB4=B8C8E4A4?;024N0;;
8=C464A 4!# 438CN8=5> Q[^RZ
270A02C4A BCA BcaX]V c^ bTPaRW Uâ
270A02C4A A4?;024 AT_[PRT\T]c bcaX]V
;>6820; 102:F0A3B CadT c^ _TaUâ\ QPRZfPaS bTPaRW
;>6820; F7>;4NF>A3 BTTZ P fW^[T fâS
;>6820; 20B4NB4=B8C8E4 2PbT \dbc \PcRW

114
Chapter 12 Edit box (%eb)

;>6820; A4?;024N0;;
2^]cX]dT d]cX[ cWT T]S ^a QTVX]X]V ^U UX[T
This function searches for the specified string and replaces it with the replacement
string. The function returns a count of the number of replacements made.

Buffer positioning:
8=C464A B2A>;;N438CN1D554A/47?>BE?>B
8=C464A 4!# 438CN8=5> Q[^RZ
8=C464A 7?>B
8=C464A E?>B
This function positions the buffer at a given point and returns 1 if successful and zero
otherwise.
8=C464A 5D=2C8>= 03E0=24N438CN1D554A/4=
8=C464A 4!# 438CN8=5> Q[^RZ
8=C464A = 2^d]c ^U RWPaPRcTab c^ \^eT
This routine moves the pointer through an edit buffer character by character. The
carriage return/line feed character pair are treated as one. = can be set to a negative
value in order to move backwards through the buffer. The number returned is the
number of character positions moved. Thus unless the start or end of the buffer was
encountered, the value of = will be returned unchanged.

Undo operations:
BD1A>DC8=4 D=3>N438CN270=64/4
8=C464A 4!# 438CN8=5> Q[^RZ
Performs one level of undo operation. A single undo may reverse the effects of several
function calls. Direct user interactions with the edit box are tagged so that one user
command is reversed at each step (even though it may be implemented in several
steps). Other operations should be tagged as required using
]TgcNTSXcN^_TaPcX^]/ described next.
BD1A>DC8=4 =4GCN438CN>?4A0C8>=/4
8=C464A 4!# 438CN8=5> Q[^RZ
Calling this function indicates to the edit box that future changes are to be considered
to belong to a new user operation. Typically you would call this routine at the head of
a menu call-back function that was about to change the edit buffer in some way. If
you perform a long series of changes without calling this function, they will all be
reversed as a block if the user performs an undo operation.

115
ClearWin+ User’s Guide Fortran

Opening a file:
8=C464A 5D=2C8>= >?4=N438CN58;4/458;4
8=C464A 4!# 438CN8=5> Q[^RZ
270A02C4A 58;4 =P\T ^U UX[T c^ ^_T]
This function discards any existing information in the edit buffer and reads the
contents of the specified text file into the buffer. It returns 1 on success and zero if it
was unable to open the file. To use this function successfully you are advised to
specify a zero buffer size with %eb to obtain a dynamically allocated buffer.

Inserting text:
BD1A>DC8=4 8=B4ACN438CNBCA8=6/4BCA
8=C464A 4!# 438CN8=5> Q[^RZ
270A02C4A BCA BcaX]V c^ X]bTac
Inserts the given string (including any trailing blanks) into the buffer at the current
point and advances the current point to beyond the insertion. To insert a new line into
data containing carriage return-line feeds (i.e. the binary image of a file) you should
insert carriage return (decimal 13) followed by line feed (decimal 10).

Moving around the display:

BD1A>DC8=4 438CN<>E4N7><4/4
8=C464A 4!# 438CN8=5> Q[^RZ
Moves the cursor to the start of the line (as if the HOME) key had been pressed.
BD1A>DC8=4 438CN<>E4N4=3/4
8=C464A 4!# 438CN8=5> Q[^RZ
Moves the cursor to the end of the line (as if the END key had been pressed).
BD1A>DC8=4 438CN<>E4NC>5/4
8=C464A 4!# 438CN8=5> Q[^RZ
Moves the cursor to the top of the file (as if CTRL-HOME had been pressed).
BD1A>DC8=4 438CN<>E4N1>5/4
8=C464A 4!# 438CN8=5> Q[^RZ
Moves the cursor to the bottom of the file (as if CTRL-END had been pressed).

Deleting text:
8=C464A 5D=2C8>= 438CN34;4C4N;8=4B/4=
8=C464A 4!# 438CN8=5> Q[^RZ
8=C464A = =^ ^U [X]Tb c^ ST[TcT
This function deletes = lines starting at the current position. It returns the number of
lines actually deleted, which may be less than = if the end of the buffer is encountered.

116
Chapter 12 Edit box (%eb)

Marking blocks:
BD1A>DC8=4 438CN>?4=N;8=4N<0A:/4
8=C464A 4!# 438CN8=5> Q[^RZ
This starts a line-mode selection. Initially the selection covers the current line, but it
can be extended upwards or downwards by moving the cursor key. The selected area
can be cut/paste in the same way as an ordinary character selection.
BD1A>DC8=4 438CN>?4=N1;>2:N<0A:/4
8=C464A 4!# 438CN8=5> Q[^RZ
This starts a block (or column) selection. To use this you probably want to use the
]^NRdab^aNb]P_ option (see above) since the user will be creating and manipulating
rectangular regions on the screen.
BD1A>DC8=4 438CN2;>B4N<0A:/4
8=C464A 4!# 438CN8=5> Q[^RZ
This will close a selection of either type.

New CLEARWIN_INFO@ parameters

An extra R[TPafX]NX]U^/ parameter has been added to help programs with several
edit boxes.
³02C8E4N438CN1>G returns the address of the 438CN8=5> array of the currently
active edit box. Notice that this edit box might not have focus if, for example, the user
had just moved to a menu item.
³438CN:4H´ returns the ASCII value of the last key pressed. This information can be
obtained in response to a return of ³30C0N0;C4A0C8>=´ from
R[TPafX]NbcaX]V/³20;;102:NA40B>=´. In order to activate this feature you
must use the %eb[extended]. The call-back is called after the change has been made
so you will need to use one of the above editing functions if you want to undo the key
press.

Clipboard cut/paste
The address of an 438CN8=5> structure associated with an edit box can also be passed
to the following functions:
8=C464A 5D=2C8>= 438CN2;8?1>0A3N2>?H/4
8=C464A 5D=2C8>= 438CN2;8?1>0A3N2DC/4
8=C464A 5D=2C8>= 438CN2;8?1>0A3N?0BC4/4
8=C464A 5D=2C8>= 438CNA45A4B7/4
8=C464A 4

117
ClearWin+ User’s Guide Fortran

The first three functions perform the indicated clipboard operation using the current
cursor position and current selected text in the edit box. They would typically be
called from an edit menu call-back. The last function informs the edit control that the
contents of the buffer have been replaced. In each case the function returns one if
successful, and zero otherwise.

Scroll position
The address of an 438CN8=5> structure associated with an edit box can also be used
to get the cursor position of the top left corner of the window and to scroll vertically to
make a given line appear as the first line.
BD1A>DC8=4 438CNF8=3>FNC>?N;45C/47?>BE?>B
BD1A>DC8=4 B4CN438CN58ABCN;8=4/4E?>B
8=C464A 4!# 438CN8=5> Q[^RZ
8=C464A 7?>BE?>B
In the first of these two routines, a return value of (-1) indicates an error condition.

118
13.

Help

The question mark “?” is used as a format modifier in order to signify that a help
string is supplied. By default, the help string is displayed at the bottom of the
window. The help string is either surrounded by square brackets, or an “@” character
is placed in the format string to indicate that the help string is supplied as an extra
argument. In addition to “?”, %bh, %th and %he are used to change the manner in
which a help string is presented.

Bubble and tooltip help - %bh and %th

%bh takes an 8=C464A argument that is a control variable. When this variable is
non-zero, help text is supplied in the form of a “bubble” whenever the mouse cursor
lies over the control in question. To enable users to switch such help on and off,
simply supply a button with a call-back function that changes the integer control
variable.
For example.
8=C464A bfXcRWX
2><<>= bfXcRW
4GC4A=0; c^VV[T
270A02C4A% W[_
W[_,C^VV[T QdQQ[T WT[_ >]>UU
R 3TUX]T P Qdcc^] fXcW WT[_ PccPRW cWT WT[_
R bcaX]V fXcW P] / bh\Q^[
bfXcRW,
X,fX]X^/M.QcJBcPacL/QWc^VV[TW[_bfXcRW
4=3

8=C464A 5D=2C8>= c^VV[T

8=C464A bfXcRW
2><<>= bfXcRW
bfXcRW, bfXcRW

119
ClearWin+ User’s Guide Fortran

c^VV[T,!
4=3

A grave accent can be added to %bh. This has the effect of generating a short delay
before the help bubble appears.
%th is used as an alternative to %`bh. %th provides a help bubble in the form of a
“tooltip”.

Help format - %n.mhe

By default, help information (associated with the “?” format modifier) is displayed at
the bottom of the window. When %he is used, the point at which %he appears in a
format string specifies the location of the help information. The information could
(for example) be placed inside a box.
In the form %he (without the integer modifiers), the area for the help string will be
sized to fit the largest help string so far encountered. If further help strings are
supplied after %he, their lengths should not exceed this size. In most cases help boxes
are best placed at the bottom of a window. However, if necessary, an earlier help
string could be padded with spaces in order to increase its size.
%20he fixes the size of the area to 20 standard characters on one line, whilst %20.3he
has the same width but occupies 3 lines.
In the following example the help information is placed in a box below the %rd edit
box.
8=C464A ]NRW
270A02C4A"! bcaW[_
]NRW,
bca,=^ ^U RWX[SaT])
W[_,7^f \P]h RWX[SaT] WPeT h^d V^c.
X,fX]X^/! bc.aS/!][´bca]NRW
X,fX]X^/³^QWTRQW[_

120
14.

Window attributes

Caption - %ca[title]
%ca defines the title for a format window. The title is supplied as a standard
character string.
For example:
X,fX]X^/RPJ4aa^aL

The caption will be re-drawn whenever the window is refreshed. This means that if
the title is supplied in the argument list (signified by the “@” character in the format
string) then the window title can be changed dynamically by changing the contents of
the string and calling fX]S^fNd_SPcT/.

Window handle - %hw

%hw is used to return the window handle of the format window being created. This
will be the same as the handle returned by a call to
R[TPafX]NX]U^/³;0C4BCN5>A<0CC43NF8=3>F´. %hw takes one integer
argument for the return value.

Control handle - %lc

%lc is similar to %hw and provides the window handle of the control immediately
preceding %lc in the format string.

121
ClearWin+ User’s Guide Fortran

Leave window open - %lw[option]

By default, fX]X^/ does not return until the window that it creates is closed.
Occasionally it is useful to create a window that remains open while the program takes
other actions. %lw causes fX]X^/ to return as soon as it has created the window (the
return value of fX]X^/ is not used in this case). The format takes one 8=C464A
argument that can be used to close the window. This integer, known as the control
variable, is set to -1 while the window is still active. It is very important that the
control variable used to receive the result does not cease to exist before the window
closes. Hence it is necessary to use a variable that is either global (appears in the
main program, a 2><<>= block or <>3D;4) or static (appears in a B0E4 or 30C0
statement).
Note: Although the control variable is initialised by the call to fX]X^/, you may
choose to give it a value before the call in order to avoid a compiler warning.
%lw is also used to create a child window that is to be inserted within another window
that includes %ch. The grave accent is used in this context. In this case the window
is not displayed until the control variable is passed to the window containing %ch.
See %ch below for an example of this procedure. A child window may be used only
once. If it is not used it will be destroyed when the program terminates.
A window that has been left open by means of %lw can be closed by setting its control
variable to a non-negative value and by passing the address of the control variable to
fX]S^fNd_SPcT/.
For example:
8=C464A R^]ca^[
X,fX]X^/?a^RTbbX]V _[TPbT fPXc[fR^]ca^[
20;; S^Nb^\TcWX]VNR^\_[Tg
R^]ca^[,
20;; fX]S^fNd_SPcT/R^]ca^[
It is possible to use %lw in conjunction with graphics drawing using %gr, %og or
%dw. This provides a means of drawing to a region after it has been created.
However, it is recommended that code to draw to a graphics region be placed in a call-
back function attached to %sc.
%lw can take the option ^f]TS ( %lw[owned] ). This option defines certain
properties of the window in relation to its parent. The “owned” properties are those of
a window that does not use %lw, namely that the parent cannot overlay the child and,
if the parent is closed, the child automatically closes. For these properties to be
meaningful the parent must be created using %ww. Also %lw[owned] must be used in
the definition of a child window that appears in a call-back function of the parent.

122
Chapter 14 Window attributes

Start-up call-back - %sc

%sc takes one call-back function which is called only once when the window is first
displayed. It has several uses, one of which could be to display a start-up message.

Child window - %ch

%ch inserts a child window created by %`lw in a previous call to fX]X^/. The format
takes a single 8=C464A argument that is the control variable of the child window.
Child windows are automatically restored on top of their parent and are constrained to
lie within it. If they have a caption (as they will by default) they can be moved by the
user. Child windows created in this way are fixed in size and location (relative to the
parent window). Here is a simple example:
8=C464A R^]ca^[NePa
X,fX]X^/ffJ]^NUaP\TLO[fR^]ca^[NePa
X,fX]X^/CWXb Xb P RWX[S fX]S^f!][RWR^]ca^[NePa

Control variable - %cv

%cv is used to establish a control variable for a window that does not use %lw. It
takes an 8=C464A control variable as an argument. This is used to enable another
window to attach itself as a child using the %aw format.

Create MDI frame - %fr

%fr is used in a parent window to define a frame into which child windows are placed.
These windows can be moved and re-sized within this MDI (multi-document
interface) frame. The format takes two integer arguments that define the width and
height of the frame in pixels. A MDI frame can be preceded by the pivot (%pv), in
which case it will expand as the window expands. An example using %fr appears
with %aw below.
A grave accent (`) can be added to %fr to cause it to maintain a handle identifying the
currently selected child window. An extra integer argument is supplied to hold the
returned handle. The integer will be zero if there is no child window. When a child
window is created, the handle is obtained by using %hw (see page 121). A
comparison may then be made between the handle updated by %fr and those
previously returned by %hw.

Attach window - %aw

%aw attaches the window as an MDI child of a parent. The parent must contain an
MDI frame (%fr). %aw takes an 8=C464A argument that is a control variable
attached to the parent window (the parent must already exist). If the parent window

123
ClearWin+ User’s Guide Fortran

does not use %lw, and therefore does not have a control variable, use %cv (see above)
in the parent window. In general the child window should have a caption so that it
can be moved, maximised, minimised, etc. within the frame. This means that you
should not use the %ww ]^NRP_cX^] option in this context.
The following code provides the basis of a simple “multipad” editor using %fr and
%aw.
F8=0??
8=C464A Rca[fX]X^/
4GC4A=0; ^_T]NUd]R
270A02C4A !' U]P\T
2><<>= Rca[
U]P\T,³Uâ³
X,fX]X^/ffJ]^NQâSTaL´
X,fX]X^/³\]J5X[TJ>_T]LL´
58;4N>?4=AJ>_T]LU]P\T^_T]NUd]R438CN58;4U]P\T
X,fX]X^/³\]JJ4gXcLL´4G8C
X,fX]X^/³_eUa´#;";
X,fX]X^/³[fRca[
4=3
8=C464A 5D=2C8>= ^_T]NUd]R
2><<>= Rca[
8=C464A Rca[fX]X^/
X,fX]X^/_ePf´Rca[
X,fX]X^/³!'TQJ]^NQâSTaL;
^_T]NUd]R,
4=3

124
Chapter 14 Window attributes

Details of the standard call-back functions 58;4N>?4=A 438CN58;4, and 4G8C

are given in Chapter 20.

Drag and drop - %dr

%dr takes a call-back function that is called when a file is dropped on to a window. If
a collection of files is dropped, the call-back is called for each file in turn. This can be
achieved, for example, by the following actions:
• Open the File Manager or Explorer and select one or more files.
• Drag the files to the format window containing %dr.
• Use R[TPafX]NbcaX]V/3A>??43N58;4 in the call-back associated with
%dr.
For example, a text editor could use this feature by opening the droppped file for
editing.
The following code illustrates how %dr works:
F8=0??
8=C464A XfX]X^/
4GC4A=0; Sa^_NUd]R
X,fX]X^/RPJ3aPV P]S Sa^_LQVJVaThL
X,fX]X^/3a^_ UX[Tb WTaT
X,fX]X^/SaSa^_NUd]R
4=3
R
8=C464A 5D=2C8>= Sa^_NUd]R
8=2;D34 +R[TPafX]X]b-
270A02C4A !( UX[T]P\T
8=C464A X
UX[T]P\T,R[TPafX]NbcaX]V/3A>??43N58;4
X,fX]X^/RPJ3a^__TS UX[TLQVJVaThL
X,fX]X^/O!abUX[T]P\T
X,fX]X^/!][R]ccJ=Tgc UX[TL
Sa^_NUd]R,!
4=3

125
ClearWin+ User’s Guide Fortran

Set window position - %sp

This format code is used to initialise the position of the window on the screen. Integer
arguments x and y are used to specify the position of the top left-hand corner of the
window in screen co-ordinates.
For example:
X,fX]X^/bX.b_FWh Xb cWXb bcdRZ X] cWT R^a]Ta;;
If more than one position format is used, the positions are added vectorially. This is
particularly useful in conjunction with the get window position format %gp.

Set window size - %sz

%sz takes two 8=C464A variables (w,d) in the form:
8=C464A fW
X,fX]X^/bifW
w and h are usually given zero values in the program before the first call to fX]X^/.
Zero values are ignored by fX]X^/. (w,h) subsequently hold the current pixel width
and height of the window. These values will change when the window is sized.
When the window is closed, the latest values can be stored (in a configuration file for
example) and used the next time the same window is opened. In this way you can
recreate the window size that was last used. A maximised window is configured in
the same way because specific values are used to represent this state.

Window style - %ww[options]

This format code causes the resultant window to look like an application window,
rather than a dialog window. The window can be maximised, etc.. %ww can be
followed by an option list enclosed in square brackets (use an empty list if options are

126
Chapter 14 Window attributes

not used and the next character in the format string is an open square bracket ‘[’).
The following options are available:

RPbcbNbWPS^f This option produces a window that casts a shadow. It is most

effective when used in conjunction with ]^NUaP\T and
]^NRP_cX^].
]^NRP_cX^] Omit the caption from the window.
]^N\Pg\X]Q^g Omit the maximise and minimise boxes from the window.
]^N\PgQ^g Omit the maximise box.
]^N\X]Q^g Omit the minimise box.
]^Nbhb\T]d Omit the box at the top left that is used to produce the system
menu.
]^NQâSTa Omit the blank border that normally surrounds the window
contents, but leave the frame itself. Using this option you can,
for example, force a tool bar (textual or bit-mapped) to be placed
immediately beneath the menu.
]^NUaP\T Omit the window frame and the blank border that normally
surrounds the window contents. This option is particularly
useful with certain types of child window.
]^NTSVT This option is like ]^NUaP\T except that it leaves the default
border (an empty space around the edge of the window).
c^_\^bc Forces the window to stay on top, even if another application
gets control. This is sometimes useful when it is necessary to
execute another application without the user losing sight of the
current window.
\PgX\XbT Displays the window as a maximised window.
â
\PgX\XiT
\X]X\XbT Displays the window as a icon.
â
\X]X\XiT

Background colour - %bg[colour]

%bg is used with or without the grave accent modifier. Without the modifier, %bg
changes the background colour of the main window. With the modifier, %`bg
changes the background colour of the next (and only the next) control (used for
example with %rd, %rf, %rs, %ed, %ls). %`bg is not used for buttons. For buttons
use %bc.

127
ClearWin+ User’s Guide Fortran

By default a main window uses the background colour that the user can select from the
Control Panel in the Program Manager. This colour is returned by
6TcBhb2^[â2>;>ANF8=3>F.
The new colour can be supplied as one of the standard colours: Q[PRZ fWXcT
VaTh aTS VaTT] Q[dT and hT[[^f (for example: QVJhT[[^fL).
Alternatively %bg takes one integer argument that has a value given by A61/.
For example:
X,fX]X^/QVA61/!$$!$$
It is often desirable to base the new colour on the default by calling GetSysColor. In
other words, you could create an alternative shade of the default background colour by
unpacking the integer returned by GetSysColor and by modifying one or more of the
(red, green, blue) components. For example:
8=C464A R^[âaTSVaTT]Q[dT
R^[â , 6TcBhb2^[â2>;>ANF8=3>F
aTS , 0=3R^[â!$$
VaTT] , 0=3ABR^[â' !$$
Q[dT , 0=3ABR^[â %!$$
R^[â , A61/aTSVaTT]Q[dT$
X , fX]X^/QVR^[â
This will deepen the blue component of the background colour (the new value is
assumed to be less that 256). AB and 0=3 are Salford-supplied intrinsic functions (in
Fortran 90/95 you can use the standard intrinsics 8B75C and 80=3).

ClearWin window - %N.Mcw[options]

Using %cw you can embed a ClearWin window (as described in Chapter 23) in a
format window. The window is created N characters wide and M deep but this can be
changed by the user if the pivot format (%pv) is included. %cw takes one argument
that is the Fortran unit number that you wish to associate with the window.
Alternatively, if you pass zero, the ClearWin window is created as the default stream.
By default the window has no caption and is not scrollable. The options ebRa^[[
and/or WbRa^[[ are used to provide vertical and horizontal scroll bars. If a caption,
etc. is required (for example to make the window movable), then %cw must be
embedded in a child window which is itself embedded in the main window.
A grave accent (`) is used with %cw to obtain a handle. This handle is returned via an
integer argument. The handle is used in calls to associated routines e.g.
bTcN\PgN[X]Tb/.

128
Chapter 14 Window attributes

Although a ClearWin window can be used for both input and output, it is normally
wise to perform input using other format codes and to use ClearWin windows for
scrolling results. ClearWin windows are also very useful while debugging a program.
The call-back functions 2DC, 2>?H and ?0BC4 will work from within a window
defined by %cw.

Property sheet - %Nps

Property sheets represent a way of presenting two or more ‘sheets’ of data in a form
that resembles a card index. Each sheet is set up as a separate window using %sh.
%sh produces a child window that is hidden from view until connected to a property
sheet control using %ps. The property sheet can also have a call-back function that is
called each time the visible sheet is changed. A B744CN=> parameter is provided (see
R[TPafX]NX]U^/) so that it is possible to determine the sheet that is topmost. When
the sheet is first displayed, the B744CN=> is set to 1 and the call-back is also called.
A grave accent modifier is supplied to %ps in order provide a handle. The handle is
used set the initial sheet (at a value other than one) and to change the sheet number
under program (rather than user) control (see page 265 for further details). This
handle must be given the SAVE attribute or be a global variable (e.g. stored in a
module or common block).
If %ca is used to provide a caption for the property sheet, then the character ‘&’ will
have the effect of generating an accelerator key (this will only work for the %ps
format).
If an individual sheet is closed (e.g. by placing a button without a callback function in
the sheet) then the parent window will close.
F8=0??
8=C464A W W!XfX]X^/
270A02C4A ! ]^cTb
270A02C4A! ]P\TcT[T_W^]T
]^cTb,
]P\T,
cT[T_W^]T,
R5Xabc _a^_Tach bWTTc
X,fX]X^/bWW
X,fX]X^/U]J<B BP]b BTaXULcb(3
X,fX]X^/RPJCT[T_W^]TLSh%3
X,fX]X^/!!^QJ]^NQ^aSTaL
X,fX]X^/=P\T)RQ
X,fX]X^/ !abRQ]P\T
X,fX]X^/CT[T_W^]T) RQ
X,fX]X^/ !abRQcT[T_W^]T
RBTR^]S _a^_Tach bWTTc

129
ClearWin+ User’s Guide Fortran

X,fX]X^/bWW!
X,fX]X^/RPJ=^cTbL
X,fX]X^/U]J<B BP]b BTaXULcb(3
X,fX]X^/!"aT]^cTb
R3Xb_[Ph cWT R^\QX]TS bWTTcb
X,fX]X^/RPJ?a^_Tach bWTTcLQVJVaThL
X,fX]X^/!_bW W!
4=3

Property sheet child - %sh

This format code is used with %ps. %sh is placed in a format string for a child
window and an argument is provided so that a handle to the window is returned. This
handle is an input parameter for %ps. See %ps above for an example.

Closure control format - %cc

Sometimes, especially when an edit box is displayed, it is desirable to control the
closure of a window. %cc takes a call-back function as its argument. This function is
called before the window closes (for whatever reason). If it returns a positive value
the window is not closed. If a grave is used (%`cc) then the associated call-back
function is called after the window is closed. A single window could use both %cc
and %`cc.

Delayed auto recall - %dl

%dl allows a given call-back function to be called at regular intervals. It takes a
3>D1;4 ?A428B8>= argument that is the number of seconds to wait between calls
followed by the given call-back.
The following code produces a window that displays its message for two seconds
before closing:
X,fX]X^/³S[bXCTbcX]V´!3´4G8C´
Note: Timing messages are only received while the program is idle.

130
Chapter 14 Window attributes

Wallpaper - %wp[bitmap]
%wp takes the name of a bitmap resource. bitmap is a standard character string.
%wp “wallpapers” the window with the bitmap before the text and controls are drawn.
For example:
F8=0?? RWXciaR
8=C464A XfX]X^/
X,fX]X^/RPJFP[[_P_TaLf_JRWXciL
X,fX]X^/QVJVaThLU]JCX\Tb =Tf A^\P]L
X,fX]X^/R]^Q2[TPaFX]RQ
4=3
where the resource script chitz.rc contains:
RWXci 18C<0? R)KfX]S^fbKRWXciQ\_

%wp is most effective in windows that contain only graphical objects. If the bitmap is
smaller than the dimensions of the window, it will be repeated horizontally and
vertically to fill the space. Therefore, your bitmap should either be sufficiently large,
or it should contain a pattern that is designed to repeat, like the standard Windows
wallpaper bitmaps. A grave accent (`) is added to %wp in order to ensure that the
window will be expanded to hold at least one copy of the bitmap.

User window - %uw[class_name]

%uw enables existing Windows code to be interfaced with ClearWin+. Given a
registered Windows class (that will have its own Windows procedure), a window can
be embedded in a format window by using %uw. %uw is followed by a standard
character string giving the name of the class. It also takes the following arguments:
1) the 8=C464A width of the child in pixels,
2) the 8=C464A height of the child in pixels,
3) the Window style (This will be OR-ed with WS_CHILD. In general, no border or
caption will be specified, as these will normally be applied to the main window
e.g. using %ca.)
4) the extended window style (often zero),
5) an 8=C464A to receive the handle for the resultant child window.

131
ClearWin+ User’s Guide Fortran

Screen saver - %sv

By using %sv it is possible to create a screen saver. A format window that includes
%sv will close as soon as it receives mouse or keyboard input. The executable should
be renamed to a <filename>.SCR file, placed in the Windows directory and then
selected as the current screen saver from the Control Panel. Apart from its obvious
use, a screen saver can be used to perform a lengthy calculation. To ensure the
calculation is continued from where it was interrupted, the %cc (window closure
format) should be used to trap the closure and perform file I/O.
For example:
F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A gaTbhaTbVNWP]S[TaVQX
2><<>= gaTbhaTbVNWP]S[TaVQ
4GC4A=0; aTSaPfNbRaTT]
3>D1;4 ?A428B8>= bTRSb
bTRSb,
a,!
V,%#
Q,
gaTb,R[TPafX]NX]U^/bRaTT]NfXScW
haTb,R[TPafX]NX]U^/bRaTT]NST_cW
R QV QPRZVa^d]S R^[^da
X,fX]X^/beQVJQ[PRZL
R 3TUX]T P fX]S^f cWPc cPZTb cWT FW^[T SXb_[Ph PaTP
X,fX]X^/ffJ]^NRP_cX^]]^N\Pg\X]Q^g]^Nbhb\T]d´
´]^NUaP\T]^NQ^aSTac^_\^bcL
X,fX]X^/OVaJaVQNR^[^dabQ[PRZLgaTbhaTbVNWP]S[T
R DbT P _TaX^SXR ST[PhTS RP[[QPRZ c^ X]XcXPcT d_SPcTb
X,fX]X^/S[bTRSbaTSaPfNbRaTT]
4=3
R
8=C464A 5D=2C8>= aTSaPfNbRaTT]
8=2;D34 +fX]S^fbX]b-
8=C464A gaTbhaTbVNWP]S[TaVQ[^^_
2><<>= gaTbhaTbVNWP]S[TaVQ
20;; bT[TRcNVaP_WXRbN^QYTRc/VNWP]S[T
3> [^^_, haTb
20;; SaPfN[X]TNQTcfTT]/[^^_gaTb[^^_A61/aVQ
a,a
V,V"
Q,Q$
85a6C!$$ a,
85V6C!$$ V,V!$$

132
Chapter 14 Window attributes

85Q6C!$$ Q,Q!$$
4=33>
aTSaPfNbRaTT],
4=3

Disable screen saver - %ns

%ns is designed to cause screen saver activity to be inhibited while the window is
open. If your application opens a window and then performs a long calculation, there
is a danger that a screen saver will cut in when your program yields, even temporarily.
This is because the operating system considers the system to be idle if there is no input
for a set period of time. Many screen savers are very CPU intensive and will starve
your program of CPU resources. Use %ns to eliminate this problem.

133
ClearWin+ User’s Guide Fortran

134
15.

Graphics

Introduction
ClearWin+ includes a library of drawing routines for drawing lines and text, for
filling areas, for copying images, etc.. These routines do not have an explicit
argument referring to the ‘surface’ on which the drawing is to take place. Instead,
drawing routines are applied to what is called the current drawing surface. This
drawing surface can be:
1) one of a number of rectangular areas of the screen generated by %gr,
2) one of a number of printer bitmaps (created for example by ^_T]N_aX]cTa/),
3) an internal drawing surface created by RaTPcTNVaP_WXRbNaTVX^]/ (that is, a
bitmap that is created for copying to another drawing surface).
When it is necessary to distinguish one surface from another, the programmer
provides a unique integer identifier (called a handle) and the routine
bT[TRcNVaP_WXRbN^QYTRc/ is used to provide the switch. This chapter describes
drawing surfaces created using %gr and RaTPcTNVaP_WXRbNaTVX^]/. Printer
surfaces are described in Chapter 18.
%gr is one of four graphics format codes provided by ClearWin+. The others are %og
(used to create a region in which OpenGL routines are used; described in the next
chapter), %pl (used to create a region in which SIMPLEPLOT routines are used;
described in Chapter 17) and %dw (used to create a region in which Windows API
functions are used; described at the end of this chapter). Using these formats it is
possible to embed your graphics in a window together with other controls. The
ClearWin+ library of drawing routines is used only with %gr. Thus, only %gr (not
%og, %pl and %dw) generates a drawing surface.

135
ClearWin+ User’s Guide Fortran

Graphics format %gr[options]

There are two colour modes for ClearWin+ drawing routines: (a) VGA colour mode,
designed to emulate the EGA and VGA palette registers and used to port legacy code
to Windows and (b) RGB colour mode, the native Windows colour mode.
To assist in the porting of legacy code, the default colour mode is currently set as VGA
colour mode. However, it is recommended that all new programs should use RGB
colour mode. There are three ways to change the colour mode.
1. The default is changed to RGB colour mode by calling
bTcNaVQNR^[^dabNSTUPd[c/ at the beginning of the program. This is
recommended for new programs.
2. Alternatively, when creating a drawing surface using %gr, you can include the
option A61N2>;>DAB (see below).
3. In either case you can change the colour mode for a particular drawing surface by
calling dbTNaVQNR^[^dab/.

%gr can be followed by a list of options that is any valid combination of the following:
1;02: F78C4 A43 Specifies the initial background colour of the
1;D4 H4;;>F 6A4H drawing surface. Otherwise this defaults to the
^a 6A0H background colour of the surrounding window.

<4C058;4NA4B8I4 Options specifying the behaviour of the graphics

area as it is re-sized. See later in this chapter.
DB4ANA4B8I4
A61N2>;>DAB Selects RGB colour mode.
5D;;N<>DB4N8=?DC Specifies that mouse movements and mouse button
releases should be notified to the call-back function,
not just clicks and double clicks.
1>GNB4;42C8>= Specifies the initial selection mode, that controls the
behaviour when the user presses the left mouse
;8=4NB4;42C8>=
button and drags the mouse over the graphics area.
These options are useful for interactive programs.
DB4ANBDA5024 A Win32-only option to enable software to access
the in-memory copy of the graphics area so as to
modify it at the highest possible speed. This option
is particularly useful for image processing software.

%gr creates a ‘control’ that is a rectangular graphics area (a drawing surface) that will
be filled by subsequent calls to ClearWin+ drawing routines. In the absence of %gr,
using drawing surface routines causes ClearWin+ to create a separate window

136
Chapter 15 Graphics

containing a drawing surface together with a button to close the window. This is
analogous to the automatic creation of a ClearWin window for standard Fortran I/O.
The various options to the %gr format are explained in this and subsequent sections of
the chapter.
%gr takes two arguments that provide the pixel width and height of a rectangular
area. You may want to vary these values depending on the resolution of the user’s
screen. The pixel width and depth of the screen is obtained by calling
R[TPafX]NX]U^/ using B2A44=NF83C7 and B2A44=N34?C7.
The %gr options consisting of simple colour names (such as 1;02: supply an initial
background colour that would otherwise default to the background colour of the
surrounding window. The option A61N2>;>DAB can be used if the default has not be
changed to RGB colour mode by calling bTcNaVQNR^[^dabNSTUPd[c/ .
For example:
8=C464A Rca[X
X,fX]X^/ffVaJQ[PRZaVQNR^[^dabL#;";
X,fX]X^/QcJ>:L[fRca[
20;; SaPfN[X]TNQTcfTT]/ "!A61/!$$
This will draw a red line on a black background. In this example, %lw has been used
to leave the window open so that code to draw to the drawing surface can follow. A
alternative approach is to provide a startup call-back function using %sc and to place
the graphics code in the call-back. This approach is usually preferred unless you need
to use %lw for other reasons.
If more than one drawing surface is to be drawn (either within one window, or on
different windows) then a grave accent modifier is supplied to %gr and a third
argument is required to input an integer (called a handle) that you provide. This
handle is used in the subroutine bT[TRcNVaP_WXRbN^QYTRc/ in order to select the
current drawing surface.
The following example creates two drawing surfaces and draws to each in turn.
8=C464A Rca[W]S W]S!
30C0 W]S W]S! !
R 6aP_WXRb WP]S[Tb PaT X]_dc eP[dTb c^ Va
R
20;; bTcNaVQNR^[^dabNSTUPd[c/
X,fX]X^/OVa#;";W]S
X,fX]X^/OVa#;";W]S!
X,fX]X^/ff[fRca[
X,bT[TRcNVaP_WXRbN^QYTRc/W]S
20;; SaPfN[X]TNQTcfTT]/ "!A61/!$$
X,bT[TRcNVaP_WXRbN^QYTRc/W]S!
20;; SaPfNUX[[TSNT[[X_bT/! $&$$A61/!$$

137
ClearWin+ User’s Guide Fortran

Other drawing surfaces can be set up to write an image to memory or to write output
to the printer. The graphics calls in the above program can also be used on such
surfaces. Details appear later in this chapter and in Chapter 18.

Basic graphics primitives

Once a %gr drawing surface has been created, the following functions are used to
draw in the space:

3A0FN;8=4N14CF44=/ Draws a straight line between two points.

3A0FN270A02C4AB/ Draws text.
3A0FN4;;8?B4/ Draws an ellipse.
3A0FN58;;43N4;;8?B4/ Fills an ellipse.
3A0FN58;;43N?>;H6>=/ Fills a polygon.
3A0FN58;;43NA42C0=6;4/ Fills a rectangle.
3A0FN?>;H;8=4/ Draws a number of connected straight lines.
3A0FNA42C0=6;4/ Draws a rectangle.
3A0FN?>8=C/ Sets a pixel colour.
B4CN;8=4NBCH;4/ Sets attributes for line drawing.
B4CN;8=4NF83C7/ Sets the width for line drawing.

Drawing text
Text may be added to a %gr drawing surface by using SaPfNRWPaPRcTab/, for
example,
20;; SaPfNRWPaPRcTab/CX\T BTRb"$"'A61/!$$!$$!$$
The initial font is the current font in the format window, but it can be changed by
using the following routines. These operate on the currently selected drawing surface.
Note that generally only TrueType fonts can have their appearance varied in all of the
ways shown below.

1>;3N5>=C/ Selects/deselects bold font.

27>>B4N5>=C/ Displays a font selection dialog box.

138
Chapter 15 Graphics

64CN5>=CN=0<4/ Can be repeatedly called to obtain the name of all

installed fonts on the system.
64CNC4GCNB8I4/ Gets the dimensions of a given string.
8C0;82N5>=C/ Selects/deselects italic the font.
A>C0C4N5>=C/ Rotates the font anticlockwise by a given angle in
degrees.
B20;4N5>=C/ Multiplies the font size.
B4;42CN5>=C/ Selects a font by name.
B8I4N8=N?8G4;B/ Specifies the font size in pixels.
B8I4N8=N?>8=CB/ Specifies the font size in points.
D=34A;8=4N5>=C/ Selects/deselects underlined font.

The following program demonstrates the use of these routines

F8=0??
8=2;D34 +R[TPafX]X]b-
8=C464A XXRca[bNfXScWbNST_cWVNfXScWVNST_cWR^[^da
R 6Tc fXScW P]S WTXVWc Û bRaTT]
bNfXScW , R[TPafX]NX]U^/B2A44=NF83C7
bNST_cW , R[TPafX]NX]U^/B2A44=N34?C7
R BXiT Û VaP_WXRb PaTP
VNfXScW , !bNfXScW"
VNST_cW , !bNST_cW"
R 6aP_WXRb fX]S^f
X,fX]X^/ffRPJF8=3>FB 5>=CBL
X,fX]X^/\]J4gXcL4G8C
X,fX]X^/VaJQ[PRZaVQNR^[^dabLVNfXScWVNST_cW
X,fX]X^/³[f´XRca[
R BT[TRc FX]S^fb U^]c <^STa] STUPd[c PccaXQdcTb
R 3aPf X] X]cT]bT fWXcT
20;; bT[TRcNU^]c/<^STa]
20;; SaPfNRWPaPRcTab/ ) bT[TRcNU^]c)\^STa]
"$"'A61/!$$!$$!$$
R <d[cX_[h bXiT Û U^]c Qh !
R 3aPf X] hT[[^f
20;; bRP[TNU^]c/!3
20;; SaPfNRWPaPRcTab/!) CWXb Xb bRP[TNU^]c
""A61/!$$!$$
R D]STa[X]T U^]c
R 3aPf X] X]cT]bT RhP]
20;; d]STa[X]TNU^]c/

139
ClearWin+ User’s Guide Fortran

20;; SaPfNRWPaPRcTab/") CWXb Xb d]STa[X]TNU^]c

!'!A61/!$$!$$
R 8cP[XR U^]c
R 3aPf X] X]cT]bT VaTT]
20;; XcP[XRNU^]c/
20;; SaPfNRWPaPRcTab/#) CWXb Xb XcP[XRNU^]c
" A61/!$$
R B_TRXUh cWT bXiT ^U cWT U^]c X] _XgT[b
R 3aPf X] RhP]
20;; bXiTNX]N_XgT[b/!
20;; SaPfNRWPaPRcTab/$) CWXb Xb bXiTNX]N_XgT[b
"$$A61/ !& !&
R B_TRXUh cWT bXiT ^U cWT U^]c X] _^X]cb
R 3aPf X] X]cT]bT Q[dT
20;; bXiTNX]N_^X]cb/!
20;; SaPfNRWPaPRcTab/%) CWXb Xb bXiTNX]N_^X]cb
$A61/!$$
R A^cPcT cWT U^]c Qh & STVaTTb
R 3aPf X] X]cT]bT \PVT]cP
20;; a^cPcTNU^]c/&3
20;; SaPfNRWPaPRcTab/&) CWXb Xb a^cPcTNU^]c)&
'#$A61/!$$!$$
R D]S^ d]STa[X]T U^]c
R 3aPf X] X]cT]bT RhP]
20;; d]STa[X]TNU^]c/
20;; SaPfNRWPaPRcTab/') CWXb Xb d]S^ d]STa[X]TNU^]c
$#$A61/!$$!$$
R 4\Q^[ST] cWT U^]c
R 3aPf X] X]cT]bT fWXcT
20;; Q^[SNU^]c/
20;; SaPfNRWPaPRcTab/() CWXb Xb Q^[SNU^]c
!!"$A61/!$$!$$!$$
R DbTa bT[TRcTS U^]c STUPd[c R^[^da Q[PRZ
R 3aPf X] X]cT]bT fWXcT
R^[^da,
20;; RW^^bTNU^]c/R^[^da
20;; SaPfNRWPaPRcTab/ ) CWXb Xb RW^^bTNU^]c
"#$R^[^da
4=3
Note how RW^^bTNU^]c/ allows user selection of font style, underline, overstrike,
size and colour.

140
Chapter 15 Graphics

Re-sizing a graphics surface

It is often desirable to allow a graphics area to be re-sized by the user by altering the
size of the window in which it is contained. Like all ClearWin+ controls, by default
the drawing surface created by %gr will have a fixed size. However, %gr can take a
pivot, enabling it to be re-sized. Unlike other simple controls, the desired effect of re-
sizing a graphics area is not obvious. ClearWin+ offers the choice of either re-
drawing the image from scratch (with different contents if you wish) or of letting the
system re-scale the existing graphics.
A %gr region will change size when the enclosing window is re-sized if it is preceded
by a pivot format (%pv) and provision has been made to re-draw the graphics by one
of the following two methods:
1) If the DB4ANA4B8I4 option is given to %gr and a call-back function is supplied
(i.e. %^gr[user_resize]) then, when the window is re-sized, the whole area will be
blanked out and the call-back function will be called. It is assumed that this
function will re-draw the contents of the box. The function can determine that a
re-draw is required by calling R[TPafX]NbcaX]V/ using 20;;102:NA40B>=.
This will return the string A4B8I4 if a re-size is occurring. The
R[TPafX]NX]U^/ parameter 6A0?782BNA4B8I8=6 will also return 1 if a re-size
is occurring, but this has been superseded by the general purpose
20;;102:NA40B>= mechanism. The R[TPafX]NX]U^/ parameters
6A0?782BNF83C7 and 6A0?782BN34?C7 are used to return the new size of the
area. For convenience the box is assumed to be re-sized immediately it is created,
so it is only necessary to draw your graphics in one place in your code. Here is
some sample code:
F8=0??
8=C464A XfX]X^/
4GC4A=0; SaPf
X,fX]X^/ff_eMVaJdbTaNaTbXiTaVQNR^[^dabL';!$;SaPf
4=3

8=C464A 5D=2C8>= SaPf

8=2;D34 +fX]S^fbX]b-
8=C464A ghaTbXiT
aTbXiT,R[TPafX]NX]U^/6A0?782BNA4B8I8=6
85aTbXiT4@ C74=
g,R[TPafX]NX]U^/6A0?782BNF83C7
h,R[TPafX]NX]U^/6A0?782BN34?C7
20;; SaPfN[X]TNQTcfTT]/ghA61/!$$
4=385

141
ClearWin+ User’s Guide Fortran

SaPf,!
4=3
2) An alternative method for re-sizing a %gr region is to supply the option
\TcPUX[TNaTbXiT to the %gr format code. In this case, a record (stored in a
Windows object known as a meta-file) of all graphics operations is made and the
result is re-played at the new box size. This approach is clearly the easiest to
program, however there are two factors to consider before using this technique.
a) The number of graphics operations being sent to the region must not be
unreasonably large since each graphics call will be recorded for re-play. For
example, a fractal drawing program (that continued to draw more detail for as
long as it ran) could not use this technique because it would ultimately run out
of memory.
b) Also some images may not respond well to such automatic re-scaling. This is
because floating point co-ordinates are truncated to integers when the original
image is drawn. When scaled, they are truncated a second time. In general,
line drawing will still look good, but images drawn pixel by pixel are probably
best re-sized by method 1.

The %gr call-back function

Simple graphics operations can be performed without the use of a call-back function.
However, you will need a call-back function if you want to respond to mouse changes,
or to icon movements, or if you want to redraw in response to a re-size event.
If a call-back function is supplied with %gr, it will be called for a variety of reasons,
conveniently distinguished using R[TPafX]NbcaX]V/³20;;102:NA40B>=´.
Here is the full set of reasons for calling the call-back function:

<>DB4N;45CN2;82: These reasons are given after the corresponding

mouse button has been pressed and released, except
<>DB4N<833;4N2;82:
in 5D;;N<>DB4N8=?DC mode, when they occur
<>DB4NA867CN2;82: when the key is pressed.
<>DB4N;45CNA4;40B4 These reasons only occur if the option
<>DB4N<833;4NA4;40B4 5D;;N<>DB4N8=?DC is used with %gr. They occur
when the corresponding mouse button is released.
<>DB4NA867CNA4;40B4
<>DB4N3>D1;4N2;82: This reason is given when two successive left mouse
clicks have occurred within the interval defined as a
double click.
Individual mouse ;45CN<>DB4N2;82: events will

142
Chapter 15 Graphics

also be generated.
A4B8I4 Given when the DB4ANA4B8I4 option is used and
the window has just been created or re-sized.
Usually the call-back function will draw or re-draw
the image.
3A06N0=3N3A>? Given when an icon has been dragged and dropped
on to the graphics area.

Tip Many systems are configured so that the middle mouse button is inactive, even though
it is physically present on the mouse. For this reason it is better to avoid relying on
this button.

Once the reason for the call-back has been established, additional information can be
obtained by calling R[TPafX]NX]U^/. You can use 6A0?782BN<>DB4NG and
6A0?782BN<>DB4NH to obtain the pixel co-ordinates of the mouse event that caused
the call-back. Also 6A0?782BN<>DB4N5;06B gives full information about the state
of the mouse keys (this is most useful when the 5D;;N<>DB4N8=?DC %gr option is
used). The mouse flags are bitwise significant as follows:

1 Left button pressed

2 Right button pressed
4 Shift key pressed
8 Control key pressed
16 Middle button pressed

Tip Using the 5D;;N<>DB4N8=?DC option it is possible to respond to a mouse press by

altering parts of your image, reversing these changes when the key is released again.
This can give a very dynamic feel to your program. Remember, however, that any
operations you perform at this point should not take too long, otherwise the mouse
response will become sluggish.

Graphics selections
Consider the task of writing a simple paint program. Such programs often allow the
user to hold down the left mouse key in order to open up a box that is used to select an
area. Alternatively, the effect of dragging the mouse could be to create a line rather
than a box.
%gr drawing surfaces have an associated ‘selection mode’. This mode tells
ClearWin+ what to do if the mouse is dragged (by the left button) over the area. The

143
ClearWin+ User’s Guide Fortran

mode can be set using the 1>GNB4;42C8>= or ;8=4NB4;42C8>= options on the %gr
format code. The mode can also be changed dynamically using the
bTcNVaP_WXRbNbT[TRcX^]/ function. This operates on the current drawing
surface. The argument to this function takes the following values:

0 default - no selection
1 box selection
2 line selection

When a selection is enabled, dragging the mouse with the left button depressed opens
an XOR drawn box or line. A program obtains the co-ordinates using
VTcNVaP_WXRbNbT[TRcTSNPaTP/. Typically you would call this function on the
release of the left mouse (or possibly in response to a button press) so that the program
would respond to the final position of the line or box.
The following example uses 1>GNB4;42C8>=. When the left mouse button is
released, the program draws a diagonal line using the box position and dimensions. If
the shift key is held down, a copy of the box is produced instead of a line.
Alternatively, if the control key is held down, an ellipse is drawn to fill the box.
F8=0??
8=C464A XfX]X^/
270A02C4A' U\c
4GC4A=0; VaNUd]R

X,fX]X^/ffJ]^NQ^aSTaLRPJ1^g BT[TRcX^]LbhJ"SNST_aTbbTSL
U\c,MVaJQ[PRZQ^gNbT[TRcX^]Ud[[N\^dbTNX]_dcaVQNR^[^dabL
X,fX]X^/U\c!!VaNUd]R
4=3

8=C464A 5D=2C8>= VaNUd]R

8=2;D34 +fX]S^fbX]b-
8=C464A g h g!h!PQU[PVbVaTh
;>6820; 8bD_FPb3^f]
30C0 FPb3^f]50;B4

U[PVb,R[TPafX]NX]U^/VaP_WXRbN\^dbTNU[PVb
8bD_,0=3U[PVb<:N;1DCC>=4@

858bD_0=3FPb3^f]C74=
VaTh,A61/ & & &
20;; VTcNVaP_WXRbNbT[TRcTSNPaTP/g h g!h!
20;; bTcNVaP_WXRbNbT[TRcX^]/
850=3U[PVb<:NB785C4@<:NB785CC74=
20;; SaPfNUX[[TSNaTRcP]V[T/g h g!h!VaTh

144
Chapter 15 Graphics

4;B4850=3U[PVb<:N2>=CA>;4@<:N2>=CA>;C74=
P,$g!g
Q,$h!h
20;; SaPfNUX[[TSNT[[X_bT/g Ph QPQVaTh
4;B4
20;; SaPfN[X]TNQTcfTT]/g h g!h!VaTh
4=385
20;; bTcNVaP_WXRbNbT[TRcX^]/
4=385
FPb3^f],=>C8bD_
VaNUd]R,
4=3

Drawing device independent bitmaps

When using %gr and its associated drawing surfaces (including internal and printer
drawing surfaces) there are two sets of routines for processing device independent
bitmaps (DIBs). The first set uses a 270A02C4A array supplied by the programmer.
The second uses a handle supplied by ClearWin+.
Using a 24 bit per pixel array
The following routines are used to handle device independent bitmaps:
64CN381NB8I4/ Gets parameters from a bitmap file. p362

64CN381N1;>2:/ Extracts a rectangular block from a bitmap file. p361

?DCN381N1;>2:/ Saves a rectangular block to a bitmap file. p391

38B?;0HN381N1;>2:/ Displays a block on the current drawing p353

surface.

145
ClearWin+ User’s Guide Fortran

64CN381NB8I4/ obtains information about an existing .BMP file. The file name is
an input argument that should have the .BMP suffix. The file name may be a full path
name. If the routine succeeds, an error code is returned with the value zero whilst
other arguments return the width and height (in pixels) of the image contained in the
file. The number of bits per pixel is also returned as one of the following values:
1 Monochrome black and white image
4 16-colour image
8 256-colour image
24 Full colour image in which each pixel is represented by eight bits per
red/green/blue value.

VTcNSXQNQ[^RZ/ extracts a rectangular block (that could be the whole image) from a
given file into an array. The first index of the array is the colour index in the order
(red, green, blue). Displacements 0G and 0H into the array are typically zero but they
can be set to other values if, for example, the array is to be composed of a montage of
several blocks. Arguments F and 7 represent the width and height of the block to be
transferred, whilst 3G, 3H represent the displacement (again typically zero) into the
image in the file.
SXb_[PhNSXQNQ[^RZ/ transfers a rectangular block of given size (F × 7) from the
array at a position (0G, 0H) to a position (G, H) on the current drawing surface (e.g. a
%gr region or a printer). Two arguments named 5D=2C8>= and <>34 are normally
set to zero. An argument for the error status is returned as zero if the process is
successful.
_dcNSXQNQ[^RZ/ transfers a rectangular block from an array to given file,
destroying any previous contents. Displacements 0G and 0H into the array are
typically zero, whilst arguments F and 7 are the width and height of the image to be
created. An argument for the number of bits per pixel is currently ignored and should
set to 24. This routine always writes BMP files with 24 bits per pixel.
The use of these routines is best illustrated by a simple example. The following
example reads a BMP file, alters the array to draw a red line through the image,
displays the result, and writes a new BMP file with the modified image.
F8=0??
8=2;D34 +fX]S^fbX]b-
270A02C4A$ UX[T
270A02C4A P" !# !#
8=C464A WaTbeaTb]QNR^[^dabXTaXZR^]ca^[
R =^cT h^d \Ph ]TTS c^ P[cTa cWXb _PcW
UX[T,R)KfX]S^fbKbTcd_Q\_
20;; VTcNSXQNbXiT/UX[TWaTbeaTb]QNR^[^dabXTa

146
Chapter 15 Graphics

85XTa=4>AWaTb6C !#>AeaTb6C !# BC>? CA>D1;4

20;; VTcNSXQNQ[^RZ/UX[TP !# !#WaTbeaTbXTa
85XTa=4 BC>? CA>D1;4
R 3aPf P SXPV^]P[ aTS bcaX_T ^eTa cWT X\PVT
Z,<8=WaTbeaTb
3> X, Z
P XX,RWPa!$$
P!XX,RWPa
P"XX,RWPa
4=33>
R 3Xb_[Ph cWT X\PVT
X,fX]X^/Va[fWaTbeaTbR^]ca^[
20;; SXb_[PhNSXQNQ[^RZ/P !# !#WaTbeaTbXTa
R FaXcT cWT X\PVT PfPh c^ P]^cWTa UX[T
UX[T,R)KcT\_KYd]ZQ\_
20;; _dcNSXQNQ[^RZ/UX[TP !# !#WaTbeaTb!#XTa
4=3

The example is written in Fortran 77 with the array A declared to be ‘sufficiently

large’. With Fortran 90 you can use an allocatable array instead. Note that the
resulting BMP file will typically be larger than the original because the colours will
have been expanded to 24 bits per pixel.

Using a DIB handle

An alternative approach is to use routines that transmit a handle for a device
independent bitmap.
The routines X\_âcNQ\_/, X\_âcN_Rg/, VTcNbRaTT]NSXQ/ and
R[X_Q^PaSNc^NbRaTT]NQ[^RZ/ each return a handle to a DIB. This handle is
then used in SXQN_PX]c/, _aX]cNSXQ/, Tg_âcNQ\_/ and Tg_âcN_Rg/. When
it is no longer needed the associated memory can be released using
aT[TPbTNbRaTT]NSXQ/.
You can also use faXcTNVaP_WXRbNc^NQ\_/ and faXcTNVaP_WXRbNc^N_Rg/ in
order to write the current drawing surface to a file.
Here is a simple program that uses some of these routines:
F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A WaTbeaTb]QQ_TaR^STWSXQRca[XfXScWWTXVWc
270A02C4A$ UX[T
UX[T,R)KfX]S^fbKbTcd_Q\_
20;; VTcNSXQNbXiT/UX[TWaTbeaTb]QQ_TaR^ST
85TaR^ST=4 BC>? BXiT Taaâ

147
ClearWin+ User’s Guide Fortran

WSXQ,X\_âcNQ\_/UX[TTaR^ST
85TaR^ST=4 BC>? 8\_âc Taaâ
X,fX]X^/VaJaVQNR^[^dabL[fWaTbeaTbRca[
TaR^ST,SXQN_PX]c/WSXQ
85TaR^ST4@ BC>? ?PX]c Taaâ
RP[[ SaPfN[X]TNQTcfTT]/WaTbeaTbA61/!$$
85^_T]N_aX]cTa/&4@ C74=
20;; VTcNVaP_WXRP[NaTb^[dcX^]/fXScWWTXVWc
TaR^ST,_aX]cNSXQ/&fXScWWTXVWcWSXQWaTbeaTb
85TaR^ST4@ BC>? ?aX]c Taaâ
TaR^ST,R[^bTN_aX]cTa/&
85TaR^ST4@ BC>? 2[^bT _aX]cTa Taaâ
4=385
20;; aT[TPbTNbRaTT]NSXQ/WSXQ
4=3
This program imports a bitmap and then creates a drawing surface on the screen using
%gr. The bitmap is drawn to the screen and a red line is draw across it. The standard
printer dialog is then displayed via a call to ^_T]N_aX]cTa/. If the user clicks on
the OK button, the routine returns the value 1 and the current graphics device is now
the printer with device handle 7. The bitmap is drawn to this device. Calling
R[^bTN_aX]cTa/ sends the image to the printer.

Direct manipulation of the graphics surface

Every call to a drawing surface routine involves one or more calls the Windows API in
order to perform the operation. This is usually not a problem when high level
operations such as line drawing are being performed. However, it might be desirable
to bypass this mechanism and construct the surface directly, particularly in
applications that manipulate images and that must therefore operate at the pixel level.
This is possible under Win32 (not Win32S or Windows 3.1) by specifying the
DB4ANBDA5024 option with %gr.
When this option is used, an 8=C464A# variable is placed immediately after the two
size parameters. This variable will receive the address of a buffer containing the
graphics contents stored using 3 bytes per pixel. By manipulating this array you can
change the graphics surface directly. The 8=C464A variable should be passed to
fX]S^fNd_SPcT/ after such a manipulation to cause the screen to be updated.
Later versions of ClearWin+ may accelerate some function calls (such as
SaPfN[X]TNQTcfTT]/) by using this direct access method if DB4ANBDA5024 is
coded, but at present this is not the case.

148
Chapter 15 Graphics

The DB4ANBDA5024 option implies the A61N2>;>DAB option and must not be mixed
with <4C058;4NA4B8I4, although it can be combined with DB4ANA4B8I4. A trade-
off is involved here. The user surface will usually require more memory than the
device dependent bitmap that ClearWin+ normally uses to implement %gr. Also each
re-draw of the window will be slower. However, if you implement pixel-by-pixel
graphics by directly manipulating the buffer, you will see a substantial speed
improvement over making calls to SaPfN_^X]c/. If DB4ANBDA5024 is combined
with DB4ANA4B8I4 then the surface pointer variable will be updated each time the
window is re-sized. It is important not to copy this variable and so use an obsolete
version of the pointer. The row of the buffer has a layout corresponding to the
following array:
8=C464A QdUUTa"fXScW
The first index covers the colours as follows:
1[dT
! 6aTT]
" ATS
After each row a few bytes of padding are added if necessary to make the row a
multiple of four bytes. The next row then follows. This layout is imposed by the
Windows operating system and not by ClearWin+.
Here is a simple Fortran example:
F8=0??
8=2;D34 +fX]S^fbX]b-
4GC4A=0; SaPf
8=C464A _ca
2><<>= _ca
XP,fX]X^/ff_eMVaJQ[PRZdbTaNaTbXiT´
³dbTaNbdaUPRTL!$%!$%_caSaPf
4=3

8=C464A 5D=2C8>= SaPf

8=2;D34 +fX]S^fbX]b-
8=C464A _ca
2><<>= _ca
8=C464A fXScWST_cW\X`ghUd[[N^]_PSNfXScW
85R[TPafX]NX]U^/VaP_WXRbNaTbXiX]VT` C74=
fXScW,R[TPafX]NX]U^/VaP_WXRbNfXScW
ST_cW,R[TPafX]NX]U^/VaP_WXRbNST_cW
\,<8=fXScWST_cW
R 2P[Rd[PcT fXScW X] QXcTb ^U ^]T a^f
R aT\T\QTaX]V c^ a^d]S d_ c^ ]TPaTbc # QhcTb

149
ClearWin+ User’s Guide Fortran

_PSNfXScW,[bab"fXScW"!!
R 3aPf P SXPV^]P[ hT[[^f [X]T
3> X, \
g,X
h,X
R 2^\_dcT X]STg X]c^ PaaPh
`,"g_PSNfXScWh
Ud[[N^],!$$
R ATS R^\_^]T]c
2>A4 _ca`!,Ud[[N^]
R 6aTT] R^\_^]T]c
2>A4 _ca` ,Ud[[N^]
4=33>
4=385
SaPf,!
4=3
Note that it is possible (and often very useful) to mix calls to ClearWin+ graphics
routines and direct manipulation of the pixel buffer. If you do this under Windows NT
you must call the API function GdiFlush() to ensure that the effect of any previous
function calls have ‘flushed through’ before you manipulate the buffer directly. This
call is harmless but unnecessary under Windows 95. If you intend to perform all your
graphics by direct buffer manipulation this need not concern you.
If you want to display a large image but do not have the screen space to do so or if you
are producing a graphics and text output window, the routine bRa^[[NVaP_WXRb/
will be of great use. This routine will allow you to scroll graphics in any direction by
any displacement (see page 396).

Off-screen graphics
Sometimes, it is useful to build up graphics information in memory, rather than on the
screen. For example, such information might be subsequently copied to the screen at
several locations, or written to a file. A complex drawing could be built up off screen
whilst displaying other information. When complete, the drawing can be displayed.
In ClearWin+ there are two approaches to this issue each with its own set of routines.
The first creates an internal drawing surface using RaTPcTNVaP_WXRbNaTVX^]/
and is described below. The other approach uses what is called a virtual screen and is
described in the ClearWin+ User’s Supplement. Mixing routines from the two sets
may not produce the desired result.
An internal drawing surface uses the following set of routines together with the DIB
routines listed in the section on page 145.

150
Chapter 15 Graphics

2>?HN6A0?782BNA468>=/ Copies from one designated surface to another.

2A40C4N6A0?782BNA468>=/ Creates a drawing surface of a given size.
34;4C4N6A0?782BNA468>=/ Releases the memory for a drawing surface.
6A0?782BNC>N2;8?1>0A3/ Copies a surface to the clipboard.
B2A>;;N6A0?782B/ Scrolls a drawing surface.
B4;42CN6A0?782BN>1942C/ Selects an existing drawing surface.

Here is a short program that creates a drawing surface using

RaTPcTNVaP_WXRbNaTVX^]/, selects the surface by using
bT[TRcNVaP_WXRbN^QYTRc/ copies a bitmap and writes a message into it. The
current screen area is then selected by another call to bT[TRcNVaP_WXRbN^QYTRc/
allowing subsequent graphics drawing to be directed to the screen. When a button is
clicked the internal surface is copied to the screen using R^_hNVaP_WXRbNaTVX^]/.
F8=0??
8<?;828C =>=4
8=2;D34 +fX]S^fbX]b-
8=C464A XXRca[fXScWST_cWXTaaWSXQ
8=C464A VNWP]S[TaNWP]S[TfWXcT
?0A0<4C4A VNWP]S[T,&aNWP]S[T,'
20;; bTcNaVQNR^[^dabNSTUPd[c/
fXScW,!R[TPafX]NX]U^/B2A44=NF83C7"
ST_cW,!R[TPafX]NX]U^/B2A44=N34?C7"
fWXcT,A61/!$$!$$!$$
X,fX]X^/ffRPJ>UUBRaTT] ATVX^]bL
X,fX]X^/\]J4gXcL4G8C
X,fX]X^/[fXRca[
X,fX]X^/OVaJQ[PRZLfXScWST_cWVNWP]S[T
XTaa,RaTPcTNVaP_WXRbNaTVX^]/aNWP]S[TfXScWST_cW
XTaa,bT[TRcNVaP_WXRbN^QYTRc/aNWP]S[T
WSXQ,X\_^acNQ\_/R)KfX]S^fbKbTcd_Q\_XTaa
XTaa,SXQN_PX]c/WSXQ
20;; aT[TPbTNbRaTT]NSXQ/WSXQ
20;; SaPfNRWPaPRcTab/CWXb fPb SaPf] ^UU bRaTT]
fWXcT
XTaa,bT[TRcNVaP_WXRbN^QYTRc/VNWP]S[T
20;; SaPfNRWPaPRcTab/CWXb fPb SaPf] c^ P fX]S^f
fWXcT
X,fX]X^/QcJBW^f >UUBRaTT] 1[^RZL
XTaa,R^_hNVaP_WXRbNaTVX^]/VNWP]S[TfXScWST_cW
aNWP]S[TfXScWST_cWBA22>?H
4=3

151
ClearWin+ User’s Guide Fortran

Graphics icons
It is possible to supply the user with more interesting ways to interact with your
graphics area than merely clicking with the mouse. A %gr drawing surface can have
an icon resource ‘attached’ to it. The icon can be moved freely around the graphics
window with the mouse. Control of the icon is maintained by the call-back function
attached to %gr.
PSSNVaP_WXRbNXR^]/ is used to attach an icon resource (defined in a resource
script) to the current screen drawing surface. A =0<4 argument is used to stipulate
the resource. G and H variables are used as arguments that hold the initial location of
the image. These variables also hold the new position when the image is moved. The
call-back function for %gr can modify the G and H values if required. In this way it is
possible to ‘lock’ the image on to a horizontal or vertical plane by repeatedly setting
either G or H to a constant value.
The F83C7 and 74867C arguments of PSSNVaP_WXRbNXR^]/ should be set to zero
except when the icon image is less than 32x32 pixels. A smaller icon is constructed
by starting at the top-left corner and by filling the remaining unused area with the
‘transparent’ colour. In this case, if you do not specify the correct size of the icon then
the unused area will be detected by the mouse.
R[TPafX]NX]U^/’3A06643N82>=´ returns the handle of the icon that has
moved. This handle is initially obtained as the value returned by
PSSNVaP_WXRbNXR^]/.
When the icon is dropped, R[TPafX]NX]U^/3A>??43N82>= returns the
handle of the associated icon. A graphics icon can be removed with a call to
aT\^eTNVaP_WXRbNXR^]/.
The following program draws a horizontal scale with an icon that can be dragged
across it. The resource script attaches an icon file to the ‘arrow_r’ resource in the
program. The Windows API function ClipCursor is used to provide a clipping
rectangle for the mouse cursor when the left mouse button is held down over the icon.
The Salford intrinsic 2>A4# is used to pass a NULL pointer to ClipCursor.

F8=0?? Va $gaR

8=2;D34 +fX]S^fbX]b-

152
Chapter 15 Graphics

8=C464A Xgh
2><<>= gh
4GC4A=0; bcPacNRQVaNRQ
g,#%
h,$
X,fX]X^/ffJ]^NQ^aSTaLRPJ<^ePQ[T XR^]L
X,fX]X^/ORd2DAB>AN0AA>F
X,fX]X^/MVaJVaThaVQNR^[^dabUd[[N\^dbTNX]_dcL
" VaNRQ
X,fX]X^/bRbcPacNRQ
4=3

8=C464A 5D=2C8>= bcPacNRQ

8=2;D34 +R[TPafX]X]b-
8=C464A XghggVaTT]
2><<>= gh
X,PSSNVaP_WXRbNXR^]/Paa^fNagh !%
VaTT],A61/!$$
20;; SaPfN[X]TNQTcfTT]/$h!$ hVaTT]
3> gg,$!#$$
20;; SaPfN[X]TNQTcfTT]/ggh$gghVaTT]
4=33>
3> gg,$!$$
20;; SaPfN[X]TNQTcfTT]/ggh gghVaTT]
4=33>
bcPacNRQ,
4=3

8=C464A 5D=2C8>= VaNRQ

8=2;D34 +fX]S^fbX]b-
8=C464A \g\h\UghfWghWf]SaR#
2><<>= gh
;>6820; ;FPb3aPV8b3aPV
30C0 FPb3aPV50;B4
20;; VTcN\^dbTNX]U^/\g\h\U
8b3aPV,R[TPafX]NX]U^/Sa^__TSNXR^]=4
85=>CFPb3aPV0=38b3aPVC74=
85\g64g0=3\g;4g 0=3\h64$0=3\h;4&$C74=
Wf]S,R[TPafX]NX]U^/[PcTbcNU^a\PccTSNfX]S^f
20;; VTcNfX]S^fN[^RPcX^]/Wf]SghfW
aR ,g#'
aR!,h&
aR",g!$%
aR#,h($

153
ClearWin+ User’s Guide Fortran

;,2[X_2dab^aaR
FPb3aPV,CAD4
4=385
4=385
85FPb3aPV0=3=>C8b3aPVC74=
;,2[X_2dab^a2>A4#
FPb3aPV,50;B4
4=385
h,$
85g;C#% g,#%
85g6C!#%g,!#%
VaNRQ,
4=3

Windows graphic modes

Between any Windows application and the display hardware there exists a program
called a display driver. For every different make of video card there is a different
display driver that is either from the Windows installation disks or from the video
hardware manufacturer.
From the programmers perspective all drivers should appear the same as all Windows
programs must communicate to the video display hardware via the Windows GDI
interface. Drivers, on the other hand, will differ dramatically from display card to
display card because the structure and types of messages required to control the video
display hardware differ for each card. A video driver therefore insulates the
programmer from the complexities of hardware.
Windows supports several common display mode resolutions:
640 x 480 x 16 or 256 colours
This is the most compatible mode as all Windows compatible PCs are capable of
displaying at this resolution. However, it is very low quality and is now hardly ever
used.
800 x 600 x 16 or 256 colours
This is a popular mode as text is readable and there is a larger display area to work
with.
1024 x 768 x 16 or 256 colours
This normally used with monitors that are more than 14 inches wide. It is by far the
clearest resolution but may suffer from slow updates if the display card is not of the
accelerated type.

154
Chapter 15 Graphics

In 16 colour mode Windows uses a set palette. It holds ‘general’ colours that are of
most use. If the program requires shades or colours that do not exist in the palette,
Windows will attempt to dither that colour. Dithering gives a quick effect that often
matches the desired colour. It is done by placing pixels of different colours next to
each other so that when the user is a suitable distance away from the screen the pixels
will appear to be a third colour.
In 256 colour modes there are 256 unique palette entries. Each palette entry is made
by setting a red, a green and a blue component. In this mode, when a pixel is written,
a value between 0 .. 255 is placed in the display memory. When the display is
refreshed the red, green and blue values are ‘looked up’ and sent to the screen.
There have recently been several new display colour ‘depths’ added as new hardware
has been designed. These high colour modes store the colours directly in the display
memory thus avoiding the need for a palette at all. The two most common colour
depths are 65535 and 16.7 million. These depths allow each pixel to be set to any one
of the possible colours.
If you want to use a wide range of colours whilst avoiding the complexities of
managing a palette, one solution is to restrict the usage of your application to desktops
operating in high colour mode. For this purpose, you can use the function
WXVWNR^[^daN\^ST/ to test if the desktop is set to operate in high colour mode.
A call to R[TPafX]NX]U^/³B2A44=N=D<N2>;>DAB´ will
give the number of colours for the desktop unless this number is
greater than 256 (the value 8192 represents all values greater than
256, i.e. a high colour device). A list of palette functions is given
on page 322. These are documented in the ClearWin+ User’s
Supplement.
If the desktop graphics device is not a high colour device, when
you draw to the screen, the colour that you get will not always be
exactly the colour you specify in the program. This may cause
difficulties if you read a pixel from the screen and try to match the
colour with one that you have used earlier to draw to the screen.
The following program illustrates the problem together with one
method of solution. The program draws a set of ‘traffic lights’.
When the user clicks on any part of the picture, the colour for that
part cycles through the sequence: red, amber, green, black.
F8=0??
8=C464A XfX]X^/
4GC4A=0; UX[[NRQbcPacNRQ
X,fX]X^/ffJ]^NQ^aSTa]^N\Pg\X]Q^gL
X,fX]X^/bhJ"SNST_aTbbTSL
X,fX]X^/MVaJQ[PRZaVQNR^[^dabL !$UX[[NRQ
X,fX]X^/bRbcPacNRQ

155
ClearWin+ User’s Guide Fortran

4=3
R
8=C464A 5D=2C8>= bcPacNRQ
8=2;D34 +R[TPafX]X]b-
8=C464A XfWXcT
20;; bTcN[X]TNfXScW/!
fWXcT,A61/!!!
20;; SaPfNaTRcP]V[T/ ((!#(fWXcT
3> X,$!&$
20;; SaPfNT[[X_bT/$X"!"!fWXcT
4=33>
bcPacNRQ,
4=3
R
8=C464A 5D=2C8>= UX[[NRQ
8=2;D34 +R[TPafX]X]b-
8=C464A ghSUaTSVaTT]Q[PRZP\QTafWXcTR^[^daP
20;; VTcN\^dbTNX]U^/ghS
20;; VTcNaVQNeP[dT/ghR^[^da
aTS, VTcN\PcRWTSNR^[^da/A61/!$$
VaTT],VTcN\PcRWTSNR^[^da/A61/!$$
P\QTa,VTcN\PcRWTSNR^[^da/A61/!$$ %'
fWXcT,VTcN\PcRWTSNR^[^da/A61/!!!
Q[PRZ,

85R^[^da4@Q[PRZC74=
U,aTS
4;B485R^[^da4@aTSC74=
U,P\QTa
4;B485R^[^daT`P\QTaC74=
U,VaTT]
4;B4
U,Q[PRZ
4=385
20;; UX[[NbdaUPRT/ghR^[^daU
UX[[NRQ,
4=3
An alternative solution is to use VTcN]TPaTbcNbRaTT]NR^[^da/ in place of
VTcN\PcRWTSNR^[^da/. The effect is the same but you will probably get a different
amber colour on the screen for the following reasons.
When you draw to a screen drawing surface, ClearWin+ filters the colour through its
logical palette in order to find an optimum match (we are assuming the device is not a
high colour device). When ClearWin+ calls a Windows API drawing function, the
result is then filtered through the system palette. Now suppose we call one of the

156
Chapter 15 Graphics

drawing surface functions (such as UX[[NbdaUPRT/) but instead of using a simple

RGB value, we use the return from VTcN]TPaTbcNbRaTT]NR^[^da/. The effect is
to apply the system palette filtering first and this over-rides the ClearWin+ colour
optimisation.
The automatic ClearWin+ colour filtering described above may have the effect of
slowing the output produced on a drawing surface. You can switch this filtering off by
calling dbTNP__a^gX\PcTNR^[^dab/ . When the filtering is switch off, use
VTcN\PcRWTSNR^[^da/ in order to get the filtered colour for a particular RGB
triplet. This colour is then used in the drawing routines.

Owner draw box format - %dw[options]

The %dw format allows you to access the Windows GDI directly to prepare a bitmap
for display. This is a low level method that has been provided primarily for the
integration of certain existing packages. It does not use ClearWin+ drawing routines
(that is, it does not generate a drawing surface).
The format takes one argument that is a handle to a device context acquired by calling
the ClearWin+ function VTcNQXc\P_NSR/. This handle accesses a bitmap that is
drawn to using standard Windows API functions. It is never necessary to re-paint the
area because the bitmap remains in existence even if the window is obscured.
The device context will continue to exist (together with its associated bitmap) until
released with the ClearWin+ function aT[TPbTNQXc\P_NSR/. At normal program
termination the system will automatically release device contexts acquired by
VTcNQXc\P_NSR/, so it is only necessary to use aT[TPbTNQXc\P_NSR/ in complex
programs that manipulate many graphics bitmaps.
For example:

F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A \hNSR
\hNSR,VTcNQXc\P_NSR/$$
20;; <^eTC^\hNSR
20;; ;X]TC^\hNSR$$
X,fX]X^/Sf QcJ>:L\hNSR
R CWT ]Tgc [X]T Xb ]^c ]TRTbbPah d][Tbb
R \P]h STeXRT R^]cTgcb fX[[ QT PR`dXaTS
20;; aT[TPbTNQXc\P_NSR/\hNSR
4=3

157
ClearWin+ User’s Guide Fortran

Note that you can continue to change the graphics in the bitmap after the window has
been displayed (from call-back functions, or using the %lw format to leave the window
in place) provided that fX]S^fNd_SPcT/732 is used to update the screen, where
732 is the handle of the device context. Other routines that operate in terms of a
handle to a device context are listed on page 319.
When it is created, the bitmap will be filled with the default background window
colour (i.e. it will be invisible unless displayed inside a shaded box). The colour can
be changed with a call to the standard Windows API FillRect function.
It is possible to change the pen associated with a device context acquired by calling the
ClearWin+ function VTcNQXc\P_NSR/ (see page 361), without worrying about
deleting used pens. This is performed by calling the ClearWin+ RWP]VTN_T]/
function (see page 335). The first argument in this function is a device context
acquired by calling VTcNQXc\P_NSR/ followed by three other arguments similar
those supplied to the Windows API CreatePen function.
Currently the option list, if present, may contain:

dbTaNaTbXiT %dw can take the option dbTaNaTbXiT, which allows it to

be re-sized as the pivot item of a window. In this form,
%dw does not take a handle from VTcNQXc\P_NSR/ as an
argument, but two integers specifying the initial width and
depth of the desired owner-draw region. A call-back
function must be supplied in this case. When the call-back
function is called, it can check the R[TPafX]NX]U^/
parameter 6A0?782BNA4B8I8=6 to determine that it is
being called to re-draw the image (the image is deemed to
be re-sized once as it is created, so all the drawing code can
be placed in the call-back).
The call-back function should use R[TPafX]NX]U^/ to
obtain 6A0?782BN32, 6A0?782BNF83C7, and
6A0?782BN34?C7. Traditional Windows programmers
should note that although your function will be called to
re-draw the image each time the size changes, you will not
be called each time a F<N?08=C message is processed. For
example, if the image is obscured and then exposed again
without change, your function will not be called.

Ud[[N\^dbTNX]_dc With this option the %dw call-back function is called each
time the mouse is moved, or a button is pressed or released
within the area of the control. Otherwise the call-back
function only responds to mouse input when the user clicks

158
Chapter 15 Graphics

on the control.

You can use VTcN\^dbTNX]U^/ to obtain mouse data from within a %dw call-back
function.

Updating the screen

By default a call to a graphics function will not produce an instantaneous update of the
screen. Instead ClearWin+ waits until you have finished your current sequence of
graphics calls from within your call-back (i.e. it waits until the application is idle).
This mechanism is suitable for most circumstances. However, a call to the routine
_TaUâ\NVaP_WXRbNd_SPcT/ will cause an immediate update should this be
required.
When your application is in an idle state or a call to _TaUâ\NVaP_WXRbNd_SPcT/
is made, changes to the graphics buffer are copied to the screen. ClearWin+ keeps
track of the smallest rectangle to enclose the changed areas and updates only this
region. As a result, if your program updates information at opposite corners of a large
graphics region (as an extreme example) it may be faster to insert calls to
_TaUâ\NVaP_WXRbNd_SPcT/ so that each small region is updated separately.
If you use %dw, ClearWin+ cannot automatically detect the smallest rectangle to be
updated and so by default it updates the whole of the graphics region whenever a
change is made. A call to the routine bTcNd_SPcTNaTRcP]V[T/g h g!h!
sets the update rectangle making the program run faster. Once used, this routine must
be called whenever the update rectangle changes.

159
ClearWin+ User’s Guide Fortran

160
16.

OpenGL

Introduction
OpenGL provides a relatively simple, platform independent, way to produce complex
(possibly animated) 2 or 3-dimensional images. Lighting and perspective effects are
easily introduced, although in order to achieve high performance, full ray tracing
(which produces shadows and effects caused by multiply scattered light rays) is not
available. The performance of OpenGL is sufficient that it is often used for 3-D
animation. The following two books explain the use of OpenGL without going into
platform-specific details:
OpenGL Programming Guide
OpenGL Reference Manual
See the end of this chapter for further details. OpenGL is available via two DLLs that
may already be installed on your PC.
This chapter does not present a tutorial on OpenGL nor does it describe the OpenGL
API. You are advised read the official “Red Book” learning guide to OpenGL, and to
visit the OpenGL web site at http://www.OpenGL.org
Examples in the Red Book are simplified by the use of a specially designed and
written auxiliary OpenGL library (called GLAUX). GLAUX provides an easy way to
open a window with the OpenGL attributes that you require. However, it is limited in
its use of mouse, keyboard and message handling and has the overwhelming
disadvantage you cannot attach menus or buttons. Also, it only allows one window to
be opened. ClearWin+ is very similar to GLAUX with regard to the ease with which
OpenGL windows can be opened. However, ClearWin+ has none of the above
restrictions. Nevertheless, the Red Book examples provide a convenient tutorial
approach to learning how to call the OpenGL library from ClearWin+. Much of this

161
ClearWin+ User’s Guide Fortran

chapter is devoted to discussing how to convert the Red Book examples that use
GLAUX to ClearWin+.

OpenGL - %og[options]
In order to open an OpenGL window with ClearWin+, you must use the %og format
code:
X,fX]X^^VJbcPcXRL

%og takes an list of options consisting of any valid combination of the following:
S^dQ[T This option is used for animation and causes OpenGL output to
be sent to an in-memory buffer until the
bfP_N^_T]V[NQdUUTab/ subroutine is called. This helps to
reduce flicker at the expense of requiring more memory.
ST_cW % Specifies 16 bits of depth buffering.

ST_cW"! Specifies 32 bits of depth buffering.

bcT]RX[ Stencil buffer. The stencil buffer is used to define masks used to
prevent part of image being drawn. For example, OpenGL only
allows convex polygons to be filled. More complex polygons
require the use of the stencil buffer.
PRRd\ The accumulation buffer is used to accumulate images for effects
such as anti-aliasing motion blur, depth of field etc.
dbTaNaTbXiT Same as %gr usage.

bcPcXR Used to redraw window after it has been partially revealed.

Any combination of these attributes is permitted. Depth buffering is an option that

can be omitted. If both ST_cW % and ST_cW"! are specified, ST_cW"! takes effect.
These attributes, with the exception of bcPcXR, are directly analogous to the GLAUX
equivalent. For example, the GLAUX attribute AUX_ACCUM is the same as the
ClearWin+ attribute ACCUM.
Converting examples written using GLAUX to ClearWin+ is, therefore, relatively
straight forward. Most of the differences arise through language choice rather than by
the use of ClearWin+. A Fortran program will inevitably have a slightly different
structure from a C program.

162
Chapter 16 OpenGL

The conversion of a Red Book example

The example in listing 1.2 of the Red Book, simple.c is reproduced below. Each line
in the source is numbered to aid description.
bX\_[TR
!
" X]R[dST +6;V[W-
# X]R[dST +6;V[PdgW-
$ X]R[dST +bcS[XQW-
%
&
' X]c \PX]X]c PaVR RWPa PaVe
( j
Pdg8]Xc3Xb_[Ph<^ST 0DGNB8=6;4 k 0DGNA61*
Pdg8]Xc?^bXcX^] $ $*
! Pdg8]XcFX]S^f BX\_[T >_T]V6; BP\_[T*
"
# V[2[TPa2^[^a *
$ V[2[TPa6;N2>;>AN1D554AN18C*
% V[2^[^a"U *
& V[<PcaXg<^ST 6;N?A>942C8>=*
' V[;^PS8ST]cXch *
( V[>acW^ *
! V[1TVX]6;N?>;H6>=*
! V[ETacTg!U$ $*
!! V[ETacTg!U$ $*
!" V[ETacTg!U$ $*
!# V[ETacTg!U$ $*
!$ V[4]S*
!% V[5[dbW*
!& Nb[TT_ *
!' aTcda]*
!( l
When converting to Fortran, lines 1 to 9 may be ignored. Lines 10 to 12 describe the
window properties to GLAUX. These properties are:
AUX_SINGLE single buffered. This is ClearWin+ default and is not necessary in
the ClearWin+ version.
AUX_RGB use RGB colours. ClearWin+ only supports RGB colours for
OpenGL. Colour index modes are unsuitable for shading and anti-aliasing and so
are not supported.
0, 0 initial window position. This is specified using %sp in ClearWin+.

163
ClearWin+ User’s Guide Fortran

500, 500 initial window size. This is specified using %og in ClearWin+.
"Simple OpenGL Sample" window caption.
In addition, GLAUX windows may be closed using the Escape key. Specify this with
%es using ClearWin+.
ClearWin+ uses %lw to allow a window to stay open when the fX]X^/ call returns.
If %lw were not specified, the drawing commands following would have no effect.
Lines 10 to 12 are replaced with the following calls to fX]X^/. The ampersands at
the end of every line are used to combine several fX]X^/ calls into one format
window.
R0[[^fb cWT dbTa c^ R[^bT cWT fX]S^f fXcW cWT +TbR- ZTh
X,fX]X^/Tb
RFX]S^f RP_cX^]
X,fX]X^/RPJBX\_[T >_T]V6; BP\_[TL
RBTcb X]XcXP[ fX]S^f _^bXcX^] c^
X,fX]X^/b_
R<PZTb cWT bP\T bch[T Û fX]S^f Pb 6;0DG
X,fX]X^/ffJ]^NQâSTaL
R2aTPcTb cWT >_T]6; fX]S^f P]S aTcda]b [TPeX]V Xc ^_T]
X,fX]X^/^VJbcPcXRL[f$ $Rca[
This may all be combined into:
X,fX]X^/TbRPJBX\_[T >_T]V6; BP\_[TL
X,fX]X^/b_ffJ]^NQâSTaL^VJbcPcXRL[f
$$Rca[
The use of line 28 with the Red Book example is to keep the window open for 10
seconds before closing it. This is unnecessary since the ClearWin+ window will stay
open anyway until the user closes it. Note that the integer variable, Rca[ is required
since we have used %lw but that the variable itself is unused.
The Fortran include files clearwin.ins and opengl.ins must be included at the top of
the main program.
The remainder of the program is virtually unchanged. The full ClearWin+ version
appears below.
?A>6A0< BX\_[T
8=2;D34 +R[TPafX]X]b-]^[Xbc
8=2;D34 +^_T]V[X]b-]^[Xbc
A40; c c!
8=C464A X Rca[
X,fX]X^/TbRPJBX\_[T >_T]V6; BP\_[TL
X,fX]X^/b_ffJ]^NQâSTaL^VJbcPcXRL[f

164
Chapter 16 OpenGL

$ $ Rca[

20;; V[2[TPa2^[^a
20;; V[2[TPa6;N2>;>AN1D554AN18C
20;; V[2^[^a"U
20;; V[<PcaXg<^ST6;N?A>942C8>=
20;; V[;^PS8ST]cXch
20;; V[>acW^ S S S S S S
20;; V[1TVX]6;N?>;H6>=
20;; V[ETacTg!U$ $
20;; V[ETacTg!U$ $
20;; V[ETacTg!U $ $
20;; V[ETacTg!U $ $
20;; V[4]S
20;; V[5[dbW
4=3
As can be seen, the OpenGL calls and their positions are unchanged. A couple of
calls to fX]X^/ have replaced the calls to GLAUX. Overall, the two programs are
very similar. This will be reinforced but qualified when we look at other examples.

Argument types
Some OpenGL functions take single precision arguments, others double precision. In
many cases it is possible to determine the argument type from the variant of the name.
For example, glColor3f requires single precision arguments whereas, glColor3d
requires double precision arguments.
With other OpenGL functions, the name does not help. For example, glAccum and
glClearColor require single precision arguments whereas, glOrtho takes double
precision arguments.
Unlike OpenGL functions, all GLAUX functions that take floating-point arguments
require the arguments to be double precision.
You should carefully check the types of the arguments to any function before using it.
You must specify a double precision constant by using a ‘D’ exponent. Any constants
for which you use neither ‘D’ nor DBLE( ) will be regarded as single precision and
will yield unexpected results.
When linking, you are recommended to link directly with the import libraries rather
than the DLLs. Using the import library will cause mismatched arguments to result in
a link failure and enable you to quickly correct any errors.

165
ClearWin+ User’s Guide Fortran

Call-backs and initialisation

This next sample program is considerably more advanced. It uses double.c and
Listing 1.3 from the Red Book. It illustrates the use of the mouse and various call-
back functions. We will convert it to ClearWin+.
X]R[dST V[^bW
!
" X]R[dST +6;V[W-
# X]R[dST +6;V[dW-
$ X]R[dST +6;V[PdgW-
%
&e^XS \hX]Xce^XS*
'e^XS 20;;102: b_X]3Xb_[Ph e^XS*
(e^XS 20;;102: bcPac8S[T5d]R 0DGN4E4=CA42 TeT]c*
e^XS 20;;102: bc^_8S[T5d]R 0DGN4E4=CA42 TeT]c*
e^XS 20;;102: \hATbWP_T6;bXiTX f 6;bXiTX W*
! e^XS 20;;102: SXb_[Phe^XS*
"
# bcPcXR 6;U[^Pc b_X] , *
$
% e^XS 20;;102: SXb_[Phe^XS
& j
' V[2[TPa 6;N2>;>AN1D554AN18C*
(
! V[?dbW<PcaXg *
! V[A^cPcTU b_X] *
!! V[ATRcU !$ !$ !$ !$*
!" V[?^_<PcaXg *
!#
!$ V[5[dbW*
!% PdgBfP_1dUUTab*
!& l
!'
!( e^XS 20;;102: b_X]3Xb_[Ph e^XS
" j
" b_X] , b_X] !*
"! XU b_X] - "%
"" b_X] , b_X] "%*
"# SXb_[Ph*
"$ l
"%
"& e^XS 20;;102: bcPac8S[T5d]R 0DGN4E4=CA42 TeT]c
"' j
"( Pdg8S[T5d]Rb_X]3Xb_[Ph*

166
Chapter 16 OpenGL

# l
#
#! e^XS 20;;102: bc^_8S[T5d]R 0DGN4E4=CA42 TeT]c
#" j
## Pdg8S[T5d]R*
#$ l
#%
#& e^XS \hX]Xc e^XS
#' j
#( V[2[TPa2^[â *
$ V[2^[â"U *
$ V[BWPST<^ST[ 6;N5;0C*
$! l
$"
$# e^XS 20;;102: \hATbWP_T6;bXiTX f 6;bXiTX W
$$ j
$% XU W aTcda]*
$& V[EXTf_âc f W*
$' V[<PcaXg<^ST6;N?A>942C8>=*
$( V[;^PS8ST]cXch*
$ XU f +, W
% V[>acW^ $ $ $6;U[^PcW6;U[^Pcf
%! $6;U[^PcW6;U[^Pcf *
%" T[bT
%# V[>acW^ $6;U[^Pcf6;U[^PcW
%$ $6;U[^Pcf6;U[^PcW $ $ *
%% V[<PcaXg<^ST6;N<>34;E84F*
%& V[;^PS8ST]cXch *
%' l
%(
% <PX] ;^^_
& >_T] fX]S^f fXcW X]XcXP[ fX]S^f bXiT cXc[T QPa
&! A610 SXb_[Ph \^ST P]S WP]S[T X]_dc TeT]cb
&"
&# X]c \PX]X]c PaVR RWPa PaVe
&$ j
&% Pdg8]Xc3Xb_[Ph<^ST 0DGN3>D1;4 k 0DGNA61*
&& Pdg8]Xc?^bXcX^] $ $*
&' Pdg8]XcFX]S^f 3^dQ[T 1dUUTaX]V*
&( \hX]Xc *
& PdgATbWP_T5d]R \hATbWP_T*
' Pdg8S[T5d]R b_X]3Xb_[Ph*
'! Pdg<^dbT5d]R 0DGN;45C1DCC>= 0DGN<>DB43>F= bcPac8S[T5d]R*
'" Pdg<^dbT5d]R 0DGNA867C1DCC>= 0DGN<>DB43>F= bc^_8S[T5d]R*

167
ClearWin+ User’s Guide Fortran

'# Pdg<PX];^^_SXb_[Ph*
'$ aTcda]*
'% l
The converted program double.for is presented below. Note the use of common blocks
rather than C global variables.
Lines 76 to 78 in the Red Book sample have been replaced by a few ClearWin+ calls
at lines 109 to 111. %og has been replaced by %^og indicating that a call-back
function, ^_T]V[N_a^R, has been provided to handle messages. The use of %pv
means that A4B8I4 messages are sent to the call-back.
Mouse messages are also sent to ^_T]V[N_a^R, as are the special B4CD? and 38ACH
messages. B4CD? is sent only once, just after the window has been created and its
arrival precedes that of A4B8I4. 38ACH is sent when the window needs repainting,
for example, after A4B8I4 or when the window is brought to the top after being
partially obscured. If you take action on the 38ACH call-back, you will not need the
bcPcXR option on %og.
The Red Book variant of the program supplies several functions to handle events.
These functions are still needed and perform the same task, but they are called directly
in response to ClearWin+ messages sent to ^_T]V[N_a^R. The reshape function
\hATbWP_Tgh is called in response to A4B8I4. SXb_[Ph is called in response to
38ACH. The mouse handling functions startIdleFunc and stopIdleFunc are called in
response to <>DB4N;45CN2;82: and <>DB4NA867CN2;82:. These are registered as
call-backs with GLAUX at lines 70 and 82-83.
In the Red Book example, the initialising call to \hX]Xc at line 79 (just after the
window has been created) is handled by ClearWin+ as a message sent to
^_T]V[N_a^R. This message is B4CD? and is always sent before the first A4B8I4
message. The GLAUX idle function has no direct ClearWin+ equivalent. Instead,
%lw is used in the fX]X^/ call and program execution falls through into the
following idle loop. The test for Rca[+ at line 113 in the ClearWin+ example,
allows the program to detect when the window has been closed so that program
termination can proceed.
BD1A>DC8=4 SXb_[Ph
! 8=2;D34 +^_T]V[X]b-]^[Xbc
" A40; b_X]
# ;>6820; S^NSaPf
$ 2><<>= S^dQ[TNR^\S^NSaPfb_X]
%
& 20;; V[2[TPa6;N2>;>AN1D554AN18C
'
( 20;; V[?dbW<PcaXg

168
Chapter 16 OpenGL

20;; V[A^cPcTUb_X]

20;; V[ATRcU!$ !$ !$ !$
! 20;; V[?^_<PcaXg
"
# 20;; V[5[dbW
$ 20;; bfP_N^_T]V[NQdUUTab
% 4=3
&
' BD1A>DC8=4 b_X]3Xb_[Ph
( 8=2;D34 +R[TPafX]X]b-]^[Xbc
! A40; b_X]
! ;>6820; S^NSaPf
!! 2><<>= 3>D1;4N2><S^NSaPfb_X]
!"
!# 85S^NSaPfC74=
!$ b_X] , b_X] !
!% 85b_X]6C"%C74=
!& b_X] , b_X] "%
!' 4=385
!( 20;; SXb_[Ph
" 4=385
" 20;; cT\_âPahNhXT[S/
"! 4=3
""
"# BD1A>DC8=4 bcPac8S[T5d]R
"$ A40; b_X]
"% ;>6820; S^NSaPf
"& 2><<>= 3>D1;4N2><S^NSaPfb_X]
"' S^NSaPf,CAD4
"( 4=3
#
# BD1A>DC8=4 bc^_8S[T5d]R
#! A40; b_X]
#" ;>6820; S^NSaPf
## 2><<>= S^dQ[TNR^\S^NSaPfb_X]
#$ S^NSaPf,50;B4
#% 4=3
#&
#' BD1A>DC8=4 \hX]Xc
#( 8=2;D34 +^_T]V[X]b-]^[Xbc
$ 20;; V[2[TPa2^[â
$ 20;; V[2^[â"U
$! 20;; V[BWPST<^ST[ 6;N5;0C
$" 4=3

169
ClearWin+ User’s Guide Fortran

$#
$$ BD1A>DC8=4 \hATbWP_Tf W
$% 8=2;D34 +^_T]V[X]b-]^[Xbc
$& 8=C464A fW
$' 3>D1;4 ?A428B8>= Pb_TRcNaPcX^
$( 85W=4 C74=
% Pb_TRcNaPcX^,A40;fW
%
%! 20;; V[EXTf_^ac f W
%" 20;; V[<PcaXg<^ST6;N?A>942C8>=
%# 20;; V[;^PS8ST]cXch
%$ 85 f;4W C74=
%% 20;; V[>acW^$S $S $SPb_TRcNaPcX^
%& $SPb_TRcNaPcX^ S S
%' 4;B4
%( 20;; V[>acW^$SPb_TRcNaPcX^
& $SPb_TRcNaPcX^ $S $S S S
& 4=385
&! 20;; V[<PcaXg<^ST6;N<>34;E84F
&" 20;; V[;^PS8ST]cXch
&# 20;; SXb_[Ph
&$ 4=385
&% 4=3
&&
&'
&( 8=C464A 5D=2C8>= ^_T]V[N_a^R
' 8=2;D34 +R[TPafX]X]b-]^[Xbc
' 270A02C4A!$% aTPb^]
'! 8=C464A fW
'" A40B>=,R[TPafX]NbcaX]V/20;;102:NA40B>=
'# 85aTPb^]4@B4CD?C74=
'$ 20;; \hX]Xc
'% 4;B4 85aTPb^]4@A4B8I4C74=
'& f,R[TPafX]NX]U^/>?4=6;NF83C7
'' W,R[TPafX]NX]U^/>?4=6;N34?C7
'( 20;; \hATbWP_TfW
( 4;B4 85aTPb^]4@<>DB4N;45CN2;82:C74=
( 20;; bcPac8S[T5d]R
(! 4;B4 85aTPb^]4@<>DB4NA867CN2;82:C74=
(" 20;; bc^_8S[T5d]R
(# 4=3 85
($
(% ^_T]V[N_a^R,!
(& 4=3

170
Chapter 16 OpenGL

('
(( ?A>6A0< S^dQ[T
8=2;D34 +R[TPafX]X]b-]^[Xbc
8=C464A X
! 8=C464A ^_T]V[N_a^RRca[
" 4GC4A=0; ^_T]V[N_a^R
# A40; b_X]
$ ;>6820; S^NSaPf
% 2><<>= S^dQ[TNR^\S^NSaPfb_X]
& 30C0 b_X]S^NSaPfCAD4
'
( X,fX]X^/TbRPJ3^dQ[T 1dUUTaX]VL
X,fX]X^/b_ffJ]^NQ^aSTaL_eM^VJS^dQ[TL[f
$$^_T]V[N_a^RRca[
!
" F78;4Rca[;C3>
# 20;; b_X]3Xb_[Ph
$ 4=3F78;4
% 4=3
This program follows the structure that will be used throughout this chapter, and your
attention is drawn again to the use of ^_T]V[N_a^R to call the reshape, display,
initialisation and mouse handling functions.

Animation and multiple windows

OpenGL achieves animation by using two buffers, the front and the back buffer.
When this, so called, double buffering is enabled, drawing (or rendering in OpenGL
terminology) is directed to the back buffer. When the image is complete, you transfer
it to the front buffer, or display, by calling bfP_N^_T]V[NQdUUTab/. This
ClearWin+ routine merely remembers the current OpenGL context and so saves the
programmer effort. When the back buffer is transferred to the display, it is supposed
to be no longer valid so two successive swap buffer calls should produce garbage on
the display. Although this does not seem to happen under Win32, the retention of the
buffer should not be relied upon, as it might not be retained on other platforms.
The program below is not a Red Book sample. It illustrates the use of multiple
windows, independently animated. This is something not possible using GLAUX.
The use of multiple OpenGL windows requires that you know the device context and
rendering context for each of the windows. Changing from one window to another
requires that you swap both the device context and the rendering context. Therefore,
you must “enquire” them and store them away. These enquiry and swapping functions
(together with some functions) are known as the WGL set. They do not form part of
OpenGL, but are essential to the Windows implementation of it. Documentation for

171
ClearWin+ User’s Guide Fortran

these functions will be found in the Microsoft Developer Network help files. You can
be sure that when ^_T]V[N_a^R is called, the expected device and rendering contexts
are current.
The font is also set by means of a WGL call, wglUseFontOutlines. Note how, in the
the program, a C type NULL pointer is simulated by 2>A4# This function call
will only be successful if the format code %fn is used in the definition of the parent
window.

0]X\PcX^] dbX]V >_T]6;

BD1A>DC8=4 SXb_[Ph
8=2;D34 +^_T]V[X]b-]^[Xbc
8=2;D34 +R[TPafX]X]b-]^[Xbc
8=2;D34 SP]X\PcTX]b

20;; V[2[TPa >A6;N2>;>AN1D554AN18C6;N34?C7N1D554AN18C

20;; V[<PcaXg<^ST 6;N<>34;E84F
20;; V[;^PS8ST]cXch
20;; V[CaP]b[PcTSSS S
20;; V[A^cPcTSb_X] SSS
20;; V[2P[[;Xbc
20;; bfP_N^_T]V[NQdUUTab
20;; V[5[dbW
4=3

BD1A>DC8=4 bfP_2^]cTgcbfX]S^f
8=C464A fX]S^f
8=2;D34 +^_T]V[X]b-
8=2;D34 SP]X\PcTX]b
20;; fV[<PZT2daaT]cSTeXRTR^]cTgcfX]S^f
aT]STaX]VR^]cTgcfX]S^f
4=3

BD1A>DC8=4 b_X]B[PQfX]S^f
8=C464A fX]S^f
8=2;D34 SP]X\PcTX]b
S^NSaPffX]S^f,CAD4
4=3

BD1A>DC8=4 bc^_B[PQfX]S^f

172
Chapter 16 OpenGL

8=C464A fX]S^f
8=2;D34 SP]X\PcTX]b
S^NSaPffX]S^f,50;B4
4=3

BD1A>DC8=4 PbbT\Q[TN[Xbc
8=2;D34 +R[TPafX]X]b-]^[Xbc
8=2;D34 +^_T]V[X]b-]^[Xbc

A40;# fWXcTNR^[^da#VaThNR^[^da#SPaZNVaThNR^[^da#
A40;# aTSNR^[^da# hT[[^fNR^[^da# VaTT]NR^[^da#
A40;# Q[dTNR^[^da# _da_[TNR^[^da# RhP]NR^[^da#
A40;' SX\T]bX^]bRP[TSUSUa^]cQPRZ
8=C464A U[PVbZ
8=C464A WSR
;>6820; ^Z
30C0 fWXcTNR^[^da
30C0 VaThNR^[^da$$$
30C0 SPaZNVaThNR^[^da"""
30C0 aTSNR^[^da
30C0 hT[[^fNR^[^da
30C0 VaTT]NR^[^da
30C0 Q[dTNR^[^da
30C0 _da_[TNR^[^da
30C0 RhP]NR^[^da
30C0 Ua^]cQPRZ S$S

20;; V[4]PQ[T6;N34?C7NC4BC
W32,R[TPafX]NX]U^/>?4=6;N34E824N2>=C4GC
20;; V[2^[^a"U

^Z,fV[DbT5^]c>dc[X]TbW32 !$$

F6;N5>=CN?>;H6>=BR^aT#

20;; V[<PcaXg<^ST 6;N<>34;E84F

20;; V[;^PS8ST]cXch
20;; V[CaP]b[PcTSSS S

R2[TPa cWT R^[^a P]S ST_cW QdUUTab

20;; V[2[TPa >A6;N2>;>AN1D554AN18C6;N34?C7N1D554AN18C

SX\T]bX^],!!S
bRP[T,SX\T]bX^](S
20;; V[3XbPQ[T6;N;867C8=6

173
ClearWin+ User’s Guide Fortran

20;; V[=Tf;Xbc 6;N2><?8;4

R5a^]c UPRT
20;; V[1TVX]6;N?>;H6>=
20;; V[2^[â"UeQ[dTNR^[^da
20;; V[ETacTg"SSX\T]bX^]SX\T]bX^]Ua^]c
20;; V[ETacTg"SSX\T]bX^] SX\T]bX^]Ua^]c
20;; V[ETacTg"S SX\T]bX^] SX\T]bX^]Ua^]c
20;; V[ETacTg"S SX\T]bX^]SX\T]bX^]Ua^]c
20;; V[4]S
R1PRZ UPRT
20;; V[1TVX]6;N?>;H6>=
20;; V[2^[â"UehT[[^fNR^[^da
20;; V[ETacTg"SSX\T]bX^]SX\T]bX^]QPRZ
20;; V[ETacTg"S SX\T]bX^]SX\T]bX^]QPRZ
20;; V[ETacTg"S SX\T]bX^] SX\T]bX^]QPRZ
20;; V[ETacTg"SSX\T]bX^] SX\T]bX^]QPRZ
20;; V[4]S
RC^_ UPRT
20;; V[1TVX]6;N?>;H6>=
20;; V[2^[â"UeaTSNR^[^da
20;; V[ETacTg"SSX\T]bX^] SX\T]bX^]Ua^]c
20;; V[ETacTg"SSX\T]bX^] SX\T]bX^]QPRZ
20;; V[ETacTg"S SX\T]bX^] SX\T]bX^]QPRZ
20;; V[ETacTg"S SX\T]bX^] SX\T]bX^]Ua^]c
20;; V[4]S
R1^cc^\ UPRT
20;; V[1TVX]6;N?>;H6>=
20;; V[2^[â"UeVaTT]NR^[^da
20;; V[ETacTg"S SX\T]bX^]SX\T]bX^]Ua^]c
20;; V[ETacTg"S SX\T]bX^]SX\T]bX^]QPRZ
20;; V[ETacTg"SSX\T]bX^]SX\T]bX^]QPRZ
20;; V[ETacTg"SSX\T]bX^]SX\T]bX^]Ua^]c
20;; V[4]S

R3aPf VaP_W

20;; V[1TVX]6;N;8=4B
20;; V[2^[^a"UefWXcTNR^[^da
20;; V[ETacTg!SbRP[TS
20;; V[ETacTg!SbRP[TS
20;; V[ETacTg!SSbRP[T
20;; V[ETacTg!SSbRP[T
Z,

174
Chapter 16 OpenGL

F78;4Z ;4 3>

20;; V[ETacTg!SbRP[T ZS
20;; V[ETacTg!SbRP[T Z S
20;; V[ETacTg!SSbRP[T Z
20;; V[ETacTg!S SbRP[T Z
Z,Z
4=3F78;4
20;; V[4]S
20;; V[2^[â"UeaTSNR^[^da
20;; V[1TVX]6;N;8=4NBCA8?
S, S
F78;4S ;C S3>
US,$S ""S !S
20;; V[ETacTg!SSbRP[T USbRP[T
S,S$S
4=3F78;4
20;; V[4]S
20;; V[2^[â"UeVaTT]NR^[^da
20;; V[1TVX]6;N;8=4NBCA8?
S, S
F78;4S ;C 3>
US,$S "%S !S
20;; V[ETacTg!SSbRP[T USbRP[T
S,S$S
4=3F78;4
20;; V[4]S
20;; V[2^[â"UeaTSNR^[^da
20;; V[;Xbc1PbT
20;; V[CaP]b[PcTS $SbRP[T($S
20;; V[BRP[TS!S!S!S
20;; V[2P[[;Xbcb$ 6;ND=B86=43N1HC4
20;; V[4]S;Xbc
4=3

BD1A>DC8=4 \hX]Xc
20;; PbbT\Q[TN[Xbc
4=3

BD1A>DC8=4 \haTbWP_TfW
8=2;D34 +^_T]V[X]b-]^[Xbc
8=C464A f
8=C464A W
3>D1;4 ?A428B8>= Pb_TRcNaPcX^

175
ClearWin+ User’s Guide Fortran

85W=4C74=
Pb_TRcNaPcX^,SQ[TfW
20;; V[<PcaXg<^ST6;N?A>942C8>=
20;; V[;^PS8ST]cXch
20;; V[d?Tab_TRcXeT"SPb_TRcNaPcX^ S $S
20;; V[EXTf_^acfW
4=385

4=3

8=C464A 5D=2C8>= ^_T]V[N_a^R

8=2;D34 +R[TPafX]X]b-]^[Xbc
8=2;D34 +^_T]V[X]b-]^[Xbc
8=2;D34 SP]X\PcTX]b]^[Xbc
8=C464A fW
270A02C4A!$% aTPb^]
aTPb^],R[TPafX]NbcaX]V/20;;102:NA40B>=

85aTPb^]4@B4CD?C74=
20;; \hX]Xc
4;B485aTPb^]4@A4B8I4C74=
f,R[TPafX]NX]U^/>?4=6;NF83C7
W,R[TPafX]NX]U^/>?4=6;N34?C7
20;; \haTbWP_TfW
4;B485aTPb^]4@38ACHC74=
20;; SXb_[Ph
fX]S^f NPRcXeT,cadT
4;B48UaTPb^]4@<>DB4N;45CN2;82:C74=
20;; b_X]B[PQ
4;B485aTPb^]4@<>DB4NA867CN2;82:C74=
20;; bc^_B[PQ
4=385

^_T]V[N_a^R ,!
4=3

8=C464A 5D=2C8>= ^_T]V[N_a^R!

8=2;D34 +R[TPafX]X]b-]^[Xbc
8=2;D34 +^_T]V[X]b-]^[Xbc
8=2;D34 SP]X\PcTX]b
8=C464A fW
270A02C4A!$% aTPb^]
aTPb^],R[TPafX]NbcaX]V/20;;102:NA40B>=

176
Chapter 16 OpenGL

85aTPb^]4@B4CD?C74=
20;; \hX]Xc
4;B485aTPb^]4@A4B8I4C74=
f,R[TPafX]NX]U^/>?4=6;NF83C7
W,R[TPafX]NX]U^/>?4=6;N34?C7
20;; \haTbWP_TfW
4;B485aTPb^]4@38ACHC74=
20;; SXb_[Ph
fX]S^f!NPRcXeT,cadT
4;B485aTPb^]4@<>DB4N;45CN2;82:C74=
20;; b_X]B[PQ!
4;B485aTPb^]4@<>DB4NA867CN2;82:C74=
20;; bc^_B[PQ!
4=385
20;; cT\_^aPahNhXT[S/
^_T]V[N_a^R!,!
4=3

?A>6A0< 0]X\PcT
8=2;D34 +^_T]V[X]b-]^[Xbc
8=2;D34 +R[TPafX]X]b-]^[Xbc
3>D1;4 ?A428B8>= b_X]NPaaPh!
8=C464A XfX]S^f fX]S^f!
8=C464A ^_T]V[N_a^R ^_T]V[N_a^R!
4GC4A=0; ^_T]V[N_a^R ^_T]V[N_a^R!
8=2;D34 SP]X\PcTX]b

S^NSaPf ,cadT
S^NSaPf!,cadT
STeXRTR^]cTgc ,
STeXRTR^]cTgc!,
aT]STaX]VR^]cTgc ,
aT]STaX]VR^]cTgc!,
b_X],S
b_X]NPaaPh ,S
b_X]NPaaPh!,S
fX]S^f NPRcXeT,UP[bT
fX]S^f!NPRcXeT,UP[bT

R2aTPcT P R^d_[T ^U >_T]6; FX]S^fb

RFX]S^f
X,fX]X^/TbRPJA^cPcX]V B[PQL
X,fX]X^/U]JCX\Tb =Tf A^\P]Lcb"S
X,fX]X^/b_ffJ]^NQ^aSTaL_eM^VJS^dQ[TST_cW %L[f

177
ClearWin+ User’s Guide Fortran

"$"$^_T]V[N_a^R fX]S^f

R6Tc P]S bPeT W32 P]S cWT AT]STaX]V 2^]cTgcb

STeXRTR^]cTgc ,fV[6Tc2daaT]c32
aT]STaX]VR^]cTgc ,fV[6Tc2daaT]c2^]cTgc

R2aTPcT P R^d_[T ^U >_T]6; FX]S^fb

RFX]S^f !
X,fX]X^/TbRPJA^cPcX]V B[PQL
X,fX]X^/U]JCX\Tb =Tf A^\P]Lcb"S
X,fX]X^/b_ffJ]^NQ^aSTaL_eM^VJS^dQ[TST_cW %L[f
#"$"$^_T]V[N_a^R!fX]S^f!

R6Tc P]S bPeT W32 P]S cWT AT]STaX]V 2^]cTgcb

STeXRTR^]cTgc!,fV[6Tc2daaT]c32
aT]STaX]VR^]cTgc!,fV[6Tc2daaT]c2^]cTgc

S^NSaPf ,cadT
S^NSaPf!,cadT

F78;4fX]S^f ;C >A fX]S^f!;C3>

85fX]S^f ;CC74=
85S^NSaPf C74=
b_X]NPaaPh ,b_X]NPaaPh !S
b_X],b_X]NPaaPh
20;; bfP_2^]cTgcb
20;; SXb_[Ph
4=385
4=385
85fX]S^f!;CC74=
85S^NSaPf!C74=
b_X]NPaaPh!,b_X]NPaaPh!!S
b_X],b_X]NPaaPh!
20;; bfP_2^]cTgcb!
20;; SXb_[Ph
4=385
4=385
20;; cT\_^aPahNhXT[S/
4=3F78;4
4=3

178
Chapter 16 OpenGL

Using a printer with OpenGL

When using OpenGL, the quality of the printer output and the rendering of colour are
especially important and it is recommended that you check your printer driver
settings, ensuring (for example) that you are using the highest setting for the number
of dots per inch.
The following functions are provided to enable you to print OpenGL images.

Function See page

>?4=N6;N?A8=C4A/ 381

>?4=N6;N?A8=C4A / 381

?A8=CN>?4=6;N8<064/ 389

References
• Woo, Mason, Jackie Neider, and Tom Davis. OpenGL Programming Guide: The
Official Guide to Learning OpenGL, Version 1.1.Reading, MA: Addison Wesley
Longman Inc. 1997. ISBN 0-201-46138-2.
• OpenGL Architecture Review Board; Renate Kempf and Chris Frazier, editors.
OpenGL Reference Manual. The Official Reference Document for OpenGL,
Version 1.1. Reading, MA: Addison Wesley Longman Inc. 1996. ISBN 0-201-
46140-4.
• Fosner, Ron. OpenGL Programming for Windows95 and Windows NT. Reading,
MA: Addison Wesley Longman Inc. 1996.
• Wright Jr., Richard S. and Michael Sweet. OpenGL Superbible: The Complete
Guide to OpenGL Programming for Windows NT and Windows 95. Waite Group
Press. 1996.
• Angel, Edward. Interactive Computer Graphics: A top-down approach with
OpenGL. Reading, MA: Addison Wesley Longman Inc. 1997. ISBN 0-201-
85571-2.

Online information
The reference pages for OpenGL are available at:
http://www.opengl.org/
http://www.sgi.com/software/opengl/

179
ClearWin+ User’s Guide Fortran

http://www.digital.com/pub/opengl/
http://msdn.microsoft.com/
The OpenGL World Wide Web Centre contains links to a variety of articles, the
OpenGL specification, and the OpenGL usenet mailing list.
Other items are available to members of the Microsoft Developer Network. Online
versions of technical articles are also available on the Microsoft Developer homepage.

180
17.

SIMPLEPLOT

Introduction
SIMPLEPLOT is a library of Fortran subroutines designed and marketed by BUSS
Ltd.1 to produce pictures of data with speed and accuracy. The basic SIMPLEPLOT
library offers a wide range of facilities for drawing Cartesian and polar graphs.
Extensions are available for contouring and surface pictures, presentation graphics for
high quality output and representations of 4D data.
ClearWin+ provides access to SIMPLEPLOT via a dynamic link library (simple.dll)
that is distributed with Salford compilers. Access to this library is available by using
the fX]X^/ function together with the %pl format code. %pl is designed to be similar
to %gr.
In this chapter we shall look at three elementary programs that illustrate the essential
features of the interface between ClearWin+ and SIMPLEPLOT. The first two
examples illustrate an automatic mode of access. This is by far the easiest way to
access the SIMPLEPLOT library from ClearWin+. The final example shows you how
to make direct calls to the SIMPLEPLOT library. Further information about
SIMPLEPLOT can be found in the documentation provided by BUSS Ltd.

1 Bradford University Software Services: Web site http://www.buss.co.uk/buss/

181
ClearWin+ User’s Guide Fortran

A simple example
In our first example we create a window and draw a quadratic curve within it.
RBX\_[T U^a
F8=0??
8=C464A =fX]X^/X
?0A0<4C4A=,
A40;' g=h=
R2aTPcT cWT SPcP c^ QT _[^ccTS
3> X, =
gX,X
hX,gX!
4=33>
R?[^c cWT SPcP
X,fX]X^/RPJB8<?;4?;>C@dPSaPcXRLQVJVaThL
X,fX]X^/_[JgNPaaPhL#!$=gh
X,fX]X^/UU][R]ccJ>:L
4=3

182
Chapter 17 SIMPLEPLOT

%pl is like %gr and takes the basic form:

fX]X^/_[J^_cX^]bL´fXScWWTXVWc
width and height represent the pixel dimensions of a SIMPLEPLOT graphics region
within the window. Some of the options take additional arguments. In this example,
the option called x_array takes three arguments namely the number of points N
followed by an array of x co-ordinates and an array of y co-ordinates.
Following the usual ClearWin+ convention, all real data is passed as DOUBLE
PRECISION values. However, SIMPLEPLOT uses single precision, so data values
should not exceed the single precision range.

%pl options
The following options are available for use with %pl in automatic mode:
Option Description
SCALE=LINEAR Specifies a Cartesian plot with linear x and y data. This
is the default.
SCALE=LOG_LINEAR Specifies a Cartesian plot with linear x and log y data.
SCALE=LINEAR_LOG Specifies a Cartesian plot with log x and linear y data.
SCALE=LOG_LOG Specifies a Cartesian plot with log x and log y data.
N_GRAPHS=<n> Specifies the number of graphs to be drawn on the same
axes (the default is N_GRAPHS=1)
X_AXIS=<text> Specifies text for x-axis label (the default is X_AXIS=X)
Y_AXIS=<text> Specifies text for y-axis label (the default is Y_AXIS=Y)
TITLE=<text> Specifies the title for graph (by default there is no title).
X_ARRAY Specifies that an array of x values is supplied. If this
option is not specified then the first x value together with
a constant increment must be supplied.
Y_MIN=<value> Specifies the minimum y value. By default this is
computed from the data.
Y_MAX=<value> Specifies the maximum Y value. By default this is
computed from the data.
COLOUR=<name> Specifies the colour of the plot (red, black, blue, etc.).
The first use of COLOUR refers to the first plot, the
second to the second plot and so on.

183
ClearWin+ User’s Guide Fortran

COLOR=<name> The same as COLOUR.

STYLE=<n> STYLE=0 gives a smooth plot. With STYLE=1, points
are plotted using small squares and the relevant colour.
The first use of STYLE refers to the first plot, the second
to the second plot and so on.

Note that where text is supplied for the label of an axis or for the title, this text is
terminated by the next comma, space or square bracket. In order to include commas,
spaces or square brackets in the text you should enclose it in single or double
quotation marks.

Here is a program that uses some of these options.

RBX\_[T!U^a
F8=0??
8=C464A XgfX]X^/=
?0A0<4C4A=,
A40;' _ _!_"h=
R?aT_PaT cWT SPcP
_ , $
_!, $
_", $
g,
3> X, =
hX,_ bX]g_"Tg_g_!
g,g
4=33>
R3Xb_[Ph P fX]S^f R^]cPX]X]V cWT VaP_W
X,fX]X^/ffJ]^NQ^aSTaLRPJB8<?;4?;>C3P\_TS fPeTL_e
X,fX]X^/_[JgNPgXb,CX\T<X[XbTR^]Sb
³hNPgXb,0\_[XcdSTcXc[T,±BP\_[T _[^c²R^[^da,aTSL
#"=3 3h
4=3
In this case, since the option X_ARRAY is not used, the argument list for %pl
includes the initial value of x (0.0D0) and the increment for x (1.0D0). Note also that
%ww and %pv are used with %pl. As a result, the window can be sized and the graph
is redrawn to fill the window. The output is illustrated below.

Here is a fragment of code that shows how to plot two graphs on one set of axes.
X,fX]X^/_[JGN0G8B,CX\T<X[XbTR^]SbHN0G8B,0\_[XcdST
C8C;4,BP\_[T=N6A0?7B,!2>;>DA,aTS2>;>DA,Q[dTGN0AA0HL
""=gPaahPaa hPaa!

184
Chapter 17 SIMPLEPLOT

There is one x-array for the two y-arrays. The first graph would be red in colour and
the second blue.

Note that the arrays of data supplied to %pl usually need to be available for as long as
the window is displayed. In particular, the data will be re-plotted if the window is re-
sized. It is also possible to call the routine bX\_[T_[^cNaTSaPf/ to force all such
plots to be re-drawn using whatever values are currently present in the arrays.
bX\_[T_[^cNaTSaPf/ is a subroutine that takes no arguments.

Direct calls to SIMPLEPLOT

As an alternative to the automatic mode described above, %pl can take the form:
fX]X^/_[JdbTaNSaPf]L´fXScWWTXVWc
width and height give the pixel dimensions of a SIMPLEPLOT graphics region.
There are no other arguments to go with %pl. Direct calls can be made to the
SIMPLEPLOT library from within a %sc call-back. Alternatively you could use %lw
and put the library calls after the set of fX]X^/ statements that describe the window.

185
ClearWin+ User’s Guide Fortran

Here is a simple example that illustrates this approach.

RBX\_[T"U^a
F8=0??
8=C464A fX]X^/XBcPac21
4GC4A=0; BcPac21
X,fX]X^/bhJ]^NQ^aSTaLRPJDbTa SaPf]L
X,fX]X^/_[JdbTaNSaPf]L#"
X,fX]X^/bRBcPac21
4=3
RCWT bcPacd_ RP[[QPRZ
8=C464A 5D=2C8>= BcPac21
8=C464A =X
?0A0<4C4A=,
A40; g=h=
R2aTPcT cWT SPcP
3> X, =
gX,X
hX,gX!
4=33>
R2P[[ B8<?;4?;>C a^dcX]Tb c^ _[^c cWT VaP_W
20;; 8=8CB?
20;; ?064 !
20;; 27B4C
20;; =4F?06
20;; C8C;4&7XVWTa2T]caTBP\_[T
20;; B20;4B
20;; 0G6A832PacTbXP]
20;; =4F?82
20;; 0G8B&G2PacTbXP]gPgXb
20;; 0G8B&H2PacTbXP]hPgXb
20;; 1A:=2Egh=
BcPac21,
4=3
When you link this program you must link with simple.dll.
Notice that this window cannot be re-sized. As a result the x and y arrays for the data
can be local to the start-up call-back function. Further information about the
SIMPLEPLOT routines that are used in this example can be found in the
documentation provided by BUSS Ltd.2

2 Web site http://www.buss.co.uk/buss/

186
Chapter 17 SIMPLEPLOT

187
ClearWin+ User’s Guide Fortran

188
18.

Using the printer

Introduction
One of the advantages of the Windows operating system is its built-in support for a
wide range of printers. ClearWin+ caters for three different types of printer output:
• Simple text output to the printer.
• HTML text output.
• Graphics output.
Before you can send output to the printer it is usually necessary to prompt the user to
select the printer to use (this also gives users the opportunity to cancel the print
request). There are several methods to obtain this information each of which is
described below.
The resolution of a printer varies from one machine to another, but typically printers
offer a much finer resolution than even a high quality graphics driver. This means
that screen images must be re-drawn for a printer after determining the resolution of
the printer selected by the user. If you are using bitmap images as part of your printer
output, you may need to use a higher resolution image on the printer than on the
screen.
If you send simple text to the printer it will look rather plain because a single font will
be used. However, this is sometimes useful for debugging purposes. It is almost as
easy to send HTML output to the printer, and this is the recommended method for
producing professional printed output from ClearWin+.
For printed output using OpenGL see page 179.

189
ClearWin+ User’s Guide Fortran

Selecting a printer
Using a standard call-back function
In most Windows applications, such as Word for Windows, a standard printer dialog
box is produced in response to a user button press or menu activation. Several
ClearWin+ standard call-back functions are supplied to perform this task, each of
which takes another call-back as an additional argument. The standard printer dialog
is automatically displayed and the call-back will contain your code to write or draw to
the printer. This call-back will only be called if the user selects a printer from the
dialog (as opposed to pressing the Cancel button).

PRINTER_OPEN Takes an integer Fortran unit number and another

callback function as arguments. Displays a dialog box
to select the printer and connects it to the given Fortran
unit number.
PRINTER_OPEN1 This also takes a Fortran unit number and another call-
back function as arguments. It uses the printer
previously selected using PRINTER_OPEN.
HTML_PRINTER_OPEN This takes a Fortran unit number and another call-back
function. It displays a dialog box to select the printer
and connects it to the given Fortran unit number.
HTML_PRINTER_OPEN1 This also takes a Fortran unit number and another call-
back function. It uses the prevously selected printer.
GPRINTER_OPEN This takes another call-back as argument and displays a
dialog box to select the printer. The printer is connected
as the current drawing surface for the duration of the
call-back, which should perform the required graphics
operations.
GPRINTER_OPEN1 This operates in the same way as GPRINTER_OPEN,
except that a previously opened printer is used.

For example, here is a program that will respond to the button press by prompting the
user for a printer and printing ‘Hello’.
4GC4A=0; _aX]cTa
X,fX]X^/³?aTbb cWXb Qdcc^] c^ _aX]c P _PVT) ³
X,fX]X^/³MQcJ?aX]cL´´?A8=C4AN>?4=´&_aX]cTa
X,fX]X^/³!][R]QcJ>:L´
4=3
R
8=C464A 5D=2C8>= _aX]cTa

190
Chapter 18 Using the printer

FA8C4&´7T[[^´
2;>B4&
_aX]cTa,!
4=3
Notice that the unit is closed before the call-back function exits. Typically, the call-
back function should return a value of 2 to indicate that the associated window should
stay open without a screen update. However, other call-back return values may be
used as described on page 205.
Using the 7C<;N?A8=C4AN>?4= or 7C<;N?A8=C4AN>?4= standard call-backs it is
easy to generate pleasantly formatted text output to the printer. This mechanism uses
the same subset of HTML as that used by %ht except that one mark-up <PB> is added
to set a page break.. Here is a simple example:
F8=0??
8=C464A XfX]X^/
4GC4A=0; cTbc
X,fX]X^/bR7C<;N?A8=C4AN>?4=&cTbc
4=3
R
8=C464A 5D=2C8>= cTbc
FA8C4&P+W -CWT ^dc_dc+W -
FA8C4&PCWXb Xb +X-8cP[XR+X-+_-
FA8C4&P0]S cWXb Xb +Q-1^[S+Q-+_-
2;>B4&
cTbc,!
4=3
Under Win16, it is necessary to call 8=8CN?A8=C4AN7C<;/.
The standard call-backs 6?A8=C4AN>?4= and 6?A8=C4AN>?4= do not connect the
printer to a Fortran unit number, but rather they create a drawing surface that
becomes the current drawing surface. The call-back that is an additional argument to
these standard call-backs is used to draw to this surface. The current drawing surface
reverts to the previous surface (if any) at the end of the call-back. An example is
given on page 194.

Using OPEN_PRINTER@ etc. to create a drawing surface

Alternatively, you can use explicit function calls to create a drawing surface and to
attach it to a printer for graphics drawing:

>?4=N?A8=C4A/ Displays the standard printer dialog to enable

graphics output to be sent to a printer.
>?4=N?A8=C4A / Re-opens a graphics printer using settings
from a previous call to >?4=N?A8=C4A/.

191
ClearWin+ User’s Guide Fortran

>?4=N?A8=C4ANC>N58;4/ Displays the standard printer dialog to enable

graphics output to be sent to a file.
>?4=N?A8=C4A NC>N58;4/ Sends graphics output to a file supplied as an
argument.

Each of these functions returns zero if the user cancels the operation, and each takes a
handle argument as input that is used to switch between drawing surfaces using
bT[TRcNVaP_WXRbN^QYTRc/. An example is given on page 195.

Customising the printer dialog box

ClearWin+ uses the standard Windows dialog box to interrogate the user, in each of
the above approaches. This has the advantage that the style of the box will take on the
‘look and feel’ of the operating system in use and will be familiar to your users.
In order to change the default behaviour of the printer dialog box you can call
_aX]cTaNSXP[^VN^_cX^]b/ in order to specify the information that is to be
requested in the printer dialog box when it opened using ?A8=C4AN>?4= etc. or
^_T]N_aX]cTa/ etc. (also you can obtain the values selected by the user with calls to
R[TPafX]NX]U^/).
_aX]cTaNSXP[^VN^_cX^]b/ takes nine integer arguments referred to as A1 to A9.
The following table indicates the changes that are possible:

Feature CLEARWIN_INFO@ Default Remarks

parameter for result behaviour

Print to - Available, If a printer is selected with this

file initially not option checked, the user will
checked be prompted for a file name.
No programming action is
required to support this
feature. This box will be
hidden if A2 is non-zero, and
will be initially checked if A9
is non-zero.
Selection PRINTER_SELECTION Available, This is a radio button which is
initially not used to indicate that only
checked selected material is to be
printed. It is up to you to read
the parameter and act on it as
required. This box will be

192
Chapter 18 Using the printer

greyed out (not hidden) if A3

is non-zero, and will be
initially selected if A6 non-
zero.
Page PRINTER_FIRST_PAGE Available, This enables a range of pages
numbers PRINTER_LAST_PAGE set to 1,1. to be selected in various ways.
The control is disabled if A2 is
non-zero. If all pages are
selected the range is returned
as 1-32767. If A5 is non-zero
the range selection option will
be initially selected. If A8 is
non-zero the all-pages option
will be initially selected.
Collate PRINTER_COLLATE Available This control is always
available. Some printer
drivers support this option
explicitly and the program is
not informed of the selection
because no action is required.
If the parameter is set, an
appropriate response is
required from the program. If
A7 is non-zero the collate box
is initially checked.
Copies PRINTER_COPIES Available This control is always
available. Some printer
drivers support this option
explicitly and the program is
not informed of the selection
because no action is required.
If the number of copies is
greater than 1, the program
should reproduce the output.
Default - Will occur A warning will be generated if
warning the user has no printer selected
as the default. This wil be
suppressed if A4 is non-zero.

Also R[TPafX]NX]U^/³?A8=C4AN?064=D<14AB´ returns 1 if the ‘Page Range’

is set to ‘Pages’.

193
ClearWin+ User’s Guide Fortran

At most one of A5, A6, A8 should be set non-zero, as they select mutually exclusive
options. These defaults work for both built in call-backs and explicit routine calls.
Four other R[TPafX]NX]U^/ parameters are also used to control the initial
appearance of the printer dialog box. These parameters are set using
bTcNR[TPafX]NX]U^/. The parameters are:
?A8=C4AN3450D;CN<8=N?064
?A8=C4AN3450D;CN<0GN?064
?A8=C4AN3450D;CN5A><N?064
?A8=C4AN3450D;CNC>N?064
In some situations it may be necessary to set these parameters in a multiple call-back,
for example:
X,fX]X^/MQcJ?aX]cLbTcN_aX]cTaNX]U^?A8=C4AN>?4=
where bTcN_aX]cTaNX]U^ is a user-defined function that makes appropriate calls to
bTcNR[TPafX]NX]U^/.

Printer graphics
Here is a simple program that uses the standard call-back 6?A8=C4AN>?4= to repond
to a button press and draws a diagonal line across the entire page. 6?A8=C4AN>?4=
creates a drawing surface and an additional call-back argument is used to to contain
code to draw to this surface.
F8=0??
8=C464A XfX]X^/
4GC4A=0; cTbc
X,fX]X^/MQcJ>_T]L6?A8=C4AN>?4=cTbc
4=3
R
8=C464A 5D=2C8>= cTbc
8=2;D34 +fX]S^fbX]b-
8=C464A g\Pgh\Pg
20;; VTcNVaP_WXRP[NaTb^[dcX^]/g\Pgh\Pg
20;; SaPfN[X]TNQTcfTT]/g\Pg h\Pg $
cTbc,!
4=3
Notice that the call to VTcNVaP_WXRP[NaTb^[dcX^]/ will work for all types of
drawing surfaces. This means that the same code can be used to generate graphics
output to the screen and to the printer.

194
Chapter 18 Using the printer

By using ^_T]N_aX]cTa/ etc., it is possible to have two drawing surfaces, one

attached to the screen and the other to a graphics printer or plotter. In the following
example one handle is attached to a %gr region (a screen drawing surface) whilst a
second handle is attached to a graphics printer drawing surface.
8=C464A Rca[W]S W]S!
30C0 W]S W]S! !
X,fX]X^/OVa#;";W]S
X,fX]X^/ff[fRca[
Y,bT[TRcNVaP_WXRbN^QYTRc/W]S
20;; SaPfN[X]TNQTcfTT]/ "! $
Z,^_T]N_aX]cTa/W]S!
Y,bT[TRcNVaP_WXRbN^QYTRc/W]S!
20;; SaPfNUX[[TSNT[[X_bT/! $&$$!
Z,R[^bTN_aX]cTa/W]S!
As usual, ^_T]N_aX]cTa/ generates a standard “Open Printer” dialog box from
which the user selects a graphics printer or plotter. Subsequent calls to ClearWin+
drawing routines are written to this drawing surface and the output is generated when
the ClearWin+ routine R[^bTN_aX]cTa/ or the routine ]TfN_PVT/ is called.
Notes:
• ^_T]N_aX]cTa/ etc. may be used independently of fX]X^/.
• In the above example, Y and Z can be used to test for the success of the associated
function calls.

Using a metafile to print multiple copies

Here is another sample program which (like the above example) shows how to draw to
a screen drawing surface in parallel with output to a graphics printer or plotter. In
this case the image is scaled according to which device is used. Multiple copies are
printed by calling S^NR^_XTb/ but this routine requires a metafile recording of the
current image before it is called.
8=2;D34 +fX]S^fbX]b-
A40; bRP[X]V
8=C464A XfRaTb]R^_XTb
8=C464A bRaTT]NWTXVWc_aX]cTaNWTXVWc
8=C464A bRaTT]NfXScW_aX]cTaNfXScW
8=C464A bRaTT]NXS_aX]cTaNXS
4GC4A=0; VaP_WXRb
2><<>= bRP[X]VbRaTT]NXS_aX]cTaNXS
20;; bTcNaVQNR^[^dabNSTUPd[c/

195
ClearWin+ User’s Guide Fortran

bRP[X]V,
R 6XeT XS ]d\QTab c^ cWT bRaTT] P]S _aX]cTa
bRaTT]NXS,
_aX]cTaNXS,!
R
X,fX]X^/³ffRPJBP[UâS VaP_WXRbL´
X,fX]X^/OVaJQ[PRZL´%##'bRaTT]NXS
X,fX]X^/³OQcJ>:L[ffR
20;; VaP_WXRb
20;; VTcNVaP_WXRP[NaTb^[dcX^]/bRaTT]NfXScW
bRaTT]NWTXVWc
R BT[TRc _aX]cTa P]S bcPac S^Rd\T]c
aTb,^_T]N_aX]cTa/_aX]cTaNXS
85aTb=4C74=
20;; dbTNaVQNR^[^dab/_aX]cTaNXScadT
20;; VTcNVaP_WXRP[NaTb^[dcX^]/_aX]cTaNfXScW
_aX]cTaNWTXVWc
R BRP[X]V UPRcâ Uâ _aX]cTa
bRP[X]V,_aX]cTaNfXScWbRaTT]NfXScW
R >_T] \TcPUX[T c^ aTRâS _aX]cTa SaPfX]V
20;; ^_T]N\TcPUX[T/_aX]cTaNXS
20;; VaP_WXRb
]R^_XTb,R[TPafX]NX]U^/_aX]cTaNR^_XTb
R Bc^_ aTRâSX]V
20;; R[^bTN\TcPUX[T/_aX]cTaNXS
]R^_XTb,]R^_XTb
R <PZT R^_XTb Û cWT _PVT
20;; S^NR^_XTb/_aX]cTaNXS]R^_XTb
R ?aX]c S^Rd\T]c
aTb,R[^bTN_aX]cTa/_aX]cTaNXS
20;; bT[TRcNVaP_WXRbN^QYTRc/bRaTT]NXS
bRP[X]V,
4=385
4=3

BD1A>DC8=4 VaP_WXRb
8=2;D34 +fX]S^fbX]b-
8=C464A g h
8=C464A W_^[igPgQTaa
A40; bRP[X]V
8=C464A bRaTT]NXS_aX]cTaNXS
2><<>= bRP[X]VbRaTT]NXS_aX]cTaNXS
20;; bTcN[X]TNfXScW/"
R BT[TRc U^]c

196
Chapter 18 Using the printer

20;; bTcNcTgcNPccaXQdcT/ "bRP[X]V

gP,"bRP[X]V
gQ,"$bRP[X]V
20;; SaPfNRWPaPRcTab/74;;>gPgQA61/!$$!$$!$$
20;; bTcN[X]TNfXScW/
i,!bRP[X]V
20;; SaPfN[X]TNQTcfTT]/iiA61/!$$
20;; SaPfN[X]TNQTcfTT]/iiA61/!$$
R 4[[X_bT
i, bRP[X]V
gP,'bRP[X]V
gQ,#bRP[X]V
20;; SaPfNT[[X_bT/iigPgQA61/!$$
gP,%bRP[X]V
20;; SaPfNUX[[TSNT[[X_bT/iigPgQA61/!$$
R ?^[h[X]T
g ,!"bRP[X]V
h ,!bRP[X]V
R 2^ST U^a g!# P]S h!#
g$,g
h$,h
20;; SaPfN_^[h[X]T/gh$A61/!$$
R ?^[hV^]
g ,"bRP[X]V
h ,!$bRP[X]V
R 2^ST U^a g!# P]S h!#
g$,"bRP[X]V
h$,!$bRP[X]V
20;; SaPfNUX[[TSN_^[hV^]/gh$A61/!$$
4=3

197
ClearWin+ User’s Guide Fortran

198
19.

Hypertext windows

Hypertext %N.Mht
Most programmers and many users will be familiar with the use of Web Browsers
such as Internet Explorer. Such browsers display information that has been encoded
as ASCII files containing Hypertext Markup Language (HTML). A subset of HTML
forms the basis for ClearWin+ hypertext windows.
Hypertext windows provide a way of building very easy to use GUI applications. A
hypertext window contains text with hypertext links, that enable users to switch
between pages (by clicking on highlighted text and images) or to initiate parts of your
program. A hypertext window is created using %ht and can be surrounded by other
controls as required.
For example, the format %70.20ht[introduction] would create a hypertext window of a
width sufficient to display 70 average width characters and 20 rows. The text would
be supplied by a prior call to PSSNWh_TacTgcNaTb^daRT/ with the name of a
hypertext resource, say ‘start’, containing the required initial topic called
‘introduction’. This would be defined as a resource thus:
bcPac 7H?4AC4GC \hUX[TWc\
You must use the Salford resource compiler SRC for hypertext files, rather than the
Microsoft compiler RC. By default, SRC is automatically invoked when a program
containing the WINAPP directive is compiled.
The file called browse.htm, that is built into the ClearWin+ browser program, is
available as an example program and is an excellent illustration of a hypertext file.
Note that hypertext resources are stored in a compressed format, which is not
accessible to your users if they choose to binary edit your program file.

199
ClearWin+ User’s Guide Fortran

The HTML text is displayed in the window that is both left and right justified with
scroll bars if necessary. The %ht format may be preceded by a pivot format (%pv) so
that the text area changes size as the window is adjusted by the user.
Mark-up codes are contained within diamond brackets < >. For example, a paragraph
end is marked using . Mark-up codes are case insensitive. Some codes define a
condition that pertains until cancelled by a corresponding mark-up starting with a ‘/’
character. For example, bold face text is preceded by and followed by .
Special characters (such as the diamond brackets used to define mark-up codes) are
encoded as follows:

&LT; or < produces ‘<’

&GT; or > produces ‘>’
&AMP; or & produces ‘&’
Hypertext files may contain portions of text that are included conditionally, under
program control. This is called conditional hypertext. The browse program uses this
feature to change the text depending on the programming language selected from the
corresponding menu item.
The following HTML codes are currently available in ClearWin+:
<TITLE> ... </TITLE>
This supplies a title to a topic. The title will be placed in the caption of the format
window using %ht.
<H1> ... </H1>
Supplies a principle heading to the text. The text will be enlarged and centred.
Although the other heading styles (H2 .. H6) may be used, they currently operate
in the same way as H1. This may change in future versions of the software.
<HTML> ... </HTML>
In standard HTML these codes are almost redundant. They optionally enclose the
entire text. However they are vital for ClearWin+ hypertext as they are used to
delimit separate topics. Each topic should be surrounded by these tags and contain
a DOC tag.
<DOC name="doc_name">
This defines the topic name, and has no analogue in non-ClearWin+ HTML. Each
topic should have a distinct name enclosed in double quotation marks as shown.
<a HREF="name"> ... </a>
This is an HTML anchor that encloses text (or an image) that will be highlighted
in blue and will react to a left mouse click. Note that standard HTML anchors
have a somewhat more general syntax. The name will usually be another topic
name (defined by DOC). If the name does not correspond to a topic and a call-
back function is supplied with %ht, then the call-back function will be called. The

200
Chapter 19 Hypertext windows

function can determine the text on the anchor by calling

R[TPafX]NbcaX]V/2DAA4=CNC4GCN8C4<. In this way, it is possible to
execute code in response to a mouse click.
Hypertext can also contain Uniform Resource Locators (URL’s) that link to the
web, for example <a href="http://www.salford.co.uk"> or to local files, for
example <a href="file:///c:\myproj\test.htm">. Local files must have the .HTM or
.HTML extension. Alternatively, if the file has a .EXE extension, it will be
executed (see also DB4NDA;/ and 8=C4A=4CN;8=: standard call-back). By using
file URLs, it is possible to create complex webs of inter-related documents without
having all the information stored in the executable file.

Marks the end of paragraph. Subsequent text will start on a fresh line with a small
gap separating it from the previous text.
 
Forces a line break with no extra gap.
<HR>
Rules a horizontal line across the page.
 ... 
Creates bold text.
 ... 
Creates underlined text.
 ... 
Creates italic text.
<RED> ... </RED>
Sets the text colour. Other available colours are BLUE, BLACK, GREEN,
WHITE, and YELLOW. Hypertext links are coloured blue by default so you may
want to avoid the use of this text colour (although the colour of a link can be
changed by nesting a colour change inside the link). These are not standard
HTML mark-ups.
<IMG SRC="name" ALIGN="align_option">
Using this mark-up you can insert a bitmap into your text. name should be the
name of a BITMAP resource you have added in the list of included resources
(quotation marks are required), and align_option should be one of TOP, MIDDLE,
BOTTOM. The alignment specification is optional and the default is BOTTOM.
This determines the way in which the image is aligned with the surrounding text.
By embedding an image in an anchor construct you can display an image that
responds to mouse clicks. GIF files may also be used in this context (see %gi, page
243, for further information).
<UL> ... </UL>

201
ClearWin+ User’s Guide Fortran

Text embedded between these mark-up codes is considered to form an unordered

list. Each list item is preceded by a <LI> mark-up and will start on a fresh line
with a bullet mark. Lists embedded in lists will nest to the right.
<OL> ... </OL>
Produces an ordered list numbered from 1.
<IF name> ... </IF> - See conditional hypertext below.
<PB>
Sets a page break for use with 7C<;N?A8=C4AN>?4=, see page 191.
A format window can contain at most one hypertext control. It may also contain other
controls, menus, etc. as desired. It is, however, possible to embed several child
windows, each containing hypertext, within a single parent window. Only one
hypertext control per window is allowed because the window provides certain services
to the control. Thus the containing window will be displayed with vertical scroll bars
if the hypertext is too long for the space provided. Note that this happens entirely
automatically. It is an error to attempt to attach vertical scroll-bars (%vs) to a window
containing hypertext. Horizontal scroll bars are never needed, since hypertext is
always adjusted to fit the width available.
A standard call-back function ?A4E8>DBNC4GC is available within a window
containing hypertext. This would normally be attached to a menu item and causes the
hypertext window to ‘go back’ one topic. A menu item attached to this call-back will
be automatically greyed if the hypertext is at the top level.
A call-back function C4GCN78BC>AH is also available. When invoked it displays a
history box associated with a hypertext control in the window. The user can choose to
switch to any previously viewed hypertext topic. It is an error to invoke this call-back
from a window that does not contain hypertext.
By default, hypertext windows are given a grey background, although this can be
changed using %`bg. In most cases it is desirable to give the parent window a
matching grey background using %bg[GREY].
The title of a window containing hypertext will consist of any explicit title (%ca)
followed by the title of the current hypertext topic (as supplied by the <TITLE>)
mark-up separated by a hyphen (-).
If there are syntax errors in your mark-up codes, such errors will be reported at run
time rather than when the resource is compiled. A error dialog box will appear
showing the offending code together with a few lines of the text that follows it.
If a call-back function is supplied to %ht, this function will be called when a jump is
made to a topic that has not been defined. Alternatively, a grave accent (`) is supplied
in order to ensure that the call-back will be called the first time and each time the
hypertext topic changes. The call-back function can then interrogate the following
R[TPafX]NbcaX]V/ parameters:

202
Chapter 19 Hypertext windows

2DAA4=CNC4GCN8C4<
2DAA4=CNC4GCN3>2D<4=C
2DAA4=CNC4GCNC8C;4
Equation character strings, that follow the rules for %eq (see page 100), may also be
used in hypertext documents. Equation strings are embedded between <equation>
and </equation>. The string between these delimiters is treated as a pure equation -
no mark-up codes are recognized in this context. So, for example, the ‘<’ symbol
should be written as it is.

Conditional Hypertext
The ClearWin+ BROWSER program uses conditional hypertext to display different
information depending on the programming language selected.
For example:
Call the <if Fortran> WINIO@ <else> winio </if> function to display a window.
This uses an named integer parameter with the name ‘Fortran’, set up using the
bTcNR[TPafX]NX]U^/ function. The <if> clause is selected if the parameter is non-
zero. The <else> clause is optional. Conditional constructs can be nested, and may
contain arbitrary amounts of other mark-up codes and text.
If a call-back function changes the value of a parameter referenced in a conditional
construction, it should either return 1 (to cause all controls in the window to be
updated) or use fX]S^fNd_SPcT/ to ensure that the hypertext is updated.
To get a working example of the use of this format code, open the browse.htm file and
the associated program browse.cpp.
For example:
F8=0?? ³aTb^daRTaR´

R >][h RP[[ cWT ]Tgc [X]T ^]RT
20;; PSSNWh_TacTgcNaTb^daRT/³Wh_TaWT[_´
X,fX]X^/³RPJ7h_TacTgc WT[_ bhbcT\L´
X,fX]X^/³ffQVJVaThL_e´
X,fX]X^/³M%!!WcJ8]ca^SdRcX^]L´RP[[QPRZ
Where resource.rc contains:
Wh_TaWT[_ 7H?4AC4GC ³WT[_UX[TWc\´
A summary of ClearWin+ hypertext functions is given on page 325. Details can be
found in Chapter 27.

203
ClearWin+ User’s Guide Fortran

Linking to the web

When whole URLs (i.e. URLs with '://' embeded in their name) are used within a
<a>HREF=...</a> link in a (%ht) hypertext document, the default web browser is
invoked to process the link.
A routine is also available to perform this task:
BD1A>DC8=4 DB4NDA;/DA;
270A02C4A DA;
This routine uses the Windows shell to open the URL. As a result it can be used to
‘open’ other objects such as a file with a name that has a registered extension (e.g.
.DOC files). You can use this routine in a ClearWin+ window call-back function
(attached to a menu item or button) in order to create a link to a web site or document.
This facility is also available via the 8=C4A=4CN7H?4A;8=: standard call-back
function (see page 210).
There is also a routine to read the contents of a URL (assuming the machine has
access to the internet):
BD1A>DC8=4 A403NDA;/DA;58;4<>344AA>A
270A02C4A DA;
270A02C4A 58;4
8=C464A <>34
8=C464A 4AA>A
If this routine succeeds (i.e. an internet connection is available and the URL can be
accessed), ERROR is set to zero and the data from the URL is transfered to the
specified file (which can be a full path name). If MODE=0, the data is assumed to be
text and newlines are converted to DOS style. If MODE=1, binary data is assumed.
The URL can be quite general. In particular, you can use an FTP address assuming
anonymous access is possible, or an HTTP address with extra information attached.
For example, you could query a search engine directly using this routine.
If necessary, the system will dial up the service provider to process this call. By
default the connection will not be closed after the transfer has completed. The
following call will close a modem connection if one exists.
20;; 1A40:N<>34<N2>==42C8>=/

204
20.

Standard call-back functions

ClearWin+ call-back functions

fX]X^/ call-back functions consist of functions with no arguments that return an
integer result. A returned zero or negative value causes the parent window to close.
The corresponding call to fX]X^/ will return the same value made positive. A
returned value of 1 leaves the window open and updates the whole display area to
reflect any changes in the data. This is not normally the most suitable return value
because frequent returns can cause the screen to flicker. A returned value of 2 leaves
the window open but does not update it. This value is best for repetitive display
updates but you must update the parts of a window that have changed by calling
fX]S^fNd_SPcT/ (see page 26). The call-back function used with %mg may also
return the value 3 (see page 257).
A number of frequently used call-back functions can be specified as character strings
that denote standard call-back functions. (Note that there is never any confusion
between a pointer to one of these character strings and a genuine function pointer,
because all functions start with a distinctive sequence of machine instructions. The
system decides whether the supplied pointer points to a function or to one of the
special strings described below. If the supplied pointer points to an illegal address,
this will cause an immediate program fault to be reported.)
Standard call-back functions usually appear within the argument list that follows the
format string in a call to fX]X^/. Some standard call-back functions require
additional arguments that are placed in the fX]X^/ argument list immediately after
the string that denotes the standard call-back. The following functions are available.

205
ClearWin+ User’s Guide Fortran

ABOUT
This takes one character string argument (which may include newline characters) and
displays a simple “about” box. Each line of the text is centred, and an OK button is
supplied for the user to close the box.

BEEP[sound option]
If you require a button to make a (Windows) beep sound this call-back will provide a
quick and simple way of doing so. It may be most useful when used in conjunction
with the call-back joiner ³+´. It takes one of the following five possible arguments:

J4G2;0<0C8>=L
J@D4BC8>=L
J70=3L
J<1>:L
J0BC4A8B:L
These correspond to the warning icons built into Windows (see page 78).
For example:
X,fX]X^/ MQcJ?A4BBL 144?J<1>:L RQN^_T]UX[T

CASCADE
If this function is invoked from a window containing a MDI frame (%fr). The child
windows created with %aw are cascaded leaving the active window at the top.

CONFIRM_EXIT
This call-back function takes one character string argument and displays it as a yes/no
question. It is designed to be used with a button or menu option that will exit a
window. If the user responds yes, the function returns zero, thus closing the window
with the return number of the original button. If the user responds no (the default
response) the window remains open.

COPY, CUT, PASTE

These three call-back functions transfer information between the edit box (%eb, %rd,
%rf, %fs, or %re) that has the focus and the clipboard. Typically, they are used as the
call-back function for an edit-copy/cut/paste menu item. These call-back functions
require no additional fX]X^/ arguments.

206
Chapter 20 Standard call-back functions

Menu items and buttons attached to these callback functions are greyed according to
circumstances. For example, a control associated with the 2DC function would be
greyed if no text were currently marked as selected on the screen. However, if the
control has a grey control variable then this variable takes precedence.
Apart from %eb, standard accelerator keys (Ctrl+C, Ctrl+X, and Ctrl+V) can also be
used for 2>?H, 2DC and ?0BC4.

CONTINUE
This function returns a non-zero value which therefore leaves the window open. It is
used as a dummy when no action is required.

EDIT_FILE_OPEN
This standard call-back is used with %eb and takes a character string argument
containing a file pattern (e.g. '*.TXT'). A second character string argument (called
fname say) is required for the resultant file name (of size 129). A standard Windows
‘file open’ dialog is displayed and the resultant file is written to fname. The file is
then displayed in a %eb edit box that is included in the current format window,
replacing any text already there. This standard call-back must only be used in a
format window containing one and only one %eb edit box. The corresponding edit
box is usually supplied with a buffer length of zero when it is set up, so that the system
allocates the buffer and adjusts its size as necessary. An example program appears on
page 212.

EDIT_FILE
This is used with %eb and takes one character string argument that is the file name of
the file to be opened. Unlike 438CN58;4N>?4=, the standard Windows ‘file open’
dialog is not presented.

EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
These call-back functions operate on a %eb edit box in same same manner as
438CN58;4N>?4=. If an edit box has not been filled using 438CN58;4N>?4=
438CN58;4NB0E4 operates like 438CN58;4NB0E4N0B and displays the standard
‘file save’ dialog. Each call-back takes two character string arguments: one for the
file pattern and the other for the resultant file name (see 438CN58;4N>?4= above).
The contents of the edit box are written to the file but the edit box is not closed. An
example program appears on page 212.

207
ClearWin+ User’s Guide Fortran

EXIT
This closes the window. If a window closure call-back (%cc) has been specified, the
%cc call-back is called before the closure takes place.

DEC
This takes one 8=C464A variable as an argument and subtracts 1 from the variable
each time 342 is called. Any controls that use this variable are automatically updated.

FATAL
The 50C0; call-back terminates the program at once without performing any of the
normal cleanup activities. Typically this is attached to the OK button in a window
that displays a fatal error condition. Use this only if the program is likely to be
corrupt and where performing a normal cleanup might hang the system.

FILE_OPENR[caption]
58;4N>?4=A is used to display the standard Windows ‘file open’ dialog. It takes a
character string argument which is a buffer to receive the file name selected by the
user from the dialog. Initially this buffer must be preset to be either blank or have the
form ‘*.abc’ otherwise the behaviour of 58;4N>?4=A is indeterminate. A call-back
function should follow the buffer in the argument list. This call-back is called if the
user selects a file (as opposed to pressing cancel, etc.).
For example:
4GC4A=0; RQ
8=C464A RQ
270A02C4A !( bcaNUX[T
bcaNUX[T,³ ³
X,fX]X^/³MQcJ>_T] UX[TL´ ³58;4N>?4=AJ>_T]L´ bcaNUX[T RQ
The value returned to the calling fX]X^/ is the return value of this call-back function,
or 1 if no file is selected (so that the underlying window is kept open). By default (if
the file name string is initially blank) the file selection box starts by displaying all files
from the current directory. However, this and several other default actions of
58;4N>?4=A can be modified by the prior use of the %fs and %ft formats or by
setting the file name string to the form ‘*.abc’ before the call. For an example of the
use of the 58;4N>?4=A and ±² call-back functions see the description of the %aw
format on page 123. See also %fs and %ft on page 105.

208
Chapter 20 Standard call-back functions

FILE_OPENW[caption]
58;4N>?4=F is analogous to 58;4N>?4=A but allows the user to type in a new file
name, since it is assumed that the file is required for writing.

GPRINTER_OPEN
6?A8=C4AN>?4= is used to produce output on a graphics printer or plotter. It
operates in a manner similar to ?A8=C4AN>?4=. However, 6?A8=C4AN>?4= takes
only one argument which is a call-back function supplied in the program. This call-
back function will use drawing surface routines to produce the graphics output (see
Chapter 15).
Note that graphics printing and plotting can also be carried out using
^_T]N_aX]cTa/ (see page 382).

HELP_CONTENTS
74;?N2>=C4=CB takes one character string argument giving the full path name of a
help file (.HLP). The file is opened at its contents page. When the main window
closes, the help window will also be closed if it has been left open.

HELP_ON_HELP
74;?N>=N74;? provides the standard help-on-help information. This also takes a
character string argument giving the name of a help file.

HTML_PRINTER_OPEN
7C<;N?A8=C4AN>?4= provides for the output of text with embedded HTML
markups. See page 191 for further details.

INC
8=2 takes one 8=C464A variable as an argument and adds 1 to this variable each time
8=2 is called. Any controls that use this variable are automatically updated.

209
ClearWin+ User’s Guide Fortran

INTERNET_HYPERLINK
8=C4A=4CN7H?4A;8=: takes one 270A02C4A string argument which is the full
URL of a file on the web. For example:
X,fX]X^/MQcJBP[U^aSL8=C4A=4CN7H?4A;8=:
Wcc_)fffbP[U^aSR^dZ
See also DB4NDA;/.

PRINT_ABORT
?A8=CN01>AC is used to cancel a print job whilst it is being spooled.

PRINTER_OPEN
?A8=C4AN>?4= displays the standard Windows ‘Print’ dialog that enables the user to
select a printer. The function takes two arguments. The first is an integer that is the
Fortran unit number on which to open the printer. The second argument is a call-back
function supplied in the program. If the printer is successfully selected, the call-back
function is called. (The value returned by the call-back becomes the value returned by
the enclosing fX]X^/. Hence, a return value of 1, for example, has the effect of
keeping the parent window open). If no printer is selected, ?A8=C4AN>?4= returns 1
to keep the window open. The call-back function should perform print operations
using standard Fortran output statements (for example, FA8C4) on the specified unit
number. It is necessary to 2;>B4 the unit number in order to dispatch the output to
the printer.

PRINTER_OPEN1
?A8=C4AN>?4= has the same purpose and takes the same arguments as
?A8=C4AN>?4= but does not display the standard Windows ‘Print’ dialog. Instead it
uses the default printer or the printer that was selected in an ealier call to
?A8=C4AN>?4=.

PRINTER_SELECT
?A8=C4ANB4;42C displays the standard Windows ‘Print’ dialog and is used in
with the standard call-back >?4=N?A8=C4A
conjunction or the routine
^_T]N_aX]cTa /.

210
Chapter 20 Standard call-back functions

SELECT_ALL
B4;42CN0;; has no arguments and selects all of the text in the current %eb edit box.

SET
The B4C call-back takes two arguments each of type 8=C464A. When the call-back is
called, the first argument is set to the value of the second at the time when fX]X^/ is
called. B4C returns the value 1 so that any necessary updates take place. Here is an
example.
F8=0??
8=C464A effX]X^/gRca[
e,
g,
f,fX]X^/OR]MccJBTcLB4Ceg
f,fX]X^/!][#aSe
f,fX]X^/[fRca[
g,!
4=3
The variable v is initially zero and tekes the value 1 (rather than 2) when the button is
clicked.

SOUND
If you require a sound that is not one of the standard system sounds (see 144? above)
and a sound card is installed, you can include small sound samples previously stored
in standard wave file format (.WAV). The wave file must be included in a resource
script or in the resource section of the program. For example:
<hB^d]S B>D=3 S^V]^XbTfPe
The following code illustrates how the sample is played back.
X,fX]X^/³MQcJ1PaZL³ ³B>D=3´ ³<hB^d]S´

STOP
This call-back function closes the window and terminates the program.

SUPER_MAXIMISE
The BD?4AN<0G8<8B4 (the spelling BD?4AN<0G8<8I4 also accepted) call-back is
used to expand a window so that only the client area is visible. This is useful to

211
ClearWin+ User’s Guide Fortran

enable a graphic display to be shown on the entire screen. Programs that use this call-
back should provide an accelerator key or other means to exit from this mode (there
will be no standard or system menu visible).

TEXT
The C4GC call-back can only be invoked from a format window that uses %ht. It
provides a quick way of displaying text in a window. The text itself is provided in a
character string that is placed in the fX]X^/ argument list after this call-back.

TEXT_HISTORY
The C4GCN78BC>AH call-back can only be invoked from a format window that
includes %ht. A dialog box is displayed that shows the hypertext history and allows
the user to select an earlier topic.

TOGGLE
The C>66;4 call-back is used to toggle an 8=C464A variable between 0 and 1. The
variable follows the call-back in the fX]X^/ argument list.

+
Sometimes it is useful to invoke more than one call-back function at once. The ±²
call-back function takes two subsequent call-back functions as arguments and calls
each in turn. The return value from the ±² call-back function is the return from the
second call. For an example of the use of the ±² and 58;4N>?4=A call-back
functions see the description of %aw on page 123. Note that the result of
R[TPafX]NbcaX]V/³20;;102:NA40B>=´ reflects the original reason for the
call-back and not ±².

A simple text editor

The following example uses a number of the above call-back functions. It implements
a simple editor.
F8=0??
8=C464A XfX]X^/
270A02C4A !( UX[T]TfNUX[TWT[_NUX[T
WT[_NUX[T,\hWT[_W[_
X,fX]X^/\]J5X[TJ>_T]LL438CN58;4N>?4=UX[T

212
Chapter 20 Standard call-back functions

X,fX]X^/\]JJBPeTLL 438CN58;4NB0E4]TfNUX[T
X,fX]X^/\]JJBPeT 0bLL438CN58;4NB0E4N0B]TfNUX[T
X,fX]X^/\]JJ4gXcLL 4G8C
X,fX]X^/\]J4SXcJ2^_hLL2>?H
X,fX]X^/\]JJ2dcLL 2DC
X,fX]X^/\]JJ?PbcTLL ?0BC4
X,fX]X^/\]J7T[_J2^]cT]cbLL74;?N2>=C4=CBWT[_NUX[T
X,fX]X^/\]JJ7T[_ ^] WT[_LL 74;?N>=N74;? WT[_NUX[T
X,fX]X^/%!TQ
4=3

213
ClearWin+ User’s Guide Fortran

214
21.

Format code reference

This chapter provides a detailed reference to format codes that can be used with
fX]X^/. New features are continuously being added to ClearWin+, details of which
can be found in the enhancements files on the distribution disks.
An introduction to format windows and the fX]X^/ function is presented on page 22.
It includes general information about format strings and the form of a format code;
about format modifiers, option lists, standard character strings, and help strings. It
also describes the general order in which components appear in the format string and
in the fX]X^/ argument list. Please note that lowercase n and m are used to represent
optional size modifiers, whilst uppercase N and M denote mandatory size modifiers
(e.g. %br).

%ac
Purpose To define an accelerator key.

Syntax fX]X^/³PRJZThNSTbRaX_cX^]L´RQNUd]R
TgcTa]P[ RQNUd]R
Description key_description is a standard character string (can be replaced by @ and a F8=8>/
argument) that may include key words of the form: Rca[, bWXUc, P[c, TbR, ST[, X]b,
b_PRT, QPRZb_PRT, T]cTa, [TUc, aXVWc, d_, S^f], _Vd_, _VS], cPQ, W^\T, T]S,
ZTh_PSNRT]caT, U U !. Character keys must be combined with one or more of
Rca[, bWXUc and P[c, but the forms Rca[P[ccharacter are reserved for use by
the system.

Example fX]X^/³PRJ2ca[BWXUc3T[L´RQNUd]R

215
ClearWin+ User’s Guide Fortran

Syntax fX]X^/³P_´ Xg Xh

X]cTVTa XgXh X]_dc
fX]X^/³OP_´ag ah
S^dQ[T _aTRXbX^] agah X]_dc
Modifiers Grave accent (`) - use 3>D1;4 ?A428B8>= real rather than 8=C464A input.
Description The units of measurement corresponds to the average width and the height of the
default font. Use with care as this format overrides the normal mechanism to prevent
controls overlapping.

Example fX]X^/³P_´ !; %;

Syntax fX]X^/³Pf´ Rca[

X]cTVTa Rca[ X]_dc
Description Used in conjuction a frame (%fr). ctrl is a variable associated with %lw or %cv in the
frame. %aw can be used with %pv.

216
Chapter 21 Format code reference

Notes a) The system menu will contain Ctrl-F4 to close a child window (as opposed to the
parent window), and Ctrl-F6 to move to the next MDI child.
b) As additional children are added to a frame these windows are offset with respect to
the origin to make all windows visible. This offset is not reset to zero when all the
children in a frame are closed.
c) If the standard call-back function 20B2034 is invoked from a window
containing a MDI frame, this will cascade the child windows with the active
window left at the top.

Example See page 124.

Example fX]X^/³QR´ A61/ ! !

fX]X^/³QRJfWXcTL´
See also %bt, %tt, %bg

217
ClearWin+ User’s Guide Fortran

%bd
Purpose To specify all four window borders individually.

Syntax fX]X^/³QS´ [TUc c^_ aXVWc Q^cc^\

S^dQ[T _aTRXbX^] [TUcc^_aXVWcQ^cc^\ X]_dc
Modifiers Grave accent (`) - the arguments are integer pixel values.
Description The units of measurement correspond to the average width and the height of the
default font. The exact size of each border can be set using this format. A negative
value leaves the corresponding border unchanged.

%bf
Purpose To switch to bold font.

Syntax fX]X^/³QU´
Modifiers Grave accent (`) - use the grave to switch off.
Description %bf is cancelled by %`bf, %fn and %sf.

fX]S^fcTgc, RP_cX^]cTgc, PRcXeTQ^aSTa, X]PRcXeTQ^aSTa (use this for

dialog box backgrounds), P__f^aZb_PRT (use this for the MDI backdrop),
WXVW[XVWc (use this when you are adding your own draw focus), WXVW[XVWccTgc,
Qc]UPRT, Qc]bWPS^f, VaThcTgc, Qc]cTgc, X]PRcXeTRP_cX^]cTgc, and
Qc]WXVW[XVWc. The definition of these colours depends on the user’s desktop
configuration (if you require the actual value for an RGB colour, use the API function
GetSysColor with the named colour parameters defined the file windows.ins; e.g.
2>;>AN1C=5024).
colour_value is typically a value returned by A61/.
Use without the grave modifier to set the background colour of the main window. Use
with the grave modifier to set the background colour of the next control (e.g. %rd, %rf,
%rs, %ls, but not %bt).

Example fX]X^/³QV´ A61/ ! !

fX]X^/³QVJfWXcTL´
fX]X^/³QVJQc]UPRTL´ the default button face colour.
See also %bc, %wp

%bh
Purpose To provide a bubble help system.

Syntax fX]X^/³QW´Rca[
X]cTVTa Rca[ X]_dc
Modifiers Grave accent (`) - introduces a delay before the message appears.
Description Set ctrl to 1 in order to enable help messages and to 0 in order to disable messages.

Syntax fX]X^/³=QaJ^_cX^]bL´ UX[[ R^[^daNeP[dT

S^dQ[T _aTRXbX^] UX[[ X]_dc
X]cTVTa R^[^daNeP[dT X]_dc
Modifiers Question mark (?) - a help string is supplied.
Description fill specifies the amount of fill in the range 0 to 1 inclusive.
colour_value is the RGB value of the fill colour.
N is a integer constant giving the length of the bar in average characters.
options may include ]^NQ^aSTa and _TaRT]cPVT, and one of [TUcNaXVWc,
aXVWcN[TUc, c^_NQ^cc^\, Q^cc^\Nc^_. _TaRT]cPVT adds a progress indicator
(in the form of a percentage) to a horizontal bar only.

Example fX]X^/³ $QaJQ^cc^\Nc^_L´ UX[[ A61/!!

Example fX]X^/³O.mM QcJ>:LJ2[XRZ fWT] S^]TL´ VaTh RQNUd]R

(see the example below).

sel is an integer that provides the index of the node that is currently selected.
If a grave accent is provided, bmp_str is a character string giving a list of 16x16
bitmap resources in the form 'bmp1,bmp2'. If a bitmap has a one-pixel border of a
certain colour, then this colour is used as a mask for the bitmap. Pixels with the mask
colour are replaced by the background colour. The default mask is white.
%bv can take a pivot (%pv). Also the right mouse button can be used to trigger a
popup menu (%pm) defined in the parent window. The background colour for %bv is
white and at the moment this cannot be changed.
Example
270A02C4A' XcT\b#
8=C464A bT[
XcT\b ,0411^^Z
XcT\b!,1202WP_cTa
XcT\b",220BTRcX^]
XcT\b#,220BTRcX^] !
bT[,
X,fX]X^/OQe!!XcT\b#bT[Q\_ Q\_!
As for %tv, the first character in each string provides the index for the level of the
node. The second character marks the node as either expanded (E) or collapsed (C).
The third character is only required if a list of bitmaps is provided and gives the index
to select a bitmap from the list.
Options
TSXcN[PQT[b Allows the text for a node to be edited.
bW^fNbT[TRcX^]NP[fPhb Always show the selection, if any, even if the
control does not have the focus.
]^NQ^aSTa Displays the control without a border.
WPbN[X]Tb The tree is displayed with nodes joined by lines.
[X]TbNPcNa^^c The root node also has a line to its left.
Use this with WPbNQdcc^]b if you need buttons at
the first level.
WPbNQdcc^]b +/- expansion buttons are displayed.
_PXaTSNQXc\P_b 'Expanded'/'collapsed' bitmaps are paired in the list.

223
ClearWin+ User’s Guide Fortran

R[TPafX]NX]U^/A>FN=D<14A. If the call-back function returns the value 4

then editing of this node is prevented.
With 438CN:4HN3>F= you can validate each character as it is typed. Use
R[TPafX]NX]U^/:4H1>0A3N:4H to get the key and/or
R[TPafX]NbcaX]V/438C43NC4GC to get the resulting string with the character
inserted. If the call-back function returns the value 4 then the character is not
accepted. If you want to translate the input key to another key then the call-back
function must return the ASCII character code (31<code<256) of the translated key.
With 4=3N438C you can get the result of the edit by the call
R[TPafX]NbcaX]V/438C43NC4GC. If the call-back function returns the value 4
then the new label is rejected the original label is restored. Otherwise, unlike %lv, the
edit is accepted and your data is automatically updated. You cannot delete a node by
accepting a blank entry.
Expanding a node
When a node is expanded or collapsed, the call-back function is called with the reason
8C4<N4G?0=343. You can respond to this (as for %tv) by changing the bitmap
index and calling fX]S^fNd_SPcT/XcT\b. However, it is simpler and much faster
if you use the option _PXaTSNQXc\P_b. If you provide this option, each 'expanded'
bitmap must follow immediately after the corresponding 'collpased' bitmap in the list.
Also the bitmap change is automatically done for you and your data is automatically
modified to reflect the change. You can save and restore the data if you want to reload
the control with the same expanded state.

Call-back reasons
8C4<N4G?0=343 A node has been expanded or collapsed (see above).
1468=N438C A label is about to be edited (see above).
438CN:4HN3>F= The user has pressed a keyboard key during a label edit.
R[TPafX]NX]U^/:4H1>0A3N:4H provides the key
code (see above).
4=3N438C A label has been edited (see above).
B4CNB4;42C8>= A node has been selected.
R[TPafX]NX]U^/A>FN=D<14A provides the index.
<>DB4N3>D1;4N2;82: The user has double-clicked using the left mouse button.
R[TPafX]NX]U^/A>FN=D<14A provides the index.
:4HN3>F= The user has pressed a keyboard key.
R[TPafX]NX]U^/:4H1>0A3N:4H provides the key
code.

Example See page 71.

224
Chapter 21 Format code reference

Syntax fX]X^/³Qg´ ST_cW

S^dQ[T _aTRXbX^] ST_cW X]_dc
Description %bx is used, particularly after %tt or %tb, in order to provide a grey toolbar at the top
of the window. depth is measured as a fraction of the character height and this amount
is added to the height, one half above and one half below the buttons.
%bx can only be used once in any window. Its use is not restricted to %tt and %tb.
%bx creates a grey background from the point where it is used to the top of the
window. It automatically removes the border (as in %ww[no_border]) and the grey
background spans the width of the window.

Example fX]X^/³RPJ4SXc FX]S^fL´

b1 Right mouse button only

b2 Left and right buttons (the default)
b3 Left , right and middle buttons
title1 Title above button boxes
title2 Title above palette
iconic Transparent and inverse transparent selection

Example fX]X^/³R[JQ"cXc[T!,?P[TccTL´R^[^daNeP[dTb

%cn
Purpose To centre text and controls in the window.

Syntax fX]X^/³R]´
Modifiers Grave accent (`) - extends the scope to the remainder of the window.
Description %cn is principally used on text and buttons. It forces everything which follows it, up
to the next new line or form-feed character, to be centred in the window.
When used within a box (%ob) the centring applies within that box.

RWTRZN^]NU^RdbN[^bb Perform checks, calls the call-back, and updates the

corresponding data item only when focus is transferred to
another control. This is particularly valuable if numeric
limits have been imposed by %il/%fl.
SPcPNQ^aSTa Put a border round data boxes (default).
Ud[[NRWTRZ Perform checks and call-back every change (default).
aXVWcNYdbcXUh Align the text to the right border. Not for %el.
[TUcNYdbcXUh Align the text to the left border (default).
]^NSPcPNQ^aSTa Omit border round data boxes. Not for %el.

Example fX]X^/³R^JRWTRZN^]NU^RdbN[^bbL´
See also %rd, %rf, %rs, %re, %el

%cu
Purpose Establishes a cursor for the next control in a format.

Syntax fX]X^/³RdJRdab^aN]P\TL´
fX]X^/³ORd´ R^]bc
X]cTVTa R^]bc X]_dc
fX]X^/³=RdJ]P\T LJ]P\T!L J]P\T=L´bT[
fX]X^/³O=Rd´ R^]bc R^]bc! R^]bc= bT[
X]cTVTa bT[ R^]bc R^]bc! R^]bc= X]_dc
Modifiers Grave accent (`) - cursor is specified by using a ClearWin+ parameter from
windows.ins.
Description cursor_name is a standard character string (can be replaced by @) that is used to

228
Chapter 21 Format code reference

identify a cursor via a resource script.

The alternative uses a grave accent modifier together with const which is one of:

2DAB>AN0AA>F Standard arrow cursor

2DAB>AN8140< Text I-beam cursor

2DAB>ANF08C Hourglass cursor

2DAB>AN2A>BB Cross hair cursor

2DAB>AND?0AA>F Vertical arrow cursor

2DAB>ANB8I4 A square with a smaller square inside its lower-right corner

2DAB>AN82>= Empty icon

2DAB>ANB8I4=FB4 Double-pointed cursor with arrows pointing Northwest and

Southeast
2DAB>ANB8I4=4BF Double-pointed cursor with arrows pointing Northeast and
Southwest
2DAB>ANB8I4F4 Double-pointed cursor with arrows pointing west and east

2DAB>ANB8I4=B Double-pointed cursor with arrows pointing North and South

If const is not one of these values then it is assumed to be a valid Windows API handle
of an existing cursor (cf. %bm and %ic).
Another pair of alternatives uses a positive integer N to provide a selection of N
different cursors. In this case the variable sel is given a value in the range 1 .. N in
order to specify a particular cursor. The examples below illustrate the first pair of
alternatives.

Example fX]X^/³RdJ\hRdabâL´
\hRdabâ 2DAB>A UX[TRda aTb^daRT UX[T
fX]X^/³ORd´2DAB>AN8140<
See also %dc, bTcNRdabâNfPXcX]V/

229
ClearWin+ User’s Guide Fortran

%cv
Purpose To set a control variable for a window.

Syntax fX]X^/³Re´Rca[
X]cTVTa Rca[ ^dc_dc
Description %cv has the same effect as %lw but does not leave the window open. The returned
value of ctrl can be used with %aw.

Syntax fX]X^/³=<RfJ^_cX^]bL´ U^acaP]Nd]Xc

fX]X^/³O=<RfJ^_cX^]bL´ U^acaP]Nd]Xc WP]S[T
X]cTVTa U^acaP]Nd]Xc X]_dc
X]cTVTa WP]S[T ^dc_dc
Modifiers Grave accent (`) - used to return a handle for the window.
Question mark (?) - a help string is supplied.
Description N is the width and M the depth of the window in average characters.
%cw can take a pivot (use %pv before %cw) in order to size the window at run time.
fortran_unit is the unit number of the input/output stream. Use zero for the default
stream.
handle can be used with routines such as bTcN\PgN[X]Tb/.
If a caption, etc. is required (for example to make the window movable) the %cw
format should be embedded in a child window which is itself embedded in the main
window.
The standard call-back functions 2DC, 2>?H and ?0BC4 can be used in this context.
%cw is normally used for output and in particular for debugging.
options can be one or both of ebRa^[[ and WbRa^[[ in order to provide scroll bars.

2DAB>AN0AA>F Standard arrow cursor

2DAB>AN8140< Text I-beam cursor
2DAB>ANF08C Hourglass cursor
2DAB>AN2A>BB Cross hair cursor
2DAB>AND?0AA>F Vertical arrow cursor
2DAB>ANB8I4 A square with a smaller square inside its lower-right corner
2DAB>AN82>= Empty icon
2DAB>ANB8I4=FB4 Double-pointed cursor with arrows pointing Northwest and
Southeast
2DAB>ANB8I4=4BF Double-pointed cursor with arrows pointing Northeast and
Southwest
2DAB>ANB8I4F4 Double-pointed cursor with arrows pointing west and east
2DAB>ANB8I4=B Double-pointed cursor with arrows pointing North and South

231
ClearWin+ User’s Guide Fortran

sel is changed. The examples below illustrate the first pair of alternatives.

Example fX]X^/³SRJ\hRdab^aL´
\hRdab^a 2DAB>A UX[TRda aTb^daRT UX[T
fX]X^/³OSR´2DAB>AN8140<
See also %cu

%dd
Purpose To insert a spin wheel for an integer edit box (%rd) or a string edit box (%rs).

Syntax fX]X^/³SS´ bcT_

X]cTVTa bcT_ X]_dc
Description %dd can be used with %rd in order to provide an attached spin wheel.
step is the size of the increase/decrease. The resulting %rd value will be a multiple of
step. Any call-back function should be attached to %rd. %dd is placed before the %rd
to which it refers.
%dd can also be used with %rs. In this case it should have a non-zero step value
(which is ignored). The subsequent %rs box should have a call-back function which
uses R[TPafX]NbcaX]V/³20;;102:NA40B>=´ to identify the reasons
B?8=ND? and B?8=N3>F=. The call-back function must provide the response to
the spin (for example, by cycling through the days of the week).

Example fX]X^/³SS´ ;
See also %rd, %il, %rs

%de
Purpose To disable some other window while this window is active.

Syntax fX]X^/³ST´Wf]S
X]cTVTa Wf]S X]_dc

232
Chapter 21 Format code reference

Description %de is used to force some other window to be disabled while the current window is
active. This is the default behaviour for other ClearWin+ windows unless %ww is
used. This format is particularly useful in situations in which there are non
ClearWin+ windows present.

%df
Purpose To insert a spin wheel for a floating point value.

Syntax fX]X^/³SU´ bcT_

S^dQ[T _aTRXbX^] bcT_ X]_dc
Description %df can be used with %rf in order to provide an attached spin wheel.
step is the size of the increase/decrease. The resulting %rf value will be a multiple of
step. Any call-back function should be attached to %rf.

Example fX]X^/³SU´ 3

Example fX]X^/³S[´ !3 RQNUd]R

233
ClearWin+ User’s Guide Fortran

%dr
Purpose To provide a call-back that is called when a file or a group of files is dragged and
dropped onto the window.
Syntax fX]X^/³Sa´RQNUd]R
TgcTa]P[ RQNUd]R
Description Use a call to R[TPafX]NbcaX]V/3A>??43N58;4 within the call-back in order
to get the name of the file that has been dropped. If there is more than one file then the
call-back function is called for each in turn. You can use
R[TPafX]NX]U^/3A>??43N2>D=C to get the number of files that have been
dropped (call this n say) and then use R[TPafX]NX]U^/3A>??43N2DAA4=C to
get the index of the current file in the range from 1 to n.

Example See page 125.

Syntax fX]X^/³SfJ^_cX^]bL´ R^]cTgc

X]cTVTa R^]cTgc X]_dc
Modifiers Caret (^)
Question mark (?) - a help string is supplied.
Description context is value returned by a call to VTcNQXc\P_NSR/.
%dw will take a pivot (%pv).
See page 157 for further details.

Notes A value for d of 0.5D0 is equivalent to a half line feed.

%dy has no effect when there is no space for the next item to move into.

Syntax fX]X^/³=<TQJ^_cX^]bL´QdUUTa QdUUNbXiT

fX]X^/³O=<TQJ^_cX^]bL´QdUUTa QdUUNbXiT TSXcNX]U^
RWPaPRcTa QdUUTa X]_dc^dc_dc
X]cTVTa QdUUNbXiT X]_dc
X]cTVTa TSXcNX]U^!# X]_dc^dc_dc
Modifiers Caret (^) - the call-back function is called when a key is pressed or the mouse is
moved.
Question mark (?) - a help string is supplied.
Grave accent (`) - the program supplies edit information. The array name edit_info is
placed in the argument list after any grey control variable and before any call-back
function.
Tilde (~) - adds a variable that controls the grey (enable/disable) state. The variable
should precede the call-back function (if any) in the argument list.
Description An edit box created using %eb provides a wide range of advanced text editing features.
See Chapter 12 for details.

235
ClearWin+ User’s Guide Fortran

N represents the width of the box in average characters. M represents the depth which,
if omitted, defaults to 1.
buffer is a character string for the text which must be terminated with chr(0).
buff_size is the size of the buffer. A zero value may be supplied to allow the edit box to
allocate its own memory re-sizing as required (buffer is ignored).
%eb will take a pivot (%pv).
If the caret modifier (^) is used and the call-back function does not handle the response
to control keys such as Delete, BackSpace, etc., then it should return a zero value.

Syntax fX]X^/³T`JT`dPcX^]L´ fXScW WTXVWc

X]cTVTa fXScW WTXVWc X]_dc
Modifiers Grave accent (`) - avoids a fatal error condition when the equation is not correctly
constructed.
Description width and height provide the dimensions in pixels of a box enclosing the equation. If
the equation is fixed, zero values can be supplied and the size will be automatically
adjusted to fit the contents.
equation is a standard character string (can be replaced by @) that uses the standard
character set except for the three characters {;} that are used to define special symbols.
See page 100 for further details.

Syntax fX]X^/³U[´ [^fTa d__Ta

fX]X^/³OU[´
S^dQ[T _aTRXbX^] [^fTa d__Ta X]_dc
Modifiers Grave accent (`) - cancels an earlier %fl and restores the limits to the minimum and
maximum for the data type.
Description lower is the lower limit and upper is the upper limit.

Example fX]X^/³U[´ 3 3

See also %rf, %df, R^JRWTRZN^]NU^RdbN[^bbL

239
ClearWin+ User’s Guide Fortran

%fn
Purpose To select a font for subsequent text.

Syntax fX]X^/³U]JU^]cN]P\TL´
Description font_name is a standard character string (can be replaced by @) that provides the name
of a font that is in the user’s system.
%fn cancels %bf but not %it and %ul.

Example fX]X^/³U]JCX\Tb =Tf A^\P]L´

Syntax fX]X^/³Ua´ fXScW WTXVWc

fX]X^/³OUa´ fXScW WTXVWc Rca[
X]cTVTa fXScW WTXVWc X]_dc
X]cTVTa Rca[ ^dc_dc
Modifiers Caret (^) - call-back function is called when the topmost child window changes.
Grave accent (`) - used to provide access to the handle of the current child window.
Description width and height give the width and height of the frame in pixels.
If %fr is preceded by %pv then the frame can be re-sized at run time.
ctrl is returned as the handle of the currently selected child window (see %hw) or zero
if none is selected.
A given window cannot contain more than one frame.
Notes The call-back function is called with the ‘reason’ <38N?064NCDA= (see
R[TPafX]NbcaX]V/) whenever the topmost child window changes. Typically this
would be used in conjunction with the grave accent to get the handle of the topmost
window in a variable.

Example See page !#.

240
Chapter 21 Format code reference

Example fX]X^/³UcJCTgc UX[TbLJcgcL´

See also %fs, VTcNUX[cTaTSNUX[T/ bTcN^_T]NSXP[^VN_PcW/

241
ClearWin+ User’s Guide Fortran

%ga
Purpose To enable radio buttons and/or bitmap buttons to be ganged together so that if one is
switched on, all the others are switched off.
Syntax fX]X^/³=VP´bcPcT bcPcT! bcPcT=
X]cTVTa bcPcT bcPcT! bcPcT= ^dc_dc
Modifiers Grave accent (`) - used to specify that one control is always on.
Description N is a positive integer greater than 1. state1 . . stateN are the on/off state controls for
radio buttons and/or bitmap buttons defined elsewhere. A given state variable can be
used in more than one control (%rb and/or %tb). However, it is unusual for a variable
to appear in more than one %ga format for a given window. If it does then there must
only be one variable that is common and the effect is to merge the two gang sets. If the
grave accent is used on one of the gangs then it must be used on both.

Example fX]X^/³"VP´aQ aQ! aQ"

Syntax fX]X^/³VaJ^_cX^]bL´ fXScW WTXVWc

fX]X^/³OVaJ^_cX^]bL´ fXScW WTXVWc WP]S[T
X]cTVTa fXScW WTXVWc WP]S[T X]_dc
Modifiers Grave accent (`) - used to input a handle for the graphics area.
Caret (^) - used to supply a call-back function.
Question mark (?) - a help string is supplied.
Description width and height provide the pixel dimensions of the area. handle is a programmer-
supplied handle to distinguish between different graphics areas.
%gr can be preceded with %pv in order to re-size the area at run time. For details and
a list of the options see Chapter 15.

Example RP[[ PSSNWh_TacTgcNaTb^daRT/³WT[_´

fX]X^/³_eM%!WcJ2^]cT]cbL´RQNUd]R
WT[_ 7H?4AC4GC UX[TWc\ aTb^daRT UX[T
See also %pv

%hw
Purpose To return the handle of the current window.

Syntax fX]X^/³Wf´ WP]S[T

X]cTVTa WP]S[T ^dc_dc
Description The returned value can be used in calls to Windows API functions and is the same as
that given by R[TPafX]NX]U^/³;0C4BCN5>A<0CC43NF8=3>F³. You can test if
the current window has the focus by calling R[TPafX]NX]U^/³5>2DBNF8=3>F³.

Syntax fX]X^/³Wg´ _PVTNbcT_ \PgNeP[ RdaNeP[

X]cTVTa _PVTNbcT_ \PgNeP[ X]_dc
X]cTVTa RdaNeP[ X]_dc^dc_dc
Modifiers Caret (^) - the call-back is called when the user clicks on the scroll bar.
Description cur_val is the value that corresponds to the position of the scroll box (also called the
thumb). It returns a value between zero and max_val - 1.
page_step is the amount that cur_val is to be increased/decreased when the user clicks
on the scroll bar (other than on the thumb). For a document, page_step will be set to
the number of lines that are to be displayed in the window and max_val should be set
to n - page_step, where n is the total number of lines in the document.
With %hx and %vx the three arguments cur_val, page_step and max_val can be
passed as variables and changed dynamically with a call to fX]S^fNd_SPcT/
A call to R[TPafX]NX]U^/³8=C4A<4380C4NB2A>;;´ will determine if the
callback was called whilst the thumb was moving. A return value of 1 indicates
movement whilst zero indicates that the thumb is stationary. Both of these events
occur at the end of a move.
%hx and %vx should not be used with controls like %eb and %cw which have their
own scroll bar mechanism.

Example fX]X^/³MWg´ $; !; _^b RQNUd]R

to (200,200,200). To avoid this problem use (191,191,191) as the backgroound colour.

Example See page 58.

Syntax fX]X^/³X[´ [^fTa d__Ta

fX]X^/³OX[´
X]cTVTa [^fTa d__Ta X]_dc
Modifiers Grave accent (%`il) - cancels an earlier %il and restores the limits to the minimum and
maximum for the data type.
Description lower is the lower limit and upper is the upper limit.

Example fX]X^/³X[´ ; ;

See also %rd, %dd, %co[check_on_focus_loss]

%it
Purpose To switch to italic font.

Syntax fX]X^/³Xc´
Modifiers Grave accent (%`it) - used to switch off the effect.
Description %it is cancelled by %`it and %sf.

Syntax fX]X^/³[R´ WP]S[T

X]cTVTa WP]S[T ^dc_dc
Description The returned value can be used in calls to Windows API functions. For example
controls that do not have grey control variable can be greyed by using %lc to obtain the
window handle and then calling the API function EnableWindow.

250
Chapter 21 Format code reference

Syntax fX]X^/³[SJ^_cX^]bL´ aVQNeP[dT

X]cTVTa aVQNeP[dT X]_dc
Description rgb_value is usually set by a call to A61/. By supplying a variable for rgb_value the
value can be changed dynamically with a call to fX]S^fNd_SPcT/.
options can take the keyword b`dPaT in order to change from a disk to a square shape
and/or the keyword Q[X]ZX]V to provide a flashing effect by switching between the
given colour and black at approximately half second intervals.

Example fX]X^/³[S´ A61/!$$

%ls
Purpose To insert a list box or combo box.

Syntax fX]X^/³]\[bJ^_cX^]bL´XcT\b]d\NXcT\bRdaNXcT\
fX]X^/³m]\[bJ^_cX^]bL´XcT\b]d\NXcT\bRdaNXcT\
VaThNRca[
RWPaPRcTa] XcT\b]d\NXcT\b X]_dc
X]cTVTa ]d\NXcT\b X]_dc _PaP\TcTa
X]cTVTa RdaNXcT\ X]_dc^dc_dc
X]cTVTa VaThNRca[ X]_dc
Modifiers Grave accent (`) - used to provide a drop-down combo box (for editable lists see %el).
Caret (^) - call-back function is called when the user selects an item.
Question mark (?) - a help string is supplied.
Tilde (~) - adds a variable that controls the grey (enable/disable) state.
Description n and m are optional (m cannot be specified without n). n represents the width of the
listbox in characters and m the depth. n and m can be replaced by asterisks (*) in
which case the values of n and m must be supplied as the first two arguments in the

251
ClearWin+ User’s Guide Fortran

argument list.
num_items is the number of items in the list.
cur_item is the item number that is selected in the range zero to num_items both on
input and output. Zero signifies that no item is selected.
items is an array of text entries, one for each item. Blank entries at the end of the list
are not displayed. This means that you can use blank entries to create a list that can be
changed dynamically.
If the grave accent is used and a call-back is supplied, option can be set to the keyword
TgcT]STS. The result is that the call-back is called when the list drops down or closes
up. These events must be detected from the call-back by calling
R[TPafX]NbcaX]V/³20;;102:NA40B>=´ which returns 3A>?3>F= or
2;>B4D?.
For a list box (i.e. when a grave accent modifier is not used), the option WbRa^[[QPa
provides a horizontal scroll bar whilst the option \d[cXR^[d\] provides a multiple
column output (see page 62).
If the grave acent modifier is not used, %ls can be preceded by a pivot %pv.
grey_ctrl is 1 (enabled) or 0 (disable/greyed). Any call-back function must be placed
after this control variable.
Notes The %ls control is limited to 32768 characters.

Example RWPaPRcTa ]P\Tb#

fX]X^/³MO[b´ ]P\Tb #; bT[ RQNUd]R
See also %el, %ms, %lv, %pb, %ps

%lv
Purpose To include a list view control.

Syntax fX]X^/³[eJ^_cX^]bL´fXScWWTXVWcXcT\b]d\NXcT\bbT[eXTf
fX]X^/³O[eJ^_cX^]bL´fXScWWTXVWcXcT\b]d\NXcT\bbT[
eXTfXR^]Nbca
RWPaPRcTa XcT\b]d\NXcT\b X]_dc^dc_dc
X]cTVTa ]d\NXcT\b X]_dc _PaP\TcTa
X]cTVTa bT[]d\NXcT\b X]_dc^dc_dc
X]cTVTa fXScWWTXVWceXTf X]_dc

252
Chapter 21 Format code reference

RWPaPRcTa XR^]Nbca X]_dc

Modifiers Grave accent (`) - used to provide a list of icons.
Caret (^) - call-back function is provided.
Question mark (?) - a help string is supplied.
Description A list view control is a window that displays a collection of items, each item consisting
of an optional icon and a label. List view controls provide several ways of arranging
items and displaying individual items. For example, additional information about each
item can be displayed in columns to the right of the icon and label. This arrangement is
called a report view. Microsoft Explorer uses a list view control in order to display
directory information.
width and height provide the dimensions of the control in pixels.
num_items is an integer constant giving the number of rows in the report view. Blank
rows are not displayed in the control. This means that the number of rows that are
displayed can be changed under program control. The first blank row terminates the
input.
items is an array of num_items+1 character strings the first describing the column
headers and widths, then one string describing each row in turn (see the example below).
sel is an integer array whose elements are set to 1 if the item is selected otherwise to
zero.
view is an integer variable in the range 0..3 that represents the type of view. 0=Icon
view; 1=Report view; 2=Small icon view; 3=List view. These are available even when
no icons are provided.
If a grave accent is provided, icon_str is a character string giving a list of icon resources
in the form 'icon1,icon2'.
%lv can take a pivot (%pv). Also the right mouse button can be used to trigger a popup
menu (%pm) defined in the parent window.
Example
270A02C4A' XcT\b#
8=C464A bT["eXTf
XcT\b ,k7TPSTaN kN$
XcT\b!,k08cT\ k3PcP
XcT\b",k18cT\!k3PcP!
XcT\b#,k18cT\"k3PcP"
bT[ , *bT[!,*bT[",*eXTf,
X,fX]X^/O[e"!XcT\b"bT[eXTfXR^] XR^]!
Here we have 3 rows with 2 columns. items(1) provides data for the column headings

253
ClearWin+ User’s Guide Fortran

and widths. The first character defines the separator between the data for each column.
In this example, the first column has the caption "Header". A trailing underscore
followed by an integer provides the pixel width of the column. If this is ommitted then
the length of the text defines the width. In this example the second column header is
blank and the second column width is 50 pixels. The number of characters (80 in this
case) must be sufficient to allow ClearWin+ to add the column width to each heading (4
characters per column).
items(2) provides data for the first row of a report. Again the first character defines the
separator. The second character defines the icon as an index (A,B,C...) into the list of
icons 'icon1,icon2' (when a grave accent is used). Next comes the label and then the
data for column two etc..
Options
bX]V[TNbT[TRcX^] Allows only one item at a time to be selected.
By default Shift and Control keys can generate multiple
selections.
TSXcN[PQT[b Allows item text to be edited (first column in report view).
]^NR^[d\]NWTPSTab Column headers are not displayed in report view
(items(1) is still needed for column widths)
bW^fNbT[TRcX^]NP[fPhb Always show the selection, if any, even if the control does
not have the focus.
]^NQ^aSTa Displays the control without a border.
]^N[PQT[NfaP_ Displays the item label on a single line in an icon view.
P[XV]Nc^_ Items are top-aligned in icon and small icon view.
P[XV]N[TUc Items are left-aligned in icon and small icon view
TSXcNRT[[b Allows all columns in the report view to be edited (see below).

Label editing
TSXcN[PQT[b enables label editing and requires a call-back function that can test for
the call-back reasons 1468=N438C, 4=3N438C and 438CN:4HN3>F=.
With 1468=N438C you can get the index of the selected item by the call
R[TPafX]NX]U^/A>FN=D<14A. If your call-back function returns the value 4
then editing of this item is prevented.
With 438CN:4HN3>F= you can validate each character as it is typed. Use
R[TPafX]NX]U^/:4H1>0A3N:4H to get the key and/or
R[TPafX]NbcaX]V/438C43NC4GC to get the resulting string with the character
inserted. If the call-back function returns the value 4 then the character is not accepted.
If you want to translate the input key to another key then the call-back function must
return the ASCII character code (31<code<256) of the translated key.
With 4=3N438C you can get the result of the edit by the call
R[TPafX]NbcaX]V/438C43NC4GC. Having validated the label, you should then

254
Chapter 21 Format code reference

get the index using R[TPafX]NX]U^/A>FN=D<14A and reconstuct the relevant

row of the items array by adding an icon identifier and extra column data as required
(otherwise the original data will be restored). Creating a blank row in response to a
label edit is not recommended.
Selecting a view
It is possible to create a menu item or a toolbar button that changes the view state (Icon
view, Report view, Small icon view, List view). Here is some sample code for the
associated call-back function.
8=C464A 5D=2C8>= RWP]VTNeXTf
8=C464A eXTf
2><<>= eXTf
eXTf,eXTf
85eXTf + eXTf,"
20;; fX]S^fNd_SPcT/eXTf
RWP]VTNeXTf,!
4=3
Column widths
If the last column does not extend to the right of the control then ClearWin+ will adjust
the width of this column so that it fills the area.
If a column width is changed at run time then ClearWin+ stores the new width in row 1
of the data. This means that the adjusted widths will be used when the control is
redrawn. If you want to use the same widths when the program is re-used then you will
need to save and restore the modified data.
Cell editing
The option TSXcNRT[[b is effective in a report view where it over-rides TSXcN[PQT[b.
By using TSXcNRT[[b you can edit the data in any column. A grid is displayed
resulting in a spreadsheet appearance. The call-back function can be used to prevent the
editing of any given cell and to validate each input character and as well as the final
result. For this purpose TSXcNRT[[b uses the call-back reasons 1468=N438C,
438CN:4HN3>F= and 4=3N438C etc. as in TSXcN[PQT[b. The only difference is that
unlike TSXcN[PQ[Tb, TSXcNRT[[b initially responds to a single mouse click.
R[TPafX]NX]U^/A>FN=D<14A and R[TPafX]NX]U^/2>;D<=N=D<14A
identify the cell that is being edited.
When editing cells, use the arrow keys to move vertically and horizontally and CTRL
with arrow keys to move horizontally once editing has commenced. This movement will
step over any cells that are disabled. The selection array (with one element for each row)
contains the row number of the current selection. However, when validating input it is
simpler to use R[TPafX]NX]U^/2>;D<=N=D<14A.

255
ClearWin+ User’s Guide Fortran

Call-back reasons
1468=N438C A label or cell is about to be edited (see above).
438CN:4HN3>F= The user has pressed a keyboard key during a label or cell
edit. R[TPafX]NX]U^/:4H1>0A3N:4H provides the
key code (see above).
4=3N438C A label or cell has been edited (see above).
B4CNB4;42C8>= A item has been selected.
R[TPafX]NX]U^/³A>FN=D<14A´ provides the index.
2>;D<=N2;82: The user has clicked on a column header.
R[TPafX]NX]U^/³2>;D<=N=D<14A´ provides the index.
<>DB4N3>D1;4N2;82: The user has double-clicked using the left mouse button.
R[TPafX]NX]U^/³A>FN=D<14A´ provides the index.
:4HN3>F= The user has pressed a keyboard key.
R[TPafX]NX]U^/³:4H1>A03N:4H´ provides the key
code.
In reponse to a column click you might choose to sort the items using the given column
index. Having reconstructed the data, you should then make a call to
fX]S^fNd_SPcT/XcT\b in order to view the new order.
Example See page 65.

Syntax fX]X^/³\V´ \bVN]^ RQNUd]R

X]cTVTa \bVN]^ X]_dc
TgcTa]P[ RQNUd]R
Description This format provides direct access to specified Windows messages. It should be used
with care since it is possible to interfere with other ClearWin+ processing.
msg_no is the message number of the message to be processed. User numbers should
begin at WM_USER +1000. cb_func is the call-back function that is to be called when
the message is received. The call-back function can use R[TPafX]NX]U^/ with the
strings <4BB064N7F=3, <4BB064NF?0A0<, and <4BB064N;?0A0< in order
to get the standard arguments for a Windows call-back function.
When writing the %mg call-back function, use a return value of 3 if you want
ClearWin+ to apply the default processing of the message msg_no. Other values have
the usual effect (zero closes the window etc.) but cause the default processing to be
bypassed. Occasionally the internal Windows dialog procedure that processes
messages requires a particular return other than the default value which is zero (e.g.
under certain conditions when using WM_NOTIFY). In this case you should make a
call to the subroutine bTcN\VNaTcda]NeP[dT/ before returning. This subroutine
takes one integer argument which is the value to be returned by the internal Windows
dialog procedure.

X]cTVTa WP]S[T X]_dc

Modifiers Grave accent (`) - use a Windows API handle.
Description icon_name is a standard character string (can be replaced by @) associated with the
name of an icon file in a resource script.
handle is a value returned by a modified form of the API function LoadIcon.

Example fX]X^/³\XJ\hXR^]L´
\hXR^] 82>= UX[TXR^ aTb^daRT UX[T
See also \PZTNXR^]/, %ic

%mn
Purpose To attach a menu to the window.

Syntax fX]X^/³\]J\T]dNb_TRL´
Modifiers Question mark (?) - All the strings are placed in order at the end of the format
description, one for each and every menu item that has a call-back function.
Grave accent (`) -Creates an enhanced menu (see page 86).
Description See page 81.

Syntax fX]X^/³]\\bJ^_cX^]bL´ XcT\b ]d\NXcT\b bT[

RWPaPRcTa] XcT\b]d\NXcT\b X]_dc
X]cTVTa ]d\NXcT\b X]_dc _PaP\TcTa
X]cTVTa bT[]d\NXcT\b X]_dc^dc_dc
Modifiers Grave accent (`) - used to provide multiple selection using the CTRL and SHIFT keys
and mouse dragging.
Caret (^) - call-back function is called when the user selects an item.

258
Chapter 21 Format code reference

Question mark (?) - a help string is supplied.

Description n and m are optional (m cannot be specified without n). n represents the width of the
listbox in characters and m the depth.

The list of possible options is currently empty. This item is included for future
developments. If you include a help string in square brackets then you must also
include an empty options list.
num_items is the number of items in the list. If m is less than num_items then a scroll
bar is presented.
sel is an array whose elements are set to 1 if the item is selected otherwise to zero.
items is an array of text entries, one for each item. Blank entries at the end of the list
are not displayed. This means that you can use blank entries to create a list that can be
changed dynamically.
%ms will take a pivot %pv.

Example RWPaPRcTa ]P\Tb#

X]cTVTa bT[#
fX]X^/³MO\b´ ]P\Tb #; bT[ RQNUd]R
See also %ls, %el, %lv, %pb, %ps

%mv
Purpose To provide a call-back function that is to be called when the user moves or resizes the
window.
Syntax fX]X^/³\e´ RQNUd]R
TgcTa]P[ RQNUd]R
Modifiers Grave accent (`) - without the grave the call-back is for a moving window; with the
grave the call-back is for a resizing window.
Description The call-back function is also called when the window is created (if two are used, one
for moving and one for re-sizing, then both are called).
The call-back function will typically call the Clearwin+ function
VTcNfX]S^fN[^RPcX^]/ in order to determine the new size and position.
Note that certain window operations involve both moving and resizing. For example if
the user drags the top-left corner, then the window is both moved and resized
(‘moving’ changes the co-ordinates of the top left corner, ‘resizing’ changes the width

259
ClearWin+ User’s Guide Fortran

and/or height).

options list that sets a title to the box.

options is can be one or more of:

]P\TSNR Splices a name into the top line of the box (in the centre)
]P\TSN[ Splices a name into the top line of the box (on the left).
]P\TSNa Splices a name into the top line of the box (on the right)
]P\TS The same as ]P\TSNR.
]P\T[Tbb Occupies the same vertical space as ]P\TSNR etc. but has no
name.
]^NQâSTa Create an invisible box which is useful for grouping controls.
X]eXbXQ[T The same as ]^NQâSTa.
_P]T[[TS This replaces the simple line box with a 3-dimensional panel.
cWX]N_P]T[[TS Similar to panelled but perhaps a slightly more attractive effect.
bWPSTS This has the same effect as the use of the grave accent.
bcPcdb This provides a box in the form of a status bar.
Q^cc^\NTgXc Begins the next control below this box rather than to the right.
bRâTS Double line, 3-dimensional shade effect.
ST_aTbbTS Single line, 3-dimensional shade effect.
aPXbTS Single line, 3-dimensional shade effect

When n and m are used, %ob creates a rectangular grid of boxes (n across, m down)
each requiring its own %cb. Thus %3.2ob would require six %cb codes. A title cannot
be supplied for a grid of boxes. When used with the option ]^NQ^aSTa, this provides
a mechanism for positioning text and controls within rectangular sub regions of the
window (see the section on page 91 for a simple example).
%ap can be used before %ob in order to specify the position of the box from the %ap
arguments.
Notes %ob boxes can be nested, one within another, in order to provide a fine control over
the positioning of items in a window.
The options bR^aTS, ST_aTbbTS and aPXbTS should not be used with a background
colour of white or black (grey is typical).

Example fX]X^/³^QJ]P\TSNaLJATbd[cbL´
See also %ap

262
Chapter 21 Format code reference

%og
Purpose To create an OpenGL graphics region (Win32 only).

Syntax fX]X^/³^VJ^_cX^]bL´ fXScW WTXVWc

X]cTVTa fXScW WTXVWc X]_dc
Description %og takes two arguments namely the pixel width and pixel height of the region and
sets up an OpenGL graphing region. %og only works under Win32, and requires the
presence of associated DLLs. See Chapter 16 for further details.

%pb
Purpose To insert a parameter box.

Syntax fX]X^/³=<_QJ^_cX^]bL´
Modifiers Question mark (?) - can be attached to %dp, %fp, %tp, %ep and %up.
Description N is the width of the box in average characters. M is the number of lines in the control
which will include a scroll bar if M is not large enough.
options can be omitted or can take the value b^acTS to specify that the parameters are
to be alphabetically sorted by name.
After a parameter block has been defined parameters can be attached by subsequent
formats thus:
S_ - Integer parameter
U_ - Floating point parameter
c_ - Text parameter
T_ - Enumerated parameter (a set of named alternatives)
d_ - User parameter (just activates a call-back)
Each of these codes is followed by a standard character string that provides the text to
be displayed. See page 42 for further information.

Syntax fX]X^/³_[J^_cX^]bL´ fXScW WTXVWc

X]cTVTa fXScW WTXVWc X]_dc
Modifiers Question mark (?)
Description In order to use the SIMPLEPLOT graphics drawing library, the executable must have
access to a DLL called simple.dll. This DLL is supplied with Salford compilers.
When making direct calls to the SIMPLEPLOT library (see the dbTaNSaPf] option),
the program must also be linked using the DLL.
width and height represent the pixel dimensions of a SIMPLEPLOT graphics region
within the window. Information about the options that are available is given in
Chapter 17. Some of the options take additional arguments. Data that is real must be
passed as double precision values despite the fact that the SIMPLEPLOT library uses
only single precision arithmetic.
Data that is provided via additional arguments should normally be available thoughout
the life time of the window. This enables the window to be re-drawn, for example after
a re-sizing operation.

Syntax fX]X^/³_\J\T]dNb_TRL´

Modifiers Question mark (?) - All the strings are placed in order at the end of the format
description, one for each and every menu item that has a call-back function.

264
Chapter 21 Format code reference

Grave accent (`) -Creates an enhanced menu (see page 86).

Description Provides a popup menu so that when the right mouse button is pressed in the main
window a menu appears. The menu does not appear when the mouse points to a
control within the main window.
See page 84 for further details.

Syntax fX]X^/³=_b´ bWTTc bWTTc! bWTTc=

fX]X^/³O=_b´ bWTTc bWTTc! bWTTc= bWTTcN]
X]cTVTa bWTTc bWTTc! bWTTc= X]_dc
X]cTVTa bWTTcN] X]_dc^dc_dc
Modifiers Grave accent (`) - provides for a handle (sheet_n) to set and return the current sheet
number. sheet_n must be SAVEd or global (e.g. in a module or common block).
Caret (^) - the call-back function is called each time the sheet is changed and when the
first sheet is initially displayed.
Description N is the number of sheets. sheet1 to sheetN are handles for the various sheets returned
by %sh.
Each sheet is set up using a complete fX]X^/ format and %sh.
R[TPafX]NX]U^/B744CN=> can be used to return the current visible sheet
number which is initially set to one. Alternatively, a grave accent modifier can be
supplied in order to set the initial sheet (at a value other than one) and to change the
sheet number under program (rather than user) control. The program can change the
sheet number by changing bWTTcN] and calling
bTTN_a^_TachbWTTcN_PVT/bWTTcN]
%ca can be used with %sh to provide a caption. The caption can include an
accelerator key indicator ‘&’ which operates in the same way as in a menu or on a
button to select the sheet.
If a call is made to the Windows API function EnableWindow to disable one sheet,
then that sheet will no longer be selectable unless/until the window is re-enabled. If
the sheet that is currently visible is disabled, another sheet will not automatically be
selected. However, when another sheet is selected, a disabled sheet will not be re-

265
ClearWin+ User’s Guide Fortran

selectable.

Notes If an individual sheet is closed (e.g. by placing a button without a callback function in
the sheet) then the parent window will close.

Syntax fX]X^/³aQJQdcc^]NcTgcL´ Rca[

fX]X^/³maQJQdcc^]NcTgcL´ Rca[ VaThNRca[
X]cTVTa Rca[ X]_dc^dc_dc
X]cTVTa VaThNRca[ X]_dc
Modifiers Grave accent (`) - provides a check box rather than a radio button.
Caret (^) - call-back is called when the control is selected.
Question mark (?) - a help string is supplied.
Tilde (~) - adds a variable that controls the grey (enable/disable) state.
Description button_text is a standard character string (can be replaced by @) for the text attached
to the radio button. To change the text dynamically use %lc and the API function
SetWindowText.
ctrl is 1 (on) or 0 (off).
grey_ctrl is 1 (enabled) or 0 (disable/greyed). A call-back function (if present) is
placed after this control variable.

266
Chapter 21 Format code reference

%rb can be used in conjunction with the gang format code %ga. Note that it is not
conventional to gang check boxes.

Example fX]X^/³aQJ1dcc^] L´ aQ

Syntax fX]X^/³]aSJ^_cX^]L´ eP[dT

fX]X^/³m]aSJ^_cX^]L´ eP[dT VaThNRca[
X]cTVTa eP[dT X]_dc^dc_dc
X]cTVTa VaThNRca[ X]_dc
Modifiers Grave accent (`) - makes the control read-only (no box is supplied, see %co).
Caret (^) - the call-back is called when a change is made (see also %co).
Question mark (?) - a help string is supplied.
Tilde (~) - adds a variable that controls the grey (enable/disable) state.
Description n is optional and specifies the number of average width characters in the displayed
output. Only values in range can be entered (see %co). The range can be set using
%il.
If %`rd is specified, then the value presented can only be changed by the program
using fX]S^fNd_SPcT/eP[dT.
grey_ctrl is 1 (enabled) or 0 (disable/greyed). A call-back function (if present) is
placed after this control variable.
option can be set to the keyword X]XcXP[[hNQ[P]Z in order to create an edit box that
is initially empty.
The standard call-back functions 2>?H, 2DC, and ?0BC4 can be used in this
context by attaching them to menu items and/or accelerator keys.
When %dd is used before %rd, a spin wheel is added (see %dd for details).
The subroutine bTcNWXVW[XVWcTS/ can be called to select all of the text in the edit
box. It takes one argument which is the handle given by %lc.

Syntax fX]X^/³=<aTJ^_cX^]bL´ QdUUTa

fX]X^/³m=<aTJ^_cX^]bL´ QdUUTa VaThNRca[
RWPaPRcTa QdUUTa X]_dc^dc_dc
X]cTVTa VaThNRca[ X]_dc
Modifiers Grave accent (`) - makes the control read-only (scroll bars are disabled).
Caret (^) - the call-back is called when a change is made.
Question mark (?) - a help string is supplied.
Tilde (~) - adds a variable that controls the grey (enable/disable) state.
Description This control is similar to %rs but is multi-line. It has a buffer limit of 32K characters.

N represents the width of the box in average characters. M represents the depth which
should not be less than 2.
buffer is a character string for the text (maximum of 32*1024 characters).
The following options are available:

D??4A20B4 Alphabetical characters (a . . z) are converted to upper case and

displayed and stored as upper case.
;>F4A20B4 Alphabetical characters (A . . Z) are converted to lower case and
displayed and stored as lower case.
24=CA4NC4GC Text is always centred on every line.
A867CNC4GC Text is right justified on every line (the default is left justified text).
=>N7B2A>;; The text will not scroll to the right past the end of the window.
The text will auto wrap.
=>NEB2A>;; The text will not scroll beyond the bottom of the window.
7B2A>;;10A A horizontal scroll bar is added - do not use with =>N7B2A>;;
EB2A>;;10A A vertical scroll bar is added - do not use with =>NEB2A>;;.
:44?N5>2DB When the user tabs between windows, normally the focus will be
lost, however with :44?N5>2DB the selected text will remain
selected.

Notes The %rs ?0BBF>A3 option is not available with %re. %re does not take a pivot (%pv).

268
Chapter 21 Format code reference

%co can be used with %re.

Syntax fX]X^/³]aUJ^_cX^]L´ eP[dT

fX]X^/³m]aUJ^_cX^]L´ eP[dT VaThNRca[
S^dQ[T _aTRXbX^] eP[dT X]_dc^dc_dc
X]cTVTa VaThNRca[ X]_dc
Modifiers Grave accent (`) - makes the control read-only (no box is supplied, see %co).
Caret (^) - the call-back is called when a change is made (see also %co).
Question mark (?) - a help string is supplied.
Tilde (~) - adds a variable that controls the grey (enable/disable) state.
Description n is optional and specifies the number of average width characters in the displayed
output. Only values in range can be entered (see %co). The range can be set using
%fl. Values are entered in decimal or exponent form.
If %`rf is specified, then the value presented can only be changed by the program using
fX]S^fNd_SPcT/eP[dT.
grey_ctrl is 1 (enabled) or 0 (disable/greyed). A call-back function (if present) is
placed after this control variable.
option can be set to the keyword X]XcXP[[hNQ[P]Z in order to create an edit box that
is initially empty.
The standard call-back functions 2>?H, 2DC, and ?0BC4 can be used in this
context by attaching them to menu items and/or accelerator keys.
When %df is used before %rf, a spin wheel is added (see %df for details).
The subroutine bTcNWXVW[XVWcTS/ can be called to select all of the text in the edit
box. It takes one argument which is the handle given by %lc.

Syntax fX]X^/³a_´ Xg Xh

X]cTVTa XgXh X]_dc
fX]X^/³Oa_´ag ah
S^dQ[T _aTRXbX^] agah X]_dc
Modifiers Grave accent (`) - use real rather than integer input.
Description The units of measurement correspond to the average width and the height of the

270
Chapter 21 Format code reference

default font.

Example fX]X^/³a_´ '; ;

Syntax fX]X^/³]abJ^_cX^]bL´ bcaX]V

fX]X^/³m]abJ^_cX^]bL´ bcaX]V VaThNRca[
RWPaPRcTa bcaX]V X]_dc^dc_dc
X]cTVTa VaThNRca[ X]_dc
Modifiers Grave accent (`) - makes the control read-only (no box is supplied, see %co).
Caret (^) - the call-back is called when a change is made (see %co).
Question mark (?) - a help string is supplied.
Tilde (~) - adds a variable that controls the grey (enable/disable) state.
Description For the equivalent multi-line edit box see %re.

n is optional and specifies the number of average width characters in the displayed
output. The output will scroll horizontally within the specified width if necessary.
If %`rs is specified, then the string presented can only be changed by the program
using fX]S^fNd_SPcT/eP[dT.
grey_ctrl is 1 (enabled) or 0 (disable/greyed). If a call-back function is used, it is
placed after this control variable.
The standard call-back functions 2>?H, 2DC, and ?0BC4 can be used in this
context by attaching them to menu items and/or accelerator keys.
When %dd is used before %rs, a spin wheel is added (see %dd for details).
The subroutine bTcNWXVW[XVWcTS/ can be called to select all of the text in the edit
box. It takes one argument which is the handle given by %lc.
The following options are available:

?0BBF>A3 An asterisk (*) appears on the screen for each character typed
whilst the string is correctly stored.

271
ClearWin+ User’s Guide Fortran

D??4A20B4 Alphabetical characters (a . . z) are converted to upper case and

displayed and stored as upper case.
;>F4A20B4 Alphabetical characters (A . . Z) are converted to lower case and
displayed and stored as lower case.

Syntax fX]X^/³bR´ RQNUd]R

TgcTa]P[ RQNUd]R
Description Causes a given call-back to be called once only when a window is initially displayed
(for example, for drawing initial %gr data).
Notes If %gr (say) has a call-back function that receives the A4B8I4 message from
R[TPafX]NX]U^/³20;;102:NA40B>=´, this message is received before the %sc
call-back is called.
Call-back functions can often be shared by different format codes within one format
window. For example, a call-back associated with %sc may also be suitable for %mv.

%sd
Purpose To provide subscript text.

Syntax fX]X^/³bS´
Modifiers Grave accent (`) - cancels the effect of an earlier %sd.
Description This format code cannot be applied to the default font so select a font and then enclose
the text that is to be subscripted between %sd and %`sd.

Example fX]X^/³U]JPaXP[LFPcTa Xb 7bS!ObS>´

Syntax fX]X^/³bW´ WP]S[T

X]cTVTa WP]S[T ^dc_dc
Description Each time %sh is used, it creates a window that is to be linked to %ps. The returned
value of handle is an input value for %ps.
Each sheet can be provided with a caption using %ca. In this situation the caption can
include an ampersand (&) to mark an accelerator key.

! hazard ‘!’ road sign

? question mark in bubble
* information ‘i’ in bubble
# stop ‘X’ on disc.
n is optional and can be added in order to centre the icon vertically to the left of n lines
of text.

Example fX]X^/³bX´
See also %ic

%sl
Purpose To insert a slider control.

Syntax fX]X^/³=b[J^_cX^]L´ eP[dT \X] \Pg

S^dQ[T _aTRXbX^] \X] \Pg X]_dc
S^dQ[T _aTRXbX^] eP[dT X]_dc^dc_dc
Modifiers Caret (^) - call-back is called repeatedly as the user moves the slider or when an arrow
key is pressed.
Question mark (?) - a help string is supplied.
Description N is mandatory and sets the length of the control in average character units.
value is the current value represented by the slider in the range min to max. This value
can also be accessed by a call-back function whilst the slider is being moved.
option can be set to the keyword eTacXRP[ to provide an alternative to the default
which is a horizontal slider.
The slider will respond to the arrow keys on the keyboard.
The value returned by R[TPafX]NX]U^/;0C4BCNE0A801;4 can also be used
with %sl.

Example fX]X^/³!b[´ g 3 3

Example fX]X^/³b_´ !; ;

Syntax fX]X^/³bbJUX[T]P\TbTRcX^]L´ Rca[

X]cTVTa Rca[ X]_dc
Description %ss is used before %rd, %rf, or %rs in order to automatically save and restore data in
these controls.

275
ClearWin+ User’s Guide Fortran

filename/section is a standard character string (can be replaced by @).

filename is the stem of a file with the .INI extension that is stored in the standard
Windows directory.
section is the name of a section in the INI file. This name appears in square brackets
at the head of a section in the file.
The item name for the data is automatically formed from the text that appears
immediately before the control. Spaces are removed from the text in order to form the
name. See page 48 for further details.
ctrl is set to 1 to enable saving and to 0 to disable saving.

Example fX]X^/³bbJP__ Q[^RZ!L´ Rca[

Syntax fX]X^/³=\bc´ bcaX]V

RWPaPRcTa bcaX]V X]_dc
Modifiers Grave accent (`) - right justifies the string in the field.
Description Lays out a string out in a field N average characters wide and m deep. m is optional
and defaults to 1 but N must be specified The string is read-only (unlike %rs, the
string cannot be changed by the user). It can, however, be changed by the
programmer. The change is followed by a call to fX]S^fNd_SPcT/bcaX]V in
order to make a change visible. The string is re-drawn each time the window is
renewed. (%`rs provides a similar effect.)
When used as the last item in a status bar, the control will automatically expand to fill
the remaining space.

Example fX]X^/³!bc´ bca

Example fX]X^/³U]JPaXP[L4X]bcTX] bPXS 4,<2bd!Obd´

At least one of the following options must be included:

]^NQ^aSTa Removes the white border - like ffJ]^NQ^aSTaL

cWX]NQ^aSTa Produces a half-size white border.
"S Provides a three-dimensional style for subsequent controls in the
window (see below).
"SNcWX] Like "S but provides a Windows 95 style edge for controls.
"SNaPXbTS Like "S but provides a raised thin edge for controls.
"SNST_aTbbTS Like "S but provides a depressed thin edge for controls.
]^Nbhb\T]d Omit the box at the top left which can be used to produce the
system menu.
X]ST_T]ST]c Makes the window independent of other windows in the program
that are already open. This can be used to create several windows
between which the user can move at will (that is, there is no
implied window hierarchy in this case).

The "S style has an effect on the position of subsequent controls and must be used
before the controls are defined. Some controls are not affected (for example, buttons
are not changed). The window is created using the standard button face colour for its
background with the controls appearing in relief. With bhJ"SL, by default %ob
boxes are given the bR^aTS property provided the aPXbTS and ST_aTbbTS properties
are not used with %ob. ^QJbWPSTSL boxes are rendered as ^QJST_aTbbTSL
boxes.

Syntax fX]X^/³bi´ fXScW WTXVWc

X]cTVTa fXScW WTXVWc X]_dc^dc_dc
Description width and height are variables whose current values specify the pixel width and height
of the window. When non-zero values are supplied, these are used to specify the initial
width and height of the window. If the window is re-sized (see %ww) then the
variables width and height are automatically updated accordingly.
Alternatively, if zero values are supplied, the window is given a default size that suits
its contents. width and height will be updated to these values and will also be changed

278
Chapter 21 Format code reference

when the window is re-sized. If code is added to save these settings, then the values
can be used when the same window is next opened.
Special values are used to represent a maximised window. Consequently, if the
dimensions of a maximised window are saved and used to re-open the window, the
window will be restored in its maximised state.

Syntax fX]X^/³cQ´ ^UU ^] S^f] bcPcNRca[

fX]X^/³mcQ´ ^UU ^] S^f] SXbPQ bcPcNRca[ VaThNRca[
RWPaPRcTa ^UU ^] S^f] SXbPQ X]_dc
X]cTVTa bcPcNRca[VaThNRca[ X]_dc^dc_dc
fX]X^/³]\cQ´
Modifiers Tilde (~) - adds a grey control option.
Caret (^) - the call-back function is called when the user clicks on the button. The
function name is added to the end of the list of arguments for a given button.
Question mark (?) - A help string for each button is placed in order (in square
brackets) after ‘tb’.

279
ClearWin+ User’s Guide Fortran

Description This control has been superceded by %ib. For new code use %ib instead.

off, on, down and disab provide the names of bitmap resources through a resource
script.
stat_ctrl is set to 1 when the button is on and to 0 when the button is off.
grey_ctrl is set to 1 when the button is enabled and to 0 when it is disabled (greyed).
n and m are optional and both default to 1. When n is used .m is optional. These
provide for a toolbar n buttons wide and m deep. A full set of arguments are required
for each button (scanning in order across the rows of buttons) using the same order of
arguments as for a single button.
For further information see page 68.

Notes Bitmap resource names can be contructed from known Windows handles (see page 79).

Example fX]X^/³cQ´ ´^UU´ ³^]´ ³Sf]´ bcPc

^UU 18C<0? Qc Q\_ aTb^daRT UX[T
^] 18C<0? Qc!Q\_
Sf] 18C<0? Qc"Q\_
See also %ib, %bt, %tt, %ga, %bx

%tc
Purpose To set the colour of subsequent text.

Syntax fX]X^/³cRJR^[^daL´
fX]X^/³cR´ aVQNeP[dT
X]cTVTa aVQNeP[dT X]_dc
Modifiers Grave accent (`) - used with an integer argument in order to set the text colour for %eb
(see page 113).
Description colour must be one of Q[PRZ, fWXcT, VaTh, aTS, VaTT], Q[dT and hT[[^f.
rgb_value is typically obtained by a call to A61/. Using the value (-1L) resets the
colour of subsequent text to its default value.

Notes The text colour for a given control can be changed dynamically (after the window has
been created) by calling the subroutine B4CN2>=CA>;NC4GCN2>;>DA/.

Example fX]X^/³cRJaTSL´

280
Chapter 21 Format code reference

fX]X^/³cR´ A61/!!
See also %fn, %ts, %bf, %it, %ul, and the Windows API call
6TcBhb2^[^a2>;>ANF8=3>FC4GC

%th
Purpose To provide “tooltip” help.

Syntax fX]X^/³cW´ Rca[

X]cTVTa Rca[ X]_dc
Description %th specifies that help strings will appear in volatile rectangular boxes adjacent to the
associated control when the mouse is over the control. There is a programmed delay
before the help string appears, similar to %`bh but without a spike. ctrl is set to 1 to
make the help tooltip visible and zero to hide it.

a %ti window is analogous to an ordinary window. In particular, if the call-back

function returns a zero or negative number, the window will close and the icon will be
removed from the taskbar. Closure can also be effected using %lw by setting the
associated control variable to a zero value and passing it to fX]S^fNd_SPcT/.

Notes icon_name can contructed from a known Windows handle (see page 79).

Example fX]X^/³cXJ\hNXR^]LJ2[XRZ WTaTL´RQ

Within the call-back function:
RQ,!
85R[TPafX]NbcaX]V/20;;102:NA40B>=4@<>DB4N;45CN2;82:C74=

RQ,
4=385

%tl
Purpose To set up tab locations for use with %ta.

Syntax fX]X^/³=c[´ _^b _^b! _^b=

X]cTVTa _^b _^b! _^b= X]_dc
fX]X^/³=Oc[´ _^b _^b! _^b=
S^dQ[T _aTRXbX^] _^b _^b! _^b= X]_dc
Modifiers Grave accent (`) - use real rather than integer values.
Description Tab positions are measured in average character widths. All values are measured from
the left-hand edge of the window. Each %tl maintains its effect until the next %tl.

Example fX]X^/³"Oc[´ $3 !$3 "$3

Syntax fX]X^/³cb´ bXiT

282
Chapter 21 Format code reference

S^dQ[T _aTRXbX^] bXiT X]_dc

Description size is the scaling factor that defaults to 1.0. Values between zero and 1.0 cause the
font to be scaled down. Values greater than 1.0 cause it to be scaled up. The default
can be restored by using a size of 1.0 or by using %sf.
%fn must be used before %ts because the standard font cannot be scaled.

Example fX]X^/³cb´ $3

Example fX]X^/³.MccJ2P]RT[LJ7T[_ cTgcL´RQNUd]R

Syntax fX]X^/³=<ceJ^_cX^]bL´ caTT ]XcT\b bT[

283
ClearWin+ User’s Guide Fortran

RWPaPRcTa caTT]XcT\b X]_dc^dc_dc

X]cTVTa ]XcT\b X]_dc _PaP\TcTa
X]cTVTa bT[ X]_dc^dc_dc
fX]X^/³O=<ceJ^_cX^]bL´ caTT ]XcT\b bT[ XR^]Nbca
RWPaPRcTa XR^]Nbca X]_dc
Modifiers Grave accent (`) - for programmer supplied icons.
Caret (^) - call-back function that is called when the user selects an item.
Description Note that %bv provides an alternative to %tv and has more options.
N and M are not optional and specify the width and depth of the area in average
characters.
tree is a character array of nitems.
sel is the index of the item selected by the user.
icon_str is a character string giving a list of icon resources in the form
XR^] XR^]!.
options can take the keyword UXgTSNU^]c which causes the control to use a fixed font
for the names of the tree nodes. This can be useful in cases where the node names are
intended to line up. options can also take the keyword ZTT_NU^Rdb to prevent the
focus from shifting from the selected item. This is similar to the effect produced by a
list box.
If ePaXPQ[TNbXiT is included as one of the options, nitems is treated as a variable
that subsequently can be modified and updated by a call to fX]S^fNd_SPcT/.
However, the size cannot be increased above its initial value. Since blank elements in
the input array are ignored, the only reason to use this feature is to reduce the
processing time (and therefore possible flicker) when using a very large array, most of
whose elements are blank.
For further details see page 68.

Notes Icon resource names can be contructed from known Windows handles (see page 79).

Example fX]X^/³MO! %ce´caTT $;bT[³R[NQ^^Z^_NQ^^Z´RQ

R[NQ^^Z 82>= Q^^Z XR^ aTb^daRT UX[T
^_NQ^^Z 82>= Q^^Z!XR^
See also %bv, %ls, %ms, %pb, %ps, bTTNcaTTeXTfNbT[TRcX^]/

284
Chapter 21 Format code reference

%tx
Purpose To display an array of text with attributes in a rectangular region.

Syntax fX]X^/³=<cgJ^_cX^]bL´ cTgc PccaXQ ]R^[b \a^fb

RWPaPRcTa cTgc]R^[b\a^fb X]_dc
RWPaPRcTa PccaXQ]R^[b\a^fb X]_dc
X]cTVTa ]R^[b \a^fb X]_dc _PaP\TcTa
Modifiers Caret (^) - the call-back is called when a keyboard character is pressed and the control
is in focus. The program can then update the text array.
Description The text array text is displayed in a box with ncols columns and mrows rows. Initially
only N columns and M rows are visible and a scroll bar is provided.
Attributes for each character are provided through the array attrib, with each character
set to a colour index value in the range 0 to 255. Colour indexes are defined in order
by (%tc, %ty) format pairs. %tx can be preceded by a pivot (%pv).
options can include:

Ud[[N\^dbTNX]_dc The call-back function is called whenever the mouse moves

over the control.
Ud[[NRWPaNX]_dc The call-back function is called for each key-press and each key
release using Micosoft VK_ parameters.
dbTNcPQb Pressing the tab key does not move to the next control; instead,
a tab key press is available to the %tx call-back.
]^N_^_d_N\T]d Used to disable %pm within this control and to make the right
mouse click available to the this control if required.

See page 103 for further details.

Example fX]X^/³M% $cg´ cTgc PccaXQ ' ! RQNUd]R

Syntax fX]X^/³dfJR[PbbL´ fXScW WTXVWc bch[T gbch[T Wf]S

X]cTVTa fXScW WTXVWc bch[T gbch[T X]_dc
X]cTVTa Wf]S ^dc_dc
Description class is the name of a registered class with its own Windows procedure.
width and height define the dimensions of the window in pixels.
style is the Windows style (WS_CHILD is automatically included with style).
xstyle is the extended Windows style (typically zero).
hwnd is returned as the handle of the resultant child window.

Syntax fX]X^/³eg´ _PVTNbcT_ \PgNeP[ RdaNeP[

X]cTVTa _PVTNbcT_ \PgNeP[ X]_dc
X]cTVTa RdaNeP[ X]_dc^dc_dc
Modifiers Caret (^) - the call-back is called when the user clicks on the scroll bar.

286
Chapter 21 Format code reference

Description cur_val is the value that corresponds to the position of the scroll box (also called the
thumb). It returns a value between zero and max_val - 1.
page_step is the amount that cur_val is to be increased/decreased when the user clicks
on the scroll bar (other than on the thumb). For a document, page_step will be set to
the number of lines that are to be displayed in the window and max_val should be set
to n - page_step, where n is the total number of lines in the document.
With %hx and %vx the three arguments cur_val, page_step and max_val can be
passed as variables and changed dynamically with a call to fX]S^fNd_SPcT/
A call to R[TPafX]NX]U^/³8=C4A<4380C4NB2A>;;´ will determine if the
callback was called whilst the thumb was moving. A return value of 1 indicates
movement whilst zero indicates that the thumb is stationary. Both of these events
occur at the end of a move.
%hx and %vx should not be used with controls like %eb and %cw which have their
own scroll bar mechanism.

Example fX]X^/³Meg´ $; !; _^b RQNUd]R

Syntax fX]X^/³fR´ RW

RWPaPRcTa RW X]_dc
Description See page 45.

%wd
Purpose To display an integer.

Syntax fX]X^/³fS´ e
X]cTVTa e X]_dc
Description See page 45.

287
ClearWin+ User’s Guide Fortran

%we
Purpose To display a real value.

Syntax fX]X^/³fT´ e
S^dQ[T _aTRXbX^] e X]_dc
Description See page 45.

%wf
Purpose To display a real value.

Syntax fX]X^/³fU´ e
S^dQ[T _aTRXbX^] e X]_dc
Description See page 45.

%wg
Purpose To display a real value.

Syntax fX]X^/³fV´ e
S^dQ[T _aTRXbX^] e X]_dc
Description See page 45.

%wp
Purpose To supply the name of a wallpaper bitmap.

Syntax fX]X^/³f_JQXc\P_N]P\TL´
Modifiers Grave accent (`) - ensures that, if necessary, the window is expanded to hold at least
one copy of the bitmap.
Description bitmap_name is a standard character string (can be replaced by @). The bitmap is
used as a back drop to the contents of the window and, if necessary, is repeated

288
Chapter 21 Format code reference

horizontally and vertically to fill the space.

Example fX]X^/³f_JfP[[_P_TaL´
fP[[_P_Ta 18C<0? UX[TQ\_ aTb^daRT UX[T
See also %bg

%ws
Purpose To write a string.

Syntax fX]X^/³fb´ b
RWPaPRcTa b X]_dc
Description See page 45.

%ww
Purpose To change the style of a window.

Syntax fX]X^/³ffJ^_cX^]bL´
Description By default, a format window that uses neither %ww nor %sy has a caption bar but does
not have: a) system menu, b) a minimise box and c) a maximise box. Such a window
has a double frame that is raised.

%ww is used to change the style a window. If %ww is used without any of its options,
the resulting window has a caption bar that includes: a) system menu, b) a minimise
box and c) a maximise box. Such a window has a single frame that is not raised.

The list of options given below includes options for changing the border of the
window. This refers to the space that, by default, is provided by ClearWin+ to
surround the text and controls within a window (as in %bd). Do not confuse this
border with the frame of the window that is determined by the Windows API style.

A window that uses %ww can be re-sized if a pivot (%pv) is also included.
options can be one or more of:

289
ClearWin+ User’s Guide Fortran

RPbcbNbWPS^f This option produces a window which casts a shadow. It is

most effective when used in conjunction with ]^NUaP\T and
]^NRP_cX^].
]^NRP_cX^] Omit the caption from the window.
]^N\Pg\X]Q^g Omit the maximise and minimise boxes from the window.
]^N\PgQ^g Omit the maximise box.
]^N\X]Q^g Omit the minimise box.
]^Nbhb\T]d Omit the box at the top left which can be used to produce the
system menu.
]^NQâSTa Omit the blank border which normally surrounds the window
contents, but leave the frame itself. Using this format you can,
for example, force a tool bar (textual or bit-mapped) to be
placed immediately beneath the menu.
cWX]NQâSTa Produces a half-size white border.
]^NUaP\T Omit the window frame and the blank border which normally
surrounds the window contents. This option is particularly
useful with certain types of child window.
]^NTSVT This option is like ]^NUaP\T except that it leaves the default
border i.e. an empty space around the edge of the window.
]PZTS Equivalent to ]^NUaP\T with ]^NQâSTa and ]^NRP_cX^].
e^[PcX[T The window closes when the focus is lost.
X]PRcXeT Disables the window.
X]eXbXQ[T Hides the window.
UXgTSNbXiT Prevents the user from resizing the window.
c^_\^bc Forces the window to stay on top, even if another application
gets control. This is sometimes useful when it is necessary to
execute another application without the user losing sight of the
window of the main application.
\PgX\XbT Displays the window as a maximised window.
â \PgX\XiT
\X]X\XbT Displays the window as a icon.
â \X]X\XiT
bd_TaN\PgX\XbT Displays only the client area (requires an accelerator key
bd_TaN\PgX\XiT attached to the Escape key that restores the normal window).

290
Chapter 21 Format code reference

X]ST_T]ST]c Makes the window independent of other windows in the

program that are already open. This can be used to create
several windows which the user can move between at will and
where there is no implied window hierarchy.

Example fX]X^/³ffJ]^NQ^aSTa \PgX\XbTL´

Compiling and linking

Compiler options and directives for Windows

This section describes the compiler options and directives that are provided for the
purpose of creating Windows executable programs. Information about other compiler
options and directives will be found in the user guide for your Salford compiler.
Using ClearWin+, a Windows application can be created in one of two ways. One
approach is to compile the main program using the /WINDOWS command line
option and then run the linker separately (other routines that have not been compiled
with /WINDOWS may also be linked in). Further details of this approach are given
below. The other method is to use one of the compiler command line options /LINK
and /LGO and to insert the WINAPP compiler directive into the program code before
the main program.
The WINAPP directive takes the form:
WINAPP resource_file
The /WINDOWS command line option becomes redundant when this directive is
used. When used, WINAPP should be the first compiler directive in the file and must
appear before the main program. WINAPP can take either no arguments or one
argument. If the resource script file is specified, the SRC resource compiler is
invoked (see page 296) to compile the resource script. If it is not specified, the
application will simply be marked as a Windows application rather than a Console
application.
Some compilers may require a WINAPP directive to have three arguments rather than
one when a resource script is specified. In this case two zero values can be placed
before the file name. For example:
F8=0?? aTb^daRTaR

293
ClearWin+ User’s Guide Fortran

These represent stack and heap size values that are redundant in Win32 applications.
For Win32 applications, the resource file name must have a different stem (i.e. the
part before the extension) from all the other source file names. For example, do not
use prog.rc with prog.for. If you did not obey this rule, both files would be compiled
into prog.obj and one would overwrite the other.
Resources are automatically appended to the executable or DLL being created.
However, by default ClearWin+ only searches for resources in the current executable.
Calling the subroutine DB4NA4B>DA24N;81A0AH/ causes ClearWin+ to also search
in a given DLL. The call takes the form:
20;; DB4NA4B>DA24N;81A0AH/³<H;81´
where mylib.dll is the name of the DLL.
Fortran 77 routines that use ClearWin+ and/or the Windows API should include the
line
8=2;D34 +fX]S^fbX]b-
unless the routine only refers to fX]X^/ or A61/ (say) which can be declared as
8=C464A in the routine. Note the use of “<” and “>” to denote that the default
directory for system include files should be searched. The file called windows.ins
references three other files as follows:
8=2;D34 +R[TPafX]X]b-
8=2;D34 +fX]"!P_XX]b-
8=2;D34 +fX]"!_a\X]b-
These files are installed into the INCLUDE sub-directory of your chosen installation
directory (the default installation directory is c:\win32app\salford). Where
appropriate, clearwin.ins can be used in place of windows.ins in your program. This
will reduce the amount of processing at compile time.
Fortran 90/95 routines can alternatively make use of the file mswin.mod instead of
windows.ins via the statement
DB4 <BF8=
The source file for mswin.mod references three other files as follows:
<>3D;4 \bfX]
DB4 \bf"!_a\
DB4 \bfX]"!
DB4 R[afX]
4=3 <>3D;4 \bfX]
Where appropriate, clrwin can be used in place of mswin in your program. This will
reduce the amount of processing at compile time.

294
Chapter 22 Compiling and linking

It is recommended that you use the IMPLICIT NONE statement at the start of any
routine that uses the windows.ins file. Without IMPLICIT NONE, a mispelt Windows
parameter (some are very long) will not be detected at compile time. Such bugs are
very hard to find in the Windows environment.
Tip Of necessity, the three include files and the equivalent module files contain many
thousands of lines of declarations in order to provide you with full access to all the
ClearWin+ functions and the Windows API. Once you are familiar with the concepts
described in this guide, you may find it helpful to create your own include or module
file that contains only those declarations that are used by your programs. If you use
IMPLICIT NONE, and remove references to windows.ins or msmod, the compiler will
report all usage of undeclared variables and functions. You can then search the
relevant include or module files for the missing names and, using a text editor, build
up your own include or module file. Note that ClearWin+ routines (whose names
usually end in an “@” character) will appear in a C_EXTERNAL statement in order
to provide the compiler with a reference to a routine in the run time library. If you
take the time to make your own include or module file, the benefits of much faster
compilation will be immediately obvious, especially if your program contains many
sub-programs that use these include or module files.

Unlike a Console application, a Windows application does not create or inherit a

console (i.e. a DOS box), and any default input/output is directed to a ClearWin
window (which can be embedded inside other windows using %cw). Although a
simple ClearWin+ window can be displayed from a Console application, the rules
concerning which Windows API calls will work from within a Console application are
ill-defined (ClearWin+ calls all ultimately resolve into API calls). Therefore, it is
recommended that all ClearWin+ applications should be set up as Windows
applications using the WINAPP directive.

SLINK commands
If the /LINK and /LGO compiler command line options are not used, SLINK must be
called in order to link programs.
If your application uses a resource script (resource.rc say) then it must be separately
compiled using the Salford Resource Compiler SRC. This generates the object file
resource.obj which can then be loaded in the same way as other object files.
The following example shows the commands required to compile and link a simple
Windows application from a file myapp.for using FTN77:
5C=&& <H0?? F8=3>FB

BA2 A4B>DA24

295
ClearWin+ User’s Guide Fortran

B;8=:
;> <H0??
;> A4B>DA24
58;4
Note
a) Because myapp.obj and resource.obj are both used in the SLINK commands it is
evident that we cannot use myapp.rc as the name of the resource.
b) If there is more than one file of source code in addition to myapp.for then the first
to be loaded must contain the main program and be marked as a Windows
application either by using the /WINDOWS compiler option or by including the
WINAPP directive.
c) Not more than one resource object can be loaded.
d) A SLINK command line of the form:
bdQbhbcT\ fX]S^fb\PY^a\X]^a
specifies the Windows GUI style to use. The default is now
bdQbhbcT\ fX]S^fb#
The former Windows 3.10 subsystem can also be obtained by setting the
environment variable
LINK_SUBSYSTEM=3

Using the Salford Resource Compiler

If a program uses a resource script and neither of the compiler options /LGO and
/LINK are used to compile and link the program, then the Salford Resource Compiler
SRC must be used to compile the resource script. An alternative method can also be
used with FTN95 (see below).
When SRC is called it creates a permanent compilation of the resource script. With a
few exceptions and a few additions, SRC uses the same resource script syntax as the
Microsoft Resource Compiler RC. However, most ClearWin+ programmers will find
that they only use the following kinds of resources:
18C<0?
82>=
2DAB>A
685
7H?4AC4GC
B>D=3

296
Chapter 22 Compiling and linking

Once a resource script has be written, it should be stored in a file with the .RC
extension. The resource can then be compiled with a call to SRC of the form:
BA2 A4B>DA24
This command takes the file resource.rc as input and produces an object file called
resource.obj. This means that resource must not be used as the stem for both a
Fortran filename and resources in the same directory and project. The resulting object
file can then be linked with other object files using SLINK as follows.
B;8=:
;> <H0??
;> A4B>DA24
58;4

FTN95
Using FTN95, it is possible to append resource directives to the end of a program
using the RESOURCES directive. Everything after this directive (up to the end of
the file) is treated as resources and passed to the SRC command. The result is
combined with the object code produced by FTN95. In order to use the
RESOURCES directive, the SRC command must be available on the PATH. All
the resources for a program must be supplied in one place.
Here is a simple example:
F8=0??
8=C464A XfX]X^/
X,fX]X^/³RPJ0 QTPdcXUd[ QXc\P_L´
X,fX]X^/³Q\J\hQXc\P_L!][R]OQcJ>:L´
4=3
A4B>DA24B
\hQXc\P_ 18C<0? R)KQXc\P_bK_XR Q\_

297
ClearWin+ User’s Guide Fortran

298
23.

ClearWin windows

Introduction
This chapter describes the attributes of a ClearWin window. A summary of functions
that can be used with ClearWin windows is given on page 315. Details of these
functions can be found in Chapter 27.
A ClearWin window has the attributes of a Windows window but has added
functionality. In particular a ClearWin window can be used in association with the
standard Fortran I/O routines A403 FA8C4 and ?A8=C.
Note that a ClearWin window is not the same as a window created with fX]X^/
(which is called a format window). It is, however, possible to embed a ClearWin
window in a format window (see page 123).
Graphics can be drawn to a ClearWin window by using VTcNVaP_WXRbNSR/ and by
calling Windows API drawing functions (details are given in the ClearWin+ User’s
Supplement). However, it is recommended that graphics objects should be drawn to a
format window created using %gr, %pl or %og.
A ClearWin window (that is not embedded in a format window) can be created by
calling RaTPcTNfX]S^f/ (this function returns a standard Windows handle).
STbca^hNfX]S^f/ is used to kill the window and R[TPaNfX]S^f/ clears any I/O
text that appears in the window. However, it does not clear graphics that have been
drawn to the associated device context. d_SPcTNfX]S^f/ is called to “invalidate” a
ClearWin window and hence redraw it. Various other routines can be used to control
the font of the text and to get and set the handle for default I/O, whilst
^_T]Nc^NfX]S^f/ can be used to attach a Fortran unit number to a particular
ClearWin window.

299
ClearWin+ User’s Guide Fortran

As an alternative to using a Fortran A403 statement, the programmer can access a

ClearWin window keyboard buffer via the routines: UTTSNfZThQ^PaS/
U[dbWNfZThQ^PaS/ VTcNfZTh/ VTcNfZTh / and fZThNfPXcX]V/
It is strongly recommended that either the routine bTcNP[[N\PgN[X]Tb/ or the
routine bTcN\PgN[X]Tb/ be used before creating a ClearWin window (including
default ClearWin windows). These routines are used to limit the amount of
memory that is used by a ClearWin window. See below for further details.

Simple programs
Using ClearWin+, simple programs can be compiled unchanged. As soon as standard
output is generated which would have gone to the screen, or the program attempts to
read from the keyboard, a ClearWin window is set up by the ClearWin+ system.
Successive lines of output are written to this window (entitled >dc_dc), which scrolls
when necessary. The window acts like a terminal, so keyboard input is echoed in the
window. The window can be scrolled, moved, or resized by the user. The system
retains the information output to the window so that F<N?08=C messages can be
handled without any special programmer action. As an example, here is a complete
application program to calculate square roots:
F8=0??
3>D1;4 ?A428B8>= S
3> F78;4CAD4
A403 S
?A8=C B@ACS
4=33>
4=3
Notice that this program does not require an explicit exit path. Each time it pauses for
input, the system will be prepared to accept a window close request (Alt-F4). When
your program exits, its window will remain open until closed by the user in order to
ensure that the user has time to read the output.
Because ClearWin+ must store away every line that you send to a window - to cater
for possible repaint requests or user scroll operations - it is important to limit the
amount of output to manageable proportions. Store is consumed from the heap and is
reclaimed when the ClearWin window is closed or cleared. It is recommended that
the routine bTcNP[[N\PgN[X]Tb/ (or bTcN\PgN[X]Tb/) be used to limit the
amount of store that is consumed.
In a similar way, DOS applications that contain calls to the Salford graphics library
can also be compiled unchanged. In this case ClearWin+ will automatically create a
simple format window for the drawing.

300
Chapter 23 ClearWin windows

Explicit ClearWin window creation

When ClearWin+ creates a ClearWin window for you it is created full screen by
default. Also, the window uses the Windows system fixed font (referred to as
BHBC4<N58G43N5>=C in the Windows documentation). In general, it is better to
create a ClearWin window explicitly so that you have a handle to it and you can exert
more control. For example, the following would create a half-size window in the
centre of the screen:
F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A fX]gbXiThbXiTg_^bh_^b
gbXiT,R[TPafX]NX]U^/bRaTT]NfXScW!
hbXiT,R[TPafX]NX]U^/bRaTT]NST_cW!
g_^b,gbXiT#
h_^b,hbXiT#
fX],RaTPcTNfX]S^f/<^^] [P]SX]Vg_^bh_^bgbXiThbXiT

The first ClearWin window that you create will be the parent window. When this
window is closed the program will terminate.
Once you have created it, you can inform the system that your window is the default
ClearWin window, thus:
20;; bTcNSTUPd[cNfX]S^f/fX]
A ClearWin window can also be attached to a specified Fortran unit, for example:
20;; ^_T]Nc^NfX]S^f/&fX]
FA8C4&´P´ ´CTbcX]V´
Fortran units connected to ClearWin windows are opened for input and output. When
you close such a unit, the corresponding window is closed and all the heap storage
required to hold the output is returned to the system.
When your program terminates, the ClearWin windows that it has created will remain
open for viewing, scrolling etc. until closed by the user (e.g. by pressing Alt-F4).

Text output to ClearWin windows

Textual window input/output uses, by default, a Windows font called
BHBC4<N58G43N5>=C output in black. You are not limited to the use of this font;
Windows can write text in a wide variety of fonts and colours. You simply use

301
ClearWin+ User’s Guide Fortran

appropriate Windows API routines to create one or more fonts and then attach them to
a window.
In order to create a new font, it is usually best to start with the parameters defining the
system font and modify them to obtain what you require.
For example:
F8=0??
8=2;D34 +fX]S^fbX]b-
8=C464A [UWTXVWc[UfXScW[UTbRP_T\T]c
[UâXT]cPcX^][UfTXVWc[UXcP[XR[Ud]STa[X]T
[UbcaXZT^dc[URWPabTc[U^dc_aTRXbX^]
[UR[X__aTRXbX^][U`dP[Xch[U_XcRWP]SUP\X[h
270A02C4A' [UUPRT]P\T
8=C464A ]TfU^]c
20;; VTcNbhbcT\NU^]c/[UWTXVWc[UfXScW[UTbRP_T\T]c
[UâXT]cPcX^][UfTXVWc[UXcP[XR[Ud]STa[X]T
[UbcaXZT^dc[URWPabTc[U^dc_aTRXbX^]
[UR[X__aTRXbX^][U`dP[Xch[U_XcRWP]SUP\X[h[UUPRT]P\T
R 0[cTa cWT STUPd[c _PaP\TcTab c^ S^dQ[T cWT bXiT
R P]S b_TRXUh XcP[XR
[UWTXVWc,![UWTXVWc
[UfXScW ,![UfXScW
[UXcP[XR,
R 2aTPcT5^]c Xb P FX]S^fb 0?8 Ud]RcX^]
]TfU^]c,2aTPcT5^]c[UWTXVWc[UfXScW[UTbRP_T\T]c
[UâXT]cPcX^][UfTXVWc[UXcP[XR[Ud]STa[X]T
[UbcaXZT^dc[URWPabTc[U^dc_aTRXbX^]
[UR[X__aTRXbX^][U`dP[Xch[U_XcRWP]SUP\X[h[UUPRT]P\T

20;; bTcNSTUPd[cNU^]c/]TfU^]c

The default font used by a ClearWin window (BHBC4<N58G43N5>=C) can be changed
by a call to either bTcNSTUPd[cN_a^_^acX^]P[NU^]c/ or to
bTcNSTUPd[cNU^]c/. These routines will alter the default font used by ClearWin+
on all ClearWin windows created subsequent to the call. The original default can be
restored by a call to bTcNSTUPd[cNc^NUXgTSNU^]c/.

302
Chapter 23 ClearWin windows

Getting text from a ClearWin window

It is possible to extract the data placed into a ClearWin window by calling:
8=C464A 5D=2C8>= 64CN2;40AF8=NC4GC/F8=1D554A2>?H
8=C464A F8= 2>?H
270A02C4A 1D554A
F8= is the handle of ClearWin window in question. To obtain the handle of the
default window use:
F8=,64CN3450D;CNF8=3>F/
If 2>?H is zero, the function returns the length of the required buffer but no data is
copied. If 2>?H is 1, the data is also copied to the buffer.

Obsolete ClearWin window functions

The following functions are considered to have been superseded by the introduction of
fX]X^/ in ClearWin+. They are documented in the ClearWin+ User’s Supplement.
ADD_FORTRAN_WINDOW_CALLBACK@ Adds a call-back function for a given
ClearWin window and message.
ADD_TEXT_DESCRIPTOR@ Adds a text descriptor to a window.
ADD_WINDOW_MENU@ Sets the menu in a given window.
ATTACH_FORTRAN_MENU@ Loads a named menu from the program
resource.
GET_FILENAME@ Displays a dialog box from which a
filename can be selected.
GET_GRAPHICS_DC@ Returns a device context to a bitmap.
MAKE_DIALOG_BOX@ Creates and display a given dialog box.
SET_WIN_ESCAPE@ Sets the escape character for a specified
ClearWin window.

303
ClearWin+ User’s Guide Fortran

304
24.

Using the Windows API

Calling Windows API routines from Fortran

As the Windows API is based upon C++, it is easier to use the API from a C++
program. However, it is possible to program the API from Fortran but Fortran data
structures do not easily map on to the data structures that are used by the Windows
API. One way forward, is to employ mixed language programming, keeping your
existing Fortran as far as possible unchanged, and using C++ to provide an interface
to the Windows API.
Programmers who are not familiar with C++ will probably prefer to avoid learning a
new language. If this is the case, the following points should be kept in mind when
calling Windows API functions from Fortran.
All Windows API routines which do not take the address of a routine as an argument
(or return one as a result) are available for calling from Fortran. Owing to the fact
that the Windows API routines are written in C++, it is necessary to use the Salford
Fortran statement STDCALL to declare access to Win32 API routines. Examples of
BC320;; statements can be seen in the file win32api.ins.
Each pointer argument to a Windows API routine has been specified as a F8=A45 or
F8=BCA8=6 (the latter in the case of character arguments that need converting to null-
terminated C-strings) and the actual argument should be a variable or array to which
the pointer refers. The defintion of BC320;; appears below.

305
ClearWin+ User’s Guide Fortran

The Fortran STDCALL statement

The STDCALL declaration allows the Fortran programmer to call Win32 API
routines written in C++.
The syntax of the declaration for a STDCALL function is as follows:
BC320;; ]P\T J´P[XPb´L JSTbR L J)aTbch_TL
where:
name
is the name by which it will be called in the Fortran program.
alias
is the C++ Windows API name (or the required __stdcall function name ). Note
that this appears in single quotes and is case-sensitive.
desc
is an argument descriptor, and is either REF, VAL, STRING, INSTRING, or
OUTSTRING.
STRING, INSTRING and OUTSTRING may be followed optionally by an
integer in parentheses. This integer specifies the maximum length for the
corresponding argument in the C routine, in each case where the length of the
corresponding Fortran character object cannot be determined (i.e. the actual
argument is CHARACTER*(*) ). If the integer is not specified, then a default
value of 256 (bytes) is assumed for the maximum length of the string.
restype
is the type of the function. If this does not appear then the function does not
return a result (equivalent to the C type void). Valid types are INTEGER, REAL,
DOUBLE PRECISION, COMPLEX, DOUBLE COMPLEX, LOGICAL and
STRING. INTEGER, REAL and LOGICAL may be followed by a length
specifier of the form “*n”. If the function result is declared to be of type STRING
then the function result should be assigned to a variable of type CHARACTER.
Some examples of valid STDCALL declarations are:
BC320;; BD1 BD1!
BC320;; BD1! ´6Tc0cca´)8=C464A
BC20;;; 2BD1"A45BCA8=6!)BCA8=6
BC320;; BD1# ´6TcBXiT´ A45E0;E0;8=BCA8=6>DCBCA8=6
If no argument specifiers are specified, then default argument linkage is assumed.
This is as follows:
Arrays:
by reference (i.e. as a pointer)

306
Chapter 24 Using the Windows API

INTEGER and REAL scalars:

by value
LOGICAL:
by value, as an integer of the appropriate length, 1 representing .TRUE. and 0
representing .FALSE.
CHARACTER objects:
Copied to a compiler defined temporary variable. A trailing null is added to the
end of the significant length of the string (i.e. there are no trailing spaces). The
temporary variable is then passed by reference. In addition, if the actual argument
is a scalar or array element, the result in the temporary variable is copied back,
and padded to the right with blanks if necessary. This is equivalent to the
STRING linkage descriptor described below.
Where linkage descriptors are specified, the number of arguments in each call must
agree with the number of descriptors specified. The various categories of objects
which may correspond to particular argument descriptors are as follows:
Numeric and LOGICAL scalars:
Value or reference (VAL or REF)
Arrays, externals, dummy procedures:
Reference (REF)
CHARACTER objects:
Reference or string (REF, STRING, INSTRING or OUTSTRING)
The three variants of the STRING descriptor are as follows:
STRING
The corresponding argument is both input and output, and is copied to a
temporary variable on entry to the routine (with a trailing null inserted at the end
of the significant length), and if the argument is a scalar or array element, is
copied back to the actual argument, blank padded to the right if necessary.
INSTRING
The corresponding argument is an input argument with respect to the external
routine. The argument is only copied to the temporary variable, and not copied
back.
OUTSTRING
The argument is returned by the external routine. The temporary variable is set up
to be the length of the corresponding scalar or array element plus one, or of
specified or default (256) length if the corresponding argument is
CHARACTER*(*), but the value is only copied out. Obviously, this descriptor is
only appropriate where the actual argument is a scalar or array element.
When it is required to pass a NULL pointer to a string, the value 0 (zero) should be
used.

307
ClearWin+ User’s Guide Fortran

Some Windows API functions allow a particular argument to take two different types
in different circumstances. For example, an LPSTR in some circumstances and an
integer in others. This is outside the scope of the STDCALL mechanism. If this
feature affects you then you should copy the STDCALL statement for the relevant API
and modify it to have a different Fortran name and argument list, but keeping the
same called name.
A common example is the Windows API function LoadCursor which is used to load
either a cursor defined in the program resource or a predefined system cursor. This
has the following definition:
72DAB>A F8=0?8 ;^PS2dabâ070=3;4 W8]bcP]RT;?BCA [_2dabâ=P\T
When used to load a cursor from the program resource, hInstance is the instance
handle of the application. lpCursorName is a character string containing the name of
the cursor in the program resource. This form of the function will have the
STDCALL declaration :
BC320;; ;>032DAB>A ;^PS2dabâ0 E0; 8=BCA8=6)8=C464A#
When used to load a predefined system cursor, the first argument hInstance is set to
zero and the second argument lpCursorName is an integer containing one of a number
of predefined values which specifies the cursor to be loaded. This form of the function
will have the STDCALL declaration :
BC320;; ;>032DAB>A ;^PS2dabâ0 E0; E0;)8=C464A#
However, having two differing STDCALL statements for the same Fortran function is
not allowed. The solution is to change the Fortran name. For example
BC320;; ;>032DAB>A ;^PS2dabâ0 E0; 8=BCA8=6)8=C464A#
BC320;; ;>032DAB>A! ;^PS2dabâ0 E0; E0;)8=C464A#
The same situation arises with some other functions that have the form as
LoadCursor, for example LoadBitmap and LoadIcon.
A further example is given by the Windows API printer Escape function which can
take many different forms. One of these has the following form:
X]c F8=0?8 4bRP_TWSR 64CC427=>;>6H =D;; =D;;[_CTRW]^[^Vh
lpTechnology is an LPSTR (long pointers to strings) so the STDCALL declaration for
this form of the function for use in a Fortran program would be:
BC320;; 4B20?4 4bRP_T E0; E0; E0;8=BCA8=6
>DCBCA8=6)8=C464A#
A second form of this Escape function is:
X]c 4bRP_TWSR B4C2>?H2>D=C bXiTÛX]c
[_=d\2^_XTb [_0RcdP[2^_XTb

308
Chapter 24 Using the Windows API

lpNumCopies, and lpActualCopies are both LPINT (long pointers to integers) so the
STDCALL declaration for this form of the function would be:
BC320;; 4B20?4 4bRP_T E0; E0; E0; A45 A45)8=C464A#
As before, having two differing STDCALL statements for the same Fortran function is
not allowed and the solution is to change the Fortran name. For example
BC320;; 4B20?4 4bRP_T E0; E0; E0;8=BCA8=6
>DCBCA8=6)8=C464A#
BC320;; 4B20?4! 4bRP_T E0; E0; E0; A45A45)8=C464A#

The Fortran STOP and PAUSE statements

You may wish to trap the BC>? or ?0DB4 Fortran statements for your own additional
processing. These standard Fortran routines call upon other routines named BC>?/
and ?0DB4/ respectively and the user may provide alternative definitions for these
routines to over-ride the system defaults.
In order to do this you should provide your own BC>?/ subroutine with the following
specification:
BD1A>DC8=4 BC>?/<4BB064
270A02C4A <4BB064
When you have completed your ‘clean up’ operation in BC>?/ you should call on the
system routine 4G8C/ as the last instruction within BC>?/ to allow ClearWin+ to
‘clean up’ before termination (4G8C/ has no arguments and does not return to the
calling routine).
BD1A>DC8=4 4G8C/
Similarly, you may also provide your own version of the ?0DB4/ routine with the
specification:
BD1A>DC8=4 ?0DB4/<4BB064
270A02C4A <4BB064
The default ?0DB4/ message action uses the MessageBox function to put up a
MODAL dialog box captioned ‘Pause’ with a BC>? icon, a single OK button and the
pause message which is a argument in the standard ?0DB4 routine. This default
action may be modified if the user writes his own ?0DB4/ routine. No call-on (like
the call to 4G8C/ above) is necessary or possible.

309
ClearWin+ User’s Guide Fortran

A routine called 01>AC/ is available for use when the program needs to terminate
because of an error condition.

Using Windows API structures from Fortran

The difficulty of accessing Windows API structures from Fortran can be alleviated by
the use of Fortran statement functions and Fortran 4@D8E0;4=24 statements.
For example, suppose the text metrics for the system font are required in order to
determine the size of a main window before it is created. This requires finding the
height of a single line of text. The Windows API function GetTextMetrics returns
the metric properties of the system font in a structure, ;?C4GC<4CA82B. The specific
fields of interest are tmHeight and tmExternalLeading.
Examining the windows.h file, it will be seen that the structure length is 29 bytes. In
order to represent this in Fortran, any array may be used, provided its length is at least
29 bytes. In the interests of efficiency it is a good idea to keep 4-byte alignment, so an
array 32 bytes long might be used to hold the structure. After the call to
GetTextMetrics, the relevant field values may be extracted by use of statement
functions, using the address of the structure as the argument. For example:
X]cTVTa C4GC<4CA82B"!
X]cTVTa! [X]TNWVWcc\7TXVWcc\4gcTa]P[;TPSX]V
X]cTVTa# Pc\

c\7TXVWcX,R^aT!X
c\4gcTa]P[;TPSX]VX,R^aT!X'

V^cNc\,6TcCTgc<TcaXRbWf]SC4GC<4CA82B
Pc\,[^RC4GC<4CA82B
[X]TNWVWc,c\7TXVWcPc\c\4gcTa]P[;TPSX]VPc\
2>A4! and ;>2 are Salford Fortran intrinsic functions.
The use of 4@D8E0;4=24 statements is illustrated on page 111.

310
25.

Programming tips

This chapter contains a collection of coding ideas for experienced users of

ClearWin+. The topics presented here are in no particular order and do not fit
comfortably in other parts of the manual.

Tricks with boxes

The %ob format has a number of uses. Consider what happens if you use
%3.4ob[invisible]. In this case the grid structure will be invisible, but the contents of
the various cells will still be laid out in a rectangular pattern.
Boxes can be nested, so some or all of the entries in this lattice can also be boxes.
Invisible boxes can be used to create groupings of controls. For example, suppose you
had a format string such as:
± "[bQcJ2PbT L][QcJ2PbT !L][QcJ2PbT "L][QcJ2PbT $L²
Because the list box is not very deep, it is quite likely that the first one or two buttons
would appear to the right of the list box, while the rest would be separated underneath
the box. Obviously you could solve the problem by right justifying all the buttons, but
that might not be what was required. A better solution is to surround the buttons with
an invisible box.
While you are developing a window it may be a good idea to make all boxes visible, so
as to understand the layout. When everything is right you can add the invisible option
to the %ob format.

311
ClearWin+ User’s Guide Fortran

Debugging with an auxiliary terminal

A common problem encountered while developing Windows applications is that
temporary debugging output tends to interfere with the appearance of the application.
Although ClearWin+ connects the standard output to a large window for debugging
purposes, this can be less than satisfactory because the debug window may obscure
part of the program under development. A very effective alternative is to connect the
RS232 port to an old fashioned ‘dumb’ terminal (these can be obtained second hand
very cheaply) or to a cheap PC (an AT or XT will do - anything with an RS232 port).
If you use a PC you will need to execute a command on the PC to read the RS232 port
to the screen (e.g. TYPE COM2). Output can be sent to the RS232 terminal even in
the most sensitive parts of a Windows program, such as while the program is
responding to the WM_PAINT message (e.g. while a %eb box is requesting re-
colouring).
You can use any COM port, but typically COM1 is connected to the mouse and COM2
is free, so we will assume you are using COM2 in what follows. To write to the
COM2 port simply open the file COM2 and write to it - these names are reserved by
Windows and do not correspond to ordinary file names. It is important to ensure that
the COM port has been set up with the same baud rate as the terminal. Typically you
should include a suitable MODE command in the autoexec.bat file (e.g. MODE
COM2:9600,n,8,1). If in doubt as to whether the link is working, try piping a
command from a DOS box to the port, e.g. DIR > COM2.
Great care should be taken to remove all debugging output to RS232 ports before
shipping an application. Failure to do this may cause interference with modems or
other devices attached to your user’s PC.
The following routines are used to send output to an auxiliary terminal:
BD1A>DC8=4 B4CNAB!"!N2><<NBCA40</?>AC
8=C464A ?>AC
BD1A>DC8=4 AB!"!N?A8=CN74G/<4BB064 E0;D4
270A02C4A <4BB064
8=C464A E0;D4
BD1A>DC8=4 AB!"!N?A8=CN342/<4BB064 E0;D4
270A02C4A <4BB064
8=C464A E0;D4
?>AC is the COM port number which defaults to the value 2 (i.e. COM2). The string
<4BB064 is used to identify the integer E0;D4 when it is displayed on the terminal.

312
Chapter 25 Programming tips

Recording mouse and keyboard events

A simple method is available to enable mouse and keyboard actions within a
ClearWin+ application to be recorded and replayed. This facility should be thought of
as a debug/test facility as it cannot be made totally reliable if the circumstances of the
playback differ from those of the recording. In particular, mouse positions will differ
if playback occurs at a different screen resolution (see below). The format of recorded
files may also vary between versions of ClearWin+.
Recording is enabled by calling BC0ACN2;40AF8=NA42>A34A/. This subroutine
takes one 270A02C4A variable specifying the name of the file to hold the recording.
Recorded operations are written to the file immediately (rather than being buffered) to
help in situations in which the application aborts. Recording stops when
BC>?N2;40AF8=NA42>A38=6/ is called, or when the application terminates. The
file is created as a text file, and here are some typical contents:
+;45CN<>DB4N3>F=1C' ($!#-
+;45CN<>DB4ND?1C' ($!#-
+;45CN<>DB4N3>F=1C$!!# "-
+;45CN<>DB4ND?1C$!!# "-
+;45CN<>DB4N3>F=<08= # -
+;45CN<>DB4ND?<08= # -
Each event occupies one line of the file and starts with a name for the event. The
second field names the control receiving the input. For example, the first two lines
refer to button number 8 of the first ClearWin+ window. A name in this form is
known as a fully qualified control name. Observe that the first two letters of a control
name are derived from the format used to create it. Sometimes a user clicks on the
main window rather than a control. In this case the ‘control name’ field has the form
shown in the last two lines above. The last two fields for mouse operations are the co-
ordinates of the mouse relative to the control in question.
Note that this scheme at least means that some mouse operations, such as button
clicks, are unaffected by changes in screen resolution. The reason why recorded input
does not make explicit reference to Windows handles is that different handle numbers
will be supplied by Windows each time a program is run.
The control naming scheme is effective whether or not recording has been enabled.
The following two routines can be used to convert between control names and the
corresponding Windows handles:
8=C464A# 70=3;4N5A><N2>=CA>;N=0<4/=0<4
270A02C4A =0<4
270A02C4A 2>=CA>;N=0<4N5A><N70=3;4/7
8=C464A# 7

313
ClearWin+ User’s Guide Fortran

These routines will generate incorrect results if they are given bad arguments.
The subroutine BC0ACN2;40AF8=N?;0H102:/ can be used to play back a recorded
file. This subroutine takes one 270A02C4A variable specifying the name of the file
that holds the recording. When play back is completed, normal mouse and keyboard
input is resumed.
It is vital that the playback does not deviate from the recording in any way. For
example, if your application displays an extra window if some file is present, then that
file must be either present for both the recording and playback, or absent for both.
The problem of mouse actions being sensitive to the screen resolution and font sizes is
ameliorated somewhat by the following:
a) Menus, edit boxes, and text arrays store additional information that stores the data
in a resolution-insensitive form. This facility may be extended to cover more
controls in future.
b) Mouse co-ordinates are always stored relative to the control in which they occur.
This means that, for example, a mouse click at point (40,50) in a graphics area of
some fixed resolution will be recorded correctly.

Breaking into the debugger

Under Win32, pressing 2CA;1A40: or 2CA;B2A>;;;>2: will break to the
debugger if an application is awaiting input from within a ClearWin+ window. No
action is taken if the program is not running under the debugger. This feature is
effective with either the normal debugger (SDBG) or the machine level debugger
(SUSWT32).

314
26.

Library overview

ClearWin window functions

This section summarises the functions that can be used with ClearWin windows.
This type of window is described in Chapter 23.

CLEAR_WINDOW@ Clears a given ClearWin window to its

given background colour.
CREATE_WINDOW@ Creates and displays a ClearWin window.
DESTROY_WINDOW@ Closes and destroys a displayed ClearWin
window.
FEED_WKEYBOARD@ Inserts a key into the keyboard buffer.
FLUSH_WKEYBOARD@ Empties the keyboard buffer.
GET_CLEARWIN_TEXT@ Gets text from a ClearWin window.
GET_DEFAULT_WINDOW@ Returns the handle of the current default
ClearWin window for standard Fortran
I/O.
GET_WKEY@ Gets a key from the keyboard buffer.
GET_WKEY1@ Gets a key from the keyboard buffer but
does not wait.
OPEN_TO_WINDOW@ Attaches a ClearWin window to a Fortran
unit.
SET_ALL_MAX_LINES@ Sets the maximum number of lines to be
stored for all ClearWin windows.

315
ClearWin+ User’s Guide Fortran

SET_MAX_LINES@ Sets the maximum number of lines to be

stored for a given ClearWin window.
SET_DEFAULT_FONT@ Sets the default standard I/O font for
ClearWin windows.
SET_DEFAULT_TO_FIZED_FONT@ Resets the default standard I/O font for
ClearWin windows to “System Fixed”.
SET_DEFAULT_PROPORTIONAL_FONT@ Sets the default standard I/O font for
ClearWin windows to “System”.
SET_DEFAULT_WINDOW@ Sets the default ClearWin window for
standard I/O.
UPDATE_WINDOW@ Redraws a ClearWin window.
WIN_COUA@ Outputs n characters from a string to a
ClearWin window.
WIN_GETCHAR@ Reads a character from the keyboard.
WIN_GETLINE@ Reads a line of text from the keyboard.
WKEY_WAITING@ Checks if the keyboard buffer is not
empty.

Clipboard functions
CLIPBOARD_TO_SCREEN_BLOCK@ Copies a bitmap on the clipboard to a DIB.
COPY_FROM_CLIPBOARD@ Copies data from the clipboard.
COPY_TO_CLIPBOARD@ Copies data to the clipboard.
GRAPHICS_TO_CLIPBOARD@ Copies a drawing surface to the clipboard.
METAFILE_TO_CLIPBOARD@ Sends a metafile to the clipboard.
PLAY_CLIPBOARD_METAFILE@ Plays a clipboard metafile on the current
drawing surface.
SIZEOF_CLIPBOARD_TEXT@ Gets the size of text on the clipboard.

316
Chapter 26 Library overview

File mapping functions

MAP_FILE_FOR_READING@ Maps a file to memory.
MAP_FILE_FOR_READ_WRITE@ Maps a file to memory.
UNMAP_FILE@ Closes a file map.

Format window functions

The following functions are primarily for use with F8=8>/.

ADD_CURSOR_MONITOR@ Names a call-back function that monitors

which window or control has the cursor.
ADD_FOCUS_MONITOR@ Names a call-back function that monitors
which window or control has the focus.
ADD_KEYBOARD_MONITOR@ Names a call-back function that monitors the
use of the keyboard.
ADD_MENU_ITEM@ Creates a dynamic menu using %mn.
DISPLAY_POPUP_MENU@ Activates a popup menu defined using %pm.
GET_MOUSE_INFO@ Obtains the position of the mouse, the mouse
buttons, and the keyboard shift keys at the
time when the last owner-draw (%^dw) or
graphics region (%^gr) call-back function was
called.
GET_WINDOW_LOCATION@ Gets the location and size of a given window.
MOVE_WINDOW@ Moves a window given its handle.
PERMIT_ANOTHER_CALLBACK@ Allows another call-back function to be
called.
REMOVE_CURSOR_MONITOR@ Releases a call-back function that monitors
which window or control has the cursor.
REMOVE_FOCUS_MONITOR@ Releases a call-back function that monitors
which window or control has the focus.
REMOVE_MENU_ITEM@ Removes a dynamically attached %mn menu
item.
REPLY_TO_TEXT_MESSAGE@ Replies to a message from an application that
uses SEND_TEXT_MESSAGE@.

317
ClearWin+ User’s Guide Fortran

RESIZE_WINDOW@ Resizes a window given its window handle.

SEE_PROPERTYSHEET_PAGE@ Sets the sheet number for %ps.
SEE_TREEVIEW_SELECTION@ Ensures that the current %tv item is visible.
SEND_TEXT_MESSAGE@ Sends a message to an application that uses
%rm.
SET_CLEARWIN_STYLE@ Modifies the default styling controls for
format windows
SET_CONTROL_TEXT_COLOUR@ Changes the colour of a text control.
SET_CONTROL_VISIBILITY@ Shows or hides a control or window.
SET_HIGHLIGHTED@ Selects all of the text in a %rd, %rf or %rs
edit box.
SET_OLD_RESIZE_MECHANISM@ Reverts to the old ClearWin+ resizing
strategy.

General functions
ABORT@ Used to terminate a program in the event of an
error.
HIBYTE@ To get the top 8 bits of a 16 bit integer.
HIWORD@ To get the top 16 bits of a 32 bit integer.
LOBYTE@ To get the bottom 8 bits of a 16 bit integer.
LOWORD@ To get the bottom 16 bits of a 32 bit integer.
START_PROCESS@ To start a new process.
TEMPORARY_YIELD@ Yields program control.
WINDOWS_95_FUNCTIONALITY@ Tests if Windows 95 is in use.
YIELD_PROGRAM_CONTROL@ Yields program control.

Graphics functions (bitmaps,cursors,icons)

ADD_GRAPHICS_ICON@ Places a movable icon in a graphics window.
GET_IM_INFO@ Obtains information from a graphics file.

318
Chapter 26 Library overview

MAKE_BITMAP@ Embeds a bitmap in program code.

MAKE_ICON@ Embeds an icon in program code.
REMOVE_GRAPHICS_ICON@ Removes an icon created using
ADD_GRAPHICS_ICON@.

SET_CURSOR_WAITING@ Produces a temporary hour-glass cursor.

See also Graphics functions (device independent bitmap).

Graphics functions (device context)

The following routines transmit a handle to a device context and are particularly
associated with the %gr and %dw formats described in Chapter 15.
64CN18C<0?N32/ returns a handle for use with %dw whilst 64CN2DAA4=CN32/
returns a handle for a device context created by using %gr. These routines allow
ClearWin+ to be used with Windows API functions and as such are unlikely to be of
interest to a majority of ClearWin+ programmers.

ACTIVATE_BITMAP_PALETTE@ Ensures that the palette is set correctly for the

current window.
ATTACH_BITMAP_PALETTE@ Attaches a palette to a DC.
CHANGE_PEN@ Changes the pen in a device context acquired
through GET_BITMAP_DC@.
CLEAR_BITMAP@ Clears a bitmap device context acquired by
GET_BITMAP_DC@.

GET_BITMAP_DC@ Creates a device context for use with %dw.

GET_CURRENT_DC@ Gets the current graphical device context.
RELEASE_BITMAP_DC@ Releases a bitmap device context acquired by
GET_BITMAP_DC@.

Graphics functions (device independent bitmap)

Using a 24 bit per pixel array
DISPLAY_DIB_BLOCK@ Displays an array on the screen.
GET_DIB_BLOCK@ Reads a BMP file into an array.
GET_DIB_SIZE@ Gets information from a BMP file.

319
ClearWin+ User’s Guide Fortran

PUT_DIB_BLOCK@ Saves an array to a BMP file.

Using a handle
CLIPBOARD_TO_SCREEN_BLOCK@ Copies a bitmap on the clipboard to a DIB.
DIB_PAINT@ Displays a DIB.
EXPORT_BMP@ Exports a DIB to a BMP file.
EXPORT_PCX@ Exports a DIB to a PCX file.
GET_SCREEN_DIB@ Copies part of a graphics area.
IMPORT_BMP@ Reads in a BMP file.
IMPORT_PCX@ Reads in a .PCX file.
PRINT_DIB@ Prints a device independent bitmap.
RELEASE_SCREEN_DIB@ Releases memory for a DIB.

See page 145 for further details.

Graphics functions (font,text)

BOLD_FONT@ Makes text on a drawing surface bold.
CHOOSE_FONT@ Displays a standard Windows dialog box so that the
user can select a font and its colour.
DRAW_CHARACTERS@ Draws text on a drawing surface.
FONT_METRICS@ Gets the system metrics for the default font and the
current drawing surface.
GET_FONT_ID@ Gets the font identifier for the current drawing
surface.
GET_FONT_NAME@ Returns the name of a loaded font.
GET_SYSTEM_FONT@ Gets the attributes of the system font.
GET_TEXT_SIZE@ Gets the dimensions of a given character string.
ITALIC_FONT@ Makes text on a drawing surface italic.
ROTATE_FONT@ Rotates the font being used on a drawing surface.
SCALE_FONT@ Scales the font being used on a drawing surface.

320
Chapter 26 Library overview

SELECT_FONT@ Selects a font for a drawing surface.

SELECT_FONT_ID@ Selects a font for a drawing surface.
SIZE_IN_PIXELS@ Sets the font size for a drawing surface.
SIZE_IN_POINTS@ Sets the font size for a drawing surface.
UNDERLINE_FONT@ Underlines text on a drawing surface.
USE_WINDOWS95_FONT@ Sets the default font to Windows 95 font (Windows 95
only).

Graphics functions (lines,fill)

The following routines draw to the current drawing surface. The colour value that is
used will depend on the selected colour mode for the surface (either RGB mode or
VGA mode). See Chapter 15 for details.

CLEAR_SCREEN@ Clears a drawing surface.

DRAW_BEZIER@ Draws a Bezier spline.
DRAW_ELLIPSE@ Draws an ellipse.
DRAW_FILLED_ELLIPSE@ Fills an ellipse.
DRAW_FILLED_POLYGON@ Fills a polygon.
DRAW_FILLED_RECTANGLE@ Fills a rectangle.
DRAW_LINE_BETWEEN@ Draws a straight graphics line.
DRAW_POINT@ Sets the colour of a pixel..
DRAW_POLYLINE@ Draws a number of connected straight lines.
DRAW_RECTANGLE@ Draws a rectangle.
FILL_SURFACE@ Fills a area with a given colour.
FILL_TO_BORDER@ Fills a area with a given colour.
GET_GRAPHICS_SELECTED_AREA@ Gets the current screen ‘rubber-band’
rectangle.
GET_POINT@ Gets the colour of a pixel..
SET_GRAPHICS_SELECTION@ Selects a screen ‘rubber-band’ mode.
SET_LINE_STYLE@ Sets the line style.

321
ClearWin+ User’s Guide Fortran

SET_LINE_WIDTH@ Sets the line width.

Graphics functions (metafiles)

A metafile is a device independent representation for graphics images. You need to
open a metafile if you use either 3>N2>?84B/ or ?A8=CN6A0?782BN?064/ to print a
graphics image (an example appears on page 195).

CLOSE_METAFILE@ Closes a previously opened metafile.

DO_COPIES@ Produces multiple printer copies using a
metafile.
METAFILE_TO_CLIPBOARD@ Sends a metafile to the clipboard.
OPEN_METAFILE@ Records graphics sequences so that they can be
replayed to the printer.
PLAY_CLIPBOARD_METAFILE@ Plays a clipboard metafile on the current
drawing surface.
PRINT_GRAPHICS_PAGE@ Prints a drawing surface using a metafile.

Graphics functions (palette)

GET_MATCHED_COLOUR@ Gets the closest match on the current
drawing surface.
GET_NEAREST_SCREEN_COLOUR@ Gets the closest screen colour match from
the system palette.
GET_RGB_VALUE@ Gets the RGB value of the colour of a pixel
on the current drawing surface.
HIGH_COLOUR_MODE@ Tests if the screen is a high colour device.
SET_RGB_COLOURS_DEFAULT@ Changes the global default colour mode.
USE_APPROXIMATE_COLOURS@ Switches off colour matching.
USE_RGB_COLOURS@ Switches between VGA colour mode and
A61 colour mode on a drawing surface.

The following functions access an intenal ClearWin+ palette - a logical palette that is
attached to the device context of each drawing surface. Palettes are redundant if the

322
Chapter 26 Library overview

graphics device is a high colour device (i.e. has more than 8 bits per pixel). These
functions are documented in the ClearWin+ User’s Supplement.

GET_COLOURS@ Accesses palette data.

GET_PCL_PALETTE@ Accesses palette data.
LOAD_PCL_COLOURS@ Loads standard PCL colours.
LOAD_STANDARD_COLOURS@ Loads standard VGA colours.
PERFORM_COLOURS@ Implements a palette change.
SET_COLOURS@ Loads given palette data.

Graphics functions (printer,files)

CLOSE_PRINTER@ To output to a graphics printer or plotter.
CLOSE_PRINTER_ONLY@ Closes a graphics printer or plotter without
output.
GET_PRINTER_ORIENTATION@ Gets the printer orientation as portrait or
landscape.
NEW_PAGE@ Provides a new page on the current drawing
surface.
OPEN_GL_PRINTER@ Begins OpenGL output to a graphics printer.
OPEN_GL_PRINTER1@ Begins OpenGL output to a graphics printer.
OPEN_PRINTER@ Begins output to a graphics printer or plotter.
OPEN_PRINTER_TO_FILE@ Begins output to a file.
OPEN_PRINTER1@ Begins output to a graphics printer or plotter.
OPEN_PRINTER1_TO_FILE@ Begins output to a file.
PRINT_OPENGL_IMAGE@ Prints an OpenGL image.
SELECT_PRINTER@ Configures and selects the active printer.
SET_PRINTER_ORIENTATION@ Sets the printer orientation to portrait or
landscape.

Graphics functions (screen,regions)

Regions
COPY_GRAPHICS_REGION@ Copies one drawing surface to another.
CREATE_GRAPHICS_REGION@ Creates a drawing surface.
DELETE_GRAPHICS_REGION@ Removes a drawing surface.
GRAPHICS_TO_CLIPBOARD@ Copies a drawing surface to the clipboard.
SCROLL_GRAPHICS@ Scrolls a drawing surface.
SELECT_GRAPHICS_OBJECT@ Selects a drawing surface.
WRITE_GRAPHICS_TO_BMP@ Writes a drawing surface to a file.
WRITE_GRAPHICS_TO_PCX@ Writes a drawing surface to a file.

These are used together with the DIB functions listed on page 319. An alternative set
of routines uses the concept of a virtual screen (a legacy from DOS programming).
The alternative set is described in the ClearWin+ User’s Supplement.

Other routines
GET_GRAPHICAL_RESOLUTION@ Gets the width and height of the current
drawing surface.
GRAPHICS_WRITE_MODE@ Selects replace/XOR mode before writing to
a drawing surface.
PERFORM_GRAPHICS_UPDATE@ Refreshes a drawing surface’s display.

Hypertext functions
The following routines can be used in association with the %ht format described in
Chapter 19.

ADD_HYPERTEXT@ Adds text to the hypertext system.

ADD_HYPERTEXT_RESOURCE@ Opens a hypertext resource that is included
in a resource file.
CHANGE_HYPERTEXT@ Changes the topic in a hypertext control.

324
Chapter 26 Library overview

Information functions
The following routines can be used in association with the F8=8>/ function.

CLEARWIN_FLOAT@ Interrogates the state of the ClearWin+

environment.
CLEARWIN_INFO@ Interrogates the state of the ClearWin+
environment.
CLEARWIN_STRING@ Obtains string information from
ClearWin+.
CLEARWIN_VERSION@ Gets the current ClearWin+ version
information.
SET_CLEARWIN_FLOAT@ Sets or change a floating point value
associated with a named string.
SET_CLEARWIN_INFO@ Sets or change an integer value associated
with a named string.
SET_CLEARWIN_STRING@ Sets or change a string value associated
with a named string.

Mouse functions
GET_MOUSE_INFO@ Gets the mouse position, mouse state and
keyboard state.
SET_MOUSE_CURSOR_POSITION@ Sets the mouse position relative to a given
window.

Movie functions
SHOW_MOVIE@ To show a video.
MOVIE_PLAYING@ To test if a video is still playing.

325
ClearWin+ User’s Guide Fortran

Standard dialog functions

CHOOSE_COLOUR@ Displays a standard Windows dialog box so
that the user can select a colour.
CHOOSE_FONT@ Displays a standard Windows dialog box so
that the user can select a font and its colour.
DEFINE_FILE_EXTENSION@ Allows application registry under Windows
95.
GET_FILTERED_FILE@ Accesses the standard ‘open’ dialog box.
SET_OPEN_DIALOG_PATH@ Sets the initial directory before displaying the
standard file open dialog box.

CLOSE_CD_TRAY@ Closes an open CD-drive tray.

CLOSE_WAV_FILE@ Closes a WAV file opened by
OPEN_WAV_FILE_READ@ or
OPEN_WAV_FILE_WRITE@.

GET_TRACK_LENGTH@ Returns the length of a CD track.

OPEN_CD_TRAY@ Opens a CD-drive tray.
OPEN_WAV_FILE_READ@ Opens a WAV file for reading in sections.
OPEN_WAV_FILE_WRITE@ Opens a WAV file for reading in sections.
PLAY_AUDIO_CD@ Plays the audio CD from the current
position.
PLAY_SOUND@ Sends a sample to the audio output device.
PLAY_SOUND_RESOURCE@ Sends a resource B>D=3 to the current audio
device.
RECORD_SOUND@ Records sound from the sound input device.
SET_CD_POSITION@ Sets the position of the CD read head to
CA02: + <8;;8B42>=3B (offset).

326
Chapter 26 Library overview

SET_SOUND_SAMPLE_RATE@ Sets the sampling speed.

SOUND_PLAYING@ Tests for ongoing sound output.
SOUND_RECORDING@ Tests if a recording is being made.
SOUND_SAMPLE_RATE@ Returns the current sound sampling rate.
STOP_AUDIO_CD@ Stops audio playback from the CD.
WAV_FILE_READ@ Reads a WAV file as a samples wave-form.
WAV_FILE_WRITE@ Stores any recorded data.
WRITE_WAV_FILE@ Stores any recorded data.

Useful API functions

The following API functions are simple to use and are occasionally useful in
ClearWin+ programs. Details can be found in Microsoft SDK documentation.

BringWindowToTop Brings the specified window to the top of the “Z order”.

ClipCursor Confines the mouse cursor to a given rectangle. Use
CORE4(0) to represent the NULL pointer. Use an integer
array to represent the RECT structure.
CopyFile Copies one file to another.
CreateProcess For simplicity, use BC0ACN?A>24BB/
EnableWindow Enables/disables a window.
FindWindow Finds the handle of a window from its class name and/or its
title.
GetDeskTopWindow Gets the window handle of the screen.
GetWindowLong Gets window parameters such as style and extended style.
GetWindowText Gets the title of a window.
IsIconic Tests if a window is minimised.
IsWindowVisible Tests if a window is visible.
IsZoomed Tests if a window is maximised.
MoveWindow Changes a window’s position and dimensions.*
SetWindowLong Sets window parameters such as style and extended style.

327
ClearWin+ User’s Guide Fortran

SetWindowPos Changes a window’s position, dimensions and state.*

SetWindowText Sets the title of a window.
ShellExecute Opens or prints a file (e.g. accesses a website).
ShowWindow Changes a windows state: visible, minimised, etc.
WinExec Starts another application (see also BC0ACN?A>24BB/).
WinHelp Displays a Windows help file.

* See also 64CNF8=3>FN;>20C8>=/ and its associated notes.

328
27.

Library reference

ABORT@
Purpose To terminate a program in the event of an error.
Syntax BD1A>DC8=4 01>AC/
Description Normally when a program terminates - e.g. by executing a STOP statement, or by
encountering the END statement in the main program - any windows that are open are
left open until the user closes them and call-back functions continue to be called to
service the open windows.
Sometimes, if for example a serious error is detected, it may be necessary to terminate
the program immediately in which case the subroutine 01>AC/ should be called.

ACTIVATE_BITMAP_PALETTE@
Purpose To ensure that the palette is set correctly for the current window.
Syntax BD1A>DC8=4 02C8E0C4N18C<0?N?0;4CC4/ 32
8=C464A 32
Description This subroutine restores the current palette that the device context is using. This is
usually handled by Clearwin+.
See also 0CC027N18C<0?N?0;4CC4/ 2;40AN18C<0?/ 2A40C4N18C<0?/
64CN18C<0?N32/

329
ClearWin+ User’s Guide Fortran

ADD_ACCELERATOR@
Purpose To associate an accelerator key with a given window.
Syntax BD1A>DC8=4 033N0224;4A0C>A/ F :4HN=0<4 5
8=C464A F
270A02C4A :4HN=0<4
4GC4A=0; 5
Description This associates the callback function 5 with the named key (see the definition of %ac
on page 88 for details of the names of keys). F is the handle of the window which you
can obtain using %hw when the window is created. If a previous accelerator definition
for this key in this window exists then it is removed.
Notes You could use this routine if you were writing a configurable editor and you wished to
change the accelerator definitions of the surounding window dynamically.
The call-back function cannot be a string representing a standard call-back.
See also %ac, A4<>E4N0224;4A0C>A/

ADD_CURSOR_MONITOR@
Purpose To name a call-back function that monitors which window or control has the cursor.
Syntax BD1A>DC8=4 033N2DAB>AN<>=8C>A/ 21N5D=2
4GC4A=0; 21N5D=2
Description A general mechanism is available to enable programmers to monitor the
window/control that has the cursor (or the focus, see 033N5>2DBN<>=8C>A/).

21N5D=2 is the name of a routine that is either a function returning an integer, or a

BD1A>DC8=4. The return value (if any) is not used. Cursor call-back functions can
use the 2;40AF8=N8=5>/ parameter 2DAB>ANF8=3>F to determine the window
handle of the control or window which has the cursor.
Notes a) Window handles can be obtained using %hw or %lc.
b) Although window handles are unique at any given time, handles can (and often do)
get re-used after a window has been destroyed.
See also A4<>E4N2DAB>AN<>=8C>A/ 033N5>2DBN<>=8C>A/

330
Chapter 27 Library reference

ADD_FOCUS_MONITOR@
Purpose To name a call-back function that monitors which control has the focus.
Syntax BD1A>DC8=4 033N5>2DBN<>=8C>A/ 21N5D=2
4GC4A=0; 21N5D=2
Description See 033N2DAB>AN<>=8C>A/. Focus call-back functions use the 2;40AF8=N8=5>/
parameter 5>2DBB43NF8=3>F.
Notes The 2;40AF8=N8=5>/ parameter used here is not the same as 5>2DBNF8=3>F
which returns the handle of the F8=8>/ window which has focus rather than the
control within the window that has the focus.
See also A4<>E4N5>2DBN<>=8C>A/

ADD_GRAPHICS_ICON@
Purpose To place a movable icon or bitmap in a %gr graphics region.
Syntax 8=C464A 5D=2C8>= 033N6A0?782BN82>=/=0<4 G H
F83C7 34?C7
270A02C4A =0<4
8=C464A G H F83C7 34?C7
Description A %gr graphics region may have an icon resource ‘attached’ to it. The icon can be
moved freely around the graphics window with the mouse. Control of the icon is
maintained by the call-back function attached to the %gr window with the caret
modifier (^).
The =0<4 argument is that used for the resource that is included in your program. The
G and H values, initially hold the location the image is draw to. They also hold the new
position when the image is moved. The 2;40AF8=N8=5>/ parameter
3A06643N82>= is set to the value of the handle of the moved icon. The handle is
initially obtained as the returned from the function. The call-back function may
modify the G and H values if required. The purpose of this may be to ‘lock’ the image
onto the horizontal or vertical plane by continuously setting either the G or H variables
to a constant value.
When the icon is dropped 2;40AF8=N8=5>/ parameter 3A>??43N82>= is set to
the handle of the icon. A graphics icon can be removed with a call to
A4<>E4N6A0?782BN82>=/.

331
ClearWin+ User’s Guide Fortran

The F83C7 and 74867C parameters should be set at zero except when the icon image
occupies less than the possible 32x32 icon area e.g. 16x16. A small icon can be
constructed by starting at the top-left corner and filling the remaining unused area with
the ‘transparent’ colour. If you do not specify the correct size of the icon then the
unused area will be detected by the mouse.
Return value Returns a non-zero value for success or zero for failure.
See also A4<>E4N6A0?782BN82>=/

ADD_HYPERTEXT@
Purpose To add text to the hypertext system.
Syntax BD1A>DC8=4 033N7H?4AC4GC/ 1D554A B8I4 7C4GC=0<4
270A02C4A 1D554A 7C4GC=0<4
8=C464A B8I4
Description 033N7H?4AC4GC/ adds, to the hypertext resource base, a hypertext document
containing one or more hypertext topics. Note that this routine does not take a copy of
the hypertext data so you must ensure that the memory is not changed or discarded
before any hypertext processing is complete. The format code %ht is used to display
the hypertext resource. Resources may be included in the resource section of your
program/resource script.
See also 033N7H?4AC4GCNA4B>DA24/

ADD_HYPERTEXT_RESOURCE@
Purpose To open a hypertext resource that is included in a resource file.
Syntax BD1A>DC8=4 033N7H?4AC4GCNA4B>DA24/ =0<4
270A02C4A =0<4
Description The resource file must be added to combine the hypertext document with the program
using it. The resource filename should be placed on the F8=0?? line after the stack
and heap size declarations.
See %ht format and the browse example code included with the ClearWin+ release.
See also 033N7H?4ACC4GC/

332
Chapter 27 Library reference

Example
F8=0?? $ $ ³<H?A>6A2´
Where myprog.rc is a list of resources.
For example:
7H?B><48=5> 7H?4AC4GC X]U^ Wc\

ADD_KEYBOARD_MONITOR@
Purpose To name a call-back function that monitors the use of the keyboard.
Syntax BD1A>DC8=4 033N:4H1>0A3N<>=8C>A/ 21N5D=2
4GC4A=0; 21N5D=2
Description See 033N2DAB>AN<>=8C>A/. Keyboard call-back functions use the
2;40AF8=N8=5>/ parameter :4H1>0A3N:4H.
Notes This routine replaces 64CNF:4H/ and 64CNF:4H / and should be used in preference
to these routines. Calls to these routines will fail if 033N:4H1>0A3N<>=8C>A/ has
been called.
See also A4<>E4N:4H1>0A3N<>=8C>A/

ADD_MENU_ITEM@
Purpose To create a dynamic menu using %mn.
Syntax BD1A>DC8=4 033N<4=DN8C4</ 70=3;4 =0<4 4=01;4
2742: 20;;102:N5D=2C8>=
8=C464A 70=3;4 4=01;4 2742: 20;;102:N5D=2C8>=
270A02C4A =0<4
Description By using %mn, menu items can be added at run time. This is of greatest use when you
wish to show a file history or a list of open windows. Items are added one at a time to
the end of the pop down menu that contains the handle.
In %mn (see page 81) an asterisk (*) must be added where a text description would
previously have been placed and a integer argument, instead of a call-back, must be
provided to hold the 70=3;4.
For example:

333
ClearWin+ User’s Guide Fortran

X,fX]X^/³\]JFX]S^fJLL´70=3;4
70=3;4 can then be passed to 033N<4=DN8C4</.
=0<4 is the new string to put into the menu i.e. the new menu item. 4=01;4 controls
the enabling of the item (1 for enabled, zero for disabled, i.e. greyed) and the 2742:
will add or remove a tick character (1 for checked, zero for unchecked). A call-back
function must be provided so that ClearWin+ can act upon a menu selection. A
separator is obtained if =0<4 is input as 270A.
Example See page 83.
See also A4<>E4N<4=DN8C4</ %mn

ATTACH_BITMAP_PALETTE@
Purpose To attach a palette to a DC.
Syntax 8=C464A 0CC027N18C<0?N?0;4CC4/ 732 ?
8=C464A 732 ?
Description To attach a colour palette to a device context. This should not normally be needed as
B4CN2>;>DAB/ provides sufficient flexibility.
Return value On success 1 will be returned. -1 indicates that the screen type cannot provide the
palette requested due to too few palette entries available. A zero indicates that the
display is in full colour mode and therefore does not use a palette.
See also 02C8E0C4N18C<0?N?0;4CC4/

BOLD_FONT@
Purpose To change the current drawing surface text to/from bold.
Syntax BD1A>DC8=4 1>;3N5>=C/ 02C8E4
8=C464A 02C8E4
Description When using the function 3A0FN270A02C4AB/ on a drawing surface with any font
selected (other than a Hershey font), a call to this routine with a value of one will
make any further text output bold. A further call with a value of zero will reverse the
effect.

334
Chapter 27 Library reference

0224;4A0C>A Call associated with %ac.

1DCC>=N?A4BB A button has been pressed.

2>;>DA8=6 User_colour event for edit box (%eb).

30C0N0;C4A0C8>= The contents of %eb, %rd (etc.) box have been altered.

38ACH Indicates an OpenGL window is in need of re-

painting.
3A06N0=3N3A>? Call in response to dropping a file onto the window.

4=D<4A0C43N?0A0<4C4A An enumerated parameter (%ep) has been selected

from within a parameter box.
58;4N>?4= Call from 'FILE_OPENR' or 'FILE_OPENW'.

608=8=6N5>2DB Edit box gets input focus.

7H?4AC4GCN270=64 Called when hypertext is being changed.

7H?4AC4GCN;8=: Call-back from activating a hypertext link in %ht.

8C4<N3>D1;4N2;82:43 Listbox item double clicked.

8C4<NB4;42C43 Listbox item selected.

:4HN3>F= A keyboard key has been pressed.

;>B8=6N5>2DB Edit box loses input focus.

<4=DNB4;42C8>= A menu item has been invoked.

342
Chapter 27 Library reference

<4BB064N7>>: Call of %mg related function.

<>DB4N;45CN2;82: Left button down.

<>DB4N;45CNA4;40B4 Left button up.

<>DB4N3>D1;4N2;82: Left double click.

<>DB4N<833;4N2;82: Middle button down.

<>DB4N<833;4NA4;40B4 Middle button up.

<>DB4N<>E4 Mouse movement.

<>DB4NA867CN2;82: Right button down.

<>DB4NA867CNA4;40B4 Right button up.

A4B8I4 Called when a control is being re-sized.

DB4AN?0A0<4C4A A user parameter (%up) has been selected from within

a parameter box.
C8<4A Call associated with %dl.

F8=3>FN2;>B4 Call in response to %cc.

F8=3>FNBC0ACD? Call in response to %sc.

Called as part of a compound call-back.

. Not currently in a call-back.

Return value Returns the value of the specified string parameter.

25NA855 Resource interchange format

25NBH;: Microsoft symbolic link format
25NC4GC Text format
25NC855 Tag image file format
25NF0E4 Wave format
The 1D554A will contain =D< bytes copied from the clipboard. To determine the
length of 25NC4GC or 25N>4<C4GC the routine B8I4>5N2;8?1>0A3NC4GC/ can be
called.
Return value Returns 1 for success or zero for failure.
See also 2>?HNC>N2;8?1>0A3/ 2;8?1>0A3NC>NB2A44=N1;>2:/
B8I4>5N2;8?1>0A3NC4GC/
Example

8=C464A PSSa[T]X
270A02C4A QdUUTa !#
[T],bXiTÛNR[X_Q^PaSNcTgc/
85[T]6CC74=
20;; VTcNbcâPVT/PSSa[T]
85PSSa6CC74=
X,R^_hNUa^\NR[X_Q^PaS/PSSa[T] 25NC4GC
20;; \êT/QdUUTa22>A4 PSSa[T]
4=385
4=385

COPY_GRAPHICS_REGION@
Purpose To copy screen blocks in drawing surfaces defined by %gr etc..
Syntax 8=C464A 5D=2C8>= 2>?HN6A0?782BNA468>=/
34BCN6A 3G 3H 3F83C7 374867C
BA2N6A BG BH BF83C7 B74867C 2>?HN<>34
8=C464A 34BCN6A 3G 3H 3F83C7 374867C
BA2N6A BG BH BF83C7 B74867C 2>?HN<>34
Description You must have at least one drawing surface open (see for example %`gr on page 136).
34BCN6A is the handle of the destination drawing surface and BA2N6A is the source
drawing surface, however, the handles specified can be the same. If you set either or
both to zero then the current drawing surface is assumed for the source and/or
destination.

347
ClearWin+ User’s Guide Fortran

3G 3H 3F83C7 and 374867C specify the destination rectangular region.
BG BH BF83C7 and B74867C specify the source rectangular region.
If 3F83C7 = BF83C7 and 374867C = B74867C then a normal copy will occur. If
there are any differences then the image will be ‘stretched’ accordingly.
2>?HN<>34 defines the method of copying. Windows defines 255 different copy
methods (ROPS). The most useful are described below:

Hex Value Name Logical Description

22! BA22>?H source (most common - a direct copy)

''2% BA20=3 source and destination
%%#% BA28=E4AC source xor destination
##"!' BA24A0B4 source and not destination
44'% BA2?08=C source or destination
""' =>CBA22>?H not source
0% =>CBA24A0B4 not (source or destination)
11!!% <4A64?08=C not source or destination
$$( 3BC8=E4AC not destination
#! 1;02: 0
55%! F78C4 1

Return value Returns 1 for success or zero for failure.

Notes Under Win32 it is possible to stretch a drawing surface when copying from the screen
to a printer but not every printer supports this mode.
See also B2A>;;N6A0?782B/ B4;42CN6A0?782BN>1942C/
2A40C4N6A0?782BNA468>=/ 34;4C4N6A0?782BNA468>=/

COPY_TO_CLIPBOARD@
Purpose To copy data to the clipboard.
Syntax 8=C464A 5D=2C8>= 2>?HNC>N2;8?1>0A3/ 1D554A =D< CH?4

348
Chapter 27 Library reference

270A02C4A 1D554A
8=C464A =D< CH?4
Description =D< contents of 1D554A will be placed into the Windows clipboard and will be of the
CH?4 specified. For a list of the available data types see the
2>?HN5A><N2;8?1>0A3/ function.
Return value Returns 1 on success or zero on failure.
See also 2>?HN5A><N2;8?1>0A3/2;8?1>0A3NC>NB2A44=N1;>2:/
6A0?782BNC>N2;8?1>0A3/ B8I4>5N2;8?1>0A3NC4GC/

CREATE_BITMAP@
Purpose To create a bitmap from bitmap data.
Syntax 8=C464A 5D=2C8>= 2A40C4N18C<0?/ ?CA
8=C464A ?CA
Description Creates a bitmap from a pointer to data that is in the same format as a .BMP file.
When the program is terminated the bitmap will be deleted. The function returns a
handle that can be used with %`bm or in Windows API functions that require a
HBITMAP handle.
Return value Returns a handle to the new bitmap. A zero return indicates failure.
See also <0:4N18C<0?/

CREATE_CURSOR@
Purpose To create a cursor from data in a .CUR file.
Syntax 8=C464A 5D=2C8>= 2A40C4N2DAB>A/ ?CA
8=C464A ?CA
Description Creates a cursor from a pointer to data that is in the same format as a .CUR file. When
the program is terminated the cursor will be deleted. The function returns a handle
that can be used, for example, with %`cu or in Windows API functions that require a
HCURSOR handle.
Return value Returns a handle to the new cursor. A zero return indicates failure.

349
ClearWin+ User’s Guide Fortran

CREATE_GRAPHICS_REGION@
Purpose To create an internal (off-screen) drawing surface.
Syntax 8=C464A 5D=2C8>= 2A40C4N6A0?782BNA468>=/ 70=3;4
F83C7 74867C
8=C464A 70=3;4 F83C7 74867C
Description This routine is used to create internal drawing surfaces. For example, it can be used to
display part of a large bitmap. Areas of the buffer can be copied into a %gr region (for
example) using 2>?HN6A0?782BNA468>=/. If you make extensive use of this
function it is recommended that you delete unwanted surfaces with a call to
34;4C4N6A0?782BNA468>=/.
70=3;4 is an input value, chosen by the programmer, that must be unique. It is used
to identify the surface in calls to related functions. F83C7 74867C specify the size
in pixels of the region.
The colour mode for the surface will be determined by the default colour mode or by
the colour mode of the current %gr drawing surface.
Return value Returns 1 for success, otherwise zero.
See also 34;4C4N6A0?782BNA468>=/ 2>?HN6A0?782BNA468>=/ B2A>;;N6A0?782B/

CREATE_WINDOW@
Purpose To create and display a ClearWin window.
Syntax 8=C464A 5D=2C8>= 2A40C4NF8=3>F/C8C;4GHGFHF
8=C464A GHGFHF
270A02C4A C8C;4
Description Creates a window of width GF, height HF and title C8C;4 at position (GH).
Do not confuse this function with the similarly named routine in the Windows API
called CreateWindow.
Return value Returns a standard Windows handle.

350
Chapter 27 Library reference

DEFINE_FILE_EXTENSION@
Purpose Allows application registry under Windows 95.
Syntax BD1A>DC8=4 3458=4N58;4N4GC4=B8>=/4GC=0<4 ?0C7
34B2A 82>=N83G =4F
270A02C4A !( =0<4 ?0C7 34B2A8?C8>=
8=C464A 82>=N8=34G =4F >?C8>=
Description Under Windows 95 it is possible to register an application with the system so that if a
data file is opened via Explorer your application will be called to process it.
The 4GC=0<4 variable is a string that contains the extension, the ?0C7 must contain
the full path and program name. A text description should be supplied in
34B2A8?C8>=. The 82>=N8=34G selects the icon to be used by Windows. If you
specify -1 no icon is used otherwise the relevant icon is used. i.e. if you have four
icons in your resource, by placing a value of 2 in 82>=N8=34G the second icon
resource will be used. =4F >?C8>= option should be set to a non zero value to activate
the file type addition to Windows 95.
For example:
270A02C4A !( _]P\T
20;; VTcN_a^VaP\N]P\T/_]P\T
Z,STUX]TNUX[TNTgcT]bX^]/³82>´_]P\T
³8R^] UX[T TSXc^a´
You can obtain the file name passed to your program, by Windows 95 as if you were
examining the arguments on the command line.
For example:
...
270A02C4A !( R\]P\/UX[Tc^^_T]
UX[Tc^^_T],R\]P\/
...

64CN?A>6A0<N=0<4/ and 2<=0</ are Salford library functions.

351
ClearWin+ User’s Guide Fortran

DELETE_GRAPHICS_REGION@
Purpose To remove an internal drawing surface.
Syntax 8=C464A 5D=2C8>= 34;4C4N6A0?782BNA468>=/ 70=3;4
8=C464A 70=3;4
Description This routine will remove from memory a drawing surface that has previously been
defined by 2A40C4N6A0?782BNA468>=/. 70=3;4 is the value used in an earlier
call to 2A40C4N6A0?782BNA468>=/.
Return value Returns 1 for success, otherwise zero.
See also 2A40C4N6A0?782BNA468>=/ 2>?HN6A0?782BNA468>=/ B2A>;;N6A0?782B/

DESTROY_WINDOW@
Purpose To close and destroy a displayed ClearWin window.
Syntax BD1A>DC8=4 34BCA>HNF8=3>F/F
8=C464A F
Description Destroys a window specified by F and any child windows that may be owned by it.
Fonts owned by the window are not destroyed. W is the window handle returned by
2A40C4NF8=3>F/.

DIB_PAINT@
Purpose To display a device independent bitmap (DIB).
Syntax 8=C464A 5D=2C8>= 381N?08=C/ 7>A8I E4AC 7381
5D=2C8>= <>34
8=C464A 7>A8I E4AC 7381 5D=2C8>= <>34
Description Displays the DIB with handle 7381 on the current device with 7>A8I and E4AC
relative displacement (they may be negative). 5D=2C8>= selects the type of logical
restore operation with respect to the previous screen :
0 REPLACE former pixel
1 AND with former pixel
2 OR with former pixel

352
Chapter 27 Library reference

3 XOR with former pixel

<>34 specifies if
0 the dib palette should be used,
1 the current palette should be used and the image not dithered,
2 dithering should be used.
Before you can call this function the DIB must first be loaded using
64CNB2A44=N1;>2:/, 8<?>ACN1<?/, 8<?>ACN?2G/, or
2;8?1>0A3NC>NB2A44=N1;>2:/.
Return value Returns 1 the function is successful otherwise zero.

DISPLAY_DIB_BLOCK@
Purpose To display a device independent bitmap.
Syntax BD1A>DC8=4 38B?;0HN381N1;>2:/ GH?0AA0H0F070G0HF7
5D=2C8>=<>344A2>34
270A02C4A ?0AA0H"0F07
8=C464A GH0F070G0HF75D=2C8>=<>344A2>34
Description All of the arguments are input values except for 4A2>34 which returns the error status.
This routine transfers a rectangular block of size F × 7 from the array ?0AA0H at
position (0G, 0H) to the position (G, H) on the current graphics device (e.g. a %gr
window or a printer). 5D=2C8>= and <>34 are the same as in 381N?08=C/ and will
normally be set to zero. The variable 4A2>34 is returned as zero if the process is
successful.
See also 64CN8<N8=5>/ 64CN381NB8I4/ 64CN381N1;>2:/ ?DCN381N1;>2:/
?A8=CN381/
Example See page 145.

DISPLAY_POPUP_MENU@
Purpose To activate a popup menu defined using %pm.
Syntax BD1A>DC8=4 38B?;0HN?>?D?N<4=D/

353
ClearWin+ User’s Guide Fortran

Description This subroutine will activate a pre-defined popup menu. It can be used when the right
mouse button is pressed over a %gr drawing surface that has 5D;;N<>DB4N8=?DC
activated (see page 136).

DO_COPIES@
Purpose To produce multiple printer copies of a graphics image using metafiles.
Syntax 8=C464A 3>N2>?84B/ 70=3;4 =D<
8=C464A 70=3;4 =D<
Description Sends =D< copies to the printer. A metafile must have been created with a call to
>?4=N<4C058;4/ and also closed by 2;>B4N<4C058;4/ before 3>N2>?84B/ can be
used. The 2;40AF8=N8=5>/ parameter ?A8=C4AN2>?84B will return the number of
copies the user has selected.
The call to 2;>B4N?A8=C4A/ will have automatically sent one copy to the printer.
See also >?4=N?A8=C4A/ 2;>B4N?A8=C4A/
Example See page 195.

DRAW_BEZIER@
Purpose To draw a Bezier spline.
Syntax BD1A>DC8=4 3A0FN14I84A/ G H = 2>;>DA
8=C464A G=H==2>;>DA
Description G and H are arrays giving the co-ordinates of the = knots and 2>;>DA is the colour
value using the current colour mode.

DRAW_CHARACTERS@
Purpose To draw text on the current drawing surface.
Syntax BD1A>DC8=4 3A0FN270A02C4AB/BCA878E82>;
270A02C4A BCA
8=C464A 878E82>;

354
Chapter 27 Library reference

Description 3A0FN270A02C4AB/ draws text, using the current font and attributes, at the point (87,
8E). These co-ordinates represent the bottom left-hand corner of the first character.
BCA contains the character string to be drawn. The text is positioned to the nearest
pixel. 82>; provides the colour for the text that appears on the existing background
using the current colour mode.
See also B4;42CN5>=C/ B20;4N5>=C/ D=34A;8=4N5>=C/ 8C0;82N5>=C/
1>;3N5>=C/ B8I4N8=N?8G4;B/ B8I4N8=N?>8=CB/ A>C0C4N5>=C/
64CN5>=CN=0<4/ 27>>B4N5>=C/.

DRAW_ELLIPSE@
Purpose To draw an ellipse on the current drawing surface.
Syntax BD1A>DC8=4 3A0FN4;;8?B4/8G28H2808182>;
8=C464A 8G28H2808182>;
Description 3A0FN4;;8?B4/ draws an ellipse with centre at (8G2, 8H2), with horizontal semi-
axis 80, vertical semi-axis 81 and colour 82>; using the current colour mode. This
routine can be used to produce a circle on the drawing surface if the axes are scaled
appropriately.
See also 3A0FN58;;43N4;;8?B4/

DRAW_FILLED_ELLIPSE@
Purpose To fill an ellipse on the current drawing surface.
Syntax BD1A>DC8=4 3A0FN58;;43N4;;8?B4/8G28H2808182>;
8=C464A 8G28H2808182>;
Description 3A0FN58;;43N4;;8?B4/ fills an ellipse with centre at (8G2, 8H2), with horizontal
semi-axis 80, vertical semi-axis 81 and colour 82>; using the current colour mode.
This routine can be used to fill a circle if the axes are scaled appropriately.
See also 3A0FN4;;8?B4/

355
ClearWin+ User’s Guide Fortran

DRAW_FILLED_POLYGON@
Purpose To fill a polygon on the current drawing surface.
Syntax BD1A>DC8=4 3A0FN58;;43N?>;H6>=/8G8H=82>;
8=C464A 8G=8H=
8=C464A =82>;
Description 3A0FN58;;43N?>;H6>=4/ draws a straight line from (8G(1), 8H(1)) to (8G(2),
8H(2)), and continues until (8G(=), 8H(=)) and fills the enclosed region. 82>;
specifies the fill colour value using the current colour mode.
See also 3A0FN?>;H;8=4/

DRAW_FILLED_RECTANGLE@
Purpose To fill a rectangle on the current drawing surface.
Syntax BD1A>DC8=4 3A0FN58;;43NA42C0=6;4/8G 8H 8G!8H!82>;
8=C464A 8G 8H 8G!8H!82>;
Description 3A0FN58;;43NA42C0=6;4/ fills a rectangle in colour 82>; using the current colour
mode. (8G , 8H ) and (8G!,8H!) are opposite corners.
See also 3A0FNA42C0=6;4/

DRAW_LINE_BETWEEN@
Purpose To draw a straight line on the current drawing surface.
Syntax BD1A>DC8=4 3A0FN;8=4N14CF44=/8G 8H 8G!8H!82>;
8=C464A 8G 8H 8G!8H!82>;
Description 3A0FN;8=4N14CF44=/ draws a line with colour value 82>; using the current
colour mode) from (8G , 8H ) to (8G!, 8H!). The coordinates are pixel numbers
relative to the top left of the drawing surface.
See also 3A0FN?>;H;8=4/

356
Chapter 27 Library reference

DRAW_POINT@
Purpose To set a single pixel colour on the current drawing surface.
Syntax BD1A>DC8=4 3A0FN?>8=C/878E82>;
8=C464A 878E82>;
Description 3A0FN?>8=C/ sets the pixel at (87,8E) on the current drawing surface to colour value
82>; using the current colour mode.
See also 64CN?>8=C/, 64CNA61NE0;D4/

DRAW_POLYLINE@
Purpose To draw a number of connected straight lines.
Syntax BD1A>DC8=4 3A0FN?>;H;8=4/8G8H=82>;
8=C464A 8G=8H=
8=C464A =82>;
Description 3A0FN?>;H;8=4/ draws a straight line from (8G(1), 8H(1)) to (8G(2), 8H(2)), and
continues until (8G(=), 8H(=)). That is, it joins = points with straight lines. 82>;
specifies the colour value using the current colour mode. For a closed polygon, simply
set the last pair of coordinates equal to the first pair.
See also 3A0FN;8=4N14CF44=/, 3A0FN58;;43N?>;H6>=/

DRAW_RECTANGLE@
Purpose To draw a rectangle on the current drawing surface.
Syntax BD1A>DC8=4 3A0FNA42C0=6;4/8G 8H 8G!8H!82>;
8=C464A 8G 8H 8G!8H!82>;
Description 3A0FNA42C0=6;4/ draws a rectangle in colour 82>; using the current colour mode.
(8G , 8H ) and (8G!, 8H!) are opposite corners.

BTT P[b^ 3A0FN58;;43NA42C0=6;4/

357
ClearWin+ User’s Guide Fortran

EXPORT_BMP@
Purpose To exports a device independent bitmap to a .BMP file.
Syntax BD1A>DC8=4 4G?>ACN1<?/ 7381 58;4=0<4 4AA>A
8=C464A 381N70=3;44AA>A
270A02C4A 58;4=0<4
Description Writes a DIB to a bitmap file specified by 58;4=0<4. 7381 is a handle returned for
example by 64CNB2A44=N381/, 2;8?1>0A3NC>NB2A44=N1;>2:/ or
8<?>ACN1<?/.

4AA>A returns one of the following:

success
unable to open file
" unable to write to file
See also 8<?>ACN1<?/ FA8C4N6A0?782BNC>N1<?/ 381N?08=C/ ?A8=CN381/

EXPORT_PCX@
Purpose To export a device independent bitmap to a .PCX file.
Syntax BD1A>DC8=4 4G?>ACN?2G/ 7381 58;4=0<4 4AA>A
8=C464A 381N70=3;44AA>A
270A02C4A 58;4=0<4
Description Writes a DIB to a PCX file specified by 58;4=0<4. 7381 is a handle returned for
example by 64CNB2A44=N381/, 2;8?1>0A3NC>NB2A44=N1;>2:/ or
8<?>ACN?2G/.
4AA>A returns one of the following:
success
unable to open file
" unable to write to file
See also 8<?>ACN?2G/ FA8C4N6A0?782BNC>N?2G/ 381N?08=C/ ?A8=CN381/

358
Chapter 27 Library reference

FEED_WKEYBOARD@
Purpose To insert a key into a ClearWin window keyboard buffer.
Syntax BD1A>DC8=4 5443NF:4H1>0A3/:4H4AA>A
8=C464A :4H4AA>A
Description This routine is only for use in a ClearWin window (e.g. with %cw). :4H is the ASCII
code for the key to be inserted. Currently 4AA>A always returns zero for success.
See also 5;DB7NF:4H1>0A3/ 64CNF:4H/ 64CNF:4H / F:4HNF08C8=6/

FILL_SURFACE@
Purpose To fill an area of the current drawing surface with a given colour.
Syntax BD1A>DC8=4 58;;NBDA5024/ GBC0AC HBC0AC BDA5N2>;
58;;N2>;
8=C464A GBC0AC HBC0AC BDA5N2>; 58;;N2>;
Description GBC0AC, HBC0AC are the co-ordinates of the focus, 58;;N2>; is the colour to fill with
and BDA5N2>; is the current colour of the region to fill. The colour values relate to
the current colour mode.
See also 58;;NC>N1>A34A/

FILL_TO_BORDER@
Purpose To fill an area of the current drawing surface with a given colour.
Syntax BD1A>DC8=4 58;;NC>N1>A34A/ GBC0AC HBC0AC 58;;N2>;
BC>?N2>;
8=C464A GBC0AC HBC0AC 58;;N2>; BC>?N2>;
Description GBC0AC, HBC0AC are the co-ordinates of the focus, 58;;N2>; is the colour to fill with
and BC>?N2>; is the colour of the closed boundary of the area to fill. The colour
values relate to the current colour mode
See also 58;;NBDA5024/

359
ClearWin+ User’s Guide Fortran

FLUSH_WKEYBOARD@
Purpose To empty a ClearWin window keyboard buffer.
Syntax BD1A>DC8=4 5;DB7NF:4H1>0A3/
Description This routine is only for use in a ClearWin window (e.g. with %cw).
See also 5443NF:4H1>0A3/ 64CNF:4H/ 64CNF:4H / F:4HNF08C8=6/

FONT_METRICS@
Purpose To get the system metrics for the default font and the current drawing surface.
Syntax BD1A>DC8=4 5>=CN<4CA82B/ <4CA82B
8=C464A <4CA82B!
Description The array is returned with values for the following 20 system metrics:
Height, Ascent, Descent, InternalLeading, ExternalLeading, AveCharWidth,
MaxCharWidth, Weight, Overhang, DigitizedAspectX, DigitizedAspectY,
FirstChar, LastChar, DefaultChar, BreakChar, Italic, Underlined, StruckOut,
PitchAndFamily, CharSet.

GET_BITMAP_DC@
Purpose To obtain the device context of a bitmap which may be written to using the Windows
API graphics functions and used in a %dw format.
Syntax 8=C464A 5D=2C8>= 64CN18C<0?N32/ 7N18CB EN18CB
8=C464A 7N18CBEN18CB
Description The bitmap is created of size 7N18CB × EN18CB pixels. The device context can be
destroyed by A4;40B4N18C<0?N32/ but will be returned to the system at normal
program termination.
A4;40B4N18C<0?N32/ should be used when multiple bitmaps are created and when
they need not be saved.
Return value The function returns a handle to the device context.
See also 2;40AN18C<0?/ A4;40B4N18C<0?N32/ %dw

360
Chapter 27 Library reference

GET_CLEARWIN_TEXT@
Purpose To get text from a ClearWin window.
Syntax 8=C464A 5D=2C8>= 64CN2;40AF8=NC4GC/ F8=1D554A2>?H
8=C464A F8=2>?H
270A02C4A 1D554A
Description F8= is the handle of ClearWin window in question. To obtain the handle of the default
window use:
F8=,64CN3450D;CNF8=3>F/
Return value If 2>?H is zero, the function returns the length of the required buffer but no data is
copied. If 2>?H is 1, the data is also copied to the buffer.

GET_CURRENT_DC@
Purpose To get the device context of the current drawing surface.
Syntax BD1A>DC8=4 64CN2DAA4=CN32/ 32
8=C464A 32
See also B4;42CN6A0?782BN>1942C/

GET_DEFAULT_WINDOW@
Purpose To return the handle of the current default ClearWin window for standard Fortran I/O.
Syntax 8=C464A 5D=2C8>= 64CN3450D;CNF8=3>F/

GET_DIB_BLOCK@
Purpose To read a BMP format file into a character array.
Syntax BD1A>DC8=4 64CN381N1;>2:/ 58;4=0<4 ?0AA0H 0F 07 03G
03H F 7 3G 3H 4A2>34
270A02C4A 58;4=0<4
270A02C4A ?0AA0H"0F07

361
ClearWin+ User’s Guide Fortran

8=C464A 0F0703G03HF73G3H4A2>34
Description All of the arguments are input values except for ?0AA0H which contains the returned
data and 4A2>34 which returns the error status.

58;4=0<4 is the name of the BMP file.

0F and 07 are dimensions of ?0AA0H.
03G and 03H are offsets used when writing the data to ?0AA0H.
F and 7 are the width and height of the image data to be copied.
3G and 3H are offsets used when reading the data from the file.

The first dimension of ?0AA0H is used to store the red, green and blue values for each
pixel. 4A2>34 will return:
BD224BB
! A403 4AA>A
# <4<>AH 4AA>A
$ =>C 0 1<? 58;4
103 58;4
" 103 =D<14A
% >C74A 4AA>A
See also 64CN381NB8I4/ ?DCN381N1;>2:/ 381N1;>2:N?08=C/
Example See page 145.

GET_DIB_SIZE@
Purpose To get information from a BMP data file.
Syntax BD1A>DC8=4 64CN381NB8I4/ 58;4=0<4 F83C7 74867C =11?
4A2>34
270A02C4A 58;4=0<4
8=C464A F83C7 74867C =11? 4A2>34
Description This routine is similar to 64CN8<N8=5>/ but returns the number of bits per pixel
=11? as follows:

362
Chapter 27 Library reference

NBBP Number of colours

1 2
4 16
8 256
24 16MB

C8C;4: The caption for the dialog box.

58;4: The full path returned by the dialog box.

?0C7: The input path.

58;C4A=0<4B: An array of strings for the description of file filters.

58;C4AB?42B: An array of strings for the corresponding filters.

=58;C4AB The number of file filters.

<DBC4G8BC: An input value that is set to 1 if the file to be selected must

already exist.
Notes After this routine has been called, 2;40AF8=N8=>5/³58;C4AN8C4<NB4;42C43´
provides the index of the file filter that was selected by the user. This can be called, for
example, to detect if the file was saved using a different file extension.

363
ClearWin+ User’s Guide Fortran

Example
F8=0??
8=C464A XfX]X^/^_T]NUd]R
4GC4A=0; ^_T]NUd]R
X,fX]X^/RPJ8\PVT X]U^L
X,fX]X^/\]J5X[TJ>_T]4gXcLL^_T]NUd]R4G8C
4=3
R
8=C464A 5D=2C8>= ^_T]NUd]R
8=2;D34 +fX]S^fbX]b-
270A02C4A UX[T !(U^a\Pc !cXc[T!_PcW !(
8=C464A =58;C4AB
?0A0<4C4A=58;C4AB,!
270A02C4A! UX[c]P\T=58;C4ABUX[cb_TR=58;C4AB
cXc[T,>_T] 1Xc\P_ 5X[T
UX[T,
_PcW,R)KfX]S^fb
UX[c]P\T ,1Xc\P_ UX[Tb
UX[cb_TR ,Q\_
UX[c]P\T!,0[[ UX[Tb
UX[cb_TR!,
20;; VTcNUX[cTaTSNUX[T/cXc[TUX[T_PcWUX[c]P\TUX[cb_TR
=58;C4AB

^_T]NUd]R,
4=3

GET_FONT_ID@
Purpose To get the current font identifier.
Syntax BD1A>DC8=4 64CN5>=CN83/ 83
8=C464A 83
Description 83 is returned as the identifier of the font for the current drawing surface.
See also 27>>B4N5>=C/, B4;42CN5>=CN83/

364
Chapter 27 Library reference

GET_FONT_NAME@
Purpose To return the name of the loaded font.
Syntax BD1A>DC8=4 64CN5>=CN=0<4/ =0<4 =D<
270A02C4A =0<4
8=C464A =D<
Description The name of an installed font is returned in the =0<4 parameter. =D< references the
installed fonts and should start at 1. If a call is made and there is no associated font to
the number supplied an empty string will be returned.
Example 8=2;D34 +fX]S^fbX]b-
270A02C4A! ]P\T
3> Z, "
20;; VTcNU^]cN]P\T/]P\TZ
85]P\T4@ BC>?
?A8=C ]P\T
4=33>
4=3

GET_GRAPHICAL_RESOLUTION@
Purpose To determine the width and height of the current drawing surface.
Syntax BD1A>DC8=4 64CN6A0?7820;NA4B>;DC8>=/ F83C7 74867C
8=C464A F83C7 74867C
Description F83C7 and 74867C are set to the values for the current drawing surface.

GET_GRAPHICS_SELECTED_AREA@
Purpose To get the current %gr ‘rubber-band’ selection.
Syntax BD1A>DC8=4 64CN6A0?782BNB4;42C43N0A40/G H G!H!
8=C464A G H G! H!
Description The four parameters are set to the values of the current graphics selection which is
defined by the ‘rubber-band’ line activated with a call to
B4CN6A0?782BNB4;42C8>=/. The selection mode must be set to either 1 or 2 before

365
ClearWin+ User’s Guide Fortran

this routine can be used.

See also B4CN6A0?782BNB4;42C8>=/, %gr
Example See page 143.

GET_IM_INFO@
Purpose To obtain information from a graphics file.
Syntax BD1A>DC8=4 64CN8<N8=5>/ 58;4=0<4 F83C7 74867C
=1N2>;>DAB =1N8<064B 5>A<0C 4AA>A
270A02C4A 58;4=0<45>A<0C
8=C464A F83C7] 74867C] =1N2>;>DAB]
8=C464A =1N8<064B 4AA>A
Description This subroutine accesses the information that is contained within a .1<? or .?2G file
supplied in 58;4=0<4. The relevant data is returned in the supplied parameters. The
F83C7 and 74867C will contain the dimension of the image. F83C7, 74867C and
=1N2>;>DAB are arrays. =1N8<064B is returned as the number of images and ]
should set at a value which is always greater than or equal to =1N8<064B. 5>A<0C
will be returned as a single character string, either ‘BMP’ or ‘PCX’.
4AA>A will return:
BD224BB
! A403 4AA>A
$ =>C 0 1<? 58;4
103 58;4
$ D=:=>F= 5>A<0C
See also 64CN381NB8I4/

GET_MATCHED_COLOUR@
Purpose To find the closest RGB colour match for the current drawing surface.
Syntax 8=C464A 5D=2C8>= 64CN<0C2743N2>;>DA/2>;>DA
8=C464A 2>;>DA
Description 64CN<0C2743N2>;>DA/ selects the RGB palette colour that is the best match to the

366
Chapter 27 Library reference

supplied RGB 2>;>DA on the current drawing surface. An error condition arises if
RGB colour mode is not selected on the current drawing surface. If there is no current
drawing surface then the function returns its input value. Likewise, the function
returns its input value if the region is a printer or if the graphics device is a high colour
device (i.e. more than 8 bits per pixel).
Return value Returns the closest match for the current drawing surface.
See also 64CN=40A4BCNB2A44=N2>;>DA/ DB4NA61N2>;>DAB/
Example See page 155.

GET_MOUSE_INFO@
Purpose To obtain the position of the mouse, the mouse buttons, and the keyboard shift keys at
the time when the last owner-draw (%^dw) or graphics region (%^gr) call-back
function was called.
Syntax BD1A>DC8=4 64CN<>DB4N8=5>/ G H 5;06B
8=C464A GH5;06B
Description This routine should be called immediately on entry to the call-back function. It does
not make sense to call this function in other contexts. The G and H values are pixel
positions relating to the bitmap associated with the format code (%gr or %dw). Pixel
co-ordinates are measures from (0,0) at the top left corner of the area. 5;06B contains
the following flags (the parameters will be found in windows.ins):
<:N;1DCC>= 1 Left mouse button depressed
<:NA1DCC>= 2 Right mouse button depressed
<:NB785C 4 Keyboard shift key depressed
<:N2>=CA>; 8 Keyboard control key depressed
<:N<1DCC>= 16 Middle mouse button depressed
Notes 2;40AF8=N8=5>/ can be used instead. These values are returned using
6A0?782BN<>DB4N5;06B, 6A0?782BN<>DB4NG and 6A0?782BN<>DB4NH.

367
ClearWin+ User’s Guide Fortran

GET_NEAREST_SCREEN_COLOUR@
Purpose To find the closest colour match for the screen from the system palette.
Syntax 8=C464A 5D=2C8>= 64CN=40A4BCNB2A44=N2>;>DA/2>;>DA
8=C464A 2>;>DA
Return value Returns the RGB colour from the Windows system palette that will be displayed when
the specified colour value is used on the screen (the value returned by the Windows
API function GetNearestColor).
Notes You can use this function to provide a colour for a drawing surface if you want to over-
ride the colour matching carried out automatically by ClearWin+. See page 156 for
further details.
See also 64CN<0C2743N2>;>DA/

GET_POINT@
Purpose To get a pixel colour on the current drawing surface.
Syntax BD1A>DC8=4 64CN?>8=C/878E82>;
8=C464A 878E82>;
Description 64CN?>8=C/ gets the colour value 82>; using the current colour mode of the pixel at
(87, 8E) on the current drawing surface. The colour value is given in terms of the
current colour mode of the surface.
See also 64CNA61NE0;D4/, 3A0FN?>8=C/

GET_PRINTER_ORIENTATION@
Purpose To get the printer orientation as portrait or landscape.
Syntax 8=C464A 64CN ?A8=C4AN>A84=C0C8>=/
Return vlaue Returns 0 for portrait and 1 for landscape.

368
Chapter 27 Library reference

GET_RGB_VALUE@
Purpose To get the RGB value of the colour of a pixel on the current drawing surface.
Syntax BD1A>DC8=4 64CNA61NE0;D4/ 7>A E4A E0;D4
8=C464A 7>AE4AE0;D4
Description The horizontal and vertical co-ordinates locate the pixel on the current drawing
surface. An RGB value is always returned irrespective of the current colour mode for
the surface.
See also 64CN=40A4BCNB2A44=N2>;>DA/ B4CN2>;>DAB/ DB4NA61N2>;>DAB/

GET_SCREEN_DIB@
Purpose To copy part of a graphics area.
Syntax BD1A>DC8=4 64CNB2A44=N381/ 7381 G H G! H!
8=C464A 7381 G H G! H!
Description 7381 is returned as the handle of a new device context that contains a copy of part of
the current graphics area. G , H are input as the pixel co-ordinates of the top left
hand corner of the area to copy whilst G!, H! are the corresponding co-ordinates of the
bottom right hand corner.
See also 381N?08=C/, ?A8=CN381/, 4G?>ACN1<?/, A4;40B4NB2A44=N381/

GET_SYSTEM_FONT@
Purpose To get the attributes of the system font.
Syntax BD1A>DC8=4 64CNBHBC4<N5>=C/;574867C;5F83C7
;54B20?4<4=C;5>A84=C0C8>=;5F4867C
;58C0;82;5D=34A;8=4;5BCA8:4>DC;5270AB4C
;5>DC?A428B8>=;52;8??A428B8>=;5@D0;8CH
;5?8C270=350<8;H;?5024=0<4
8=C464A ;574867C;5F83C7 ;54B20?4<4=C
;5>A84=C0C8>=;5F4867C;58C0;82
;5D=34A;8=4;5BCA8:4>DC;5270AB4C
;5>DC?A428B8>=;52;8??A428B8>=;5@D0;8CH

369
ClearWin+ User’s Guide Fortran

;5?8C270=350<8;H
270A02C4A ;?5024=0<4
Description These attributes may be used to build new fonts by modification. i.e. scaling,
italicisation etc.. Modified parameters can then be supplied to the Windows API
function CreateFont. See the Windows API documentation of CreateFont for further
details.

GET_TEXT_SIZE@
Purpose To get the dimensions of a graphics character string.
Syntax BD1A>DC8=4 64CNC4GCNB8I4/ BCA F83C7 34?C7
270A02C4A BCA
8=C464A F83C734?C7
Description This routine returns the pixel F83C7 and 34?C7 of a given character string BCA when
drawn on the current drawing surface. Trailing spaces will be included so either use a
substring notation or terminate the significant characters by 270A.

GET_TRACK_LENGTH@
Purpose To get the length of a CD track.
Syntax 8=C464A 5D=2C8>= 64CNCA02:N;4=6C7/ CA02:
8=C464A CA02:
Description Call this routine to obtain the length of an audio CD’s track in milliseconds. If the
track length returned is zero then this track does not exist. This result can be used to
determine the number of audio tracks available. The first track number is 1 rather than
zero.
Return value Returns the required track length or zero on failure.
See also 2;>B4N23NCA0H/ B4CN23N?>B8C8>=/ ?;0HN0D38>N23/ BC>?N0D38>N23/

370
Chapter 27 Library reference

GET_WINDOW_LOCATION@
Purpose To get the location and size of a given window.
Syntax BD1A>DC8=4 64CNF8=3>FN;>20C8>=/ 70=3;4 G H F83C7
74867C
8=C464A 70=3;4 G H F83C7 74867C
Description 70=3;4 is a window handle obtained, for example, by using %hw or %lc. Other
arguments are returned with the pixel coordinates and dimensions of the window.
Notes For main windows the G,H location is in absolute screen coordinates. For child
windows attached by %aw to a frame, the coordinates are relative to the top left corner
of the frame. For controls and other child (%ch) windows G and H are relative to the
parent window.
This routine (together with the associated move and resize routines) can be used on
windows created using F8=8>/ or on other windows if the window handle is available.
They are particularly useful to control the placement of MDI child windows.
Moving individual controls and un-framed child windows may be unwise as it can
cause controls to overlap on the screen.
Windows will be partially or totally concealed if they are moved outside the area of the
screen or the enclosing window or frame (in the case of child windows). This is
normal and can be used if desired.
Some interesting effects can be obtained by using these functions. For example,
suppose that a child window (which might contain a large graphics region) were
attached to a frame that was too small to contain it. By calling <>E4NF8=3>F/ (e.g.
in response to a scroll call-back function) with negative values of G and/or H, the
contents of the window could be scrolled within the frame.

The API function BringWindowToTop may also be useful when re-arranging

windows.
See also <>E4NF8=3>F/ A4B8I4NF8=3>F/

GET_WKEY@
Purpose To get a key from a ClearWin window keyboard buffer.
Syntax 8=C464A 5D=2C8>= 64CNF:4H/
Description This routine is only for use in a ClearWin window (e.g. with %cw). If necessary, it

371
ClearWin+ User’s Guide Fortran

waits for the user to press a key on the keyboard. However, the routine will yield to
other processes.
Notes 033N:4H1>0A3N<>=8C>A/ provides a better mechanism for handling keyboard input.
Return value Returns the ASCII code for the first key and removes it from the buffer.
See also 5443NF:4H1>0A3/5;DB7NF:4H1>0A3/64CNF:4H /F:4HNF08C8=6/

GET_WKEY1@
Purpose To get a key from a ClearWin window keyboard buffer.
Syntax 8=C464A 5D=2C8>= 64CNF:4H /
Description This routine is only for use in a ClearWin window (e.g. with %cw). It is like
64CNF:4H/ but immediately returns zero if the buffer is empty.
Notes 033N:4H1>0A3N<>=8C>A/ provides a better mechanism for handling keyboard input.
Return value Returns the ASCII code for the first key and removes it from the buffer. If the buffer is
empty it returns zero.
See also 5443NF:4H1>0A3/ 5;DB7NF:4H1>0A3/ 64CNF:4H/ F:4HNF08C8=6/

GRAPHICS_TO_CLIPBOARD@
Purpose To allow the interchange of graphics between drawing surfaces and other Windows
applications.
Syntax 8=C464A 5D=2C8>= 6A0?782BNC>N2;8?1>0A3/G H G!H!
8=C464A G H G! H!
Description Places a rectangular area of a drawing surface on to the clipboard so that other
Windows programs can use the image.
G H is the top left corner of the area.
G! H! is the lower right corner of the area.
Return value Returns 1 for success and zero on failure.
See also 2>?HN5A><N2;8?1>0A3/ 2>?HNC>N2;8?1>0A3/

372
Chapter 27 Library reference

2;8?1>0A3NC>NB2A44=N1;>2:/

GRAPHICS_WRITE_MODE@
Purpose To select replace/XOR mode before writing to the current drawing surface.
Syntax BD1A>DC8=4 6A0?782BNFA8C4N<>34/<>34
8=C464A <>34
Description This routine sets the graphics write mode for the current drawing surface depending on
the value of <>34. Any value other than 3 will force all subsequent graphics output to
replace existing pixels. A value of 3 will cause the output to be G>Aed with existing
pixels.

HIBYTE@
Purpose To get the top 8 bits of a 16 bit integer.

Syntax 8=C464A 5D=2C8>= 781HC4/F>A3

8=C464A! F>A3
Notes This is the ClearWin+ Fortran equivalent of the Microsoft C macro with the same
name.

HIGH_COLOUR_MODE@
Purpose To test if the screen is a high colour device.
Syntax ;>6820; 5D=2C8>= 7867N2>;>DAN<>34/
Description A high colour device is one that has more than 8 bits per pixel (i.e. more than 256
colours). A high colour device does not make use of colour palettes. If you want to use
a wide range of colours whilst avoiding the complexities of managing a palette, one
solution is to restrict the usage to desktops operating in high colour mode. Thus you
can use this function to test if the desktop is set to operate with more than 256 colours
per pixel and to send a error message and close down on failure.
Return value Returns .TRUE. for success.

373
ClearWin+ User’s Guide Fortran

HIWORD@
Purpose To get the top 16 bits of a 32 bit integer.

Syntax 8=C464A! 5D=2C8>= 78F>A3/3F>A3

8=C464A 3F>A3
Description Windows API functions sometimes return two values in a long integer with one value in
the top 16 bits and one value in the bottom 16 bits. GetTextExtent does this for
example, returning the height of the text in the top 16 bits and the width in the bottom
16 bits.
Notes This is the Fortran ClearWin+ equivalent of the Microsoft C macro with the same
name.

IMPORT_BMP@
Purpose To read in a BMP file.
Syntax 8=C464A 5D=2C8>= 8<?>ACN1<?/ 58;4=0<4 4AA>A
270A02C4A 58;4=0<4
8=C464A 4AA>A
Description Reads in a BMP file and returns a DIB handle to the image. The handle can then be
used with 381N?08=C/, ?A8=CN381/ and 4G?>ACN1<?/. 4AA>A returns one of the
following:
0 success
2 unable to read file
4 insufficient memory
5 not a BMP file
10 unable to open file
Return value Returns a handle to the image or zero on failure.
See also 64CNB2A44=N181/, A4;40B4NB2A44=N381/, 8<?>ACN?2G/
2;8?1>0A3NC>NB2A44=N1;>2:/

374
Chapter 27 Library reference

IMPORT_PCX@
Purpose To read in a .PCX file.
Syntax 8=C464A 5D=2C8>= 8<?>ACN?2G/ 58;4=0<4 4AA>A
270A02C4A 58;4=0<4
8=C464A 4AA>A
Description Reads in a PCX file and returns a DIB handle to the image that is compatible with
windows bitmaps allowing it be used with 381N?08=C/ ?A8=CN381/ and
4G?>ACN1<?/. 4AA>A returns one of the following:
0 success
2 unable to read file
4 insufficient memory
6 not a PCX file
10 unable to open file
Return value Returns a handle to the image or zero on failure.
See also 64CNB2A44=N181/, A4;40B4NB2A44=N381/, 8<?>ACN1<?/
2;8?1>0A3NC>NB2A44=N1;>2:/

ITALIC_FONT@
Purpose To set/unset italic font style for text on the current drawing surface.
Syntax BD1A>DC8=4 8C0;82N5>=C/ 8C0;
8=C464A 8C0;
Description This routine sets or resets the italic property of the current drawing surface. Any
subsequent calls to the 3A0FN270A02C4AB/ routine will reflect the change.
See also A>C0C4N5>=C/ B20;4N5>=C/ B4;42CN5>=C/ D=34A;8=4N5>=C/
1>;3N5>=C/

LOBYTE@
Purpose To get the bottom 8 bits of a 16 bit integer.

Syntax 8=C464A 5D=2C8>= ;>1HC4/F>A3

8=C464A! F>A3

375
ClearWin+ User’s Guide Fortran

Notes This is the ClearWin+ Fortran equivalent of the Microsoft C macro with the same
name.

LOWORD@
Purpose To get the bottom 16 bits of a 32 bit integer.

Syntax 8=C464A! 5D=2C8>= ;>F>A3/3F>A3

8=C464A 3F>A3
Notes This is the Fortran ClearWin+ equivalent of the Microsoft C macro with the same
name.

MAKE_BITMAP@
Purpose To embed a bitmap in program code.
Syntax 8=C464A 5D=2C8>= <0:4N18C<0?/1<?N30C0 GA4B HA4B
270A02C4AHA4B 1<?N30C0 GA4B
8=C464A GA4B HA4B
?0A0<4C4A GA4BHA4B
Description Bitmaps are usually included in a program statically via resources or dynamically with
Windows API calls. This routine is provided so that bitmaps may be included in the
source code as text data and then translated into bitmap format. A (HBITMAP) handle
to a bitmap is returned that can be used for example with %`bm. This provides a
speedy method of designing simple graphics that would otherwise require image
editing software.
The character arrays may include the following characters:
- (minus) Black
b Dark blue
r Dark red
g Dark green
y Dark yellow (brown)
m Dark magenta
c Dark cyan
w Grey
l Light grey
B Blue
R Red
G Green

376
Chapter 27 Library reference

Y Yellow
M Magenta
C Cyan
W White
Return value Returns a bitmap handle to the new bitmap.
See also <0:4N82>=/

MAKE_ICON@
Purpose To embed an icon in program code.
Syntax 8=C464A 5D=2C8>= <0:4N82>=/ 82>=N30C0
270A02C4A"! 82>=N30C0"!
Description This routine allows an icon to be embedded in the program code. A 32x32 character
array must be defined to accommodate the icon data. The characters can be defined as
any of the following:
- (minus) Black
b Dark blue
r Dark red
g Dark green
y Dark yellow (brown)
m Dark magenta
c Dark cyan
w Grey
B Blue
R Red
G Green
Y Yellow
M Magenta
C Cyan
W White
If any other character is used then a transparent colour is assumed which will allow the
background to show through. A (HICON) handle to the icon is returned which may be
used for example with %`ic. The icon is automatically discarded at program
termination.
Return value Returns a handle to the new icon.
See also <0:4N18C<0?/

377
ClearWin+ User’s Guide Fortran

Example

8=2;D34 +fX]S^fbX]b-
270A02C4A"! XR^]"!
8=C464A WXR^]
WXR^],\PZTNXR^]/82>=
30C0 XR^] AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
30C0 XR^]!AHH11HH11HH11HH11HH11HH11HH11HHA

30C0 XR^]"AHH11HH11HH11HH11HH11HH11HH11HHA
30C0 XR^]" AHH11HH11HH11HH11HH11HH11HH11HHA
30C0 XR^]"!AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Z,fX]X^/RPJ<PZT XR^]L][OXR782>=
4=3

MAP_FILE_FOR_READ_WRITE@
Purpose To map a file to memory (Win32 only).
Syntax 8=C464A 5D=2C8>= <0?N58;4N5>ANA403NFA8C4/ 58;4=0<4 B8I4
270A02C4A 58;4=0<4
8=C464A B8I4
Description See <0?N58;4N5>ANA4038=6/
In <0?N58;4N5>ANA403NFA8C4/ the variable B8I4 can be input as zero, in which
case it will be returned as the original size of the file. Otherwise, the mapped memory
region will be set to B8I4 bytes and the file will be extended if necessary. If the file
does not exist it will be created. In this routine the contents of the file can be changed.
Return value Returns the starting address of the mapped view or zero on failure.
See also <0?N58;4N5>ANA4038=6/, D=<0?N58;4/

MAP_FILE_FOR_READING@
Purpose To map a file to memory (Win32 only).
Syntax 8=C464A 5D=2C8>= <0?N58;4N5>ANA4038=6/ 58;4=0<4 B8I4
270A02C4A 58;4=0<4
8=C464A B8I4

378
Chapter 27 Library reference

Description When a file is memory mapped, a region of memory is defined so that accesses to that
memory effectively access the disk file. A file may be opened for reading using
<0?N58;4N5>ANA4038=6/.
58;4=0<4 is the name of the file to be opened and B8I4 is returned as the size of the
file.
Use the various Salford 2>A4 intrinsic functions to access the contents of the file. Any
attempt to alter the contents of the file will cause an error.
Return value Returns the starting address of the mapped view or zero on failure
Notes To call a routine with a mapped file as an argument use the form
<HBD122>A4 ?CA where ?CA is the value returned by
<0?N58;4N5>ANA4038=6/.
See also <0?N58;4N5>ANA403NFA8C4/, D=<0?N58;4/

METAFILE_TO_CLIPBOARD@
Purpose To send a metafile to the clipboard.
Syntax 8=C464A 5D=2C8>= <4C058;4NC>N2;8?1>0A3/
Description This function can be used after a call to >?4=N<4C058;4/ followed by calls to
graphics drawing routines. It causes the image to be stored on the clipboard in
metafile format. Alternatively, if the %gr option \TcPUX[TNaTbXiT is used, this
function can be used to send the resulting metafile to the clipboard.
Return value Returns 1 for success or zero for failure.
Notes If a background colour is specified for %gr (e.g. %gr[black]), this information is not
recorded in the metafile.
See also >?4=N<4C058;4/ 2;>B4N<4C058;4/ ?;0HN2;8?1>0A3N<4C058;4/

MOVE_WINDOW@
Purpose To move a window.
Syntax BD1A>DC8=4 <>E4NF8=3>F/ 70=3;4 G H
8=C464A 70=3;4 G H

379
ClearWin+ User’s Guide Fortran

Description 70=3;4 is typically a value obtained by using %hw or %lc. G and H are input as the
new location of the window in pixel coordinates.

See 64CNF8=3>FN;>20C8>=/ and its associated notes.

The subroutine ?4A<8CN0=>C74AN20;;102:/ allows a call-back function to permit

an additional call-back. This routine will only permit one additional call-back, but it
can be called as many times as desired, each time enabling a further call-back. When
using this routine it is assumed that a call will also be made to a routine such as
C4<?>A0AHNH84;3/ to permit the processing of further messages.
Notes Many programs that seem to require this facility may be presenting the user with a
non-standard interface and should be re-structured. For example, suppose a window
offers a menu item which will start a lengthy calculation which the user may wish to
abort. The usual way to handle this is to display a small additional window with a
Cancel button and possibly a progress bar. Since this additional window is distinct
from the window which contained the original menu item, there is no need to call the
above routine.

PLAY_AUDIO_CD@
Purpose To play the audio CD from the current position.
Syntax 8=C464A 5D=2C8>= ?;0HN0D38>N23 3DA0C8>=
8=C464A 3DA0C8>=
Description Plays an audio CD starting at the current location which can be set with a call to
B4CN23N?>B8C8>=/. If duration is any valid number greater than 0 it will play for
that amount of time in milliseconds. If the duration is less than 0 it will play that
number of tracks i.e. a value of -4 will play the next four tracks.

386
Chapter 27 Library reference

Return value Always returns 1.

See also 2;>B4N23NCA0H/ >?4=N23NCA0H/ B4CN23N?>B8C8>=/ BC>?N0D38>N23/
64CNCA02:N;4=6C7/
Example
RP[[ bTcNRSN_^bXcX^]/
RP[[ _[PhNPdSX^NRS/

PLAY_CLIPBOARD_METAFILE@
Purpose To play a clipboard metafile on the current drawing surface.
Syntax 8=C464A ?;0HN2;8?1>0A3N<4C058;4/ 2>;
8=C464A 2>;
Description This can be used after a call to <4C058;4NC>N2;8?1>0A3/ 2>; is used to set the
background colour using the current colour mode.
Return value The value 1 is returned for success and zero for failure.
See also >?4=N<4C058;4/ 2;>B4N<4C058;4/

PLAY_SOUND@
Purpose To send a sample to the audio output device.
Syntax 8=C464A 5D=2C8>= ?;0HNB>D=3/ ;45C A867C B0<?;4B
8=C464A! ;45CB0<?;4B A867CB0<?;4B
8=C464A B0<?;4B
?0A0<4C4A B0<?;4B
Description ;45C and A867C are arrays that contain the 16 bit sample data. The number of
samples is B0<?;4B. You should check the values returned by B>D=3N?;0H8=6/ and
B>D=3NA42>A38=6/ so that a call is not made to this routine until the sound device is
idle.
Return value Returns 1 for success and a zero on failure
See also FA8C4NF0E4N58;4/ ?;0HNB>D=3NA4B>DA24/ A42>A3NB>D=3/
B>D=3N?;0H8=6/ B>D=3NA42>A38=6/ B4;42CNB0<?;8=6NA0C4/

387
ClearWin+ User’s Guide Fortran

PLAY_SOUND_RESOURCE@
Purpose To send a resource B>D=3 to the current audio device.
Syntax 8=C464A 5D=2C8>= ?;0HNB>D=3NA4B>DA24/ =0<4
270A02C4A' =0<4
Description This routine plays any resource that is of type B>D=3. Care should be taken not to
include samples (.WAV files) that are more than a few seconds for two reasons. 1) the
sample occupies memory and 2) the routine is synchronous and will halt all other
output until the sample has completed playback. It is necessary to supply a valid
resource name to this routine.
For example:
Include in the resource section of your program:
<HF0E4 B>D=3 ±S^VQPaZfPe²
In the code section:
aTb,?;0HNB>D=3NA4B>DA24/ ³<HF0E4´
Return value Returns 0 for success, otherwise -1.
See also FA8C4NF0E4N58;4/ ?;0HNB>D=3/ A42>A3NB>D=3/ B>D=3N?;0H8=6/
B>D=3NA42>A38=6/ B4;42CNB0<?;8=6NA0C4/

PRINT_DIB@
Purpose To print a device independent bitmap.
Syntax 8=C464A 5D=2C8>= ?A8=CN381/ 83 ?ANG ?ANH
?ANF83C7 ?AN74867C 7381 G H F83C7 74867C
8=C464A 83 ?ANG ?ANH
?ANF83C7 ?AN74867C 7381 G H F83C7 74867C
Description 83 is the handle of the printer as supplied to >?4=N?A8=C4A/.

?ANG ?ANH is the printer offset position to start printing (using the printer
resolution).

?ANF83C7 ?AN74867C represent the size of the area to print (using the printer
resolution).

388
Chapter 27 Library reference

7381 is the handle of the DIB returned by 8<?>ACN1<?/, 8<?>ACN?2G/,

64CNB2A44=N381/ or 2;8?1>0A3NC>NB2A44=N1;>2:/.

G H is the offset position from which to start reading the bitmap

F83C7 74867C represent the size of the bitmap area to print.

Return value Returns 1 for success or zero for failure.
See also 381N?08=C/, A4;40B4NB2A44=N381/, 4G?>ACN1<?/

PRINT_GRAPHICS_PAGE@
Purpose To print a metafile graphics page.
Syntax BD1A>DC8=4 ?A8=CN6A0?782BN?064/
Description The current metafile image is printed to the graphics printer destination. The page is
not cleared and can still be drawn to.
See also >?4=N<4C058;4/, 3>N2>?84B/

PRINT_OPENGL_IMAGE@
Purpose To print an OpenGL image.
Syntax 8=C464A ?A8=CN>?4=6;N8<064/83;40E4N>?4=
8=C464A 83
;>6820; ;40E4N>?4=
Description 83 is the user-defined identification number previously used with
>?4=N6;N?A8=C4A/ or >?4=N6;N?A8=C4A /.
;40E4N>?4= = .TRUE. specifies that the current print job is to be left open as there
are more drawings to be sent. ;40E4N>?4= = .FALSE. specifies that the printer
connection with this 83 is to be closed.
See also >?4=N6;N?A8=C4A/ >?4=N6;N?A8=C4A /

389
ClearWin+ User’s Guide Fortran

PRINTER_DIALOG_OPTIONS@
Purpose To configure the standard printer dialog box.
Syntax BD1A>DC8=4 ?A8=C4AN380;>6N>?C8>=B/
=>N?A8=CNC>N58;4 =>N?064N=D<14AB =>NB4;42C8>=
=>N3450D;CNF0A=8=6 B4CNB><4N?064B B4CNB4;42C8>=
B4CN2>;;0C4 B4CN0;;N?064B B4CN?A8=CNC>N58;4
8=C464A
=>N?A8=CNC>N58;4 =>N?064N=D<14AB =>NB4;42C8>=
=>N3450D;CNF0A=8=6 B4CNB><4N?064B B4CNB4;42C8>=
B4CN2>;;0C4 B4CN0;;N?064B B4CN?A8=CNC>N58;4
Description The following table describes the effect of setting an argument value to 1 rather than
zero.

=>N?A8=CNC>N58;4 Hides the ‘Print to file’ check box.

=>N?064N=D<14AB Disables the ‘Page numbers’ radio button.
=>NB4;42C8>= Disables the ‘Print selection’ radio button.
=>N3450D;CNF0A=8=6 Disables ‘No default printer’ warning.
B4CNB><4N?064B ‘Page rage’ radio button is set.
B4CNB4;42C8>= ‘Selection’ radio button is set.
B4CN2>;;0C4 ‘Collate copies’ check box is checked.
B4CN0;;N?064B ‘Print all pages’ radio button is set.
B4CN?A8=CNC>N58;4 ‘Print to file’ check box is checked.

The following 2;40AF8=N8=5>/ strings hold some of the selected options after the
printer dialog box has closed.
³?A8=C4ANB4;42C8>=´ ‘Print selection’ was set.
³?A8=C4AN2>;;0C4´ ‘Print collate copies’ was checked.
³?A8=C4AN?064=D<14AB´ ‘Print page numbers’ was set.
These values will be either 1 or zero.
Note You can deduce the ‘print all pages’ radio button selection by
³?A8=C4ANB4;42C8>=´ and ³?A8=C4AN?064=D<14AB´ both being equal to zero.
See also Selecting a Printer, page 190.

390
Chapter 27 Library reference

PUT_DIB_BLOCK@
Purpose To save a DIB block in a BMP file (24 bits per pixel).
Syntax BD1A>DC8=4 ?DCN381N1;>2:/ 58;4=0<4 ?0AA0H 0F 07 03G
03H F 7 =1?? 4A2>34
270A02C4A 58;4=0<4
270A02C4A ?0AA0H"0F07
8=C464A 0F0703G03HF7=11?4A2>34
Description All of the arguments are input values except for 4A2>34 which returns the error status.
58;4=0<4 is the name of the BMP file.
0F and 07 are dimensions of ?0AA0H.
03G and 03H are offsets used when reading the data from ?0AA0H.
F and 7 are the width and height of the image data to be copied.
?0AA0H is the same as in 64CN381N1;>2:/.

=1?? is currently not used but should be set to 24 because currently this routine always
writes out BMP files with 24 bits per pixel.
4AA>A will return:
BD224BB
4AA>A >= 58;4 >?4=
" 4AA>A >= FA8C4
" 103 =D<14A
See also 64CN381NB8I4/ 64CN381N1;>2:/ 381N1;>2:N?08=C/
Example See page 145.

RECORD_SOUND@
Purpose To record sound from the sound input device.
Syntax 8=C464A A42>A3NB>D=3/ ;45C A867C B0<?;4B 5;06
8=C464A! ;45CB0<?;4B A867CB0<?;4B
8=C464A B0<?;4B 5;06
?0A0<4C4A B0<?;4B
Description ;45C and A867C are arrays of 8=C464A! 16 bit data . They will be filled with sound
data so enough memory should be allocated to them which should be the same value as

391
ClearWin+ User’s Guide Fortran

B0<?;4B. 5;06 is a return value that is currently unused. You should check the
B>D=3N?;0H8=6/ and B>D=3NA42>A38=6/ results so that a call is not made to this
routine until the sound device is idle.
Return value Returns 1 for success or zero on failure.
See also FA8C4NF0E4N58;4/ ?;0HNB>D=3/ B>D=3N?;0H8=6/ B>D=3NA42>A38=6/
B4;42CNB0<?;8=6NA0C4/ ?;0HNB>D=3NA4B>DA24/

RELEASE_BITMAP_DC@
Purpose To release a bitmap device context acquired by 64CN18C<0?N32/.
Syntax BD1A>DC8=4 A4;40B4N18C<0?N32/732
8=C464A 732
Description The device context and its associated bitmap are released. This function must not be
called whilst a window that uses the device context is still active. 732 is the value
returned by a previous call to 64CN18C<0?N32/.
See also 64CN18C<0?N32/, 2;40AN18C<0?/, %dw

RELEASE_SCREEN_DIB@
Purpose To release the memory for a DIB.
Syntax BD1A>DC8=4 A4;40B4NB2A44=N381/ 7381
8=C464A 7381
Description 7381 is input as the handle of a device independent bitmap created for example by
64CNB2A44=N381/., 8<?>ACN1<?/, or 2;8?1>0A3NC>NB2A44=N1;>2:/.

REMOVE_ACCELERATOR@
Purpose To remove an accelerator key created using %ac or 033N0224;4A0C>A/.
Syntax BD1A>DC8=4 A4<>E4N0224;4A0C>A/ F :4HN=0<4
8=C464A F
270A02C4A :4HN=0<4

392
Chapter 27 Library reference

Description Removes the key with name :4HN=0<4 from the window with handle F. See
033N0224;4A0C>A/ for further details.
See also %ac, 033N0224;4A0C>A/

REMOVE_CURSOR_MONITOR@
Purpose To release a call-back function that monitors which window or control has the cursor.
Syntax BD1A>DC8=4 A4<>E4N2DAB>AN<>=8C>A/ 21N5D=2
4GC4A=0; 21N5D=2
Description See 033N2DAB>AN<>=8C>A/.

REMOVE_FOCUS_MONITOR@
Purpose To release a call-back function that monitors which window or control has the focus.
Syntax BD1A>DC8=4 A4<>E4N5>2DBN<>=8C>A/ 21N5D=2
4GC4A=0; 21N5D=2
Description See 033N5>2DBN<>=8C>A/.

REMOVE_GRAPHICS_ICON@
Purpose To remove an icon from a %gr drawing surface.
Syntax BD1A>DC8=4 A4<>E4N6A0?782BN82>= 70=3;4
8=C464A 70=3;4
Description 70=3;4 is the value returned by an earlier call to 033N6A0?782BN82>=/.
See also 033N6A0?782BN82>=/

393
ClearWin+ User’s Guide Fortran

REMOVE_KEYBOARD_MONITOR@
Purpose To release a call-back function that monitors the use of the keyboard.
Syntax BD1A>DC8=4 A4<>E4N:4H1>0A3N<>=8C>A/ 21N5D=2
4GC4A=0; 21N5D=2
Description See 033N:4H1>0A3N<>=8C>A/

REMOVE_MENU_ITEM@
Purpose Removes a dynamically attached %mn menu item.
Syntax BD1A>DC8=4 A4<>E4N<4=DN8C4</ 70=3;4
8=C464A 70=3;4
Description Use this routine to remove the last menu item that was previously been attached with a
call to 033N<4=DN8C4</ (see page 333).
See also 033N<4=DN8C4</

REPLY_TO_TEXT_MESSAGE@
Purpose To reply to a message from an application that uses B4=3NC4GCN<4BB064/.
Syntax BD1A>DC8=4 A4?;HNC>NC4GCN<4BB064/ A4?;H
270A02C4A A4?;H
Description This routine can be used within a call-back function associated with %rm. The
message and reply can be up to 255 characters long.
See also %nc, %rm, B4=3NC4GCN<4BB064/

RESIZE_WINDOW@
Purpose To resize a window given its window handle.
Syntax BD1A>DC8=4 A4B8I4NF8=3>F/ 70=3;4 F83C7 74867C
8=C464A 70=3;4 F83C7 74867C

394
Chapter 27 Library reference

Description 70=3;4 is typically a value obtained by using %hw or %lc. F83C7 and 74867C are
input as the new size of the window in pixels.

See 64CNF8=3>FN;>20C8>=/ and its associated notes.

retrieved using 2;40AF8=N5;>0C/. User defined parameters can be very useful to

communicate information between modules in a program (especially between DLL’s
under Win32). This function cannot be used to set system 2;40AF8=N5;>0C/
values.
See also 2;40AF8=N5;>0C/

SET_CLEARWIN_INFO@
Purpose To set or change an integer value associated with a named string.
Syntax BD1A>DC8=4 B4CN2;40AF8=N8=5>/ BCA8=6 E0;D4
270A02C4A BCA8=6
8=C464A E0;D4 *
Description This function will create and assign a value to a private named parameter that can be
retrieved using 2;40AF8=N8=5>/. User defined parameters can be very useful to
communicate information between modules in a program (especially between DLL’s
under Win32). This function cannot be used to set system 2;40AF8=N8=5>/ values
except for the printer dialog parameters described on page 194.
See also 2;40AF8=N8=5>/

SET_CLEARWIN_STRING@
Purpose To set or change a string value associated with a named string.
Syntax BD1A>DC8=4 B4CN2;40AF8=NBCA8=6 BCA8=6 E0;D4
270A02C4A BCA8=6 E0;D4
Description This function will create and assign a value to a private named parameter that can be
retrieved using 2;40AF8=NBCA8=6/. User defined parameters can be very useful to
communicate information between modules in a program (especially between DLL’s
under Win32). This function should not be used to set system 2;40AF8=NBCA8=6/
values except for:
?A8=C4AN3>2D<4=C
This is the name of the document that is about to be printed. Its default value is
“ClearWin+ Output”.
See also 2;40AF8=NBCA8=6/

401
ClearWin+ User’s Guide Fortran

SET_CLEARWIN_STYLE@
Purpose Modifies the default styling controls for format (F8=8>/) windows.
Syntax 8=C464A 5D=2C8>= B4CN2;40AF8=NBCH;4/ =4FBCH;4
8=C464A =4FBCH;4
Description The default style for a format window is (FBN>E4A;0??43F8=3>F FBN7B2A>;;
FBNEB2A>;; This can be changed to any valid combination of Windows styles
contained in the windows.ins file so that any subsequent widows have a new style.
FBN>E4A;0??43 FBN?>?D?
FBN278;3 FBN2;8?B81;8=6B
FBN2;8?278;3A4= FBNE8B81;4
FBN38B01;43 FBN<8=8<8I4
FBN<0G8<8I4 FBN20?C8>=
FBN1>A34A FBN3;65A0<4
FBNEB2A>;; FBN7B2A>;;
FBNBHB<4=D FBNC782:5A0<4
FBN<8=8<8I41>G FBN<0G8<8I41>G
FBN6A>D? FBNC01BC>?
FBN>E4A;0??43F8=3>F FBN?>?D?F8=3>F
FBN278;3F8=3>F FBN4GN3;6<>30;5A0<4
FBN4GN=>?0A4=C=>C85H

Return value The previous settings are returned and should be stored if the effect you wish to
generate is only temporary.

SET_CONTROL_TEXT_COLOUR@
Purpose To change the text colour of a control after a window/dialog has been created.
Syntax BD1A>DC8=4 B4CN2>=CA>;NC4GCN2>;>DA/70=3;42>;>DA
8=C464A 70=3;42>;>DA
Description 70=3;4 is the window handle of the control obtained by using %lc. 2>;>DA is the
RGB colour value (see A61/).
Notes Unless the colour is to be varied you can set the text colour of a control using %tc
before the control when the window is created, possibly followed by another %tc to
reset it after the control has been specified.

402
Chapter 27 Library reference

A call to B4CN2>=CA>;NC4GCN2>;>DA/ can be made in the callback function for the

control in question. This means, for example, that it is possible to construct a control
that displays text in red for negative values and black for positive values.

SET_CONTROL_VISIBILITY@
Purpose To show or hide a control or window.
Syntax BD1A>DC8=4 B4CN2>=CA>;NE8B818;8CH/70=3;4B7>F
8=C464A 70=3;4B7>F
Description 70=3;4 is the window handle obtained by using %lc or %hw. B7>F is set to 1 to show
the window or 0 to hide it. This routine provides the same functionality as the API
function ShowWindow but also performs certain necessary housekeeping internal to
ClearWin+. It is therefore preferred to ShowWindow.

SET_CURSOR_WAITING@
Purpose To produce a temporary hour-glass cursor.
Syntax BD1A>DC8=4 B4CN2DAB>ANF08C8=6/ F08C
8=C464A F08C
Description If F08C is set to a non-zero value, the routine changes the cursor to an hour-glass with
immediate effect. A zero value then causes the previous cursor to be restored, again
with immediate effect.

SET_DEFAULT_FONT@
Purpose To set the default standard I/O font for ClearWin windows.
Syntax BD1A>DC8=4 B4CN3450D;CN5>=C/75>=C
8=C464A 75>=C
Description This routine is not suitable for format windows. It sets the default standard I/O font for
ClearWin windows to 75>=C. 75>=C must be the handle to an existing font which
can for example be obtained by calling the CreateFont Windows API function.
Note Any font changes will affect only those ClearWin windows subsequently created. If
you wish to change the default font for all ClearWin windows then this can only be

403
ClearWin+ User’s Guide Fortran

achieved by calling one of the ClearWin+ set-font functions before any windows are
created or any standard I/O is performed.

SET_DEFAULT_PROPORTIONAL_FONT@
Purpose To set the default standard I/O font for ClearWin windows to “System”.
Syntax BD1A>DC8=4 B4CN3450D;CN?A>?>AC8>=0;N5>=C/
Description This routine is not suitable for format windows. The font is proportionally spaced.
You can revert to a mono spaced font by using B4CN3450D;CNC>N58G43N5>=C/

SET_DEFAULT_TO_FIXED_FONT@
Purpose To reset the default standard I/O font for ClearWin windows to “System Fixed”.
Syntax BD1A>DC8=4 B4CN3450D;CNC>N58G43N5>=C/
Description This routine is not suitable for format windows. The font is mono-spaced.

SET_DEFAULT_WINDOW@
Purpose To set the default ClearWin window for standard I/O.
Syntax 8=C464A 5D=2C8>= B4CN3450D;CNF8=3>F/F
8=C464A F
Description All future standard I/O requests will be directed to this window. W is a handle created
by 2A40C4NF8=3>F/.
Return value Returns the handle of the previous default window.

SET_GRAPHICS_SELECTION@
Purpose To select a ‘rubber-band’ mode for a %gr region.
Syntax BD1A>DC8=4 B4CN6A0?782BNB4;42C8>=/ <>34
8=C464A <>34

404
Chapter 27 Library reference

Description <>34 can be any of the following:

0 No selection
1 Rectangle
2 Line
This routine is used when mouse input is processed within a %gr drawing surface. It
remains local to the current drawing surface selected with
B4;42CN6A0?782BN>1942C/.
Mode 1 makes a box appear whenever the left mouse button is pressed. The corner of
the box will stay anchored to that point until the mouse button is released. The other
corner will follow the mouse cursor around the drawing surface until the mouse button
is released. By processing the mouse state and the released information it is possible to
determine the co-ordinates of the selected region.
Mode 2 is similar to mode 1 but a straight line joins the first point to the second whilst
the left mouse button is held down.
Mode 0 deactivates the box and line high-lighting mechanism. All the lines are drawn
on to and removed from the display with an XOR write which prevents the destruction
of any underlying graphics.
It is important to note that you should only call this routine once for each line mode
change required.
See also 64CN6A0?782BNB4;42C43N0A40/
Example See page 143.

SET_HIGHLIGHTED@
Purpose To select all of the text in a %rd, %rf or %rs edit box.
Syntax BD1A>DC8=4 B4CN7867;867C43/70=3;4
8=C464A 70=3;4
Description 70=3;4 is the window handle of the edit box obtained by using %lc.
See also %rd, %rf, %rs

405
ClearWin+ User’s Guide Fortran

SET_LINE_STYLE@
Purpose To set the style for a line on the current drawing surface.
Syntax BD1A>DC8=4 B4CN;8=4NBCH;4/ E0;D4
8=C464A E0;D4
Description This routine changes the line style on the current drawing surface. E0;D4 is one of the
following predefined Windows constants (available from the file windows.ins):

?BNB>;83 solid line

?BN30B7 dashed line

?BN3>C dotted line

?BN30B73>C alternating dashes and dots

?BN30B73>C3>C alternating dashes and double dots

?BN=D;; pen is invisible

?BN8=B8345A0<4 the dimensions of a figure are reduced so that it fits entirely

in the bounding rectangle, taking into account the width of
the pen.

Notes ?BN8=B8345A0<4 can be ORed with one of the other values.

?BNB>;83, ?BN=D;; and ?BN8=B8345A0<4 are only available with a line width
greater than 1.

?BN=D;; can be used to remove the black border when printing a ‘filled polygon’, for
example, on a black and white printer.
See also B4CN;8=4NF83C7/

SET_LINE_WIDTH@
Purpose To set the line width on the current drawing surface.
Syntax BD1A>DC8=4 B4CN;8=4NF83C7/ E0;D4
8=C464A E0;D4
Description Changes the pixel thickness of a line when drawing on a drawing surface. The default
value is 1.

406
Chapter 27 Library reference

Set E = 0 for portrait and E = 1 for landscape.

SET_RGB_COLOURS_DEFAULT@
Purpose To set the global default to RGB colour mode.
Syntax BD1A>DC8=4 B4CNA61N2>;>DABN3450D;C/ 1>>;
8=C464A 1>>;
Description Currently by default ClearWin+ operates in VGA colour mode in which colours are
represented by palette index values. RGB colour mode is recommended for new
programs and this routine can be used to change the default. DB4NA61N2>;>DAB/ is
similar but relates to a given drawing surface. See page 136 for further details.
Use an input value of 1 to change the default to RGB colour mode.
See also DB4NA61N2>;>DAB/, VaJaVQNR^[^dabL

408
Chapter 27 Library reference

SET_SOUND_SAMPLE_RATE@
Purpose To set the sampling speed.
Syntax BD1A>DC8=4 B4CNB>D=3NB0<?;4NA0C4/ A0C4
8=C464A A0C4
Description The sampling rate is the frequency at which the sound sample will be played back or
recorded. Do not change this value whilst B>D=3N?;0H8=6/ or B>D=3NA42>A38=6/
return a value of 1. The maximum value that is permissible is dependant of the sound
device being used and you should consult the relevant technical notes supplied with it.
Common Windows values are maximum 44100 (44.1KHz), midrange 22050
(22.05khz) and minimum 11025 (11.025khz) - also the default. It should also be noted
that there will be an absolute minimum. There is no sense in recording at anything
less than 8000 (Hz), which is approximately the same sample rate as a telephone
connection, as the recording quality would be too low for practical use.
When selecting a suitable value it should also be noted that the sample rate must be set
to twice that of the maximum frequency you wish to record, this is to preserve quality
and reduce alias distortion.
For example:
If the maximum frequency to be recorded is 10khz (10000) then the sample rate must
be set to 20Khz (20000).
Note that this will require a large of amount storage.
See also FA8C4NF0E4N58;4/ ?;0HNB>D=3/
B>D=3N?;0H8=6/?;0HNB>D=3NA4B>DA24/ B>D=3NA42>A38=6/
B>D=3NA42>A38=6/B>D=3NB0<?;4NA0C4/

SHOW_MOVIE@
Purpose To show a video.
Syntax BD1A>DC8=4 B7>FN<>E84/58;4>?C
8=C464A >?C
270A02C4A 58;4
Description B7>FN<>E84/ opens the given .AVI file and shows it in a window. If >?C is zero, the
user must click the play button to start the movie. If >?C is 1, the movie starts
immediately. Do not call this routine with a file which does not exist - if necessary
check in advance.

409
ClearWin+ User’s Guide Fortran

When B7>FN<>E84/ returns, the movie window will be displayed and will be under
the user’s control. The <>E84N?;0H8=6/ function can be used to determine when the
user finally closes the window. If a second call to B7>FN<>E84/ is made before a
previous movie has finished playing, Clearwin+ will wait until the first movie
completes.
Movie files can include a sound track, which will be played if a sound card us installed
in your PC.

SIZE_IN_PIXELS@
Purpose To set the font size in pixels.
Syntax BD1A>DC8=4 B8I4N8=N?8G4;B/ 74867C F83C7
8=C464A 74867C F83C7
Description This routine allows you to specify the height and width of a font in pixels.
See also B8I4N8=N?>8=CB/

SIZE_IN_POINTS@
Purpose To set the font size in points.
Syntax BD1A>DC8=4 B8I4N8=N?>8=CB/ 74867C F83C7
8=C464A 74867C F83C7
Description Sets the 74867C and F83C7 of a font that is being used on a drawing surface.
See also B8I4N8=N?8G4;B/ B4;42CN5>=C/

SIZEOF_CLIPBOARD_TEXT@
Purpose To get the size of the text held in the clipboard.
Syntax 8=C464A 5D=2C8>= B8I4>5N2;8?1>0A3NC4GC/
Description This routine returns the length of the Windows clipboard text array (25NC4GC or
25N>4<C4GC format). The returned length includes a null (270A) character that
terminates the string.

410
Chapter 27 Library reference

Return value Returns the length of the string or zero on failure.

?;0HNB>D=3NA4B>DA24/ B>D=3NA42>A38=6/ B4;42CNB0<?;8=6NA0C4/

START_PROCESS@
Purpose To create a new process and wait for it to terminate.
Syntax 8=C464A 5D=2C8>= BC0ACN?A>24BB/ 2><<0=3 ?0A0<<0=3?0A0<<0=3 is the command line that is to be executed. ?0A0<B is a string of parameters
that is appended to the command line.
Return value Returns 0 or a positive value if successful. A return value of -1 indicates an error
condition.
Notes The new process is given the same ‘show’ state as that used when creating the calling
process. This will usually be ‘show normal’ or ‘show maximised’.
The alternative function BC0ACN??A>24BB/ takes the same form but returns
immediately (i.e. it does not wait for the created process to terminate).
Example 8=C464A BC0ACN?A>24BB/X
X,BC0ACN?A>24BB/ad]TgT
4=3

STOP_AUDIO_CD@
Purpose To stop audio playback from the CD.
Syntax BD1A>DC8=4 BC>?N0D38>N23/
See also 2;>B4N23NCA0H/ ?4=N23NCA0H/?;0HN0D38>N23/B4CN23N?>B8C8>=/

TEMPORARY_YIELD@
Purpose Provides an alternative to H84;3N?A>6A0<N2>=CA>;/HNC4<?>A0A8;H.
Syntax BD1A>DC8=4 C4<?>A0AHNH84;3/

412
Chapter 27 Library reference

UNDERLINE_FONT@
Purpose To add an underline to text on the current drawing surface.
Syntax BD1A>DC8=4 D=34A;8=4N5>=C/ 02C8E4
8=C464A 02C8E4
Description When using the function 3A0FN270A02C4AB/ ^n a drawing surface with any font
selected, a call to this routine with a value of 1 will make subsequent text underlined.
A further call with a value of 0 will switch off the effect.
See also A>C0C4N5>=C/ B20;4N5>=C/ B4;42CN5>=C/ 8C0;82N5>=C/ 1>;3N5>=C

UNMAP_FILE@
Purpose To close a file map (Win32 only).
Syntax BD1A>DC8=4 D=<0?N58;4/ ?CA
270A02C4A ?CA
Description File maps are closed automatically when the program terminates but can be closed
sooner by calling this routine. ?CA is a value returned by <0?N58;4N5>ANA4038=6/
or <0?N58;4N5>ANA403NFA8C4/
See also <0?N58;4N5>ANA4038=6/, <0?N58;4N5>ANA403NFA8C4/

UPDATE_WINDOW@
Purpose To redraw a ClearWin window.
Syntax BD1A>DC8=4 D?30C4NF8=3>F/F
8=C464A F
Description Causes the entire client area to be ‘invalidated’ and therefore re drawn. This should
not be confused with the ClearWin+ function F8=3>FND?30C4/ (see page 26) that is
used for format windows.

413
ClearWin+ User’s Guide Fortran

USE_APPROXIMATE_COLOURS@
Purpose To switch off colour matching for all drawing surfaces.
Syntax BD1A>DC8=4 DB4N0??A>G8<0C4N2>;>DAB/ 1>>;
8=C464A 1>>;
Description By default, routines that draw to a drawing surface use a colour matching algorithm
that selects an optimum colour match corresponding to the supplied colour value.
Colour matching can be switched off (for all drawing surfaces) by calling this routine
with the argument set to zero. A non-zero value switches on again.
If automatic colour matching is switched off, a matched colour can still be obtained
from 64CN<0C2743N2>;>DAB/. The result is used as an RGB value in any of the
drawing surface routines.
Using this routine may lead to a significant improvement in the performance of your
program since colour matching is often unnecessary. When colour matching is
desirable, it is only necessary to apply the matching algorithm once for each colour that
is used.

USE_RGB_COLOURS@
Purpose To switch between colour modes on a drawing surface.
Syntax 8=C464A 5D=2C8>= DB4NA61N2>;>DAB/ 70=3;4 1>>;
8=C464A 70=3;4 1>>;
Description 70=3;4 is the programmer’s handle for the drawing surface as used for example in
B4;42CN6A0?782BN>1942C/ and %`gr. If 70=3;4 is zero then the current drawing
surface is assumed. 1>>; can be either 1 or 0. If it is 1 then the A61 colour mode will
be used otherwise E60 colour mode (see page 136).
Return value Returns 1 for success or zero if the handle is not valid.
See also B4CNA61N2>;>DABN3450D;C/, VaJaVQNR^[^dabL

USE_WINDOWS95_FONT@
Purpose To set the default F8=8>/ font to Windows 95 font (Windows 95 only).
Syntax BD1A>DC8=4 DB4NF8=3>FB($N5>=C/

414
Chapter 27 Library reference

Description If this routine is called, by default all F8=8>/ dialogs will use the Windows 95 font
where available. This is equivalent to placing %`sf at the front of each F8=8>/ string
and adding a grave accent to every existing %sf format.
See also %sf

WAV_FILE_READ@
Purpose To read a WAV file as a samples wave-form.
Syntax 8=C464A 5D=2C8>= F0EN58;4NA403/ 70=3;4 ;45C
A867CB0<?;4B
8=C464A 70=3;4B0<?;4B
8=C464A! ;45CB0<?;4B A867CB0<?;4B
Description Samples sound data is read from the WAV file, returning at most B0<?;4B values.
70=3;4 should have been returned by a call to >?4=NF0EN58;4NA403/.
Return value Returns the number of samples read, which can be less than B0<?;4B if the end of the
file is reached.
See also >?4=NF0EN58;4NA403/

WAV_FILE_WRITE@
Purpose To store any recorded data.
Syntax BD1A>DC8=4 F0EN58;4NFA8C4/ 70=3;4 ;45C A867CB0<?;4B
8=C464A 70=3;4B0<?;4B
8=C464A! ;45CB0<?;4B A867CB0<?;4B
Description The data contained in ;45Cand A867C is written to disk in WAV file format. 70=3;4
should have been returned by a call to >?4=NF0EN58;4NFA8C4/.
See also >?4=NF0EN58;4NFA8C4/

415
ClearWin+ User’s Guide Fortran

WIN_COUA@
Purpose To output n characters from a string to a ClearWin window.
Syntax BD1A>DC8=4 F8=N2>D0/FBCA=
8=C464A F=
270A02C4A BCA
Description Outputs = characters from the string BCA to the ClearWin window with handle FThis
function provides an alternative to the standard Fortran routines FA8C4 and ?A8=C
that are normally used for text output to a ClearWin window.

WIN_GETCHAR@
Purpose To read a character from the keyboard.
Syntax 8=C464A F8=N64C270A/F
8=C464A F
Description Changes the input focus to the ClearWin window with handle F and reads a character
from the keyboard. This function provides an alternative to the standard A403 routine.

WIN_GETLINE@
Purpose To read a line of text from the keyboard.
Syntax BD1A>DC8=4 F8=N64C;8=4/F;8=4
8=C464A F
270A02C4A ;8=4
Description Changes the input focus to the ClearWin window with handle F and reads a line of text
from the keyboard. This function provides an alternative to the standard A403 routine.

WINDOWS_95_FUNCTIONALITY@
Purpose To test if Windows 95 is in use.
Syntax 8=C464A 5D=2C8>= F8=3>FBN($N5D=2C8>=0;8CH/

416
Chapter 27 Library reference

Return value Returns the value 1 if Windows 95, otherwise zero.

WKEY_WAITING@
Purpose To test if there are any keys in a ClearWin window keyboard buffer.
Syntax 8=C464A 5D=2C8>= F:4HNF08C8=6/
Description This routine is only for use in a ClearWin window (e.g. with %cw).
Return value Returns the number of keys in the keyboard buffer.
See also 5443NF:4H1>0A3/ 5;DB7NF:4H1>0A3/ 64CNF:4H/ 64CNF:4H /

WRITE_GRAPHICS_TO_BMP@
Purpose To write the current drawing surface to a BMP file.
Syntax BD1A>DC8=4 FA8C4N6A0?782BNC>N1<?/ 58;4=0<4 4AA>A
270A02C4A 58;4=0<4
8=C464A 4AA>A
Description Writes the current drawing surface to the file with name 58;4=0<4. 4AA>A returns
one of the following:
0 success
1 no current drawing surface or unable to open file
3 unable to write to file
See also 8<?>ACN1<?/ 4G?>ACN1<?/

WRITE_GRAPHICS_TO_PCX@
Purpose To write the current drawing surface to a PCX file.
Syntax BD1A>DC8=4 FA8C4N6A0?782BNC>N?2G/ 58;4=0<4 4AA>A
270A02C4A 58;4=0<4
8=C464A 4AA>A
Description Writes the current drawing surface to the file with name 58;4=0<4. 4AA>A returns
one of the following:

417
ClearWin+ User’s Guide Fortran

0 success
1 no current drawing surface or unable to open file
3 unable to write to file
See also 8<?>ACN?2G/ 4G?>ACN?2G/

WRITE_WAV_FILE@
Purpose To store any recorded data.
Syntax BD1A>DC8=4 FA8C4NF0EN58;4/ 58;4=0<4 270= B0<?;4B
;45C A867C
270A02C4A 58;4=0<4
8=C464A 270= B0<?;4B
8=C464A! ;45CB0<?;4B A867CB0<?;4B
?0A0<4C4A B0<?;4B
Description The data contained in ;45Cand A867C is written to disk in wave file format.
58;4=0<4 should be set to the desired file name. 270= can be either 1 (mono) or 2
(stereo). B0<?;4B is the length of both the ;45Cand A867C data arrays (they should
be identical).
This routine writes a whole WAV file in one go, so it must be of a size that can fit into
memory.
See also B>D=3NA42>A38=6/ A42>A3NB>D=3/
B>D=3N?;0H8=6/?;0HNB>D=3NA4B>DA24/ ?;0HNB>D=3/
B4CNB>D=3NB0<?;4NA0C4/

YIELD_PROGRAM_CONTROL@
Purpose To process Windows messages.
Syntax BD1A>DC8=4 H84;3N?A>6A0<N2>=CA>;/>?C8>=
8=C464A >?C8>=
Description This routine contains a Windows message loop. It is called automatically by
ClearWin+ so that the programmer does not need to include a message loop in a
program. It can be used within a program to ensure that a process does not totally take
over the CPU. >?C8>= may be either HN?4A<0=4=C;H or HNC4<?>A0A8;H.
You may need to call this routine using HNC4<?>A0A8;H, if the program makes

418
Chapter 27 Library reference

protracted use of the CPU and you want to allow it to respond to events (such as mouse
events) whilst the processing continues. Call this routine at suitable points during the
process to enable the message queue for the current application to be processed.
(Message queues for other applications that are running will automatically be
processed because Windows 95 and Windows NT are pre-emptive multi-tasking
operating systems.) C4<?>A0AHNH84;3/ is the same as
H84;3N?A>6A0<N2>=CA>;/HNC4<?>A0A8;H
Calling this routine using HN?4A<0=4=C;H is equivalent to reaching the END
statement of a ClearWin+ program.

419
ClearWin+ User’s Guide Fortran

420
28.

Glossary

Accelerator keys
An accelerator key is a key sequence, such as Alt-C that can directly activate some
process in a window (i.e. without popping up a menu). Accelerators can be defined
using %ac. A special case of an accelerator key is defined using %es, which causes a
window to respond to the ESC key by closing.
Bitmap
A rectangular image stored as binary data (see %bm). Bitmaps are stored in files with
the .BMP suffix.
Button
A button is a control that is designed to respond to a mouse click. Several types of
buttons are available. Simple 3-dimensional press and release buttons containing text
(and sometimes an icon as well) can be created using %bt. Radio buttons are created
with %rb. These are point like structures (with the name along side) that toggle when
pressed. Buttons containing a picture can be created with %tb.
Call-back function
A ClearWin+ call back function is a function passed to F8=8>/ (and certain other
functions) that is called when certain events occur. In ClearWin+, all such functions
take no arguments and return an integer result.
Caption
The distinctively coloured strip across the top of most windows that contains the title
together with some controls for manipulating the window. A window can be dragged
by its caption. See %ca.
Child window
A child window is a window that is contained within a larger window (which could be
a child of yet another window). The sub-windows of an MDI application (see %fr and
%aw) are children, as are the separate sheets of a property sheet (see %ps and %sh).

421
ClearWin+ User’s Guide Fortran

However, most controls, such as buttons, are considered by Windows to be children of

the window that contains them. This is why controls can be referred to by their
window handle (see %lc).
ClearWin window
A ClearWin window (no ‘+’) refers to a window created to contain output that would
have gone to the screen if the program were not a Windows application. The name
refers to the fact that the original ClearWin only created such relatively primitive
windows. A ClearWin window is still useful for debugging purposes, and may be
properly embedded in a format window using %cw. Keyboard input can also be taken
from a ClearWin window, but this is not recommended in finished programs.
Clipboard
The clipboard is a structure maintained by Windows that can contain information
which is to be copied within or between applications. The clipboard ‘knows’ the
format of the data that it contains, so a text editor will not accidentally paste data of
another format (e.g. an image) into its contents. By convention, the clipboard is
accessed as a direct response to controls with names such as ‘paste’, ‘cut’, ‘copy’. It is
extremely anti-social to use the clipboard in any other way, as users learn to rely on
the contents of the clipboard remaining unchanged unless they explicitly alter them.
Colour modes
When drawing to drawing surfaces, ClearWin+ operates in one of two colour modes;
RGB mode or VGA mode. In VGA mode, colour values are represented as indexes into
a colour palette by which ClearWin+ emulates a DOS environment. This mode is
useful for porting DOS programs to Windows. Currently the default colour mode is
VGA mode. In RGB mode ClearWin+ uses RGB colours (the native Windows colour
representation). RGB mode is recommended for new programs.
DLL
This stands for Dynamic Link Library - a library of code that can be linked to a
program at run time. DBOS provides such a mechanism, as does Win32. The Win32
file salflibc.dll is an example of a DLL.
Drawing surfaces
ClearWin+ includes a library of drawing routines for drawing lines and text, for
filling areas, for copying from one place to another, etc.. These drawing routines are
applied to the current drawing surface. This surface could be one of a number of
rectangular areas of the screen generated by %gr, it could be one of a number of
printer bitmaps (created for example by >?4=N?A8=C4A/) or it might be an internal
bitmap created by 2A40C4N6A0?782BNA468>=/ (that is, a bitmap that is created for
copying to another drawing surface). B4;42CN6A0?782BN>1942C/ is used to switch
from one drawing surface to another.

422
Chapter 28 Glossary

Edit box
This term is used to refer to boxes created with %eb to perform text editing. The term
may also include other boxes containing editable text, such as numeric input boxes
created with %rd, %rf, etc..
Focus
A control is said to have focus if it is the one that will respond to keyboard input.
Even buttons can have focus - a button with focus can be activated by pressing the
space bar. Usually the appearance of a control changes slightly when it acquires
focus.
Font
Information describing the graphical layout of a set of characters. Windows fonts can
be variable pitch (e.g. Times New Roman) or fixed pitch (e.g. Courier New). Variable
pitch fonts fit characters into different amounts of horizontal space depending on their
shape and the shapes of their neighbours (see %fn). Each font type comes in several
sizes (see %ts) and variants - italic (%it), bold (%bf) and underline (%ul).
Format
format window a window that has been created using F8=8>/.
format string the first argument of F8=8>/.
format code a format substring beginning with %.
format modifier one of the characters ^ ` ~ ? appearing in a format code.
GIF file
An image file format popular in World Wide Web documents. GIF files can be
partially transparent and/or animated. They can be incorporated into ClearWin+
programs as resources and accessed using the %gi format.
Greyed out
This expression refers to the process by which certain menu items, buttons, etc. can be
given a washed out appearance which is an indication to the user that they are not
available in current circumstances. Many controls and menus can be controllably
greyed using the ‘~’ format modifier together with an integer control variable that
specifies the current state.
GUI
This stands for Graphical User Interface, and refers to a program with a Windows
interface (or the equivalent on other platforms).
Handle
A handle is an integer supplied by Windows (in the context of Windows
programming) used to refer to an object. Thus a window handle is an integer used to
refer to a whole window or an individual control (most of which are treated as small
child windows). A bitmap handle is an integer used to refer to a bitmap, etc..

423
ClearWin+ User’s Guide Fortran

High colour device

A high colour graphics device is one that uses more than 8 bits (256 colours) per
pixel. Colour palettes become redundant when using such a device. The function
7867N2>;>DAN<>34/ can be used to test for a high colour device.
HTML
Hypertext Mark-up Language is the language used to create Internet Web pages. A
simplified form can be used to create hypertext pages in a format window (see %ht).
Icon
An icon is a special sort of image, stored in a binary file with the .ICO suffix. It is
partially transparent. Thus an icon can appear to have any shape (see %ic and %mi).
ClearWin+ uses icons of size 32x32. However, larger transparent images can be
manipulated as GIF files.
Maximise
The process by which a window is expanded until it exactly fits the screen (or
containing window in the case of MDI children). Menu options in the system menu
(and buttons on the top right of the window) enable the user to select and de-select this
state for a window. %ww[maximise] can be used to create a window in this state.
MDI
This stands for Multiple Document Interface. This is a style of program in which one
large window contains one or more smaller windows within it. These windows can be
opened, closed, moved, etc. independently. Most Windows editors adopt this style
with one window per opened file. The %fr and %aw formats can be used to create
such programs under ClearWin+.
Menu
Menus are text structures that respond to mouse clicks (and usually certain Alt-key
sequences) to enable users to give commands to the program. There are three types of
menus in Windows. 1) Ordinary window menus that start just below a window’s
caption and drop down to reveal sub options when they are clicked (see %mn). 2) The
so called system menu, that can be activated by clicking in the top left corner of a
window (see %sm), and 3) popup menus that appear when the right mouse button is
clicked (see %pm). See also shortcut keys.
Minimise
The process by which a window is shrunk to an icon (also known as iconification).
Menu options in the system menu (and buttons on the top right of the window) enable
the user to select this state. The user can access the system menu in order to return
the window to normal by clicking on the icon. Use %mi to define the icon that will be
used in the minimised state.

424
Chapter 28 Glossary

Resources
Microsoft jargon for non-program information (e.g. images or sounds) built into a
program. Resources are specified in resource scripts, and are compiled with the
resource compiler (SRC). ClearWin+ programs use resources to incorporate images,
sounds, and hypertext into the program.
RGB colours
The Windows API represents a colour in terms of the intensity (in the range 0 to 255)
of its red, green and blue components. Each component is thus an 8-bit value and the
three components are packed into a 32-bit integer with the least significant 8 bits
being red, the next 8 bits green and then blue. The most significant 8 bits are not
used. The packing process is done for you by the function A61/. For example
A61/!$$ represents pure red.
Screen resolution
The number of pixels horizontally and vertically on the entire screen. Typical values
are 640 x 480, 800 x 600, and 1024 x 768. The screen will also have a colour
resolution, typically 16, 256, 16k, or higher.
Screen saver
A program designed to run while the computer is idle. Usually such programs are
designed to stop as soon as mouse or keyboard input is received (see %ns and %sv).
Scroll bar
A scroll bar is a structure to the right of a window or control that can be used to shift
the contents vertically, or at the bottom of a window to shift the contents horizontally.
A scroll bar has an arrow structure at either end that will scroll the contents by one
unit (e.g. one line if the contents is text) and a moveable control (known as a thumb)
that can be dragged to make larger movements. Movements of one page (the exact
meaning of which depends on the window contents) can be made by clicking above or
below the thumb (see %hx and %vx).
Shortcut keys
A shortcut key represents a way of accessing a menu using the keyboard. Each item of
a menu can have a letter underlined, indicating that it can be selected by holding
down the Alt key and pressing the letter (or certain other keys). The components of
subsequent sub-menus can then be selected by pressing further keys corresponding to
underlined letters in the menus. The whole process of underlining the letters and
responding to the keyboard is controlled by merely prefixing the letter in the menu
item by an ‘&’ (see %mn and %sm).
Standard character string
This is the name given to text in a format string that is either placed in square
brackets or is replaced by an @ symbol and represented by an argument.

425
ClearWin+ User’s Guide Fortran

Status bar
This is a strip at the bottom of a window with a distinct colour (usually grey) in which
special information is placed. See the %ob format for details of how to create one.
Thumb
The name given to a blank box that appears on a scroll bar. One of the mechanisms
for scrolling involves dragging this box with the mouse.
Toolbar
A toolbar is a rectangular array of bitmap buttons, usually but not always located
under the window menu bar. Toolbars can be created as arrays of bitmap buttons
using %tb.
Win16
This refers to programs that interact with the 16-bit API of Windows 3.1. This is also
available under Windows 95. Salford compilers generate 32-bit code for Win16 that
operates using a 16/32 interface. Although the Win16 API is available under
Windows NT, there are certain restrictions that prevent the above 16/32 interface from
working - Win32 must be used for this operating system. The ClearWin+ User’s
Supplement provides additional information for writing Win16 applications.
Win32
This refers to programs that exploit the 32-bit mode of operation available in
Windows 95 and Windows NT. All Salford compilers are 32-bit, but the non-Win32
products execute in 32-bit mode but provide an interface to the 16-bit operating system
via DBOS and/or WDBOS.
Windows application
A Windows program - that is any program that opens at least one window. Non
Windows applications use DBOS and read and write to the screen or DOS box.
Under Win32 the difference is very slight, however under Win 3.1 non-Windows
applications created with Salford compilers use DBOS and operate from within a
DOS box.
Windows control
A windows control is any part of a window that operates as a distinctive entity. For
example, buttons, %rd integer input boxes, and toolbars are all controls.
Windows API
This is the set of routines supplied by Microsoft to access the features of Windows.
All Windows programs ultimately call these routines. For example, requests to
ClearWin+ are executed internally by making calls to the Windows API.

426
Chapter 28 Glossary

Windows message
Windows communicates information about events (such as key presses, mouse
movements, etc.) to the program by means of ‘messages’. These are small structures
that are stored in a queue and accessed by means of a call to the Windows API. This
process is handled automatically by ClearWin+. Specific Windows messages are
referred to by names such as WM_PAINT, WM_CREATE, etc.
WM_PAINT message
This is a message sent by Windows to an application to tell it to ‘re-paint’ one of its
windows (for example because another window has obscured it). ClearWin+
programmers do not need to be aware of the fact that a window’s contents may have to
be regenerated in this way. However some call-backs, such as the re-colour call back
from %eb edit boxes, may be activated in response to this message.

427
ClearWin+ User’s Guide Fortran

428
Appendix A.

Functions ported from DBOS

This appendix contains information about functions that feature in the Salford DOS
(DBOS) graphics library. It describes the extent to which this library has been ported
to ClearWin+. The following classification of DBOS graphics functions can be made
in relation to ClearWin+.
1. Functions that are useful in new programs (marked 9). Some of these will have
identical usage under ClearWin+ to that under DBOS. For some the functionality
is slightly different. Details are given in Chapter 27.
2. Functions that can be used in new programs (marked ;) but for which there is a
suitable alternative. Details for these functions are given in the ClearWin+ User’s
Supplement. A table of the alternative routines is given at the end of this
appendix. The alternatives are documented in this guide.
3. Functions that could be ported from existing DBOS programs but which should
not be written into new programs because there is a better alternative under
ClearWin+ (marked Ö). A table of alternative routines is given at the end of this
appendix.
4. Functions which have no operation or are not useful under ClearWin+ but can be
left in old programs that have been ported from DBOS (marked |).
5. Functions which have not been implemented under ClearWin+ (marked 8).

Graphics
CLEAR_SCREEN@ Clears the drawing surface. 9
CLEAR_SCREEN_AREA@ Clears a rectangular area of the drawing surface. ;
COMBINE_POLYGONS@ Gets the handle for a combination of polygons. Ö
CREATE_POLYGON@ Gets a handle for a specified polygon. Ö
DELETE_POLYGON_DEFINITION@ Deletes a polygon definition. Ö
429
ClearWin+ User’s Guide Fortran

DRAW_HERSHEY@ Draws an Hershey character. Ö

DRAW_LINE@ Draws a straight line on the drawing surface. Ö
DRAW_TEXT@ Draws text on the drawing surface. Ö
EGA@ Switches to EGA graphics mode. |
ELLIPSE@ Draws an ellipse. Ö
FILL_ELLIPSE@ Fills an ellipse. Ö
FILL_POLYGON@ Fills a polygon. Ö
FILL_RECTANGLE@ Fills a rectangle. Ö
GET_ALL_PALETTE_REGS@ Gets all palette registers for colour graphics. Ö
GET_DEVICE_PIXEL@ Gets a pixel colour from a graphics region. 8
GET_GRAPHICS_MODES@ Gets details of all the graphics modes. |
GET_GRAPHICS_RESOLUTION@ Gets details of the high resolution graphics mode. |
GET_PIXEL@ Gets a pixel colour from the drawing surface. Ö
GET_TEXT_MODES@ Gets information about the available text modes. 8
GET_TEXT_SCREEN_SIZE@ Gets the resolution of the current text mode. 8
GET_VIDEO_DAC_BLOCK@ Gets a block of VGA DAC registers. Ö
GRAPHICS_MODE_SET@ Sets the graphics mode to a given resolution. Ö
GRAPHICS_WRITE_MODE@ Selects replace/XOR mode before writing to the9
screen, virtual screen or printer.
HERSHEY_PRESENT@ Tests if a character number has a HersheyÖ
representation.
HIGH_RESOLUTION_GRAPHICS_MODE@ Switches to high resolution graphics mode. |
IS_TEXT_MODE@ Tests if the screen is in text or graphics mode. 8
LOAD_STANDARD_COLOURS@ Loads the standard colours for 256 colour mode. 9
MOVE_POLYGON@ Moves the position of a polygon. Ö
POLYLINE@ Draws a number of connected straight lines. Ö
RECTANGLE@ Draws a rectangle. Ö
RESTORE_GRAPHICS_BANK@ Restores the graphics bank after a BIOS call. |
RESTORE_TEXT_SCREEN@ Restores a text screen saved with 8
SAVE_TEXT_SCREEN@.
SAVE_TEXT_SCREEN@ Saves the whole of the text screen. 8
SCREEN_TYPE@ Gets the graphics screen type. |
SET_ALL_PALETTE_REGS@ Sets all palette registers for colour graphics. Ö
SET_DEVICE_PIXEL@ Sets a pixel colour on the drawing surface. ;

430
Appendix A Functions ported from DBOS

SET_PALETTE@ Sets a palette register for colour graphics. Ö

SET_PIXEL@ Sets a pixel colour on the drawing surface. Ö
SET_TEXT_ATTRIBUTE@ Sets the current graphics text attributes. ;
SET_VIDEO_DAC@ Sets a VGA DAC register. Ö
SET_VIDEO_DAC_BLOCK@ Sets a block of VGA DAC registers. Ö
TEXT_MODE@ Returns to text mode. |
TEXT_MODE_SET@ Selects the current text mode. |
USE_VESA_INTERFACE@ Forces the VESA interface to be used. |
VGA@ Switches to VGA graphics mode. |

Graphics plotter/screen
CLOSE_PLOTTER@ Closes the plotter device or file. Ö
CLOSE_VSCREEN@ Closes the virtual screen. ;
CREATE_SCREEN_BLOCK@ Creates a screen block in memory. ;
GET_DACS_FROM_SCREEN_BLOCK@ Uses palette information from a PCX file. ;
GET_SCREEN_BLOCK@ Saves a rectangular area of the screen. ;
NEW_PAGE@ Provides a new page on the drawing surface. 9
OPEN_PLOT_DEVICE@ Opens the plotter. Ö
OPEN_PLOT_FILE@ Directs plotter output to a file. Ö
OPEN_VSCREEN@ Opens a screen block as the virtual screen. ;
PCX_TO_SCREEN_BLOCK@ Loads a file a screen block. ;
PLOTTER_SET_PEN_TYPE@ Selects a pen type for the plotter. |
RESTORE_SCREEN_BLOCK@ Displays a previously saved area of the screen. ;
SCREEN_BLOCK_TO_PCX@ Saves a screen block a file. ;
SCREEN_BLOCK_TO_VSCREEN@ Loads a screen block to the virtual screen. ;
SCREEN_TO_VSCREEN@ Loads the graphics screen to the virtual screen. ;
VSCREEN_TO_PCX@ Saves the virtual screen to a file. ;
VSCREEN_TO_SCREEN@ Loads the virtual screen to the graphics screen. ;
WRITE_TO_PLOTTER@ Writes a string to the plotter. |

431
ClearWin+ User’s Guide Fortran

Graphics printer
CLOSE_GRAPHICS_PRINTER@ Closes the graphics printer device or file. Ö
GET_PCL_PALETTE@ Gets the colour definitions for a given number of9
colours.
LOAD_PCL_COLOURS@ Loads the standard colour definitions. 9
OPEN_GPRINT_DEVICE@ Opens a graphics printer. Ö
OPEN_GPRINT_FILE@ Directs graphics printer output to a file. Ö
PRINT_GRAPHICS_PAGE@ Prints a graphics page. 9
SELECT_DOT_MATRIX@ Selects an Epson compatible dot matrix printer 8
SELECT_PCL_PRINTER@ Specifies attributes of a PCL printer. Ö
SET_PCL_BITPLANES@ Sets the number of colours in the image. |
SET_PCL_GAMMA_CORRECTION@ Alters the “gamma correction” for colours. |
SET_PCL_GRAPHICS_DEPLETION@ Improves the image quality. |
SET_PCL_GRAPHICS_SHINGLING@ Makes a number of print passes. |
SET_PCL_LANDSCAPE@ Sets LANDSCAPE or PORTRAIT orientation. ;
SET_PCL_PALETTE@ Loads the colour definitions. |
SET_PCL_RENDER@ Sets the “rendering algorithm”. |

Mouse
DISPLAY_MOUSE_CURSOR@ Shows the mouse cursor on the screen. |
GET_MOUSE_BUTTON_PRESS_COUNT@ Gets the number of times a button has been pressed. |

GET_MOUSE_EVENT_MASK@ Gets the mask for the most recent mouse interrupt. |
GET_MOUSE_PHYSICAL_MOVEMENT@ Gets the mouse pad distance from the last call. |
GET_MOUSE_POSITION@ Gets the present state of the mouse cursor. Ö
GET_MOUSE_SENSITIVITY@ Gets the values of the physical movement ratios and|
the double speed threshold.
HIDE_MOUSE_CURSOR@ Hides the mouse cursor on the screen. |
INITIALISE_MOUSE@ Initialises the mouse driver. |
MOUSE@ Performs a mouse interrupt. |

432
Appendix A Functions ported from DBOS

MOUSE_CONDITIONAL_OFF@ Switches off the cursor when it enters a specified |

rectangle.
MOUSE_LIGHT_PEN_EMULATION@ Uses the mouse as a light-pen. |
MOUSE_SOFT_RESET@ Initialises the mouse. Ö
QUERY_MOUSE_SAVE_SIZE@ Gets the buffer size for the mouse state. |
RESTORE_MOUSE_DRIVER_STATE@ Restores a former state of the mouse driver. |
SAVE_MOUSE_DRIVER_STATE@ Saves the current state of the mouse driver. |
SET_MOUSE_BOUNDS@ Restricts mouse movements to a specified rectangle. |
SET_MOUSE_GRAPHICS_CURSOR@ Specifies the shape of the mouse cursor for graphics|
mode.
SET_MOUSE_INTERRUPT_MASK@ Enables mouse actions to produce interrupts. |
SET_MOUSE_MOVEMENT_RATIO@ Sets the mouse cursor sensitivity. |
SET_MOUSE_POSITION@ Moves the mouse cursor to a particular position. Ö
SET_MOUSE_SENSITIVITY@ Sets the mouse cursor sensitivity and the threshold for|
the double speed.
SET_MOUSE_SPEED_THRESHOLD@ Sets the threshold for double speed. |
SET_MOUSE_TEXT_CURSOR@ Specifies details of the mouse cursor for text mode. |

Table of alternative routines

DBOS routine ClearWin+ alternative
CLEAR_SCREEN_AREA@ DRAW_FILLED_RECTANGLE@

CLOSE_GRAPHICS_PRINTER@ CLOSE_PRINTER@

CLOSE_PLOTTER@ CLOSE_PRINTER@

CLOSE_VSCREEN@ CREATE_GRAPHICS_REGION@ etc.

COMBINE_POLYGONS@ DRAW_FILLED_POLYGON@

CREATE_POLYGON@ DRAW_FILLED_POLYGON@

CREATE_SCREEN_BLOCK@ CREATE_GRAPHICS_REGION@ etc.

DELETE_POLYGON_DEFINITION@ DRAW_FILLED_POLYGON@

DRAW_HERSHEY@ DRAW_CHARACTERS@

DRAW_LINE@ DRAW_LINE_BETWEEN@

DRAW_TEXT@ DRAW_CHARACTERS@

433
ClearWin+ User’s Guide Fortran

ELLIPSE@ DRAW_ELLIPSE@

FILL_ELLIPSE@ DRAW_FILLED_ELLIPSE@

FILL_POLYGON@ DRAW_FILLED_POLYGON@

FILL_RECTANGLE@ DRAW_FILLED_RECTANGLE@

GET_ALL_PALETTE_REGS@ GET_COLOURS@

GET_MOUSE_POSITION@ CLEARWIN_INFO@

GET_PIXEL@ GET_POINT@

GET_SCREEN_BLOCK@ CREATE_GRAPHICS_REGION@ etc.

GET_VIDEO_DAC_BLOCK@ GET_COLOURS@

GRAPHICS_MODE_SET@ LOAD_STANDARD_COLOURS@

HERSHEY_PRESENT@ DRAW_CHARACTERS@

MOUSE_SOFT_RESET@ SET_MOUSE_CURSOR_POSITION@

MOVE_POLYGON@ DRAW_FILLED_POLYGON@

OPEN_GPRINT_DEVICE@ OPEN_PRINTER@

OPEN_GPRINT_FILE@ OPEN_PRINTER_TO_FILE@

OPEN_PLOT_DEVICE@ OPEN_PRINTER@

OPEN_PLOT_FILE@ OPEN_PRINTER_TO_FILE@

OPEN_VSCREEN@ CREATE_GRAPHICS_REGION@ etc.

PCX_TO_SCREEN_BLOCK@ CREATE_GRAPHICS_REGION@ etc.

POLYLINE@ DRAW_POLYLINE@

RECTANGLE@ DRAW_RECTANGLE@

RESTORE_SCREEN_BLOCK@ CREATE_GRAPHICS_REGION@ etc.

SCREEN_BLOCK_TO_PCX@ CREATE_GRAPHICS_REGION@ etc.

SCREEN_BLOCK_TO_VSCREEN@ CREATE_GRAPHICS_REGION@ etc.

SCREEN_TO_VSCREEN@ CREATE_GRAPHICS_REGION@ etc.

SELECT_PCL_PRINTER@ OPEN_PRINTER@

SET_ALL_PALETTE_REGS@ SET_COLOURS@

SET_DEVICE_PIXEL@ DRAW_POINT@

SET_MOUSE_POSITION@ SET_MOUSE_CURSOR_POSITION@

SET_PALETTE@ SET_COLOURS@

SET_PCL_LANDSCAPE@ SET_PRINTER_ORIENTATION@

SET_PIXEL@ DRAW_POINT@

SET_TEXT_ATTRIBUTE@ BOLD_FONT@ etc.

These routines are documented in the ClearWin+ User’s Supplement.

434
Appendix A Functions ported from DBOS

SET_VIDEO_DAC@ SET_COLOURS@

SET_VIDEO_DAC_BLOCK@ SET_COLOURS@

VSCREEN_TO_PCX@ CREATE_GRAPHICS_REGION@ etc.

VSCREEN_TO_SCREEN@ CREATE_GRAPHICS_REGION@ etc.

435
ClearWin+ User’s Guide Fortran

436
Index

%fs, 105, 241

% %ft, 106, 241
%ac, 88, 215
%ga, 59, 242
%ap, 95, 216
%gd, 95, 242
%aw, 123, 216
%gf, 97, 242
%bc, 54, 217
%gi, 243
%bd, 217
%gp, 94, 244
%bf, 97, 218
%gr, 136, 245
%bg, 127, 218
%he, 120, 245
%bh, 119, 219
%ht, 199, 246
%bi, 54, 219
%hw, 121, 246
%bk, 220
%hx, 62, 247
%bm, 75, 220
%ib, 58, 247
%br, 61, 221
%ic, 77, 249
%bt, 51, 221
%if, 249
%bv, 71, 222
%il, 42, 250
%bx, 59, 225
%it, 97, 250
%ca, 121, 225
%lc, 121, 250
%cb, 226
%ld, 251
%cc, 130, 226
%ls, 62, 251
%ch, 123, 226
%lv, 252
%cl, 73, 227
%lw, 122, 256
%cn, 89, 227
%mg, 257
%co, 40, 228
%mi, 78, 257
%cu, 76, 228
%mn, 81, 258
%cv, 123, 230
%ms, 64, 258
%cw, 128, 230
%mv, 259
%dc, 76, 231
%nc, 260
%dd, 41, 232
%nd, 260
%de, 232
%nl, 260
%df, 41, 233
%nr, 261
%dl, 130, 233
%ns, 133, 261
%dp, 42, 263
%ob, 91, 261
%dr, 125, 234
%og, 263
%dw, 157, 234
%pb, 42, 263
%dy, 235
%pd, 100, 264
%eb, 107, 235
%pl, 264
%el, 236
%pm, 84, 264
%ep, 42, 263
%ps, 129, 265
%eq, 100, 237
%pv, 266
%es, 237
%rb, 55, 266
%ew, 238
%rd, 37, 267
%fb, 238
%re, 268
%fd, 238
%rf, 38, 269
%ff, 239
%rj, 90, 270
%fh, 239
%rm, 270
%fl, 41, 239
%rp, 270
%fn, 97, 240
%rs, 40, 271
%fp, 42, 263
%sc, 123, 272
%fr, 123, 240

Index-1
ClearWin+ User’s Guide Fortran

%sd, 98, 272 ADD_HYPERTEXT_RESOURCE@ routine, 332

%sf, 98, 273 ADD_KEYBOARD_MONITOR@ routine, 333
%sh, 130, 273 ADD_MENU_ITEM@ routine, 333
%si, 78, 273 ADD_WINIO_CHARACTER@ routine, 29
%sl, 44, 274 ADD_WINIO_FLOAT@ routine, 29
%sm, 86, 275 ADD_WINIO_FUNCTION@ routine, 29
%sp, 94, 126, 275 ADD_WINIO_INTEGER@ routine, 29
%ss, 48, 275 ADVANCE_EDIT_BUFFER@ routine, 115
%st, 100, 276 API
%su, 98, 277 CreatePen, 158
%sv, 132, 277 FillRect, 158
%sy, 277 MessageBeep, 79
%sz, 126, 278 RGB, 99, 128
%ta, 279 SelectObject, 335
%tb, 56, 279 Attach window (child window), 123
%tc, 99, 280 ATTACH_BITMAP_PALETTE@ routine, 334
%th, 119, 281
%ti, 281
%tl, 90, 282 B
%tp, 42, 263 Background colour
%ts, 99, 282 of window, 127
%tt, 54, 283 BEEP, standard call-back, 206
%tv, 68, 283 Bitmap, 75, 421
%tx, 103, 285 Bold fonts, 97
%ul, 97, 286 BOLD_FONT@ routine, 334
%up, 42, 263 Box selection, 144
%uw, 131, 286 Boxes, 91, 311
%vx, 62, 286
behaviour with %cn, 90
%wc, 45
shaded, 262
%wd, 45
BREAK_MODEM_CONNECTION@ routine, 204
%we, 46
Button, 421
%wf, 47
%wg, 47 bitmap button, 56
%wp, 131, 288 call-back, 51
%ws, 48 colour, 54
%ww, 126, 289 greying, 52
%wx, 48 icon format, 54
radio, 55
textual toolbar, 54
&
& menu accelerator, 81
+, standard call-back, 212 C
? format modifier, 24, 119 Call-back
^ format modifier, 24 HTML_PRINTER_OPEN, 191
` format modifier, 24 Call-back function, 421
~ format modifier, 24 Call-backs, 21
Captions, 121, 421
CASCADE, standard call-back, 206
A Centring, 89
ABORT@ routine, 329 CHANGE_HYPERTEXT@ routine, 335
ABOUT, standard call-back, 206 CHANGE_PEN@ routine, 335
Absolute position, 95 Child window format, 123
Accelerator keys, 88, 421 Child windows, 421
ACTIVATE_BITMAP_PALETTE@ routine, 329 MDI frames, 123
ADD_ACCELERATOR@ routine, 330 other, 123
ADD_CURSOR_MONITOR@ routine, 330 CHOOSE_COLOUR@ routine, 335
ADD_FOCUS_MONITOR@ routine, 331 CHOOSE_FONT@ routine, 336
ADD_GRAPHICS_ICON@ routine, 331 CLEAR_BITMAP@ routine, 336
ADD_HYPERTEXT@ routine, 332

Index-2
Index

CLEAR_SCREEN@ routine, 336 CURRENT_MENU_ITEM, 342

CLEAR_WINDOW@ routine, 337 CURRENT_TEXT_ITEM, 341, 342
ClearWin window, 422 DROPPED_FILE, 342
text output, 301 PRINTER_DOCUMENT, 401
CLEARWIN_FLOAT@ routine, 337 CLEARWIN_STRING@ routine, 341
CLEARWIN_INFO@ CLEARWIN_VERSION@ routine, 343
ACTION_X, 337 Clipboard, 422
ACTION_Y, 337, 338 CLIPBOARD_TO_SCREEN_BLOCK@ routine, 344
ACTIVE_EDIT_BOX, 337, 338 CLOSE_CD_TRAY@ routine, 344
CALL_BACK_WINDOW, 337, 338 CLOSE_METAFILE@ routine, 345
CURSOR_WINDOW, 337, 338 CLOSE_PRINTER@ routine, 345
DRAGGED_ICON, 337, 338 CLOSE_PRINTER_ONLY@ routine, 345
DROPPED_COUNT, 337, 338 CLOSE_WAV_FILE@ routine, 346
DROPPED_CURRENT, 337, 338 Closing a window, 25
Closure control format, 130
DROPPED_ICON, 337, 338
Colour modes, 136, 422
FOCUS_WINDOW, 337, 338
Colour palette, 73
FOCUSSED_WINDOW, 338 Compiler option /WINDOWS, 293
GAINING_FOCUS, 338 Compiler options, 293
GIF_MOUSE_X, 338 Compiling a Windows application, 293
GIF_MOUSE_Y, 338, 339 Conditional hypertext, 203
GRAPHICS_DC, 338, 339 CONFIRM_EXIT, standard call-back, 206
GRAPHICS_DEPTH, 338, 339 CONTINUE, standard call-back, 207
GRAPHICS_HDC, 338, 339 CONTROL_NAME_FROM_HANDLE@ routine, 313
GRAPHICS_MOUSE_FLAGS, 339 COPY, standard call-back, 206
GRAPHICS_MOUSE_X, 339 COPY_FROM_CLIPBOARD@ routine, 346
GRAPHICS_MOUSE_Y, 339, 340 COPY_GRAPHICS_REGION@ routine, 347
GRAPHICS_RESIZING, 338, 339 COPY_TO_CLIPBOARD@ routine, 348
CREATE_BITMAP@ routine, 349
GRAPHICS_WIDTH, 338, 339
CREATE_CURSOR@ routine, 349
LATEST_FORMATTED_WINDOW, 339, 340 CREATE_GRAPHICS_REGION@ routine, 350
LATEST_VARIABLE, 339, 340 CREATE_WINDOW@ routine, 350
LATEST_WINDOW, 339, 340 Cursor format, 76
LISTBOX_ITEM_SELECTED, 339, 340 CUT, standard call-back, 206
LOSING_FOCUS, 339, 340
MESSAGE_HWND, 339, 340
MESSAGE_LPARAM, 339, 340 D
MESSAGE_WPARAM, 339, 340 Debugging with an auxilliary terminal, 312
OPENGL_DEPTH, 339, 340 DEC, standard call-back, 208
OPENGL_DEVICE_CONTEXT, 339, 340 Default cursor, 76
DEFINE_FILE_EXTENSION@ routine, 351
OPENGL_WIDTH, 339, 340
Delayed auto recall, 130
PIXELS_PER_H_UNIT, 339, 340
DELETE_GRAPHICS_REGION@ routine, 352
PIXELS_PER_V_UNIT, 339, 341 DESTROY_WINDOW@ routine, 352
PRINTER_COLLATE, 339, 341 DIB_PAINT@ routine, 352
SCREEN_DEPTH, 339, 341 Disable screen saver, 133
SCREEN_WIDTH, 339, 341 DISPLAY_DIB_BLOCK@ routine, 353
SHEET_NO, 339, 341 DISPLAY_POPUP_MENU@ routine, 353
SPIN_CONTROL_USED, 339, 341 DLL, 422
TEXT_ARRAY_CHAR, 103, 339, 341 DO_COPIES@ routine, 354
TEXT_ARRAY_MOUSE_FLAGS, 104 DRAW_BEZIER@ routine, 354
TEXT_ARRAY_RESIZING, 104 DRAW_CHARACTERS@ routine, 354
TEXT_ARRAY_WIDTH, 104 DRAW_ELLIPSE@ routine, 355
TEXT_ARRAY_X, 104 DRAW_FILLED_ELLIPSE@ routine, 355
DRAW_FILLED_POLYGON@ routine, 356
TEXT_ARRAY_Y, 104
DRAW_FILLED_RECTANGLE@ routine, 356
TREEVIEW_ITEM_SELECTED, 339, 341
DRAW_LINE_BETWEEN@ routine, 356
CLEARWIN_INFO@ routine, 337
DRAW_POINT@ routine, 357
CLEARWIN_STRING@

Index-3
ClearWin+ User’s Guide Fortran

DRAW_POLYLINE@ routine, 357 GET_DEFAULT_WINDOW@ routine, 361

DRAW_RECTANGLE@ routine, 357 GET_DIB_BLOCK@ routine, 361
Drawing surfaces, 422 GET_DIB_SIZE@ routine, 362
GET_FILTERED_FILE@ routine, 363
GET_FONT_ID@ routine, 364
E GET_FONT_NAME@ routine, 365
Edit box, 107, 423 GET_GRAPHICAL_RESOLUTION@ routine, 365
EDIT_CLOSE_MARK@ routine, 117 GET_GRAPHICAL_SELECTED_AREA@ routine, 365
EDIT_DELETE_LINES@ routine, 116 GET_IM_INFO@ routine, 366
EDIT_FILE, standard call-back, 207 GET_MATCHED_COLOUR@ routine, 366
EDIT_FILE_OPEN, standard call-back, 207 GET_MOUSE_INFO@ routine, 367
EDIT_FILE_SAVE, standard call-back, 207 GET_NEAREST_SCREEN_COLOUR@ routine, 368
EDIT_FILE_SAVE_AS, standard call-back, 207 GET_POINT@ routine, 368
EDIT_MOVE_BOF@ routine, 116 GET_PRINTER_ORIENTATION@ routine, 368
EDIT_MOVE_END@ routine, 116 GET_RGB_VALUE@ routine, 369
EDIT_MOVE_HOME@ routine, 116 GET_SCREEN_DIB@ routine, 369
EDIT_MOVE_TOF@ routine, 116 GET_SYSTEM_FONT@ routine, 369
EDIT_OPEN_BLOCK_MARK@ routine, 117 GET_TEXT_SIZE@ routine, 370
EDIT_OPEN_LINE_MARK@ routine, 117, 118 GET_TRACK_LENGTH@ routine, 370
Enhanced menu, 86 GET_WINDOW_LOCATION@ routine, 371
EQUIVALENCE, 310 GET_WKEY@ routine, 371
EXIT, standard call-back, 208 GET_WKEY1@ routine, 372
EXPORT_BMP@ routine, 358 GetTextMetrics, 310
EXPORT_PCX@ routine, 358 GIF file, 423
GPRINTER_OPEN, standard call-back, 209
Graphics, 136
F background colour, 137
FATAL, standard call-back, 208 basic primitives, 138
FEED_WKEYBOARD@ routine, 359
call-backs, 142
File filter, 106
drawing text, 138
File selection, 105
FILE_OPENR, standard call-back, 208 icons, 152
FILE_OPENW, standard call-back, 209 off-screen graphics, 150
FILL_SURFACE@ routine, 359 printers, 195
FILL_TO_BORDER@ routine, 359 re-sizing, 141
FIND_EDIT_STRING@ routine, 114 selection modes, 143
FIND_REPLACE_EDIT_STRING@ routine, 114 USER_SURFACE, 148
FLUSH_WKEYBOARD@ routine, 360 Graphics selection
Focus, 331, 337, 338, 423 Box selection, 144
Font, 423 Line selection, 144
format, 97 Rubber-banding, 143
get, 97 GRAPHICS_TO_CLIPBOARD@ routine, 372
FONT_METRICS@ routine, 360 GRAPHICS_WRITE_MODE@ routine, 373
Format codes, 23 Grey buttons, 52
Format codes, index of, 31 Greyed menus, 81
Format modifiers, 24 Greyed out, 423
Format windows, 19 Greying controls, 24
Fortran Grid display, 95
calling Windows API routines from, 305 GUI, 423
using the Windows API, 310
H
G Handle, 423
Gang controls together, 59 HANDLE_FROM_CONTROL_NAME@ routine, 313
Get and set window position, 94 Help format, 120
Get font name, 97 HELP_CONTENTS, standard call-back, 209
GET_BITMAP_DC@ routine, 360 HELP_ON_HELP, standard call-back, 209
GET_CLEARWIN_TEXT@ routine, 303, 361 HIBYTE@ routine, 373
GET_CURRENT_DC@ routine, 361 High colour device, 424

Index-4
Index

HIGH_COLOUR_MODE@ routine, 373

HIWORD@ routine, 374
N
Horizontal scroll bar, 62 NEW_PAGE@ routine, 380
HTML, 424 NEXT_EDIT_OPERATION@ routine, 115
Hypertext, 199 Null terminated strings, 108
&, 200
<, 200 O
>, 200 Open box, 91
bold, 201 OPEN_CD_TRAY@ routine, 380
colours, 201 OPEN_EDIT_FILE@ routine, 116
conditional, 203 OPEN_GL_PRINTER@ routine, 381
DOC, 200 OPEN_GL_PRINTER1@ routine, 381
horizontal rule, 201 OPEN_METAFILE@ routine, 382
HREF, 200 OPEN_PRINTER@ routine, 382
HTML, 200 OPEN_PRINTER_TO_FILE@ routine, 383
images, 201 OPEN_PRINTER1@ routine, 383
OPEN_PRINTER1_TO_FILE@ routine, 384
italic, 201
OPEN_TO_WINDOW@ routine, 384
lists, 201
OPEN_WAV_FILE_READ@ routine, 385
Paragraph, 201 OPEN_WAV_FILE_WRITE@ routine, 385
TITLE, 200 Owner draw box, 157
underline, 201

P
I Parameter box, 42
Icons, 77, 424 PASTE, standard call-back, 206
IMPLICIT NONE, 295 PAUSE Fortran statement, 309
IMPORT_BMP@ routine, 374 PERFORM_GRAPHICS_UPDATE@ routine, 385
IMPORT_PCX@ routine, 375 PERMIT_ANOTHER_CALLBACK@ routine, 386
INC, standard call-back, 209 PLAY_AUDIO_CD@ routine, 386
INSERT_EDIT_STRING@ routine, 116 PLAY_CLIPBOARD_METAFILE@ routine, 387
INTERNET_HYPERLINK, standard call-back, 210 PLAY_SOUND@ routine, 387
Italic fonts, 97 PLAY_SOUND_RESOURCE@ routine, 388
ITALIC_FONT@ routine, 375 Popup menus, 84
PRINT_ABORT, standard call-back, 210
PRINT_DIB@ routine, 388
L PRINT_GRAPHICS_PAGE@ routine, 389
Line selection, 144 PRINT_OPENGL_IMAGE@ routine, 389
List box, 62 PRINTER_OPEN, standard call-back, 210
LOBYTE@ routine, 375 PRINTER_OPEN1, standard call-back, 210
LOWORD@ routine, 376 PRINTER_SELECT, standard call-back, 210
Property sheet, 129
Property sheet close, 130
M PUT_DIB_BLOCK@ routine, 391
MAKE_BITMAP@ routine, 376
MAKE_ICON@ routine, 377
MAP_FILE_FOR_READ_WRITE@, 378 R
MAP_FILE_FOR_READING@, 378 READ_URL@ routine, 204
Maximise, 424 RECORD_SOUND@ routine, 391
MDI frames, 123, 424 Recording events, 313
Menus, 81, 424 RELEASE_BITMAP_DC@ routine, 392
METAFILE_TO_CLIPBOARD@ routine, 379 RELEASE_SCREEN_DIB@ routine, 392
Minimise, 424 REMOVE_ACCELERATOR@ routine, 392
Minimise icon, 78 REMOVE_CURSOR_MONITOR@ routine, 393
MOVE_WINDOW@ routine, 379 REMOVE_FOCUS_MONITOR@ routine, 393
MOVIE_PLAYING@ routine, 380 REMOVE_GRAPHICS_ICON@ routine, 393
Multiple selection boxes, 64 REMOVE_KEYBOARD_MONITOR@ routine, 394
REMOVE_MENU_ITEM@ routine, 394

Index-5
ClearWin+ User’s Guide Fortran

REPLY_TO_TEXT_MESSAGE @ routine, 394 SIZE_IN_POINTS@ routine, 410

RESIZE_WINDOW@ routine, 394 SIZEOF_CLIPBOARD_TEXT@ routine, 410
Resource Compiler, using SRC, 296 Slider controls, 44
Resources, 425 SLINK commands, 295
RGB colours, 425 SOUND, standard call-back, 211
RGB@ routine, 395 SOUND_PLAYING@ routine, 411
Right justify, 90 SOUND_RECORDING@ routine, 411
ROTATE_FONT@ routine, 395 SOUND_SAMPLE_RATE@ routine, 411
Routines SRC Resource Compiler, 296
Graphics, 429 Standard call-backs
Graphics plotter/screen, 431 +, 212
Graphics printer, 432 EDIT_FILE_SAVE_AS, 207
Mouse, 432 ABOUT, 206
Rubber-banding, 143 BEEP, 206
CASCADE, 206
CONFIRM_EXIT, 206
S CONTINUE, 207
Save settings, 48
COPY, CUT, PASTE, 206
SCALE_FONT@ routine, 395
DEC, 208
Screen resolution, 425
Screen saver, 132, 425 EDIT_FILE, 207
Scroll bar, 425 EDIT_FILE_OPEN, 207
SCROLL_EDIT_BUFFER@ routine, 115 EDIT_FILE_SAVE, 207
SCROLL_GRAPHICS@ routine, 396 EXIT, 208
SEE_PROPERTYSHEET_PAGE @ routine, 396 FATAL, 208
SEE_TREEVIEW_SELECTION@ routine, 397 FILE_OPENR, 208
SELECT_ALL, standard call-back, 211 FILE_OPENW, 209
SELECT_FONT@ routine, 397 GPRINTER_OPEN, 209
SELECT_FONT_ID@ routine, 398 HELP_CONTENTS, 209
SELECT_GRAPHICS_OBJECT@ routine, 398 HELP_ON_HELP, 209
SELECT_PRINTER@ routine, 398 INC, 209
SEND_TEXT_MESSAGE @ routine, 399
INTERNET_HYPERLINK, 210
SET, standard call-back, 211
PRINT_ABORT, 210
SET_ CURSOR_WAITING@ routine, 403
SET_ALL_MAX_LINES@ routine, 400 PRINTER_OPEN, 210
SET_CD_POSITION@ routine, 400 PRINTER_OPEN1, 210
SET_CLEARWIN_FLOAT@ routine, 400 PRINTER_SELECT, 210
SET_CLEARWIN_INFO@ routine, 401 SELECT_ALL, 211
SET_CLEARWIN_STRING@ routine, 401 SET, 211
SET_CLEARWIN_STYLE@ routine, 402 SOUND, 211
SET_DEFAULT_FONT@ routine, 403 STOP, 211
SET_DEFAULT_TO_FIXED_FONT@ routine, 404 SUPER_MAXIMISE, 211
SET_DEFAULT_TO_PROPORTIONAL_FONT@ routine, TEXT, 212
404 TEXT_HISTORY, 212
SET_DEFAULT_WINDOW@ routine, 404 TOGGLE, 212
SET_GRAPHICS_SELECTION@ routine, 404 Standard character string, 425
SET_LINE_STYLE@ routine, 406 Standard icons, 78
SET_LINE_WIDTH@ routine, 406 START_CLEARWIN_PLAYBACK@ routine, 314
SET_MAX_LINES@ routine, 407 START_CLEARWIN_RECORDER@ routine, 313
SET_MOUSE_CURSOR_POSITION@ routine, 407 START_PROCESS@ routine, 412
SET_OLD_RESIZE_MECHANISM@ routine, 407 Startup call-back, 123
SET_OPEN_DIALOG_PATH@ routine, 408 Status bar, 426
SET_PRINTER_ORIENTATION@ routine, 408 STDCALL statement, 306
SET_RGB_COLOURS_DEFAULT@ routine, 408 Sterling pound symbol, 100
SET_SOUND_SAMPLE_RATE@ routine, 409 STOP Fortran statement, 309
Shortcut keys, 425 STOP, standard call-back, 211
SHOW_MOVIE@ routine, 409 STOP_AUDIO_CD@ routine, 412
SIZE_IN_PIXELS@ routine, 410 STOP_CLEARWIN_RECORDING@ routine, 313

Index-6
Index

Subscript font, 98
SUPER_MAXIMISE, standard call-back, 211
W
Superscript font, 98 Wallpaper, 131
System font, 98 WAV_FILE_READ@ routine, 415
System menu, 86 WAV_FILE_WRITE@ routine, 415
SYSTEM_FIXED_FONT, 301 Web links, 204
WIN_COUA@ routine, 416
WIN_GETCHAR@ routine, 416
T WIN_GETLINE@ routine, 416
Tabs, 90 Win16, 426
TEMPORARY_YIELD@ routine, 412 Win32, 426
Text array, 103 Window control types, 126
Text colour, 99 Window position, 126
Text size, 99 Window size, 126
TEXT, standard call-back, 212 WINDOW_UPDATE@, 27
TEXT_HISTORY, standard call-back, 212 Windows 95
Thumb, 426 Graphics region updates, 150
TOGGLE, standard call-back, 212 Scalable font, 98
Toolbar, 426 WINDOWS_95_FUNCTIONALITY, 98
Tree view selection box, 68 Windows API, 426
Windows application, 426
WINDOWS compiler option, 293
U Windows control, 426
Underline font, 97 Windows message, 427
UNDERLINE_FONT@ routine, 413 WINDOWS.INS, 294
UNDO_EDIT_CHANGE@ routine, 115 WINDOWS_95_FUNCTIONALITY @ routine, 416
UNMAP_FILE@ routine, 413 WINIO@ routine, 22
UPDATE_WINDOW@ routine, 413 WKEY_WAITING@ routine, 417
USE_APPROXIMATE_COLOURS@ routine, 414 WM_PAINT message, 427
USE_RESOURCE_LIBRARY@ routine, 294 WRITE_GRAPHICS_TO_BMP@ routine, 417
USE_RGB_COLOURS@ routine, 414 WRITE_GRAPHICS_TO_PCX@ routine, 417
USE_URL@ routine, 204 WRITE_WAV_FILE@ routine, 418
USE_WINDOWS95_FONT@ routine, 414
User defined child window, 131
Y
YIELD_PROGRAM_CONTROL@ routine, 418
V
Variable string, 100
Vertical scroll bar, 62

Index-7
ClearWin+ User’s Guide Fortran

Index-8

Fortran 95 2003 For Scientists and Engineers
100% (3)
Fortran 95 2003 For Scientists and Engineers
988 pages
Fortran 77 Programmers Guide
100% (3)
Fortran 77 Programmers Guide
168 pages
FLUENT 6.3.26 User's Guide
100% (1)
FLUENT 6.3.26 User's Guide
2,501 pages
Fortran For Scientists and Engineers (4th Edition) PDF
No ratings yet
Fortran For Scientists and Engineers (4th Edition) PDF
10 pages
An Introduction To Programming in Fortran 90
No ratings yet
An Introduction To Programming in Fortran 90
63 pages
Fortran For Scientists and Engineers 4th Edition Stephen J. Chapman - Ebook PDF Download
100% (1)
Fortran For Scientists and Engineers 4th Edition Stephen J. Chapman - Ebook PDF Download
53 pages
Fortran 90
No ratings yet
Fortran 90
61 pages
J2ul 2472 02enz0
No ratings yet
J2ul 2472 02enz0
515 pages
An Introduction To Programming in Fortran 90: Guide 138
No ratings yet
An Introduction To Programming in Fortran 90: Guide 138
61 pages
Build Simple Fortran Program
No ratings yet
Build Simple Fortran Program
8 pages
Chapman SJ - Fortran 90-95 For Scientists and Engineers
100% (7)
Chapman SJ - Fortran 90-95 For Scientists and Engineers
891 pages
Fortran 77: Introduction To f77
No ratings yet
Fortran 77: Introduction To f77
14 pages
Brief Introduction To The Fortran 90 Programming Language
No ratings yet
Brief Introduction To The Fortran 90 Programming Language
33 pages
Pat Ran 2004
No ratings yet
Pat Ran 2004
26 pages
02 Fortran 1x2
No ratings yet
02 Fortran 1x2
20 pages
Salford Software Fortran 95 Example Programs
No ratings yet
Salford Software Fortran 95 Example Programs
5 pages
Fortran 6 Guide for Aerospace Students
No ratings yet
Fortran 6 Guide for Aerospace Students
7 pages
Paper 08 Modules
No ratings yet
Paper 08 Modules
57 pages
Writing Fast Fortran Routines For Python: © 2012 M. Scott Shell Last Modified 4/10/2012
No ratings yet
Writing Fast Fortran Routines For Python: © 2012 M. Scott Shell Last Modified 4/10/2012
24 pages
Introduction To Programming With Fortran 90: Advanced I/O and Files
No ratings yet
Introduction To Programming With Fortran 90: Advanced I/O and Files
27 pages
Fortran 90/95 Programming Guide
100% (1)
Fortran 90/95 Programming Guide
50 pages
Advanced Fortran Programming DURHAM UNIVERSITY
100% (1)
Advanced Fortran Programming DURHAM UNIVERSITY
31 pages
Fortran 77 Tutorial
0% (1)
Fortran 77 Tutorial
20 pages
Fortran Basics for Geophysics Students
No ratings yet
Fortran Basics for Geophysics Students
25 pages
COM 221 Practical Manual 2025
No ratings yet
COM 221 Practical Manual 2025
26 pages
LONI Fortran AdvConc F90 2012
No ratings yet
LONI Fortran AdvConc F90 2012
107 pages
Tasking 80196 Utilsguide
No ratings yet
Tasking 80196 Utilsguide
319 pages
Code::Blocks IDE for Fortran Development
No ratings yet
Code::Blocks IDE for Fortran Development
20 pages
Course For Dec2013
No ratings yet
Course For Dec2013
266 pages
Introduction To Modern Fortran: Nmm1@cam - Ac.uk
No ratings yet
Introduction To Modern Fortran: Nmm1@cam - Ac.uk
28 pages
Lecture 01
No ratings yet
Lecture 01
43 pages
Fortran 3days
No ratings yet
Fortran 3days
308 pages
Programming With Lcc-Win32
No ratings yet
Programming With Lcc-Win32
338 pages
Fortran Basics for Physics Students
No ratings yet
Fortran Basics for Physics Students
18 pages
Computing With Fortran by Haselbacher PDF
No ratings yet
Computing With Fortran by Haselbacher PDF
202 pages
A Portable Fortran 77 Compiler
No ratings yet
A Portable Fortran 77 Compiler
18 pages
Photran: 4.1 Introduction To Using Photran
No ratings yet
Photran: 4.1 Introduction To Using Photran
12 pages
Compaq Visual Fortran
No ratings yet
Compaq Visual Fortran
1,441 pages
Fortran Tutorials2
No ratings yet
Fortran Tutorials2
231 pages
Course For Dec2013
No ratings yet
Course For Dec2013
263 pages
Bigtable Schema Design Best Practices
No ratings yet
Bigtable Schema Design Best Practices
14 pages
Digital India Initiatives Overview
No ratings yet
Digital India Initiatives Overview
17 pages
Microsoft Office 2007 Document Editing Guide
No ratings yet
Microsoft Office 2007 Document Editing Guide
30 pages
SIH 2025 No Change Ppt-2
No ratings yet
SIH 2025 No Change Ppt-2
6 pages
Data Types & Programming Techniques
No ratings yet
Data Types & Programming Techniques
11 pages
SmartEd Autocad PDF
No ratings yet
SmartEd Autocad PDF
13 pages
How To Create Stored Procedures
No ratings yet
How To Create Stored Procedures
29 pages
Generative AI Leader (ILT) - Course Opening and Module1 - Gen AI - Beyond The Chatbot
No ratings yet
Generative AI Leader (ILT) - Course Opening and Module1 - Gen AI - Beyond The Chatbot
149 pages
Education & NGO Leadership Resume
No ratings yet
Education & NGO Leadership Resume
3 pages
Intelligent Continuous Improvement When BPM Meets AI
No ratings yet
Intelligent Continuous Improvement When BPM Meets AI
52 pages
Computing Section 4 LV
No ratings yet
Computing Section 4 LV
91 pages
PS Cyber Security
No ratings yet
PS Cyber Security
3 pages
Simulaciones Flsmith
No ratings yet
Simulaciones Flsmith
226 pages
FocusedBuild ConfigGuide 900
No ratings yet
FocusedBuild ConfigGuide 900
402 pages
M.Sc. in Data Science with upGrad & IU
No ratings yet
M.Sc. in Data Science with upGrad & IU
37 pages
IT Solutions for Global Enterprises
No ratings yet
IT Solutions for Global Enterprises
15 pages
Mastercam Configuration Guide
No ratings yet
Mastercam Configuration Guide
3 pages
HCAI Module4 Answers
No ratings yet
HCAI Module4 Answers
2 pages
Vpngate Vpn193359300.opengw - Net Udp 1653
No ratings yet
Vpngate Vpn193359300.opengw - Net Udp 1653
4 pages
Batch Download Guide and FAQs
No ratings yet
Batch Download Guide and FAQs
19 pages
Dtu Logo
No ratings yet
Dtu Logo
30 pages
NCTU PPT 2024-2025 - WEEK2-Linux Directories
No ratings yet
NCTU PPT 2024-2025 - WEEK2-Linux Directories
40 pages
Radioline PLC Mode - EtherNet IP EDS File - 21-2-1
No ratings yet
Radioline PLC Mode - EtherNet IP EDS File - 21-2-1
22 pages
User Manual Hazcalc: Version: Final 1.0
No ratings yet
User Manual Hazcalc: Version: Final 1.0
10 pages
Shubham CPP
No ratings yet
Shubham CPP
33 pages
Microsoft Powerpoint MCQ Questions With Answers Set-4
No ratings yet
Microsoft Powerpoint MCQ Questions With Answers Set-4
5 pages
Murat CV
No ratings yet
Murat CV
2 pages
Prerequisites Developer
No ratings yet
Prerequisites Developer
7 pages
Prepaid Card Service: Benefits ... For The Operator
No ratings yet
Prepaid Card Service: Benefits ... For The Operator
5 pages
CDSS User Manual
No ratings yet
CDSS User Manual
79 pages

Clear Win

Uploaded by

Clear Win

Uploaded by

&OHDU:LQ

2. Getting started ........................................................................................................ 5

4. Format windows ................................................................................................... 19

5. Input and output ................................................................................................... 37

7. Controls other than buttons................................................................................. 61

8. Bitmaps, Cursors, Icons....................................................................................... 75

9. Menus and accelerator keys................................................................................. 81

10. Layout and positioning ........................................................................................ 89

11. Displaying text ...................................................................................................... 97

12. Edit box (%eb)..................................................................................................... 107

13. Help...................................................................................................................... 119

14. Window attributes............................................................................................... 121

15. Graphics .............................................................................................................. 135

16. OpenGL ............................................................................................................... 161

17. SIMPLEPLOT....................................................................................................... 181

18. Using the printer ................................................................................................. 189

19. Hypertext windows ............................................................................................. 199

20. Standard call-back functions ............................................................................. 205

21. Format code reference ....................................................................................... 215

22. Compiling and linking ........................................................................................ 293

23. ClearWin windows .............................................................................................. 299

24. Using the Windows API...................................................................................... 305

The Fortran STOP and PAUSE statements.......................................................................................................................... 309

25. Programming tips ............................................................................................... 311

26. Library overview ................................................................................................. 315

27. Library reference................................................................................................. 329

28. Glossary .............................................................................................................. 421

Appendix A. Functions ported from DBOS..................................................................... 429

© Salford Software Ltd 2000

FTN77 is a registered trademark of Salford Software Ltd.

The ClearWin+ library

How to use this guide

Using FTN77 and FTN95

& P]b,fX]X^/RPJ=d\QTa 5PRc^aXbTaL

" ?A>6A0< UPRc^a!

0 or negative Closes the format window.

This is what the final program displays on the screen:

In summary return values can be:

R fU SXb_[Ph P U[^PcX]V _^X]c eP[dT 

%wd Integer output.

Advanced use of format windows

U\c,8]eP[XS eP[dT fS

Format codes grouped by function

8) Help: %bh, %he, %ht

Alphabetical index of format codes

%ac Accelerator key format. 88

%we Floating point output in exponent form. 46

Input and output

Integer input - %nrd

Floating point input - %nrf

Character string input format - %nrs

Control option format - %co[option-list]

RWTRZN^]NU^RdbN[^bb Perform checks and call-back (and update the

Integer increase/decrease format - %dd

Floating point increase/decrease format - %df

Floating point limit format - %fl

Integer limit format - %il

Parameter box - %N.Mpb[options]

8=C464A 5D=2C8>= PRcX^]

Slider format - %nsl[options]

format output for i=123 comment

format output for x=1.26 comment

format string output

(1) minimum field width,

Save settings to .INI file - %ss[filename/section]

Button format - %nbt[button_text]

Button colour - %bc[colour]

Button icon - %bi[icon_name]

Textual toolbar - %tt[button_text]

Radio button - %rb[button_text]

Bitmap button and toolbar - %n.mtb

>55 18C<0? 1C 1<?

Image button and image bar - %n.mib

Tool bar border - %bx

Gang format - %Nga

Controls other than buttons

&OHDU:LQ

& P]b,fX]X^/RPJ=d\QTa 5PRc^aXbTaL

R fU SXb_[Ph P U[^PcX]V _^X]c eP[dT

U\c,8]eP[XS eP[dT fS

8=C464A 5D=2C8>= PRcX^]

>55 18C<0? 1C 1<?

270A02C4A"% 5D=2C8>= 2^[^da]P\TaVQ

8=C464A 5D=2C8>= RP[[NQPRZ

20;; PSSN\T]dNXcT\/WP]S[T4gXc RQ

85\^ST4@" a,e e!

X,fX]X^/][ 1^g RQ

8=C464A 5D=2C8>= SXb_N]P\T