How it works for !HTMLbar
-------------------------

What follows is a guide to how to make !HTMLbar and some of the thinking behind implementing it. There are probably better ways to do it than the one I chose, but for beginners what follows may be of some use (have a copy of !RunImage open at the same time so you can look at the appropriate line numbers)...

Version 1.11
------------
Create the actual bar using TemplEd, ending up with as many buttons as you want (around 46 in this case), each of which is an icon and has an icon number. Call this window "800col" (or whatever) and save the templates file as 'bars' (or whatever). To check it works load it into memory with the handle bbar% (line 190). This aim is for this buttonbar window to open when the iconbar icon is clicked. 

PROCuser_mouseclick handles this, which involves checking for a window% of -2 (line 530) which is the iconbar, and opening the bbar% window (540) if it is -2. With bbar% open, clicks on it can be checked for by seeing if window%=bbar%(550). If it does, the button that was clicked can be found using icon%, which will be whichever number the icon has in the template file i.e. 1-46

The next step is to associate each button with the text it should insert. The simplest way would be to define (in PROCuser_initialise) 46 strings of the form 

tags1$="<a>"
tags2$="<img>" 

and so on. Then if icon%=15 the string tags15$ contains the appropriate text.

The problem with doing it this way is a fair bit of typing and the text can't be changed without altering the listing of the program, which shouldn't be something the user should have to do. 

The approach that was taken was to set up a 2D text array called tags$ (400) consisting of two rows of 51 strings, where row zero of the array is the text when clicked with select and row one the text when clicked with adjust. The text will be loaded into the array from textfile (called "tags") within the !HTMLbar application directory. This is done by a new procedure called PROCloadtags (410 and 2030). It loads the tags, one string (one line in the text file) at a time, into the tags$ array.

With all the tags now in memory it is necessary to link them to a click on a button. One way to do this would be:

CASE icon% OF
 WHEN1:print contents of tags$(1,0)
 WHEN2:print contents of tags$(2,0)
 ...
 WHEN46:print contents of tags$(46,0)
ENDCASE

Unfortunately, sending text to the text editor is more than a single command, so it makes sense to create a procedure to handle this, which is called when an icon is clicked.

WHEN1:PROCbuttpress(1)
WHEN2:PROCbuttpress(2)

and so on. This can be made more economical by having PROCbuttpress called if icon% has a value (any value) i.e. an icon has been clicked on.(560-580)

IF icon%
PROCbuttpress (icon%,button%)
ENDIF

Exactly which icon has been clicked is still stored in icon% and can be handled in PROCbuttpress by sending it as one of the parameters. It is also necessary to note which mouse button (select or adjust) was pressed. Dr Wimp records this value in button%, so button% is also sent to the procedure in the form PROCbuttpress(icon%,button%). Thus the procedure itself begins:

2180 DEF PROCbuttpress(tag%,mbutt%)

The first check is on which mouse button has been pressed (2190). The result of this test gives the row of the tags$ array to use and the value of icon% (tag% in PROCbuttpress) gives the position in the row. 

With the appropriate text tag located, the rest of PROCbuttpress sends it letter by letter to whichever window has the input focus - ideally a text editor - as if it had been typed.

A check is made to see if the text tag contains an asterisk (2260). If it does the asterisk is converted to a return, before being sent to the text editor.

The addition of PROCbuttpress means the buttons will now work as intended when clicked upon. Changing the text produced by each button is now easier - load the file called tags into a text editor and change the text as desired - but this requires quitting and reloading to take effect. The less experienced user may also baulk at delving inside the application directory. A better way is to allow the text of each button to be changed individually in the program itself, with immediate effect, but with the option to save any changes. This is an obvious job for the menu button. 

The first step is to create the menu in PROCuser_initialise (370) with two options: 
1) Change tags 
2) Save tags
and use FNuser_menu to detect when menu is pressed over the buttonbar (window%=bbar%) and open up bbarmenu% in response.


The first option leads to a window where changes are made. It consists of two writable icons containing the select and adjust text for the button to be altered, as well as an OK button to confirm any changes made to the tag text.

PROCwimp_attachsubmenu is used (380) to ensure this window (called changet%) opens automatically from the buttonbar menu. This is slightly problematic as it allows no opportunity to change the text in the writable icons. Fortunately, because of the way the WIMP works, the text can be changed before the decision is made to open the window automatically.


The solution used is to check the menu button is over an icon when pressed and then use the value of icon% to find the right place in the array of tags. Note that because the value of icon% will change as soon as another icon is clicked, the current value is stored in overbutt%, for future use.

Using PROCwimp_puticontext()(850-860) in conjunction with the icon% value, the correct text can be put into icons 1 and 3 in the change% window. Dr Wimp fortunately converts seemlessly between BASIC strings and WIMP strings, which have different string terminators. Since the text is inserted the moment the menu is opened, it is impossible to open the changet% window, before the correct text has been written into the writable icons.

Checking when OK has been pressed is again handled by PROCuser_mouseclick, this time checking for window%=changet%(590) and icon%=4(610). Instead of writing text into the icon, we want the (altered) text to be copied out and saved in the correct place in the tags$() array. icon% is now 4 (OK button pressed) so icon% can no longer be used to find the correct place in the array. This is where overbutt% comes in. It is unchanged and still points to the correct position in the array. It is then a case of using FNwimp_geticontext to put the new text into the array(620-630) (Dr Wimp again converts seamlessly between WIMP and BASIC strings). The change% window and bbarmenu% menu are then closed(640-650).

All the buttons now work and their contents can now be easily changed. All that remains is to allow the user to permanently save the changes using the Save tags option on the buttonbar(menu%=bbarmenu%) and iconbar(menu%=Iconbarmenu%) menus.

Save tags is in position 2 on both menus, so item%=2 when it is chosen. PROCuser_menuselection is used to check when this has happened (1090 and 1160) and calls PROCsavetags when it does(1100 and 1170).

PROCsavetags (line 2320) is the reverse of PROCloadtags, saving the tags as a textfile called "tags" in the !HTMLbar application directory.

Version 1.20
-----------

I decided to make changing the buttonbar a bit easier, so it didn't require digging inside the application directory. The aim was to provide a new option on the iconbar menu 'Change bar', which would allow there-and-then changes in the template being used.

The first bit, adding to the menu, was achieved by altering the list in line 340. The next step was to attached a submenu (actually a window called changeb%) to this menu item. This is done in line 360.

With the buttonbar template now depending on the user's choice, some of the setting up in PROCuser_initialise had to be altered. The template to use is stored in a textfile called 'defaultbar' saved in the application directory. PROCdefbar (line 180 and 1960) loads this and reads the name of the saved template into bar$. bar$ is then used to set up the bbar% window (line 190). The other change is to load the window (changeb%) which allows the changes to take place (line 210).

The template files were generally tidied up, so all the buttonbars are now in one template file - 'bars'.

The changeb% window consists of 8 radio icons (0-7), one 'Click to change' icon (8) and one 'Save' icon (9).

Clicks on this window are monitored in lines 670-710. If any of the radio icons are clicked on the value of the icon is recorded in selected% for further use (line 690). Initially, this is set to zero in line 390 and icon 0 is selected.

If icon 8 is clicked, then PROCnewbar is called to change the bar (line 700)
If icon 9 is clicked, then PROCsavebar saves the current choice to the textfile 'defaultbar' and closes the window and menu (line 710)

PROCnewbar - lines 2420-2560 
----------------------------
Quite a simple procedure, which just assigns bar$ a string according to the value of selected% (which is just the value of the radio icon clicked). The next step is to close the existing buttonbar (line 2530) so that bbar% can be reassigned to a new template according to bar$ (line 2540). The buttonbar is then reopened (line 2550).

PROCsavebar - lines 2580-2630
-----------------------------
This procedure opens up the 'defaultbar' textfile and writes the name of the chosen template (stored in bar$) to it.