** HiSoft BASIC tutorial 2 / 1700 words **

Can't program or won't program? With a free copy of the commercial HiSoft 
BASIC on Reader Disk there's no excuse, Paul Jones shows you how with the 
second part of his HBASIC tutorial...

** Title: Mission: Project PDO
We're starting a project called PDO, an acronym for Print Documents Out 
and guess what? It's going to print out ASCII documents...

Why? Because I've yet to see a simple program which specialises in 
printing ASCII files - the TOS Print function has no options at all and 
even text editors only offer a few options. As a programmer you're not 
restricted by what's on offer so we're going to create PDO, turning an 
idea into reality.

PDO is going to feature specialised powerful options wrapped up in an easy 
to use interface. Start thinking about any problems you have printing and 
write to me at the usual address - the future of PDO is in your hands!

Before getting started it's useful to have some idea how the 
user-interface or 'front end' will work. I'm assuming you're all at least 
aware of alert boxes, dialogs and menus. These are the building blocks 
used to interact with programs. Alert boxes are often used to report 
errors, dialog boxes usually offer multiple selections and menus are used 
to access the main program functions.
The data for all these elements is typically stored in a resource (RSC) 
file and these are easily created using a resource editor. There are 
several to choose from including shareware programs such as ORCS or the 
new RSM and commercial software such as WERCS and Interface. In this 
tutorial, I'll use WERCS because it's another HiSoft product specially 
designed for use with HBASIC. If you use a different resource editor 
you'll need an additional header editor which is supplied in the HBASIC 
bundle. Interface is a powerful, easy to use, alternative and a worthwhile 
investment if you can find anyone willing to part with a copy - Interface 
currently has no UK distributor.

You can launch a resource editor from HBASIC v1, if you've got enough 
memory. 1Mb users should be fine with WERCS, but 512Kb users might have to 
quit HBASIC is run the editor. Firstly, make sure that WERCS and its *.RSC 
are in the same directory as HBASIC.PRG. Under the 'Program' menu in 
HBASIC v1, you'll find a item called 'Run other'. Select this, followed by 
the resource editor then finally 'OK'. The editor should now run.

HBASIC v2 owners have it even easier. If you go to the 'Tool' menu, 
there's a list of items ranging from 'Tool 1' to 'Tool 9'. These are 
reserved to set links to several programs:

** TOOLS.GIF here **

To set a new tool area, find a blank one, press [Control] and click with 
the mouse pointer onto the position. This will bring up something like 
this dialog (which I have filled in as an example):

** TOOLCONF.GIF here **

Set the dialog with the same options, with the exception of the path to 
the editor which you should change to point at the location of your 
editor. Select 'OK' and save the options. Now you can run any defined tool 
by selecting its entry from the Tool menu.

** Title: R.S.C what?
Starting with a blank RSC file go to the 'Tree' menu and click on 'Form':

** TREEMENU.GIF here **

WERCS then asks for the name of the tree. The first dialog box we're going 
to create is an information box, enter:

** TREEDIAL.GIF here **

Select 'Edit'. An empty box in a window appears on screen. This determines 
the size of the dialog box. You will want plenty of space for copyright 
messages, and general information. Click and hold the mouse down on the 
bottom right hand corner to adjust the dialog to any desired size. A blank 
dialog doesn't say anything - we need to add some text. Go to the 
'Objects' menu and select 'String'. The mouse pointer changes to indicate 
the selected option. Move the pointer into the empty dialog window and 
left click to place the STRING and the mouse pointer returns to its 
original shape. Now double-click on 'STRING' to edit the text. Type in 
'PDO tutorial by Paul Jones for Atari Computing' no name is required so 
select 'OK' and the text 'STRING' will update to display the text you just 
entered. Create another string, this time edit the text to: 'magazine. 
Copyright Paul Jones 1997', again no name is required. The strings can be 
moved around using a Drag&Drop action so the strings are positioned 
centrally in the dialog - be careful to size the dialog so it can be 
displayed on an ST medium resolution screen (640x200) pixels.

Create another string 'Version: V' followed by a 'TEXT' object. Position 
this just to the right of the 'Version: V' string and double-click on it. 
The text field should read '0.00' with the name 'ver'. Click once on this 
object and, from the 'Fill' menu, select 'Opaque' text and '0' fill 
colour. Add another string 'SHAREWARE - PLEASE SEE DOCS FOR DETAILS'. Now 
select 'Button', to create a button, and edit the text to 'OK' and the 
name to 'OKBUT1'. Go to the 'Flags' menu and make sure the menu looks 
like:

** OBJECTS.GIF here **
Move the objects around until your dialog looks something like this:

** EXAMPLED.GIF here **

It doesn't matter if it's not exactly the same, so long as the version 
number and button are present, so feel free to experiment.
Finally click anywhere on the dialog box and select '0' for the colour in 
the 'Fill' menu and 'Background' in the 'Flags' menu. Well done - you've 
created your first dialog box!

The names in the dialog are so we can access the object through HBASIC. 
Texts can display whatever we want by a GEM command. This is useful for 
the version number, since we can write a routine in PDO to change the 
'0.00' to, say, '1.07'. If we didn't do this, and made the text into a 
string, everytime we changed the version number, we would have to edit the 
resource file and change the string.

Next we're going to create a menu for the program. Select the window 
closer gadget to close the dialog box - note the dialog box we just 
created has been allocated an icon. Go to the 'Tree' menu and select 
'Menu'. Set the name to 'Menu', and select 'edit'. You should see 
something like this on the screen:

** EXAMPLEM.GIF here **

Double-click on 'Your message here' and edit the text to '  About PDO...' 
with the name 'ABOUT' making sure there's a double space before the text. 
Go to the 'Object' menu and select 'Title'. Move the mouse pointer next to 
the 'File' title and press the left button. Click once on the 'File' menu. 
Select 'string' from the 'Objects' menu, and click just above the 'Quit' 
item in our new menu. Do this another three times. Click twice on the 
first string. This is to contain 'View file' with the name 'VIEW', the 
second with 'Print file' with the name 'PRIN' (edited the same as the 
first). The third should be '----------' (a row of dashes), with no name. 
Click once on this string, go to the 'Flags' menu and select 'Disabled'. 
Double click on the 'Quit' string already there. Edit the name to 'QUIT'.

Click once on 'TITLE', the new title we just created. Change the name to 
'Options'. We need five strings, add these as before and edit them as 
follows:
** bulleted list **
* Text: 'Printer options', name 'OPTS'
* Text: 'REGISTER!', name 'REG'
* Text: '---------------' no name, flag set to 'Disabled'
* Text: 'Load settings', name 'LOADS'
* Text: 'Save settings', name 'SAVES'
** end list **

Now, go to the WERCS 'File' menu and choose 'Save'. Save the RSC file in 
the same directory as your BASIC files.

Well, that's it for another issue. Next time we'll find out how to use the 
resource file we've created. Until then, experiment until you're familiar 
with your resource editor and the BASIC editor, and if you run into 
problems please do write to me!

** Boxout 1 **
Other RSC editors

Resource editors all work in a similar manner and RSC files created in one 
editor can, generally speaking, be edited in another.
The only thing is HiSoft BASIC requires is a *.BH file containing the 
locations of the objects in the file. For example, to use Interface with 
HiSoft BASIC select 'Info' from the 'File' menu:

** INTRFACE.GIF here **

Every editor should include an option to select a language. Select 'C' 
here and whenever you save your resource file Interface creates *.H file. 
Using CTOBAS.TTP (included with HBASIC) you can convert *.H files into 
*.BH files ready to include in your BASIC program - we'll cover this next 
issue.
** End boxout 1 **

** Boxout 2 **
First Contact

If you want to contact Paul for comments or advice, you can email him at 
"paulat.jones@zetnet.co.uk". He also has a website at 
"http://www.users.zetnet.co.uk/pjones/home.htm".
** End boxout 2 **

** Boxout 3 **
** On Reader Disk logo here **
RSC problems?

If you can't create a RSC file for any reason you'll find copies of 
PDO.RSC, PDO.BH, PDO.HRD and the source code to the start of PDO on the 
Reader Disk - we'll be going over this in detail next issue!
** End Boxout 3 **

** Image preferences **
** If any image have to cut/dropped, take note of this list
** List goes from most needed to least needed:
** 1   EXAMPLED.GIF - PDO Infobox
** 2   PDOMENU.GIF  - Menu of PDO
** 3   INTRFACE.GIF - Pic of language and format in Interface 2
** 4   TOOLCONF.GIF - Tool config dialog in HBASIC v2
** 5   TOOLS.GIF    - Menu of tools example
** 6   OBJECTS.GIF  - Menu of flags in WERCS
** 7   EXAMPLEM.GIF - Menu (before editing)
** 8   TREEDIAL.GIF - Input name of object
** 9   TREEMENU.GIF - Menu of tree