RISC DISC 1

home *** CD-ROM | disk | FTP | other *** search

/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / morehelp / !MoreHelp / !Help < prev next >

Wrap

Text File | 1994-08-27 | 18.7 KB | 384 lines

More Help version 1.00 © Sam Kington 27th August 1994 This program is freeware, *not* public domain – i.e., I retain copyright (see “Boring legal message”). This module will only work with RISC OS 3 or later. What this program does ********************** This program, or more accurately this module, allows you to add interactive help to programs that don’t usually give interactive help. The actual mechanism is quite intricate, but basically you tell the program to catch all the requests for interactive help going to a particular help, and to reply with messages contained in a supplied text ﬁle. The actual format of the text ﬁle is available later on in this ﬁle. Why is this useful? ******************* First of all, it allows you to quite easily add interactive help to programs – which is undeniably a good thing, especially for new users, but also for people trying out your work of art in a hurry, and ready to discard it if they can't immediately understand how it works, which is the case with most people going through their new discs full of freeware. Secondly, as both code and messages are held in the module area it doesn't eat up your precious WimpSlot. If you're struggling to keep something just inside a 32K WimpSlot, for instance, you don't want the WimpSlot to double to 64K just so you can have these nice helpful messages. This doesn’t mean you’re not using the memory – you are, there’s no miracle – but it’s slightly less wasteful. Thirdly, the help is held in a quite easily-edited text file and can be removed by commenting-out a few lines in the !Run file. Other interactive help providers like the Interface or WimpExt modules expected the help text to be held in the validation strings, which meant the help strings weren't as long as they could have been, and also made the Templates ﬁle positively massive, which means a big buffer in application space - and bang goes the WimpSlot again. Fourthly, you can add interactive help to programs without changing a single line of code (apart from the !Run ﬁle, and they get changed quite a bit anyway) - you don’t have to re-compile or re-crunch them, you just have to write the ﬁle. This also means that people who are fed up with there not being interactive help can add it themselves, then send it off to you for you to distribute. Finally, as this is a module, available to all programs, the code for decoding interactive help messages isn’t duplicated across programs – and the module is small enough for people not to worry about having it loaded. The more programs use it, the larger the savings are – so distribute it like crazy, use it in your own programs, and make More Help ﬁles for programs that don’t provide interactive help! Evangelistic mode off ;) The message ﬁle format ********************** If you want to know how the program works, for instance so you can use it on your own programs or add help messages to other people’s, you’ll need to know about Message ﬁles, as used by MessageTrans. Skip this section if you already do, or if you feel conﬁdent enough to pick it up as you go along; bear in mind, however, that the “How it works” relies to some extent on you having read this section. If you don’t know what message ﬁles look like, the best way to ﬁnd out is to look at Text ﬁles called Messages or something similar, inside application directories. A good place to start is the Resources ﬁling system, Resources:$.Resources (Choose “Open $” from the Apps icon bar menu, open the directory Resources) – all the directories contain Messages ﬁles. ADFSFiler in particular contains wildcarded tokens, AppDraw demonstrates linking one message to several tokens. Doubtless there are others, I stopped at AppDraw. (Guess how I was sorting the Filer window? ;) ) But enough of this gibberish, what does it all mean? Well, if you’ve had a look at Messages ﬁles, you’ll see they’re actually human-readable text ﬁles, with lots of lines looking something like this: SetI7:\Ssubstitute double quotes as open and closed double quotes. The important bit in this line is the “:” character: the stuff to the left is the programmer-friendly “token”, the stuff to the right is the actual message that, presumably, the user will see at one point or another (although, as lots of message ﬁles contain almost nothing but errors, you may not *want* to see the message). When the program asks for message code “SetI7”, MessageTrans looks through the ﬁle for the token “SetI7”, which will usually be at the beginning of a line. It then carries on looking through the ﬁle until it ﬁnds a colon (“:”), which will usually be directly after the token. It then reads the text between the colon and the next newline (i.e. line break), and returns this as the user-friendly message. To get rid of the ﬁrst complications, you may notice that although the Messages ﬁles are full of things like “\S”, you never see such a character combination when the messages are actually displayed. In case, “\S” is just one of several special abbreviation codes used to keep message ﬁles slightly shorter – much like abbreviations in Impression, they are expanded automatically when the message is read. The list of abbreviation codes in RISC OS 3.1 (I don’t think it has changed in RISC OS 3.5) is as follows: \S:“Click SELECT to ” \R:“Move the pointer right to ” \A:“Click ADJUST to ” \T:“This is the ” \G:“This option is greyed out because ” \W:“This window is ” \D:“Drag SELECT to ” \d:“Drag ADJUST to ” \w:“window” \s:“SELECT” \a:“ADJUST” Obviously the quote marks aren’t part of the message; also note the trailing spaces, so that “\Ssubstitute quotes” is actually displayed as “Click SELECT to substitute quotes”. A common mistake is to forget that “\S”, “\R”, and other such abbreviations include a “ to ”: “\S to substitute quotes” would actually be displayed as “Click SELECT to to substitute quotes”. Also note that there is no “\M” or “\m” – MENU nearly always brings up a menu so there is usually no need to support interactive help about it. The actual list of tokens is contained in Help’s Messages ﬁle, in Resources:$.Resources.Help in RISC OS 3.1 (somewhere else in RISC OS 3.5 I think). Messages ﬁles do not just contain lines with one token and one message: sometimes there will be several tokens for one message, or wildcarded tokens. An example, again from the Smart Quotes help ﬁle, is for the “miscellaneous” icons of the “Settings (as icons)” window: SetI?/SetI??/SetIW:\Tsettings window, using icons at the moment, where you can turn various character substitutions on and off. Use the Characters window to change the characters used as quotes, or the Diphthongs window to view and edit the list of diphthongs. Clearly, the message is found if you look for “SetIW”; it is also found for tokens “SetI?” and “SetI??”. The message could also have been deﬁned like this: SetI? SetI?? SetIW:\Tsettings window, using ... In other words, a newline (line break) or a “/” (NB: do not confuse with “\”, used for abbreviations) will tell the operating system that there are several tokens that should return the same message. All the tokens after the previous message, and before the colon (“:”), will be found and will return the message after the colon. A last complication is the wildcard character, “?”. This will match any one character (apart from the special ones like :, \ etc.), and one character only, much like the blank square in Scrabble: in this case, the “This is the settings window” message will be returned for tokens “SetI5”, “SetI22”, “SetI05” but *not* “SetI” or “SetI22S”. Note that, because although several tokens can match one message, one token cannot match several messages (that would be silly), so as soon as a match has been found MessageTrans stops searching the ﬁle. This means that, ﬁrst of all, messages at the beginning of the ﬁle will be found slightly faster (the difference is quite trivial), and secondly, wildcarded messages should always be after all other similar messages. In other words, if you want special messages for tokens “SetI5”, “SetI10” and “SetI16”, but want to use the same one for all messages of the form “SetI?” or “SetI??” or “SetIW”, the message ﬁle should look like this: SetI5:message1 SetI10:message2 SetI16:message3 SetI?/SetI??/SetIW:This is the default message Finally, because MessageTrans looks for a newline (line break) after a message, there should be one after the last message, otherwise it won’t be found. How it works ************ MoreHelp has three commands for you to use: • MoreHelp_AddTask <task name> <message ﬁle> • MoreHelp_RemoveTask <task name> • MoreHelp_AddHelpMessages AddTask will set up a ﬁlter on the speciﬁed task, and load a Messages type ﬁle (that is, a Text ﬁle, type &FFF, with a list of tokens and message inside – see above) containing the help messages: the task will now appear to give interactive help. (It isn’t, of course, More Help is, but the point of all this is that you don’t know). The task name is the name that appears in the Task Manager window. If it contains spaces, put it in quotation marks, so you would type *MoreHelp_AddTask "Smart Quotes" SmartQuote. RemoveTask will remove the speciﬁed task, messages will no longer be intercepted and interactive help will stop. AddHelpMessages will make the *last task to be added* “know” about Help messages – this is because under RISC OS 3 tasks can ask to only be told about certain messages, so will often not receive the Help messages if they preferred not to. The command should only be run once, because otherwise strange effects can happen (not my fault, I don’t think), and the best bet is to run it immediately afterwards AddTask. As a rule of thumb, run it *once* if a program isn’t producing interactive help despite your carefully honed Messages ﬁle. If you do a *Filters from the command line (F12 or Ctrl-F12) you will see how More Help operates. It sets up a ﬁlter for each of the tasks that have had interactive help added with AddTask, to intercept interactive help messages. In addition, it sets up another ﬁlter on all tasks, to intercept Close Down messages – messages sent out when a task closes down – so it can remove its ﬁlter when the task it is supplying help to quits. When it gets a help message, it ﬁnds the title of the window the pointer is over, strips spaces from it and replaces certain characters to avoid using forbidden characters (see below), then looks in the supplied message ﬁle for the corresponding message. For instance, if you asked for help on a window whose title was “Settings (as icons)”, it would look for a message token in the ﬁle called “Settings{asicons}”. It would then ﬁnd the message corresponding to the particular token, and use that as the window code. The Smart Quotes interactive help ﬁle contains the following line: Settings{asicons}:SetI So, if you held the pointer over the window entitled “Settings (as icons)”, the window code would be “SetI”. If this line wasn’t in the ﬁle for some reason, the window code would default to “UK” (unknown, not United Kingdom ;) ). The forbidden characters are as follows: , replaced by . ) replaced by } : replaced by ; ? replaced by ! / replaced by \ ( replaced by { (for neatness' sake) If you hold the pointer over the icon bar, More Help will pretend the window title was in fact “Iconbar”, so if the following line was in the message ﬁle: Iconbar:Ibar the window code would be “Ibar”. If the pointer is over a menu, it will look for the token corresponding to the window the pointer was over when MENU was clicked, and add “M” to it, so if the pointer is over the menu produced by clicking MENU on the Icon bar, the window code will be “IBarM”. It will then add the icon number or the menu entry to the code, which would then look something like “SetI22” or “IBarM2”, if the pointer was over icon number 22 in the “Settings (as icons)” window, or the third entry in the icon bar menu – the ﬁrst option is in fact option 0. Because menus are hierarchical, it will in fact add the numbers of all the menu options currently highlighted, so if the pointer was over the ﬁrst option of the ﬁrst submenu of the ﬁfth option on the menu opened from a window with the token “Main” (for instance, “Display.Font.System Font” in Edit’s main menu), the resulting token would be “MainM400”. Each menu number will be exactly one character long, to avoid confusion, which means that when we get to the eleventh menu entry there could be problems. To work out the character used for the menu entry, More Help does the following: For numbers 0-9, it uses characters “0” to “9” For numbers 10-35, it uses characters “A” to “Z” For numbers 36-71, it uses characters “a” to “z” For numbers 72-134, it uses characters “À” to “þ” This is really overkill: if you have a menu this long it’s probably either a list of fonts, a list of modules, or some other list that More Help cannot possibly know about – certainly there should be no need to supply *distinct* help messages for each entry. If you do want to provide help, say for MainM3420 to MainM342Z (or whatever), the best bet is to provide a single token, MainM342?. If the pointer is over the window’s work area, it will instead add a “W”. Finally, it will look at the icon to see whether it is selected or greyed out. If it is selected (only for icons) it will add a “S” to the token, if it is greyed out (only for menu items) it will add a “G”. It is not possible to have both. Finally, it will look for this token in the message ﬁle, and return the corresponding message, which will then be used as interactive help. Limitations *********** Because More Help works out what window it’s looking at by reading the title, if the title changes (for instance if it’s a pathname of a ﬁle) it will be impossible to deﬁne the appropriate token. You should instead deﬁne messages using the “UK” window code, which is the default code More Help will use if it can’t ﬁnd the right token. If there are no windows like that, you should have the following like in the message ﬁle: UK?/UK??/UK??/UK???/UK????: NB: there is nothing after the colon, except a newline (line break). If there are several different types of window, with varying titles, despair. Similarly, interactive help won’t be as “intelligent” as it would be if the program itself was supplying it: you won’t get things like “Move the pointer right to perform an operation on ‘!MHelpEd’” because More Help doesn’t know you clicked MENU over the application !MHelpEd. If you need complicated help like that, either write your own routines if you’re programming the application yourself, or, as before, despair. Boring legal message ******************** This application is freeware, that is, it can be distributed freely as long as only reasonable charges are made for media and distribution. I retain copyright on all program code and documentation. This software is supplied “as is”: I make no warranty, expressed or implied, of the merchantability of this software or its ﬁtness for any particular purpose. In no circumstances shall I be liable for any damage, loss of proﬁts, or any indirect or consequential loss arising out of the use of this software or inability to use this software, even if I have been advised of the possibility of such loss. In other words, if your computer crashes, blows up, you lose all your work etc. all because of More Help (unlikely I know), don’t blame me. I will, however, do my best to solve bugs, add features, answer queries etc. – but bear in mind that I don’t have access to Acorns at University (term-time). Distribution ************ This is freeware, so you can distribute this freely – and indeed I encourage you most strongly to do so. However, because I retain copyright and I want everyone to have all the ﬁles, when you distribute the !MoreHelp application you must distribute all files intact, including source code and this documentation, with this package – in other words, the ﬁles !Boot, !Run, !Sprites, !Sprites22, MoreHelp, ModSource, !Help, and Vsn100. Feel free to muck around with it as much as you like when it’s on your machine, but distribute the original ﬁles, please. You are strongly encouraged to use MoreHelp in your own programs, or to write MoreHelp help ﬁles for other programs – I have plans for a MoreHelp editor and possibly an application patcher to make this sort of thing easier. However, the most time-consuming part of writing a message ﬁle is actually writing the helpful messages (or so I ﬁnd anyway), so that isn’t *much* of a problem. About all these strange foreign characters in this ﬁle ****************************************************** OK, so if you’re reading this on a PC or a Mac or another strange machine like that, you may be wondering what all these strange ae things are. Well, they’re quotes (sorry, there was another one), dashes, ligatures, etc. Honest. But not on all machines... Basically, character sets are only standard up to character 127, which is basically alphanumerics and a few standard punctuation marks. Foreign characters, typographical oddities like quotes and ligatures, and other more obscure symbols are “non-standard”, and each computer often has its own idea of where they should go in the character set. So don’t worry: even if it’s hard to read on your current machine, it won’t be on an Acorn machine. It may look slightly strange if you’re using the System font, however. But why am I using these strange characters in the ﬁrst place? Well, they’re in the character set and they look nice in an outine font, and I’ve written a program called Smart Quotes (sorry for the plug) that substitutes these sort of characters automatically, and I’ve got it turned on at the moment... How to contact me ***************** All bug-reports, suggestions, comments or indeed any feedback at all will be welcomed. Here’s how to get to me: E-mail : 9262861k@arts.gla.ac.uk, 926286ki@udcf.gla.ac.uk during term-time These should be OK until June 1996 At Christmas, Easter and during the summer, you can get me at wombat@altern.com, wombat@email.teaser.com or sam@altern.com, in order of preference (that is, if mail bounces off one of these or I don’t answer within a week send to the next one) Snail-mail : My term-time address, at least until June 1995, is: Sam Kington Flat 2/1 44 Hotspur Street Glasgow G20 8NL SCOTLAND Again, a backup is the home address – anything that goes here will get to me eventually. Sam Kington Merlhiot 24420 Savignac les Eglises FRANCE Term-time is October to June, with bits off at Christmas (3 weeks) and Easter (4 weeks).