Toolbox

NumberRange gadget

Changes with Window 1.85

Bounding inconsistencies

The NumberRange gadget has, in the past, been a source of annoyance for developers because it has never consistently reported values of the range gadget within the bounds that have been set for it. The gadget has been updated to provide more reliable bounds to the application and to provide a useful input interface for users.

In the previous versions of the gadget, entering values into the writable field would result in an event being delivered to the application with the unbounded, raw value entered by the user. The new operation is to bound that value and reports the new value to the application if it has changed. The text of the writable field is not updated, however. The displayed value of the field is updated when the user moves from the icon if it contains a value outside the bounds. The displayed value will be forced to show a value within the bounds when the gadget's value is read.

This behaviour may appear to provoke an inconsistency between the value reported to the application. Indeed, the displayed value will differ from that which the application has received until it attempts to read the value directly. It can be seen that if the displayed value were always to be bounded then certain values for number ranges would become impossible to enter. An example of this class of impossible values could be obtained by using a lower bound of '5', upper bound of '12' and initial value of '5'. Deleting the '5' would result in an empty field, with a value of '0' - which would then be replaced immediately by '5' in order to reflect the boundaries. Thus it would be impossible to enter '10', '11', or '12' into the icon.

The actual value displayed in the NumberRange is forced to correspond to bounds under the following circumstances :

• Caret moves to another icon in the same window by keyboard navigation.
  
• Caret moves to another icon in the same window by clicking another icon.
  
• Caret moves to another icon in the same window by any application manipulating the caret .
  
• Caret moves to another icon in a different window by user clicking another icon.
  
• Caret moves to another icon in a different window by any application manipulating the caret (including the task itself, for example through Wimp_SetCaretPosition or Gadget_SetFocus).
  
• Icon is 'confirmed' by the user pressing the Return key.
  
• Application requests the value of the field using NumberRange_GetValue.
  
• Application changes the bounds of the field using NumberRange_SetBounds.
  
• Application updates the value in the field using NumberRange_SetValue.
  

'another icon' includes the '-1' case, where the icon is part of the window body.

'another window' includes the '-1' case, where the caret is associated with no window.

'any application' includes the task owning the gadget itself.

'manipulating the caret' includes the calls to Wimp_SetCaretPosition (in either its standard form, or the extended forms) and to any library provided calls which reduce to Wimp_SetCaretPosition (for example, Gadget_SetFocus).

This change affects the following composite gadgets and components :

Scale, PrintDBox, FontDBox

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015