Wimp.IconBar

New Calls

        Wimp_CreateIcon
        Wimp_DeleteIcon
        Wimp_SetIconState
        Wimp_GetIconState
        Wimp_Poll: reason code 6 (Mouse_Click) is returned to the icon owner

Overview

The window manager provides an iconbar facility to allow tasks to register icons in a central place.

The iconbar appears as a thick bar at the bottom of the screen, containing filing system icons on the left, and 'utility' icons on the right (note that the iconbar is only displayed when there are icons in it).

When the mouse is clicked on one of the icons, the Wimp returns the mouse_click event to the task which registered the icon originally.

If there are so many icons on the icon bar that it fills up, the Wimp will automatically scroll the bar whenever the mouse pointer is moved close to either end of the bar.

Interface

The following SWIs recognise funny window handles on input:

-1 = iconbar (utilities)
-2 = iconbar (filing systems)

Wimp_CreateIcon                 ; can cause other icons to shuffle
Wimp_DeleteIcon                 ; can cause other icons to shuffle
Wimp_SetIconState
Wimp_GetIconState
Wimp_GetPointerInfo                     ; these two return identical blocks:
Wimp_Poll: reason code 6 (Mouse_Click) ; Exit: R1 --> block
+0 = mouse x
+4 = mouse y
+8 = buttons ; icon's button type determines format
+12 = -2 ; icon bar window handle (NB -1 ==> background)
         +16 = icon handle      ; as returned from Wimp_CreateIcon
NB: SetIconState can be used to cause an icon to be updated (use indirected
icon if (eg) sprite name is to be changed. Note that the icon size
cannot be changed (that would cause the other icons to move).

Dimensions of iconbar

When CreateIcon is called to put an icon on the bar, the Wimp only uses the x coordinates of the icon to determine its width, and then positions the icon as it sees fit. However, for reasons of flexibility, it does not vertically centre the icon, but actually uses both the y-coordinates given to determine the icons position. This means that applications must be aware of the 'standard' dimensions of the bar, in order to positions its icons correctly.

There are two main types of icon which are put onto the icon bar: those consisiting simply of a sprite, and those consisting of a sprite with text written underneath (see Wimp.Icons for details). The diagram below summarises the rules governing the positioning of such icons:

top     92 +---------------------------------------+ 92
           !   <---c.64----><-24-->                !
           !                       +-----------+   ! 84 (max)
        68 !   +-----------+       !           !   !
           !   !           !       !           !   !
           !   !  sprite   !       !  sprite   !   !       The actual iconbar
           !   !   only    !       !           !   !       stretches right
           !   !           !       !           !   !       across the screen.
           !   !           !       +-----------+   ! 20
           !   !           !       +-----------+   ! 16
         0 !   +-----------+       !  text     !   !
           !                       +-----------+   ! -16
           !                                       !
bottom -24 +---------------------------------------+ -24

Note that there are two 'baseline' positions: one for sprites with text underneath, and one for those without. The overall effect is better if most of the sprites are of a similar size, since otherwise there is a conflict between wanting the sprites to line up on the baseline, and wanting to vertically-centre them.

The general rule is that sprites with text underneath them should always be positioned on the baseline (y=20), whereas sprites without text can safely be vertically-centred (although if they are close to 68 OS units high, it is better to put them on their baseline (y=0).

Guidance for Application software

Either: arrange it so that the application always has at least one window
present (eg. Text editor would close down when all text windows have
been closed).
Or: register an icon on the icon bar
        this is primarily for resident utilities (eg. clock / calculator)

Multi-tasking applications should never put immoveable windows on the desktop, so that the iconbar cannot be obscured. Note that old-style Wimp_Init applications cause everything else to be obscured anyway, so they are OK.