** 2 page regular HiSoft BASIC tutorial 2 / 1500 words **

Can't program or won't program? We gave away HiSoft BASIC on the Reader Disk last issue so there's no excuse, Paul Jones continues his HBASIC tutorial...

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 turn PDO from an idea into reality.

PDO will feature specialised 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. Our building blocks are alert boxes to report errors and other messages, dialogs to offer the user multiple selections and drop down menus to access the main program functions.
The data for these is typically stored in a resource (RSC) file and can be 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 the HiSoft product designed for use with HBASIC. If you use a alternative 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 via the 'Run other' option in the Program menu, if you've got enough memory. Alternatively you can quit HBASIC and run the resource editor separately. Make sure WERCS and its resource file are in the same directory as HBASIC.PRG.

HBASIC v2 owners have the luxury of a Tool menu where links to up to nine programs can be set.

** TOOLS.GIF here **

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

** TOOLCONF.GIF here **

Set the dialog to look like mine, 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.

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. Click and hold the mouse down on the bottom right hand corner to adjust the dialog to any desired size bearing in mind we'll need plenty of space to add copyright messages and general information. To add 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 something like 'PDO tutorial by Paul Jones for Atari Computing' no name is required so select OK and the text STRING displays your text. 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 position the strings centrally in the dialog - being careful to size the dialog so it can be displayed in ST medium resolution (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. You've just created your first dialog box!

The names in the dialog are used to access the object through HBASIC. Texts can display whatever we want via a GEM command. This is useful for text like the version number and we can write a routine in PDO to change the 0.00 to anything we like, 1.07 for example. If we didn't do this, and used a text string we would have to manually edit the resource file to change the version number. Finally select the window closer gadget to close the dialog box - note the dialog box we just created has been allocated an icon.

Menu making

To create a menu for the program select Menu from the Tree 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...' - be careful to leave two space characters at the start of the string and name the string ABOUT. Now select Title from the Object menu. 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. Repeat this three more times. Double-click on the first string and edit it to 'View file' with the name VIEW, similarly edit the second string to 'Print file' with the name PRIN and finally edit the third string to '----------' (a row of dashes), with no name. Click once on this string and select Disabled in the Flags menu. Double-click on the Quit string provided and edit the name to QUIT.

Click once on TITLE - the new title we just created, and change the name to Options. This time 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, save the RSC file in the same directory as your BASIC files using the Save option in the WERCS File menu.

That's it for another issue. Next time I'll explain how to use the resource file we've created from the program. 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 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 initial PDO source code on the Reader Disk - we'll cover 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