Previous: 20 Beat the clock
Next: 22 My least favourite bits
In this section:
I don’t tend to write programs that are about text, but there are functions within ClearWin+ that allow you to incorporate large blocks of text into an application, including all the tools to create, insert, cut and paste and delete things in that block.
Short strings are dealt with using the %rs format code, which in many respects is similar to the numeric input format codes %rd and %rf. You can specify the width of the control by prefixing it with n, as in %8rs where n=8, but n is optional and when used it specifies the number of average width characters in the displayed output. The output will scroll horizontally within the specified width if necessary. The format code can also take a callback, and if so, the qualifier ^ must be used. If the grave qualifier ` is used, then the string displayed in the control can only be changed by the program using WINDOW_UPDATE@(string).
The format code can also accept a grey control, which as usual is 1 for enabled or 0 for disabled (greyed-out). If a call-back function is used, it is placed after this control variable.
Some experience using this format code was that users sometimes find it tedious to enter labels when they are entering numeric values and if there is only a small number of options it is better not to expect the user to type the option name in (where there is always a possibility of making a typographic error), but to present the user with a drop-down box where the action is simply to select one of the presented options (see, for example, Figure 6.2).
This control allows the entry of passwords through the option PASSWORD, in which case an asterisk (*) appears on the screen for each character even though the string is stored correctly. Dealing with a password is a function of assessing the validity of what has been entered, and that should normally be done through a callback function. Passwords may be used so that only accredited users can have access to the program’s functionality, but even a simple password can sometimes be useful as a check when a user is about to perform an operation that might have significant consequences. An example in my own programming relates to SCAMPS, where sections of the survey that are judged to be adequately correct can be locked against further change.
Additional options UPPERCASE and LOWERCASE can be used so that the string that is entered is automatically converted to the correct case before storage regardless of what is actually entered. A fourth option, NO_ADDITIONAL_DEPTH removes the standard spacing between this control and the next line, and has an odd genesis. In early versions of ClearWin+ this option was the standard, but as the norm in Windows is to have that additional space it was included into the control. In doing so, it broke some existing codes including one of mine where the text was entered into a neat little cartouche. However, by the time the option was added I had redesigned things so the that the additional depth did not bother me and indeed I found that I preferred my later design to the original one! This option may help when placing %`rs strings on top of a background image (for example) as part of a toolbar.
It is possible to do cut-n-paste or copy-n-paste with the contents of an %rs control, but unless you program the responses yourself, the standard key sequences do not work. Instead, you have to attach standard callback functions to menu items and/or accelerator keys.
IK = WINIO@ ('%ac[Ctrl+X]&', 'CUT')
IK = WINIO@ ('%ac[Ctrl+C]&', 'COPY')
IK = WINIO@ ('%ac[Ctrl+V]&', 'PASTE')
When you no longer require the accelerator, then you can use CALL REMOVE_ACCELERATOR@.
The subroutine set_highlighted@ can be called to select all of the text in the edit box. It takes one INTEGER argument which is the handle given by %lc.
You have several choices : %rs with %dd or %ls.
When %dd is used with %rs, it should be placed the before %rs format code. In this case it should have a non-zero step value (which is ignored). The subsequent %rs box should have a call-back function which uses CLEARWIN_STRING@('CALLBACK_REASON') to identify the reasons 'SPIN_UP' and 'SPIN_DOWN'. The call-back function must provide the response to the spin, because the control itself does not.
WEEKDAY = 'Monday'
IK = WINIO@ (%dd%^`rs&', 1, WEEKDAY, KB_STRING)
This variant of the control should be used when the next or previous display value is obvious, for example, by cycling through the days of the week or months of the year, and moreover, it should be configured so that the list is endless or ‘rolls over’. An example of roll-over would be to follow Sunday by Monday again, or December by January. Other lists where the sequence is obvious includes paper, scissors, stone or tinker, tailor, soldier, sailor etc. The reason that your callback should roll over is that the spin wheel arrows do not grey out when the end of a list is reached, because there is no pre-defined list, and the sequence should be obvious because the user does not get to see all the options without scrolling through the whole list.
The advantage of %dd + %rs is that the list does not need to be assembled, and its disadvantage is the need for roll-over.
In comparison, %ls needs a list to be assembled, and because the user should be able to see all the options, then the list needs to be comparatively short.
CHARACTER*(15) LIST(6)
LIST(1) = 'Miss Scarlet'
LIST(2) = 'Colonel Mustard'
LIST(3) = 'Professor Plum'
LIST(4) = 'Mrs Peacock'
LIST(5) = 'Mr Green'
LIST(6) = 'Mrs White'
NUM = 1
IW = WINIO@ ('%15.6ls&', LIST, 6, NUM)
In this case, the sequence is not ‘obvious’, and it is unlikely that the user will want to select the next or previous value but will want to see all options. NUM is the number of the initial selection, but this will be altered and returned as the number of the selection made by the user, so it has to be a variable. The control can be greyed-out.
The length of the list is fixed, but if there are blank entries (e.g. LIST has 8 values, and the last two are blank) then two further entries could be added, or items removed from the display by blanking them.
You can do selections using radio buttons and tick boxes, but not for very long lists. Should you wish to use a facility that you have seen in someone else’s application, then a search through the online help files will usually throw up the answer quickly. Occasionally, the details are better explained in the enhancements file, but that is usually the case with relatively newly introduced facilities.
A choice has to be made as to whether the selections are all made through the menu structure, where the selection can be inspected just by dropping down the menu and looking for check marks, or via a dialog.
Small blocks of text can be input or edited using the %rs format code, and for longer blocks you have the choice of two methods and their related format codes: %eb or %re. Both of them are fairly complicated, but are described fully in the help file documentation and they certainly do not need the ‘trickery’ that is part of the methodology of %lv (and %bv). The complexity of the %eb and %re format codes is largely because the longer the block of text you expect the user to edit, the more likely it is that there will be a need for cut, copy and paste.
The format code %re uses Microsoft’s standard edit control and therefore reacts to Microsoft’s standard key sequences for editing, whereas %eb needs those key sequences to be set using a ClearWin+ callback and other functions. %re has generic similarities to %rs.
Another critical difference is that %re was for a long time restricted to editing 32k bytes or less, and %eb was not.
The description of %re in the online help file is supplemented by several entries in CWPLUS.ENH, notably 143 and 418, and the length of the associated text was increased substantially at FTN95 version 8.40 (see CWPLUS.ENH notes 422 and 424). Similar notes also apply to %eb (notes 145, 153, 165, 166, 271, 410 and 411). %eb does not appear to handle text with UTF-8 encoding.
A third option is the text array (%tx), also well described in the help file.
On the basis that a facility to edit large blocks of text would not normally be found in an older, pre-existing, Fortran program, then for space considerations I will leave this matter to the online help.
FORTRAN and the ART of Windows Programming, Copyright © Eddie Bromhead, 2023.