Previous: 8 Bitmaps and icons, cursors and other resources
Next: 10 Proper Toolbars, using %tb or %ib
In this section:
A feature of many Windows applications is a toolbar (or toolbox) consisting of a set of clickable icons. These icons are in effect action buttons that duplicate the commonest functions to be found within the drop-down menu system. Putting the actions on toolbar buttons speeds up the selection which can be very important in graphical interaction but is probably a bit of a luxury if your program does not have any of that graphical interaction. In ClearWin+ there are basically three sets of format codes for generating toolbars or toolboxes, but four ways of doing the job. Toolbars in ClearWin+ are fixed in position, but toolboxes are dialogs consisting only of toolbar buttons and are movable.
ClearWin’s toolbar facilities may be displayed typically at the head of a main window client area or down the left-hand side, although programmer imagination can be invoked to put action toolbar buttons within a status bar or indeed anywhere in a window. The top and left positions are best because when a window is resized these are the locations that stay put. The three ClearWin-specific options are:
Generally speaking, textual toolbars are the easiest to code, followed by the image bar system and the hardest is the original toolbar system. The reason lies to a large extent with the need to draw bitmap icons, because with the textual toolbars, icons are optional, and with the image bar system only one icon is required, but with the original toolbar system you may need three or four icons for every button. The icons themselves are input as BITMAP (.BMP), and not as ICON (.ICO).
A fourth option is what I call a do-it-yourself option, which is to put icons on a %gr drawing surface and to respond appropriately if the user clicks on them. You can dress up the drawing surface (or just part of it) so that it looks like a toolbar as well as functions like one.
A toolbar that takes up the whole of an independently-movable window is a toolbox.
Textual toolbars are essentially a row of buttons, and as well as the %tt and %bb format codes a textual toolbar might even be generated using %bt format codes. The example given in the compiled help for FTN95 shows three textual toolbar buttons which I have altered to include callback functions (which would need to be declared EXTERNAL in the usual way):
IW = WINIO@ ('%^tt[Compile]&', KB_COMPILE) IW = WINIO@ ('%^tt[Link]&', KB_LINK) IW = WINIO@ ('%^tt[Run]&', KB_RUN ) IW = WINIO@ ('%bx&', 0.0D0)
and used like this where the action is difficult to identify with an icon but very clear from a single short word then the textual toolbar might be very effective. They work very nicely with no space in between unless of course they are to be separated into logical groups, in which case a single space character is an adequate separator. If any of the options needs to be greyed out, then the usual grave modifier and a grey code need to be supplied. For example, using the compile-link-run sequence in the above example, Link should only become active if Compile completed successfully, with Run only becoming active if in turn, Link had no errors. Whether or not the earlier buttons become inactive when later ones are activated is dependent on program design. The relevant changes to the grey states are done in the callback functions.
A nice refinement to do with toolbars is to generate a line across the client area underneath the toolbar which is done using the %bx code, including an offset as a fraction of a grid cell height. For a textual toolbar, an offset of zero is usually effective (as in the example).
A downside of the textual toolbar approach is that it does not look very professional when the buttons are stacked in a column, nor when there is a large number of buttons. A further downside is when the actions cannot be expressed very simply with short words. The most effective appearance is given when the description on the button does not take up its entire width.
Toolbar buttons defined with %tt are less high than those generated with %bt, and if the style pleases you then they can form an effective alternative in any dialog, but if you use them in one place then for a consistent style you do need to use them everywhere. Unlike the %bt, where the button width may be controlled quite finely with a multiplier, %tt buttons come with larger steps between the button sizes.
I recommend use of the very simplest form of textual toolbar early in program development while the callback functions are being developed because the %tt buttons are so easy to generate and can act as placeholders for more elegant designs to be provided at a later stage of program development when things are definitely working, and attention is more directed towards aesthetics. On the other hand, there are very simple programs for which the textual toolbar remains perfectly adequate.
As you can imagine, with grey codes and callbacks, the format strings in the individual WINIO@ calls can get complicated, and so I continue to stress that for ease of reading (and debugging) your code it is better to keep to one button, one statement.
As well as the %bt button format, an alternative button is provided in ClearWin+ with the %bb format. Buttons using %bt may have icons as well as text, but the options in the %bb format are more sophisticated. One of those options associated with %bb is to retain colour in the icon even when the button itself is greyed out and disabled. The mechanism for automatically converting a coloured icon into grey if the option to retain colour is not taken up can produce an ugly or unrecognisable icon in the greyed-out state. There are techniques other than retaining the colour in the icon to improve the look of the greyed-out variant, and the rules are discussed below in connection with the image bar %ib approach which uses the same algorithm.
An example of the code for the first button in the main %bb toolbar is:
IA = WINIO@('%fn[Segoe UI]%ts&', 0.96D0) IA = WINIO@('%th[delay,ms_style]&', iTTH, 500) IA = WINIO@(' %^~?bb[SELECT//Select ]'// & '[Select from 30 possible traverses]%lc&', & MY_Traverse_Grey(1), KB_Select_Trav_FN, iHWTB(1))
The first two statements select the font for the buttons and its size, then set up the ‘tooltips help’ so that the help appears after a delay of 500 milliseconds. iTTH is a control because a program option is to switch off the help pop-ups.
In the %bb format code, ? says that it needs a help string, ^ that it has a callback function, and
~ that the icon is not greyed when the button is. The local name of the icon is SELECT as defined in RESOURCES. The button’s handle is also obtained using %lc and stored in iHWTB(1). The initial space character in the format string is to stop the first button being too close to the window frame. The icon is 16x16 pixels.
Two disadvantages of using %bb for a toolbar are that the icons are very small, and they need to be in the .ICO format. Windows Paint will import .ICO files but will not save in that format, so that you need a different third-party editor or to get icons from the Internet. It can be really rather difficult to make the icons reflect the function of the button and they act more as an aide memoir to the text on the button rather than indicating its function without text as in the case of a normal toolbar icon. In this respect a green tick is good on an Accept button and a red cross works well on a Cancel button,
You don’t really have to use any of the ClearWin+ toolbar options to generate what is effectively a toolbar because if your client area is a drawing surface you can of course put your icons on that with an import image command in response to detecting the mouse cursor position using full_mouse_input. Indeed, there are benefits to doing so because you cannot only respond to clicks, but you can respond to a mouseover event when the mouse is simply hovering over the icon. Responding to mouseover events is only implemented within %ib at present, and this basically means that mouseover events can only be responded to within toolbars that do not look like the present incarnation of Windows.
A further advantage of a do it yourself (DIY) toolbar implemented on a drawing surface is that intrinsically it is movable whereas once generated all the other types of ClearWin+ toolbars of fixed in their position and can only be moved if the window is closed and redrawn.
The advantage of the DIY toolbar is somewhat negated by the additional complexity created in the graphics callback to that particular drawing surface, and one solution is to basically make up the client area in a master window by two or perhaps even more %gr drawing surfaces, with one or more reserved for the do-it-yourself toolbars and not responding to any other sorts of events. What is more, it is probable that any sort of tool help will look non-standard in a DIY toolbar, but a user is unlikely to be critical if the tool help is particularly helpful and not limited in the way that it sometimes is using the standard ClearWin+ for Microsoft approaches. The number of icons (i.e. bitmaps) required for a do it yourself toolbar depends on the total functionality, but a complete set would include a normal icon, a mouseover icon, a permanently selected icon, a temporarily selected icon for use during a click and release sequence, and a greyed out icon. The greyed-out icon could be rather more complicated than allowed for with %ib variant toolbars, and thus retain more in terms of recognisability.
The method of programming a DIY toolbar is to use the IMPORT_IMAGE@ function to display the relevant bitmap, then using full_mouse_input, you can check in the graphics callback if the mouse pointer is over that image or if a click has been begun in that area. If the mouse pointer hovers, then another IMPORT_IMAGE@ can change the bitmap (by overwriting) to the mouseover state, if a click is in progress because a button on the mouse is depressed, then the IMPORT_IMAGE@ has to be changed to the ‘down’ state, and so on. You would need at least 2 bitmaps for ‘up’ and ‘down’ respectively, with a third if the ‘tool’ can be greyed-out. Four bitmaps are needed if there is a permanently selected state, and a fifth if the icon responds to mouseover.
When processing the mouse coordinates, it is easy to see if the pointer has moved off the toolbar into the body of the drawing surface, but much harder if the bitmaps are hard up against an edge. The problem can be avoided if instead of putting the homemade toolbar up against an edge it is offset by 10 or 20 pixels.
Under the right conditions, and certainly in early stages of developing a program, textual toolbars can be very helpful, but generally speaking they do not look as good as ‘proper’ toolbars. The tooltip help is rather superfluous when the buttons already have text. In the example of Figure 9.1 they work because the likely user does not need anything better and appreciates having the text and the icon.
I wrote an application that used DIY icons for a Windows tablet computer. This particular application was to duplicate the record-keeping for a student surveyor doing a levelling exercise. For those of you for whom this is unfamiliar it is what you sometimes see on a building site where the surveyor is looking through a telescope on a tripod at a 3 or 5 m long staff held by an assistant. The surveyor reads numbers off the staff and enters them into a paper notebook. The exercise requires a great deal of mental arithmetic with quite small numbers and finally a check that no errors had been made. Students often fail at the mental arithmetic, and the intention of the application was to remove the tiresome delays that the inability of today’s students to do the mental arithmetic was causing. The application was presented on the tablet screen without a caption or any sort of frame using %ww[super_maximise].
The icons, which appear down the right-hand side of the touch sensitive screen were drawn at 64x64 pixels so they could be selected with the fingertip press and all the data entry into dialog boxes was handled with the pop-up on-screen number pad or keyboard, which required no programming effort because it is built in part of Windows when in tablet mode.
Rather unfortunately, given the effort that I put in, the application proved to be a resounding failure! Basically, even Microsoft have discovered that Windows is not particularly well suited to the tablet format, and the automatic rotation of the screen when the tablet is held in different positions limits some of the design elements that can be employed.
The basic problem, however, was not with the application but compared to a paper notebook and pencil that can be folded up and stuck in the surveyor’s pocket thus freeing both hands to fiddle with the instrument, the Windows tablet being a read-write device and also slightly too big for a pocket could not be slipped into a pocket without corrupting the input. I had made the mistake of thinking that the tablet was equivalent to my Kindle e-reader where I can just fold the case and put it away.
Another disadvantage reflected an issue I had once had with a colleague who remonstrated with students who gave up in the rain, saying “do you think they can’t build motorways in the rain?” As it happened, keeping modern surveying equipment out in rain will inevitably lead to it malfunctioning and needing costly repairs in which case presumably motorway constructors just buy or lease another, but Universities take a long time to acquire costly instruments and certainly not on the timescale of a field course. The tablet computer is also somewhat susceptible to rain in a way that a proper survey notebook and pencil are not, as the paper in the pages can be written on when wet!
A recent development to ClearWin+ (from version 8.20) is to enable you to draw a complete toolbar with one image file, and several sample image files are included with the FTN95 package. The system is quite complex as it deals with all the options in one command. It’s not something I have experience with, and as you develop a toolbar only once per application, it’s something to seriously consider if you are programming a series of applications with a need for consistent toolbar design.
8. Rudyard Kipling’s ‘If’ – if you hadn’t already guessed – or knew already
9. The Eagles this time … (on the Hotel California album)
FORTRAN and the ART of Windows Programming, Copyright © Eddie Bromhead, 2023.