class references.Ref

Class Ref is the basis of a system for dynamically linking Control classes with values to be displayed and edited. An instance of Ref is used as a starting point for constructing reference objects. There are a number of different kinds of reference objects, depending on whether the underlying value is accessed through an attribute, item index or method call. All of these reference objects present a common interface, consisting of get() and set() methods, that the Control uses to access the value whenever it needs to display or update it.

The simplest way of using Ref is illustrated by the following example:
velocity_ref = Ref(vehicle).velocity
velocity_ctrl = IntField(ref = velocity_ref)
Here, the expression Ref(vehicle) creates a reference source object from which reference objects can be derived. Accessing the velocity attribute of this object creates an attribute reference object that refers to the velocity attribute of the vehicle. This attribute reference object is then attached to an IntField. The result is that the IntField will always display the current value of the vehicle's velocity attribute, and if the user enters a new value into the field, vehicle's velocity attribute will be updated.

Reference objects can themselves be a source for further reference objects. Suppose you have a multi-player turn-taking game, and you want to display information about the player whose turn it is next. You might create a reference object like this:
score_ref = Ref(world).current_game.current_player.score
Here we assume that world is a global object that doesn't change, but a game object is created each time a new game starts, and its current_player attribute switches around as the game is played. This statement creates a chain of reference objects culminating in an attribute reference for the attribute called score. Each time the get() or set() method of this reference object is called, the corresponding chain of attribute lookups is performed anew. So, if we attach our score_ref to a control, it will always display the score of the current player of the current game, whatever those objects happen to be.

As well as attribute access, indexing and calling can also be performed on a reference source:
ref_source[index] produces an item reference object that accesses an item of a sequence or mapping.
ref_source(args) produces a call reference object that performs a call when its get() method is called. This kind of reference object is read-only (but it can be used as a source of further reference objects that are read-write).

Constructor

Ref(base)
Creates a reference source object based on the given object. Reference objects can be derived from this reference source using the operations listed below.

Reference source operations

ref_source.attribute
Returns a reference object that reads and writes the specified attribute of its base object.

ref_source[index]
Returns a reference object that reads and writes the specifed item of its base object.

ref_source(arg, ...)
Returns a reference object that calls its base object with the specified arguments. This reference object is read-only, i.e. only its get() method may be used. However, read-write reference objects can be derived from it using attribute access or indexing.

+ref_source
Converts a reference to a callable object into an object that can itself be called. Arguments are passed on to the underlying callable, A typical use is to specify the action property of a button using a reference. For example,

Button("Launch", action = +Ref(game).current_player.launch_missile)

creates a button that performs game.current_player.launch_missile() when clicked.

Note that the object returned by this operation is not a reference source.

Reference object methods

Reference objects created from reference sources have the following methods. Every reference object is also a reference source, so the above reference source operations may also be applied to them.
get()
Returns the current value of the referenced attribute or item, or in the case of a call reference, calls the referenced callable object.

set(value)
Sets the value of the referenced attribute or item.

---