Chapter 4 Using Activities in ADL

4.2 Using Notification Request Objects

Using the Pressed attribute gives rise to some limitations. First, application developers frequently want a button to trigger a number of different actions, yet the Pressed attribute can send a message to a single method only. If you reset the Pressed member of a button, you lose the old setting. Second, the method that receives a message from the Pressed method cannot have arguments. This makes it impossible to provide the method receiving the message information such as the (x,y) coordinates of the mouse at the time the event occurs. In AM2, these more general uses of activities are supported through the use of Notification Request Objects, or NROs.

There are standard NRO classes provided in AM2.[11] Some are system-defined and some are user-defined (see Section 3.23, "Wrapped Classes" page 44 for a discussion of classes.) With the exception of NROs used to handle timer events (described in Section 4.3.2, "Timer NROs" page 67) an NRO is an object that has the following four members:

Note that the second and third of the NRO members on the list above are identical to the members used in setting the Pressed attribute of button objects.

The base NRO class is the Nro wrapped class. It has a special constructor named Create that takes the four arguments listed above. The following example defines an instance of an NRO for an activity named MouseDown. This NRO requests that the message ButtonDown go to the target object self along with the string "ClientData" as an argument:

Nro {'Create, 'MouseDown, self, 'ButtonDown, "Client data"} => downNro;

Each object that manages an activity must have at least two methods: Subscribe and Unsubscribe. These methods have as their sole argument a handle to an NRO. The Subscribe method registers the NRO for notification when an event triggers the activity named in that NRO. For example, suppose you created an NRO named downNro as shown above. The following statement would subscribe that NRO to the button named myButton:

{'Subscribe, &downNro} => myButton;

After this statement executes, downNro is registered with the MouseDown activity of the button object. Whenever the user clicks the mouse on that button, the message ButtonDown goes to the object pointed to by self.

The Subscribe method actually returns a value that is often ignored by ADL programmers. This value is a handle that indicates whether or not the subscription successfully completed. The return value is NULL if the subscription is not performed and a handle to the subscribed NRO otherwise.

The Nro class assumes that the receiving method has three arguments in the following order:

For example, the MouseDown activity (and all other standard activities that describe mouse events) provides six pieces of information when it sends its message to the target method. These six items in the lists of keys and values are as follows:

1. x: an integer giving the x location of the mouse when the user presses the mouse button

2. y: an integer giving the y location of the mouse when the user presses the mouse button

3. button: an integer with the number of the pressed button on the mouse (The interpretation of this number is platform-dependent.)

4. shift: a boolean that is TRUE if the shift key is down when the user presses the mouse button

5. command: a boolean that is TRUE if the key designated as the command key is down when the user presses the mouse button (The definition of the key that corresponds to the command key is platform-dependent.)

6. modifier: a boolean that is TRUE if a key designated as a modifier key is down when the user presses the mouse button (The interpretation of the key that corresponds to the modifier key is platform-dependent.)

It is important to note that the (x,y) coordinates returned by any mouse activity are given relative to the upper left corner of the widget where the mouse event occurred.

An example of an ADL program that includes a method with the appropriate arguments follows. In this example, the method named ButtonDown outputs the names and values of the arguments it receives.
An Example Using an NRO
anonymous:XFtop

{

XFbutton myButton {x=50; y=50; height=50; width=150;

recomputeSize=FALSE; label="Press Here";};

XFbutton exitButton {x=250; y=50; height=50; width=100;

recomputeSize = FALSE; label="Exit";};

Nro {'Create, 'MouseDown, self, 'ButtonDown,

"Client data"} => downNro;

upon Construct

{

exitButton.Pressed = {'Exit, theApp};

{'Subscribe, &downNro} => myButton;

}

on ButtonDown: any clientData, list keys, list values

{

any tempValue;

integer count=1;

echo("Client data is" & toString(clientData)+"\n");

while (count <= length(keys)) {

echo("Name="+toString(at(count, keys)) &

"Value=" + toString(at(count, values))+"\n");

count = count+1;

}

}

} myApplication {height=300; width=400;};

In Figure 4.3, the NRO named downNro subscribes to the button myButton. When the user presses the mouse button, the method ButtonDown receives a message. This method outputs the client data (in this case, the string "Client data") from the NRO and then outputs the name and value pairs by going through the entries on the list one by one.

A typical output from this application is as follows:

Client data is Client data
Name=x Value=27
Name=y Value=24
Name=button Value=1
Name=shift Value=TRUE
Name=command Value=TRUE
Name=modifier Value=FALSE

Note that in this example, the shift and control keys are held when the button is pushed down. Also, the (x,y) coordinates sent when an event triggers the activity are with respect to the upper left corner of the object managing the activity, which in this case is the button.

[11] NRO wrapped classes are the only current exception to the conventionthat wrapped class names begin with two capital letters. The NRO classes could have been given the names NRgeneral, NRtimer, NRmouse -- but they weren't. No one remembers why. Instead they bear the slightly more readable names Nro, TimerNro and MouseNro.
AM2 Documentation - 19 NOV 1996

Generated with Harlequin WebMaker