1 ToolAction Functional Specification

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

FieldSize in bytesType
ident_off4StringReference
ident_off_limit4word
ident_on4StringReference
ident_on_limit4word
action_no4word
click_show_name4StringReference
adjust_action_no4word
adjust_click_show_name4StringReference
ident_fade4StringReference
ident_fade_limit4word

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.