|
1 <?xml version="1.0" encoding="UTF-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|
2 <html lang="en" xml:lang="en"> |
|
3 <head> |
|
4 <meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> |
|
5 <meta name="copyright" content="(C) Copyright 2005" /> |
|
6 <meta name="DC.rights.owner" content="(C) Copyright 2005" /> |
|
7 <meta content="concept" name="DC.Type" /> |
|
8 <meta name="DC.Title" content="Handling events" /> |
|
9 <meta scheme="URI" name="DC.Relation" content="WRTKit_Common_WRTKit_tasks-GUID-24870895-4449-4307-9a54-7c90f7b3905e.html" /> |
|
10 <meta content="XHTML" name="DC.Format" /> |
|
11 <meta content="GUID-A1A86C8A-6E66-4DC8-8967-B5C9C7BC6563" name="DC.Identifier" /> |
|
12 <meta content="en" name="DC.Language" /> |
|
13 <link href="commonltr.css" type="text/css" rel="stylesheet" /> |
|
14 <title> |
|
15 Handling events</title> |
|
16 </head> |
|
17 <body id="GUID-A1A86C8A-6E66-4DC8-8967-B5C9C7BC6563"><a name="GUID-A1A86C8A-6E66-4DC8-8967-B5C9C7BC6563"><!-- --></a> |
|
18 |
|
19 |
|
20 |
|
21 <h1 class="topictitle1"> |
|
22 Handling events</h1> |
|
23 |
|
24 <div> |
|
25 |
|
26 <p> |
|
27 |
|
28 Event handling in the WRTKit is based on the "observer pattern", |
|
29 meaning that events are reported from the event source to observers |
|
30 that are said to be "listening" to event notifications. An event |
|
31 listener is simply a JavaScript function that takes a single |
|
32 argument: the event message. In fact even that single argument is |
|
33 optional and if the function is not interested in the event message |
|
34 then it can simply ignore it. |
|
35 </p> |
|
36 |
|
37 <p> |
|
38 |
|
39 All views and controls inherit from a common base class called |
|
40 "UIElement" that defines the mechanics for event observation and |
|
41 notification. From the point of view of event listeners, the most |
|
42 important methods are addEventListener() and removeEventListener(). |
|
43 These two methods are used to register and unregister listener |
|
44 functions from a view or control. |
|
45 </p> |
|
46 |
|
47 <p> |
|
48 |
|
49 There are different types of events though, and event listeners are |
|
50 typically not interested in receiving notifications of all events. |
|
51 For example an event listener that wants to know when a button has |
|
52 been pressed doesn't usually care if the pointer is currently |
|
53 hovering above the button or not. Filtering of event notifications |
|
54 works based on event type names. E.g. in this case the event |
|
55 listener would have been added so that it should be called only for |
|
56 events of the "ActionPerformed" type. The event type is given to the |
|
57 addEventListener() function when a listener is registered. If a |
|
58 listener function really wants to be notified of all event types |
|
59 then null can be specified as the event type. Note that the event |
|
60 type must also be specified when an event listener is unregistered. |
|
61 </p> |
|
62 |
|
63 <p> |
|
64 |
|
65 The code below shows a typical event listener function: |
|
66 </p> |
|
67 |
|
68 <pre> |
|
69 |
|
70 // Callback for event notifications. |
|
71 function handleEvent(event) { |
|
72 // handle event here |
|
73 } |
|
74 </pre> |
|
75 |
|
76 <p> |
|
77 |
|
78 The event message is passed to the first argument (called event in |
|
79 this case) of the event handler function. The event message is a |
|
80 JavaScript object with three properties: type, source and value. The |
|
81 type property specifies the event type name and is useful if a |
|
82 listener function is listening to several types of events. The |
|
83 source argument is a reference to the source view or control that |
|
84 sent out the event notification. If a listener function is listening |
|
85 to events from many different controls then this is useful to figure |
|
86 out in which of the controls the event occurred. Here the unique |
|
87 identifier of views and controls can come in handy to identify the |
|
88 source without needing to retain references to all the source |
|
89 controls. Finally the value property is a event-type specific |
|
90 property that contains some information about the event. For example |
|
91 if the event type is "TextChanged" from a text entry control then |
|
92 the value would be the new text value that the user has typed into |
|
93 the control. |
|
94 </p> |
|
95 |
|
96 <p> |
|
97 |
|
98 The code below demonstrates how to add and remove an event listener |
|
99 to/from a control. The example assumes that the control has already |
|
100 been created and that the ctrl variable refers to it. |
|
101 </p> |
|
102 |
|
103 <pre> |
|
104 |
|
105 // add listener to ctrl |
|
106 // function to add is handleEvent() for event type "ActionPerformed" |
|
107 ctrl.addEventListener("ActionPerformed", handleEvent); |
|
108 |
|
109 // remove listener from ctrl |
|
110 // function to remove is handleEvent() for event type "ActionPerformed" |
|
111 ctrl.removeEventListener("ActionPerformed", handleEvent); |
|
112 </pre> |
|
113 |
|
114 </div> |
|
115 |
|
116 <div> |
|
117 <div class="familylinks"> |
|
118 <div class="parentlink"><strong>Parent topic:</strong> <a href="WRTKit_Common_WRTKit_tasks-GUID-24870895-4449-4307-9a54-7c90f7b3905e.html">Common WRTKit tasks</a></div> |
|
119 </div> |
|
120 </div> |
|
121 |
|
122 </body> |
|
123 </html> |