1

# ToolAction Software Functional Specification

Document ref: | 2107,744
Project: | NC100
Revision: | $Revision: 2.1 $
Date: | $Date: 1997/04/09 16:49:00 $
Author(s): | Simon Middleton
Change: | AMR 5094

## Contents

1.0 | Overview
2.0 | Outstanding issues
3.0 | Technical background
4.0 | User interface
5.0 | Programmer interface
6.0 | Data interchange
7.0 | Data formats
8.0 | External dependencies
9.0 | Acceptance test
10.0 | Non compliances
11.0 | Development test strategy
12.0 | Product organisation
13.0 | Future enhancements
14.0 | Glossary
15.0 | References
16.0 | History

## 1.0 Overview

ToolAction is a new gadget for the Acorn Toolbox that provides a sprite version of the action button as well various other styles of button. It is sufficiently flexible that it can, in fact, replace many of the standard buttons.

## 2.0 Outstanding issues

There are no outstanding issues.

## 3.0 Technical background

The versatility of this gadget comes from the separation of its state from its pressed status. This makes it possible to display more realistic buttons using up to 6 sprites.

The six states can be described as

1. Button unpressed and off
2. Button pressed and off
3. Button unpressed and on
4. Button pressed and on
5. Button unpressed and greyed out
6. Button pressed and greyed out

The pressing is purely controlled by the wimp and lasts as long as the mouse button is held down, the state is usually controlled by the user though there is a flag for auto-toggling.

A typical use of this might be a VTR control button. This is a button with a light behind it. The pressing of the button happens physically but the operation of the light is a reflection of the operational status of the machine.

The button can also be used as a pure text button, emulating the ActionButton.

It is extended for NC100 to allow control of the selected state from software and to be able to automatically highlight when the mouse pointer is over it.

## 4.0 User interface

None.

## 5.0 Programmer interface

### 5.1 Gadget flags

toolaction_GENERATE_SELECTED_EVENT (bit 0)
  When set then an action_TOOL_ACTION_SELECTED event is sent every time the button is clicked. This event will contain the new state of the button (if toolaction_AUTO_TOGGLE is set) or else the current state.

toolaction_IS_TEXT (bit 1)
  When set the idents are displayed as text, otherwise they are assumed to be sprite names (or pairs of sprite names).

toolaction_ON (bit 2)
  Initial state of button.

toolaction_AUTO_TOGGLE (bit 3)
  When set then the state of the button toggles every time it is pressed.

toolaction_NO_PRESSED_SPRITE (bit 4)
  Normally the ident field is expected to contain two sprite names, comma-separated. The second one is displayed by the wimp whilst the mouse button is held down. If this bit is set then this behaviour is disabled and the sprite will not be selected when pressed. This stops the wimp trying to highlight a button if no pressed version is given.

  The actual effect is that when set the validation string used is "S<ident>", when the bit is clear the validation string is "R5;S<ident>".

toolaction_AUTO_REPEAT (bit 5)
  If set then the button will auto-repeat while held down. Otherwise it will be debounced.

toolaction_SHOW_TRANSIENT (bit 6)
  If set then any attached object will be shown transiently otherwise it will be shown statically.

toolaction_SHOW_AS_POP_UP (bit 7)
  If set then any attached object will be positioned with its top left corner aligned to the top right of the gadget (ie as with a popup menu gadget).

toolaction_HAS_FADE_SPRITE (bit 8)
  If set then there is a separate sprite (or pair of sprites) to be used when the gadget is faded out. Otherwise normal wimp fading will be used.
toolaction_SELECT_WHEN_OVER (bit 9)
  If set then whenever the mouse pointer is over the icon it will be selected as if pressed. When the mouse pointer is moved off the icon it will be deselected. No event is generated.

### 5.2 Methods

#### 5.2.1 ToolAction_SetIdent (0x140140)

        On entry
    	R0 = flags
    	   Bits 0- 3: which state to set ident of
    			= 0: Off state
    			= 1: On state
    			= 2: Faded state
    			3-15: reserved
    	   Bits 4-31: reserved
    	R1 = Window object id
    	R2 = 0x140140
    	R3 = Gadget component id
    	R4 -> new ident string
        On exit
    	R1-R9 preserved
        Use

This method will set the ident strings for one of the three states. The ident strings are either the text to be displayed or the sprite name (or pair of sprite names, comma-separated) of the sprites to be displayed in this state.

#### 5.2.2 ToolAction_GetIdent (0x140141)

        On entry
    	R0 = flags
    	   Bits 0- 3: which state to get ident of
    			= 0: Off state
    			= 1: On state
    			= 2: Faded state
    			3-15: reserved
    	   Bits 4-31: reserved
    	R1 = Window object id
    	R2 = 0x140141
    	R3 = Gadget component id
    	R4 -> biffer for ident string
    	R5 = size of buffer
        On exit
    	R5 = size of buffer required for ident string
        Use

Read the ident string for the given state.

#### 5.2.3 ToolAction_SetAction (0x140142)

        On entry
    	R0 = flags
    	R1 = Window object id
    	R2 = 0x140142
    	R3 = Gadget component id
    	R4 = action code for select
    	R5 = action code for adjust
        On exit
    	R1-R9 preserved
        Use

Set the action codes to be generated when select and adjust are clicked on the gadget. No code is generated unless toolaction_GENERATE_SELECTED_EVENT is set. The default value is action_TOOL_ACTION_SELECTED (0x140140).

#### 5.2.4 ToolAction_GetAction (0x140143)

        On entry
    	R0 = flags
    	R1 = Window object id
    	R2 = 0x140143
    	R3 = Gadget component id
        On exit
    	R0 = action code for select
    	R1 = action code for adjust
        Use

Read the action codes to be generated when select and adjust are clicked on the gadget.

#### 5.2.5 ToolAction_SetClickShow (0x140144)

        On entry
    	R0 = flags
    	R1 = Window object id
    	R2 = 0x140144
    	R3 = Gadget component id
    	R4 = Object id to show on select
    	R5 = Object id to show on adjust
        On exit
    	R1-R9 preserved
        Use

Set which objects are shown on select and adjust clicks. How they are shown is set in the gadget flags and cannot currently be set afterwards.

#### 5.2.6 ToolAction_GetClickShow (0x140145)

        On entry
    	R0 = flags
    	R1 = Window object id
    	R2 = 0x140145
    	R3 = Gadget component id
        On exit
    	R0 = Object id to show on select
    	R1 = Object id to show on adjust
        Use

Set which objects are shown on select and adjust clicks. How they are shown is set in the gadget flags and cannot currently be set afterwards.

#### 5.2.7 ToolAction_SetState (0x140146)

        On entry
    	R0 = flags
    	R1 = Window object id
    	R2 = 0x140146
    	R3 = Gadget component id
    	R4 = new state
        On exit
    	R1-R9 preserved
        Use

Set the state of the gadget to on or off. The faded state should be set using the generic Gadget_Flags method.

#### 5.2.8 ToolAction_GetState (0x140147)

        On entry
    	R0 = flags
    	R1 = Window object id
    	R2 = 0x140147
    	R3 = Gadget component id
        On exit
    	R0 = state
        Use

Read the state of the gadget.

#### 5.2.9 ToolAction_SetPressed (0x140148)

        On entry
    	R0 = flags
    	R1 = Window object id
    	R2 = 0x140148
    	R3 = Gadget component id
    	R4 = new state
        On exit
    	R1-R9 preserved
        Use

Set the pressed state of the gadget.

#### 5.2.10 ToolAction_GetPressed (0x140149)

        On entry
    	R0 = flags
    	R1 = Window object id
    	R2 = 0x140149
    	R3 = Gadget component id
        On exit
    	R0 = state
        Use

Read the pressed state of the gadget.

### 5.3 ToolAction template

Field | Size in bytes | Type
--- | --- | ---
ident_off | 4 | StringReference
ident_off_limit | 4 | word
ident_on | 4 | StringReference
ident_on_limit | 4 | word
action_no | 4 | word
click_show_name | 4 | StringReference
adjust_action_no | 4 | word
adjust_click_show_name | 4 | StringReference
ident_fade | 4 | StringReference
ident_fade_limit | 4 | word

### 5.4 ToolAction actions

#### action_TOOL_ACTION_SELECTED (0x140140)

          Block
    	+8:  0x140140
    	+12: flags
    		bit 0: ADJUST button clicked
    		bit 2: SELECT button clicked
    	+16: new state of gadget

If the toolaction_GENERATE_SELECTED_EVENT bit is set in the gadget flags then this message will be sent every time the gadget is pressed. The action code can be overridden by valuse set in the gadget template or at run time.

## 6.0 Data interchange

No new data interchange protocols are defined by this specification.

## 7.0 Data formats

No new data formats are defined by this specification

## 8.0 External dependencies

There are no external dependencies.

## 9.0 Acceptance test

The module shall be able to supply all the types of buttons necessary for operation of the NCBrowser toolbar as described in the NCBrowser specification and the CIS.

## 10.0 Non compliances

There are no non-compliances.

## 11.0 Development test strategy

Buttons with different flag and sprite combinations will be created and tested using ResTest to ensure that the correct events are generated and the correct sprites displayed.

## 12.0 Product organisation

Written in C and assembler to be compiled with C release 5 and ObjAsm 2. It is built as part of the NC OS build tree and runs from ROM.

## 13.0 Future enhancements

None currently planned.

## 14.0 Glossary

API | Application Programmer Interface.
CIS | Customer Interface Specification.
NC | Network Computer.
NVRAM | Non-volatile RAM. Maintains its contents when power is off.
OS | Operating System.
PDD | Product Definition Document.
RAM | Random Access Memory.
ROM | Read Only Memory.
SWI | Software Interrupt.
UI | User Interface.
ToolBox | UI Library module.
Gadget | Window component eg a button.
ADJUST | Right mouse button
SELECT | Left mouse button
Sprite | Acorn bitmap format
ResTest | Application for testing resource files using Acorn C/C++.

## 15.0 References

NCBrowser Software Functional Specification
  Document reference 2107,702
ToolAction Software Functional Specification
  Document reference 2103,739
CIS
  NC100 Customer Interface Specification, Customer.

## 16.0 History

Revision | Who | Date | Comment
1.1 | SJM | 13-Mar-97 | Created from 2103,739 and updated for NC100.
1.2 | SJM | 26-Mar-97 | Added new document reference.
1.3 | SJM | 08-Apr-97 | Corrected dates in history, fixed typos from review.
2.1 | SR | 09-Apr-97 | Automated date field, title correction, AMR allocated, internal sign off agreed.