Return to Reference Manual Table of Contents.

Return to Chapter 21 Section List

Flyweight Text Entry Fields

In the section above, an approach was presented for creating numeric text entry objects using relation rules. In this approach, each such object was a group that included a text primitive and a borderless rectangle. The group had three rules that controlled whether the text entry object was active, and that determined the textual and numerical value of the entry. The text primitive had a rule for its TextValue attribute, and the rectangle had a rule for its FillColor attribute.

The approach outlined in that section works very well. It is convenient to make new versions of the object, simply by duplicating. The approach is not the ideal one, however, if there are a large number of text entry fields in a simulation. If a simulation has 500 such textual entry fields, then using the approach will result in 2500 relation rules just for handling text entry.

When there are a large number of text entry fields in a RIDES simulation, it is better to use the flyweight text entry fields described in this section. This can result in a much smaller file size and a much smaller run-time image. The key to the flyweight approach is to use two general-purpose simulation events that know how to handle activating clicks in text entry fields and keypresses when text entry fields have been made active. These events work in conjunction with objects whose names include a special substring. In the examples referred to below, the events work with objects whose names end in 'register' and that have a TextValue attribute. A set of attributes on the .sys. scene are used to store interim values for the active text entry field. An event stuffs the new values that are typed into the field object's TextValue attribute.

Two examples

Two RIDES example files, textRegisters and numRegisters, provide examples of the flyweight approach. In these example flyweight approaches to text entry, a new field is created by creating a text primitive and giving the object a name that ends in 'register'. If a highlighting background is desired, the author creates a shape (such as a rectangle, which may be borderless or not) and gives it a name that starts the same as the name of the text object but ends in 'back'.

Two events, keyEntry_setFocus and keyEntry_keyPress handle a text register. A text register is defined as
  1. An object with a name that ends in 'register' (e.g., power_register) that has an attribute TextValue of the text type
  2. Optionally, a graphical primitive, such as a box, that has the same name as the register with 'back' appended (e.g., power_registerback).

Seven new attributes must be created for the .sys. scene. These attributes are used to hold interim values required by the events.
The two examples, textRegisters and numRegisters, show the flyweight technique at work. In textRegisters, the fields accept any type of text. In the numRegisters example, only numbers can be entered into the entry fields. The details of user interaction are different in the two examples. An author can adapt these examples to create the type of data entry behavior required for a specific application.

User interactions in the textRegisters example
In this example, entering text in a field can be canceled and its previous state restored by typing the backspace key when the field is empty.

User interactions in the numRegisters example


Some simulation developers might want to group the text object with its background object. Grouping these elements has the disadvantage that either the group must carry a copy of the text, which is wasteful, or references to the text in the group must go through an additional path part, which is ugly. Furthermore, the space saving character of the flyweight approach would be compromised by creating a new grouped object (with its attendant intrinsic attributes) for every such text entry field.

An author can use Copy and Paste to adopt the flyweight approaches from one of the two examples. The seven new .sys. attributes can be copied to the .sys. scene of the destination rides document. The two events can then also be copied and pasted.

If a simulation has 500 text entry fields, the flyweight approach will result in a file size reduction of approximately 600K to 900K. Run-time savings are likely to be even more significant. If an author needs a large number of data entry fields, the flyweight approach should be utilized.

Go to Appendix A: Environment Defaults

Return to Chapter 21 Section List

Return to Reference Manual Table of Contents