IconLab   Icon Labeller and Renumberer

by Graham Crow


IconLab is a very powerful utility that will be of use to anyone who develops applications for RISC OS. It simplifies the chore of keeping track of icon numbers during program development by 'capturing' a window from the screen as a sprite, and labelling its icons. You can dispense with all the rough sketches of your windows and their icons, and let IconLab do the work for you! It is also invaluable for examining the icon structure of other programs. It allows renumbering of icons simply by clicking on their numbers in the above display.

You can save the labelled display as a sprite file or send it to your printer.

USING ICONLAB
Running IconLab installs its icon on the icon bar. Click Select on this icon to open the main window.

There are two ways of capturing the target window:

Drag the 'hook' onto it.
Click on the hook to gain the input focus, position the pointer over the target window, and press F1.

The second method enables you to capture windows which are part of a menu structure.

After a brief delay a copy of the target window appears in IconLab's window, complete with numbered lines pointing to the icons.

THE MAIN MENU
The main menu provides four choices:

Options    - leads to an options dialogue box
Sprite     - operations affecting the displayed window sprite (shaded if no Sprite present)
Template   - operations affecting a Template file (shaded if no Template dragged on)
Renumber   - provides the means of renumbering icons (shaded unless both Sprite and Template are present)

OPTIONS
Clicking on 'Options' in the main menu opens the options dialogue box which then remains open until you close it: sliding off the main menu leaves the dialogue box as a temporary structure.

Working from top to bottom, the first block of switches are all concerned with labelling. With 'Labels' switched ON, you then need to decide whether you want the lines drawn from the edge or the centre of each icon. The former is preferable if your window has mostly icons with borders. Note that if an icon is overlapped by one or more others then lines are always drawn from its edge. Next, you can arrange for the lines to be drawn to the side margins or the bottom margin. The latter is useful for windows that are wide and short; try the icon bar! A separate option is to place the number directly on the icon. This is mainly intended for a matrix of icons such as a table, but to avoid ambiguity the number is only plotted on the icon if it is an empty indirected text-only icon, which is not covered by another. As you may guess, this has an adverse effect on the plotting speed. Finally, you may choose whether or not to display the 'rulers'. These indicate the vertical and horizontal positions which IconLab uses for drawing its lines.   

Note that labelling can be switched OFF, thus providing a convenient way of 'grabbing' a window for transferring to another application. In this case the borders are made very small. 

The next block is concerned with colour-coding the icons according to their button type. You can choose from among the eight available colours by clicking with Select. Clicking any button on the blue arrow opens a window of button types. Clicking Select on these paints them in the current colour, whilst clicking with Adjust turns them black. When you start IconLab, the default colours will be used (light green for writable; red for 'action'; dark blue for draggable, etc.) but you can change these to suit your preference. Colours are saved along with the Sprite file.

The third block provides the means of adjusting the X and Y scales. Values are intervals in pixels, and the defaults are 16 for the X-scale and 24 for the Y-scale. Depending on the number and layout of the icons in your window, you can choose a scale which gives the most pleasing effect.

You may want to save a copy of the pointer with the window. If so, set 'Pointer' to ON. The pointer will be plotted at the position the drag ends, or (if you use F1) at its resting position.

Finally, clicking on Save saves all the current settings as a text file '...Resources.Options'. These are automatically loaded next time you use IconLab. If you need to restore the saved settings at any time click on 'Load'.

SPRITE
This leads to a sub-menu:

Colours provides a key to the current colours for icon button types.
Remove  deletes the current display.
Save    leads to a save box from which you can save the display as a sprite file containing a single sprite named 'grab'.

TEMPLATES
If you intend to use IconLab's renumbering facility, you must supply it with the name of the Template file which contains the definition of the displayed window. This is done by simply dragging the Template file from a Filer window onto IconLab. The right-hand part of the filename appears above the display, together with the name of the first window.

The main menu item is now available and leads to a sub-menu:

Windows leads to a sub-menu showing all the window identifiers; you select the one which corresponds to the display.
Remove  cancels the current Template and removes the descriptors.
Save    leads to a save box for saving the Template file.

RENUMBER
The Renumber option is only available if a window containing at least one icon has been grabbed and a Template file has been dragged onto IconLab. Choosing this option opens the Renumber window whose title bar shows the range of icon numbers available.

There are two methods of renumbering:

(1) Enter the 'From' and 'To' icon numbers and press Return when the cursor is in the 'To' box.

(2) Set the 'To' icon to a starting value (normally 0) using the blue arrows then move the mouse pointer over the displayed numbers. As you traverse a number it appears in the 'From' box. Clicking Select causes renumbering to take place and the 'To' value to be incremented. You can thus renumber all the icons simply by clicking on their numbers.

You need to ensure that the displayed window matches the selected Template window. IconLab checks that the windows have the same number of icons and that the bounding box of icon zero is the same. If NOT, the error message 'Windows don't match' is given.

When an icon has been renumbered a beep sounds and the two numbers in the display are swapped. An asterisk appears in the title bar to indicate that the template file in memory has been amended. To save the amended Template file use the Template Save option.

VIEWING OR PRINTING SAVED DISPLAYS
To view a sprite file saved by IconLab, you can drag it onto an IconLab window or the icon bar icon. The words 'view only' appear in the title bar and the Template and Renumber options become disabled. Note that the sprite colours remain true even if the current mode is different from that in which the sprite was created. Since the colour codes are saved along with the sprite file the 'Sprite-Colours' option will correctly represent those used in the display. Template files
cannot be dragged onto IconLab in 'view only' mode.

To print a sprite file saved by IconLab, drag it onto Paint and choose 'Sprite - Print' from the menu. You can then specify landscape or portrait, and so on. Alternatively, drag the sprite file directly onto the printer driver.

PLOTTING STRATEGY
IconLab takes each icon in numerical order. If the 'On empty icon' option is set, it establishes whether the icon allows this, and if so paints the number in the appropriate colour. If not (or if the option is not set) it calculates whether the icon is nearer the left or the right of the window and seeks the ruler mark on the Y-scale which is nearest to the centre of its vertical range. If successful, it checks the button type and plots the line and number in the appropriate colour. If unsuccesful, the icon number is placed in a table for future action. This continues until all the icons have been processed.

If it proves impossible to place all the icons, then the remaining icons are taken in turn from the table and an attempt is made to plot them on the appropriate side using the nearest ruler mark and an 'angled' line. In cases where this would cause lines to overlap, the nearest vacant X mark within the icon range is used. If all the marks on one side are taken then attention switches to the other side. If all the marks on both sides are taken and some icons are still not placed, then a message is issued to the effect 'Unable to place N icons at this scale'. Naturally, the smaller the vertical gap, the greater the chance of placing all the icons.

If the option to plot to the bottom margin has been chosen, then only icons which can be joined vertically to a X-scale mark within their horizontal range are plotted. This normally copes adequately with windows which are wide and short.

Knowledge of the plotting strategy should help you to choose the combination of options which is most suitable for a particular window.

NOTES
If the target window is obscured by another, IconLab will automatically bring it to the top before capturing it.

If icons in the target window are partially obscured because it has been moved off the screen, scrolled, or had its size adjusted, then the labelling will be directed to that part of the icon which remains visible. Icons which are wholly invisible will not, of course, be labelled.

A template file may include the definition of an icon which has subsequently been deleted. If so, the icon is labelled with a dotted line instead of a solid one. In some modes, where the dots are very close together, this may appear as a fainter line.

If an icon has no border, and its bounding box has not been adjusted to the size of its contents, the line may be drawn some distance from what appears to be the icon.

If you change mode when a window has been grabbed by IconLab, then the display is cleared and the window must be recaptured in the new mode.

A warning is issued if you have amended but not saved a Template file and you attempt to:

Quit IconLab
Choose Shutdown from the Task menu
Drag on a Sprite file
Drag on another Template file 

Clicking Select on the hook causes the main window to gaon the input focus; clicking Adjust loses it.

Renumbering by clicking on the displayed numbers with Select increments the 'To' number; clicking with Adjust decrements it.


 Copyright RISC User 1993
