HyperBook       Run your own macros in the reduced   HBReader version, before you graduate   to the full HyperBook program    [by John Collett  <> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <>  Only by writing macros in HML (HyperBook Macro Language) can you harness the full strength of HyperBook, and tap into the virtually unlimited power of ARexx from within a HyperBook unit. Only with the full HyperBook program do you have access to the macro editor. The smaller versions called HBReader and HBBrowser do not allow it. But here is an arrangement which makes it possible to use plain ASCII texts as scripts for macros to be used in HBReader. The full HyperBook program is not required. This article and the accompanying HyperBook script called Runner.HB is intended for readers who : - Do not already have HyperBook. - Like what they have seen and heard about it so far. - Want to know a bit more about it before they decide to buy it. - Would like to explore it more deeply than the HBReader version of the program on its own normally allows. This will not and is not intended to give you a free, backdoor access to the full range of HyperBook facilities. What it will do is allow you to write and run some HyperBook macros of your own, which is not normally possible from HBReader. It will provide you with nothing like the power, range, and convenience of HyperBook itself, so do not even begin to think that this little exploratory device will save you the expense of buying the real thing. In any case, if you haven't got HyperBook, you haven't got its User Manual. In that case you won't know the syntax of the 137 commands of the HyperBook Macro Language. So you won't be able to write macros anyway, because you won't know how to. The Manual is part of what you pay for when you buy it. I'll be giving just a few small and tempting samples here for you to copy and explore. I hope they'll be enough to interest you, to give you a good idea of what can be done, and to encourage you to buy your copy of HyperBook. I have no vested interest in GoldDisk, HyperBook, or its authors' retirement fund.  Running Runner.HB  Doubleclick on the Runner.HB gadget (it requires HBReader to be in the same directory). On Runner.HB's first and only screen you will see a 'Run' gadget in the top left corner. Click on it. You will be presented with a file requester. Choose the file you wish to run as a macro, for example, one of the samples provided below. Assuming that you choose the correct type of file (plain ASCII text), that it is in the current directory, and that its syntax is correct, it will behave as if it were an orthodox macro created in HyperBook's built-in macro editor to which you do not have access from HBReader. All sorts of problems are avoided if the file holding the script is in the same directory as HBReader and Runner.HB. I tried getting round those problems and did eventually manage it, but the solution hardly justified the quantity of code it required, and so I removed it.  How it works  The 'Run' gadget activates an already-existing internally-held macro called 'readsource' which you cannot read or edit from HBReader. This macro presents the file requester, opens the file you choose (from the current directory only, remember), and uses the magic ARexx instruction 'interpret' to execute the script as if it were normal ARexx program code or regular HyperBook macro code. Use the 'Quit' option from the menu when needed. ---------------------------------------------------------------------- Possible alternative approaches I have done a fair amount of exploring before coming up with this final arrangement, and a few compromises have been made. 1 Instead of a visible 'Run' gadget, the 'readsource' macro could have been called, say, 'F1_readsource', and it could then have been called by pressing Right Amiga and the F1 key. I have two things against this : (a) I like visible gadgets on the screen. They save me having to remember which combinations of keys to press. (b) I may be wrong, but I don't think the 'Fn_' prefix works as a way of calling a HyperBook macro if you already have AutoCLI running, which I always do. 2 One well-concealed paragraph in the manual says that macro scripts can be held in the 'rexx:' directory instead of internally in a HyperBook unit. I explored this alternative method of supplying macros for HBReader and it looked promising. Try it if you like. It did have one or two advantages over the method I finally adopted, but ... ----------------------------------------------------------------------  A few tempting samples  Each of these short scripts can be lifted out of this text and stored separately, ready for use by Runner.HB. Call each one whatever you like, but they must be stored in the same directory as HBReader and Runner.HB (sorry to keep on about that point). Explore the effects of changing details within the script. /* Macro sample 1 Creating a note containing text */ a = "This macro will create a 'Note' containing" b = "this text. Its 'Action' (what it does when" c = "you click on it) will be to delete itself." text = a || '0a'x || b || '0a'x || c note = CreateNote() ; call InsertText(note,text,0) call ScaleToSize(note,370,32) ; call SetPosition(note,50,40) action = SetActionRexx(note,'call HML_Delete(initiator())') newpos = Relocate(note,':') /* End of sample 1 */ Some of the things you can change or add are The text in the note The size and position of the note The note's background colour, e.g. colour = SetBackGround(note,3) Border colour, e.g. border = SetBorder(note,2) Shadow colour, e.g. shadow = SetShadow(note,1) Shadow style(embossed or dropshadow), e.g. s = ShadowStyle(note,2) What cannot be changed without the full editing facilities Text colour (unless you change the RGB setting of the colour of the text; that could be done!) Text style (italics, bold, etc.) and font Text spacing (between letters and rows) Exact vertical and horizontal location of text within the box ----------------- /* Macro sample 2 A note with user-supplied text */ a = "Enter text to appear in the note" text = InputString(a,'') note = CreateNote() ; call InsertText(note,text,0) call ScaleToSize(note,length(text)*8 + 24,16) call SetPosition(note,50,40) action = SetActionRexx(note,'call HML_Delete(initiator())') colour = SetBackGround(note,2) ; border = SetBorder(note,3) shadow = SetShadow(note,1) ; style = ShadowStyle(note,2) newpos = Relocate(note,':') /* End of sample 2 */ Sample 2 includes some of the extras mentioned above. When the InputString requester appears for you to insert your text, check that the mouse pointer is over the empty text bar before you begin typing. I was surprised to find that the authors of HyperBook had not made such a check unnecessary. Since the note box is set to be only 12 pixels deep, be sensible about the length of the text you enter. If you make it longer than the width of the box allows, it will be wrapped automatically, and it will need a deeper box. ----------------- /* Macro sample 3 Creating a 5-item list */ a.1 = "Sort this list" ; a.2 = "Change item colour" a.3 = "Change item text" ; a.4 = "Add another item" a.5 = "Delete this list" list = CreateList() do i = 1 to 5 ; item = AppendItem(list,a.i,1) ;end this = list || '/' || i a = "call Sortlist('List1'())"  act = SetActionRexx(list || '/1',a) a = 'c=SetItemColor(initiator(),3)'  act = SetActionRexx(list || '/2',a) a = 'o=SetItemText(initiator(),"A new text")'  act = SetActionRexx(list || '/3',a) a = 'i = AppendItem('List1'(),"Added item",1)'  act = SetActionRexx(list || '/4',a) a = "call HML_Delete('List1'())"  act = SetActionRexx(list || '/5',a) call ScaleToSize(list,200,64) ; call SetPosition(list,150,40) list = Relocate(list,':') /* End of sample 3 */ Each of the items in the list has a specific action, as indicated by their text. If you click on them, they do what they are set to do. The punctuation for the five 'SetAction' entries was a bit tricky! ----------------- /* Macro sample 4 A separate ARexx program */ call HyperBookToBack() op = open('con','con:30/30/500/120/A Program/CLOSE') tab = '09'x ; lf = '0a'x || tab a = lf || 'This is a small but complete ARexx program' w = writeln('con',a) a = tab || 'which opens a console, prints these lines,' w = writeln('con',a) a = tab || 'and then waits for you to press Return.' w = writeln('con',a || lf) a = lf || 'Before and after, the HyperBook screen is' w = writeln('con',a) a = tab || 'pushed to the back and then brought forward.' w = writeln('con',a) w = writeln('con',lf || tab || 'Press Return now ') r = readch('con',2) cl = close('con') call HyperBookToFront() /* End of sample 4 */ I should have said so earlier, but of course you must have ARexx up and running in the background before any HyperBook macro will work. ----------------- /* Macro sample 5 HyperBook 'Drawing's */ do d = 1 to 6  d.d = SearchName(':','Drawing' || d) ; call SetVisibility(d.d,1)  call SetPosition(d.d,100+20*d,10 + d * 25)  end call pause(20) do d = 1 to 6  w.d = GetWidth(d.d) ; h.d = GetHeight(d.d)  call ScaleToSize(d.d,100,50) ; end call pause(20) do d = 1 to 6 ; call ScaleToSize(d.d,w.d,h.d) ; end call pause(20) do d = 1 to 6  call SetVisibility(d.d,0) ; call SetPosition(d.d,1,10 + d * 20)  end /* End of sample 5 */ Not much can be accomplished in the way of drawings without the built-in HyperBook drawing editor. There is no way you can create a drawing of your own, and Sample 5 really is a bit pointless, but it may just whet your appetite for the real thing. It contains four 'do ... end' loops. __ 1 Identifies six ultra-simple drawings ( | - / \ O and |__| ) which are on Page 1, but stored invisibly. Makes them visible and places them left of centre on screen. 2 Stores their sizes. Changes their sizes. 3 Restores them to their original size. 4 Makes them invisible, and parks them out of the way. Sample 5 does at least show some of the things that can be done with drawings, and you might like to explore copying, resizing, and combining the elements provided into real little sketches. A copy can be made by using a command such as 'd.7 = Clone(d.1,':')', which would make a copy of the drawing identified as 'd.1' in the first loop, call it d.7, and place it on the current page. ----------------- I'm not even going to try to achieve anything with a 'Picture' in the restricted environment of Runner.HB. I could only repeat what I have just tried with drawings : provide a sample, and let you copy or resize it. ----------------- /* Sample 6 Playing with buttons */ do i = 1 to 4  but.i = CreateButton()  call ScaleToSize(but.i,40,20) ; call InsertText(but.i,i,0)  call SetPosition(but.i,50 + i*80,40) ; but.i = Relocate(but.i,':')  end act = SetActionShow(but.1,but.2) act = SetActionShow(but.2,but.1) act = SetActionShow(but.3,but.1) a = "call HML_Delete('Button1'());call HML_Delete('Button2'())" b = "call HML_Delete('Button3'());call HML_Delete('Button4'())" act = SetActionRexx(but.4,a || ';' || b) /* End of Sample 6 */ Four buttons whose actions are set. Explore by clicking on them. Button 4 deletes all of them. ----------------- Explore, learn, enjoy. Then buy. Hamilton, New Zealand May, 1993 --------------------------  <> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <>