** 1 page feature / 866 words **
** On Reader Disk logo here **

ENCHANT and GEM

** ENCHANT.GIF here **

A match made in heaven? Paul Jones and Matthew Bacon think so...

This article follows the development of EncrypSTer, an encryption program, and explains how it makes use of the ENCHANT GEM Toolkit and Modules. EncrypSTer, its source code, and accompanying files are all included on the Reader Disk.

If you have been following the Basic BASIC series, you'll be aware of the steps needed to create an application and should appreciate how time consuming it can be.

ENCHANT (EnhaNCed Hisoft ApplicatioN toolkiT) is a collection of routines and libraries which enables programmers to concentrate on developing application features without worrying about the peculiarities of GEM (see review in AC#15 p30).

The starting point when developing any application using ENCHANT is its shell listings and resource file. These provide the foundation for your application and include vital data required by the GEM Toolkit routines.

For the purposes of this article we'll assume the resource file and BH constants file have already been created and are already available to ENCHANT. Before you can start writing the source code for the features of your application, you must first customise the shell listing:

** UL **
* The resource files BH CONST file must be included (requirement of HBASIC not ENCHANT).
* MyProgram$ should contain the name of your application, in this case   "EncrypSTer". It is used by ENCHANT within a multitasking environment   and when displaying error messages.
* HowManyButtons (optional) is another global variable of ENCHANT. The   value 2 indicates that both the mouse buttons are available to ENCHANT   (Left for object selection and Right for BubbleGEM help).
* The parameters of StartProgram should contain the following:
  + Path of your resource file.
  + Resource file index to be used as the menu bar.
  + Resource file index to be used as the quit item within the menu bar.
  + Resource file index of the object to be displayed when a window is   iconised.
** /UL **

At present, the shell listing does nothing more than load the resource file. For your application to respond to user input, the following subroutines should be customised (or ignored if not required). EncrypSTer uses the HandleUserMessages and HandleUserMenu subroutines:

** UL **
* HandleUserClose, is called if the global variable userclose_enabled<>0 when any window is closed.
* HandleUserMessage, is called if ENCHANT receives a pipeline message that it does not understand. This routine is, as shown later, ideally suited to provide OLGA protocol support.
* HandleUserKeys, is called if the global variable keys_enabled<>0 when a key is struck.
* HandleUserClicks, is called if the global variable clicks_enabled<>0 when a mouse button is clicked.
* HandleUserMenu, is called when a menu item is selected.
* HandleUserHook, is called if the global variable hook_enabled<>0 every n milliseconds determined by the global variable hook_timeout.
** /UL **

ENCHANT provides many powerful form handling routines. One of which allows dialogs to be displayed as non-modal dialogs using the OpenFormWindow function. OpenFormWindow takes several parameters as follows:

** NP **
 handle=OpenFormWindow(WindowName$,treeno,edit_obj,cancel_obj,closeproc&)
** /NP **

** UL **
* WindowName$ parameter should contain the title window string.
* treeno should contain the resource file index of the object to be displayed in the window.
* edit_obj should contain the text object (must be editable) to be edited when the objectformwindow is opened or zero.
* cancel_obj should contain the object that will be returned if the window close box (top left-hand corner of window) or zero.
* closeproc& should contain the address of a sub-routine which will be called when the window is closed or an exit button (or its shortcut) is selected by the user or zero.
** /UL **

Whenever the menu item Information is selected, ENCHANT will now display the non-modal dialog FORM_INFO. Whenever this form window is exited, the subroutine closeFORM_INFO will be called. As this routine is not yet defined, it should be written by the user  - it should look similar to the closeFORM_INFO code.

To give your application the professional edge they deserve, ENCHANT provides modules to enable your programs to include BubbleGEM, OLGA and ST-Guide support and it couldn't be easier. Simply include the following lines of text at the start of your source code and that's it!

** NP **
REM include BUBBLE.BAS
REM include OLGA.BAS
REM include STGUIDE.BAS
** /NP **

ENCHANT details all the calls available. The only calls we are concerned with for EncrypSTer are:

** NP **
BubbleGEM("Bubble Message")
STGuide(path of STG file, name of node in STG file)
** /NP **

The final steps are to fully test your application on as many TOS compatible machines and across a wide selection of environments (TOS, MagiC, MiNT etc.) and create a suitable ST-Guide hypertext.

Hopefully, this glimpse of ENCHANT in action has demonstrated how HBASIC developers can save many hours work using ENCHANT. If you have any questions or would like more information please do get in touch.

** boxout **
ENCHANT revision 2

Publisher:
Cadenza Software; 49 Douglas Road, Surbiton, Surrey, KT6 7RZ, UK
Email: cadenza@cyberstrider.org
http://www.cadenza.cyberstrider.org

Price:
œ15.00 plus P&P (œ3 UK, œ5 ROW). Alternatively ENCHANT can be purchased with a brand new copy of HiSoft BASIC v2.10 for only œ45 plus P&P (œ7 UK, œ15 ROW). UK P&P includes courier service.

Please make cheque/postal orders payable to "Matthew Bacon".
** /boxout **

** ENCRYPTR.GIF here **