← Back to branch summary

~ubuntu-branches/ubuntu/lucid/erlang/lucid

« back to all changes in this revision

Viewing changes to lib/gs/doc/src/gs_chapter4.xml

  • Committer: Elliot Murphy
  • Date: 2009-12-22 02:56:21 UTC
  • mfrom: (3.3.5 sid)
  • Revision ID: elliot@elliotmurphy.com-20091222025621-qv3rja8gbpiabkbe
Tags: 1:13.b.3-dfsg-2ubuntu1
* Merge with Debian testing; remaining Ubuntu changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to. (LP #438365)
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
* Fixed dialyzer(1) manpage which was placed into section 3 and conflicted
  with dialyzer(3erl).
* New upstream release (it adds a new binary package erlang-erl-docgen).
* Refreshed patches, removed most of emacs.patch which is applied upstream.
* Linked run_test binary from erlang-common-test package to /usr/bin.
* Fixed VCS headers in debian/control.
* Moved from prebuilt manpages to generated from sources. This adds
  erlang-manpages binary package and xsltproc build dependency.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/gs/doc/src/gs_chapter4.xml
1
 
<?xml version="1.0" encoding="latin1" ?>
2
 
<!DOCTYPE chapter SYSTEM "chapter.dtd">
3
 
 
4
 
<chapter>
5
 
  <header>
6
 
    <copyright>
7
 
      <year>2000</year>
8
 
      <year>2007</year>
9
 
      <holder>Ericsson AB, All Rights Reserved</holder>
10
 
    </copyright>
11
 
    <legalnotice>
12
 
  The contents of this file are subject to the Erlang Public License,
13
 
  Version 1.1, (the "License"); you may not use this file except in
14
 
  compliance with the License. You should have received a copy of the
15
 
  Erlang Public License along with this software. If not, it can be
16
 
  retrieved online at http://www.erlang.org/.
17
 
 
18
 
  Software distributed under the License is distributed on an "AS IS"
19
 
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
 
  the License for the specific language governing rights and limitations
21
 
  under the License.
22
 
 
23
 
  The Initial Developer of the Original Code is Ericsson AB.
24
 
    </legalnotice>
25
 
 
26
 
    <title>Events</title>
27
 
    <prepared></prepared>
28
 
    <docno></docno>
29
 
    <date></date>
30
 
    <rev></rev>
31
 
  </header>
32
 
 
33
 
  <section>
34
 
    <title>Event Messages</title>
35
 
    <p>Events are messages which are sent to the owner process of the object when the user interacts with the object in some way. A simple case is the user pressing a button. An event is then delivered to the owner process of the button (the process that created the button).  In the following example, the program creates a button object and enables the events click and enter. This example shows that events are enabled in the same way as objects are configured with options.</p>
36
 
    <p></p>
37
 
    <code type="none"><![CDATA[
38
 
B = gs:create(button,Win, [{click,true},{enter,true}]),
39
 
event_loop(B).
40
 
    ]]></code>
41
 
    <p>The process is now ready to receive click and enter events from the button. The events delivered are always five tuples and consist of:</p>
42
 
    <code type="none"><![CDATA[
43
 
{gs, IdOrName, EventType, Data, Args}
44
 
    ]]></code>
45
 
    <list type="bulleted">
46
 
      <item><c><![CDATA[gs]]></c> is a tag which says it is an event from the <c><![CDATA[gs]]></c> graphics server.</item>
47
 
      <item><c><![CDATA[IdOrName]]></c> contains the object identifier or the name of the object in which the event occurred.</item>
48
 
      <item><c><![CDATA[EventType]]></c> contains the type of event which has occurred. In the example shown, it  is either <c><![CDATA[click]]></c> or <c><![CDATA[enter]]></c>.</item>
49
 
      <item><c><![CDATA[Data]]></c> is a field which the user can set to any Erlang term. It is very useful to have the object store arbitrary data which is delivered with the event.</item>
50
 
      <item><c><![CDATA[Args]]></c> is a list which contains event specific information. In a motion event, the Args argument would contain the x and y coordinates.</item>
51
 
    </list>
52
 
    <p>There are two categories of events:</p>
53
 
    <list type="bulleted">
54
 
      <item><em>generic events</em></item>
55
 
      <item><em>object specific events</em>.</item>
56
 
    </list>
57
 
  </section>
58
 
 
59
 
  <section>
60
 
    <title>Generic Events</title>
61
 
    <p>Generic events are the same for all types of objects. The following table shows a list of generic event types which the graphics server can send to 
62
 
      a process. For generic events, the <c><![CDATA[Args]]></c> argument always contains the same data, independent of which object delivers it.</p>
63
 
    <p>The following sub-sections explains the event types and what they are used for.</p>
64
 
    <table>
65
 
      <row>
66
 
        <cell align="left" valign="middle"><em>Event</em></cell>
67
 
        <cell align="left" valign="middle"><em>Args</em></cell>
68
 
        <cell align="left" valign="middle"><em>Description</em></cell>
69
 
      </row>
70
 
      <row>
71
 
        <cell align="left" valign="middle">buttonpress</cell>
72
 
        <cell align="left" valign="middle">[ButtonNo,X,Y|_]</cell>
73
 
        <cell align="left" valign="middle">A mouse button was pressed over the object.</cell>
74
 
      </row>
75
 
      <row>
76
 
        <cell align="left" valign="middle">buttonrelease</cell>
77
 
        <cell align="left" valign="middle">[ButtonNo,X,Y|_]</cell>
78
 
        <cell align="left" valign="middle">A mouse button was released over the object. </cell>
79
 
      </row>
80
 
      <row>
81
 
        <cell align="left" valign="middle">enter</cell>
82
 
        <cell align="left" valign="middle">[]</cell>
83
 
        <cell align="left" valign="middle">Delivered when the mouse pointer enters the objects area.</cell>
84
 
      </row>
85
 
      <row>
86
 
        <cell align="left" valign="middle">focus</cell>
87
 
        <cell align="left" valign="middle">[Int|_]</cell>
88
 
        <cell align="left" valign="middle">Keyboard focus has changed. 0 means lost focus. 1 means gained focus.</cell>
89
 
      </row>
90
 
      <row>
91
 
        <cell align="left" valign="middle">keypress</cell>
92
 
        <cell align="left" valign="middle">[KeySym,Keycode, Shift, Control|_]</cell>
93
 
        <cell align="left" valign="middle">A key has been pressed. </cell>
94
 
      </row>
95
 
      <row>
96
 
        <cell align="left" valign="middle">leave</cell>
97
 
        <cell align="left" valign="middle">[]</cell>
98
 
        <cell align="left" valign="middle">Mouse pointer leaves the object.</cell>
99
 
      </row>
100
 
      <row>
101
 
        <cell align="left" valign="middle">motion</cell>
102
 
        <cell align="left" valign="middle">[X,Y|_]</cell>
103
 
        <cell align="left" valign="middle">The mouse pointer is moving in the object. Used when tracking the mouse in a window.</cell>
104
 
      </row>
105
 
      <tcaption>Generic Event Types</tcaption>
106
 
    </table>
107
 
 
108
 
    <section>
109
 
      <title>The Buttonpress and Buttonrelease Events</title>
110
 
      <p>These events are generated when a mouse button is pressed or released inside the object frame of a window, or frame object type. The button events are not object specific (compare to click). The format of the buttonpress event is:</p>
111
 
      <code type="none"><![CDATA[
112
 
{gs,ObjectId,buttonpress,Data,[MouseButton,X,Y|_]}
113
 
      ]]></code>
114
 
      <p>The mouse button number which was pressed is the first argument in the <c><![CDATA[Args]]></c> field list. This number is either 1, 2 or 3, if you have a three button mouse. The <c><![CDATA[X]]></c> and <c><![CDATA[Y]]></c> coordinates are sent along to track in what position the user pressed down the button. These events are useful for programming things like "rubberbanding", which is to draw out an area with the mouse. In detail, this event can be described as pressing the mouse button at a specific coordinate and releasing it at another coordinate in order to define a rectangular area. This action is often used in combination with motion events.</p>
115
 
    </section>
116
 
 
117
 
    <section>
118
 
      <title>The Enter and Leave Events</title>
119
 
      <p>These events are generated when the mouse pointer (cursor) enters or leaves an object.</p>
120
 
    </section>
121
 
 
122
 
    <section>
123
 
      <title>The Focus Event</title>
124
 
      <p>The focus event tracks which object currently holds the keyboard focus. Only one object at a time can hold the keyboard focus. To have the keyboard focus means that all keypresses from the keyboard will be delivered to that object. The format of a focus event is:</p>
125
 
      <code type="none"><![CDATA[
126
 
{gs,ObjectId,focus, Data,[FocusFlag|_]}
127
 
      ]]></code>
128
 
      <p>The FocusFlag argument is either 1, which means that the object has gained keyboard focus, or 0, which means that the object has lost keyboard focus.</p>
129
 
    </section>
130
 
 
131
 
    <section>
132
 
      <title>The Keypress Event</title>
133
 
      <p>This event is generated by an object which receives text input from the user, like entry objects. It can also be generated by window objects. The format of a keypress event is:</p>
134
 
      <code type="none"><![CDATA[
135
 
{gs,ObjectId,keypress,Data,[Keysym,Keycode,Shift,Control|_]}
136
 
      ]]></code>
137
 
      <p>The <c><![CDATA[Keysym]]></c> argument is either the character key which was pressed, or a word which describes which key it was. Examples of <c><![CDATA[Keysyms]]></c> are; <c><![CDATA[a]]></c>,<c><![CDATA[b]]></c>,<c><![CDATA[c]]></c>.., 1,2,3..., <c><![CDATA['Return']]></c>, <c><![CDATA['Delete']]></c>, <c><![CDATA['Insert']]></c>, <c><![CDATA['Home']]></c>, <c><![CDATA['BackSpace']]></c>, <c><![CDATA['End']]></c>.  The <c><![CDATA[Keycode]]></c> argument is the keycode number for the key that was pressed. Either the <c><![CDATA[Keysym]]></c> or the <c><![CDATA[Keycode]]></c> argument can be used to find out which key was pressed.  The <c><![CDATA[Shift]]></c> argument contains either a 0 or a 1 to indicate if the Shift key was held down when the character key was pressed. The Control argument is similar to the Shift key argument, but applies to the Control key instead of the Shift key.</p>
138
 
    </section>
139
 
 
140
 
    <section>
141
 
      <title>The Motion Event</title>
142
 
      <p>The motion event is used to track the mouse position in a window. When the user moves the mouse pointer (cursor) to a new position a motion event is generated. The format of a motion event is:</p>
143
 
      <code type="none"><![CDATA[
144
 
{gs,ObjectId,motion,Data,[X,Y|_]}
145
 
      ]]></code>
146
 
      <p>The current x and y coordinates of the cursor are sent along in the <c><![CDATA[Args]]></c> field.</p>
147
 
    </section>
148
 
  </section>
149
 
 
150
 
  <section>
151
 
    <title>Object Specific Events</title>
152
 
    <p>The click and doubleclick events are the object specific event types. Only some objects have these events and the <c><![CDATA[Args]]></c> field of the events vary for different type of objects. A click on a check button generates a click event where the data field contains the on/off value of the indicator. On the other hand, the click event for a list box contains information on which item was chosen.</p>
153
 
    <table>
154
 
      <row>
155
 
        <cell align="left" valign="middle"><em>Event</em></cell>
156
 
        <cell align="left" valign="middle"><em>Args</em></cell>
157
 
        <cell align="left" valign="middle"><em>Description</em></cell>
158
 
      </row>
159
 
      <row>
160
 
        <cell align="left" valign="middle">click</cell>
161
 
        <cell align="left" valign="middle">&lt;object specific&gt;</cell>
162
 
        <cell align="left" valign="middle">Pressing a button or operating on a object in some predefined way. </cell>
163
 
      </row>
164
 
      <row>
165
 
        <cell align="left" valign="middle">double-click</cell>
166
 
        <cell align="left" valign="middle">&lt;object specific&gt;</cell>
167
 
        <cell align="left" valign="middle">Pressing the mouse button twice quickly. Useful with list boxes.</cell>
168
 
      </row>
169
 
      <tcaption>Object Specific Events</tcaption>
170
 
    </table>
171
 
  </section>
172
 
 
173
 
  <section>
174
 
    <title>Matching Events Against Object Identifiers</title>
175
 
    <p>Events can be matched against the object identifier in the receive statement. The disadvantage of matching against identifiers is that the program must pass the object identifiers as arguments to the event loop.</p>
176
 
    <codeinclude file="examples/ex3.erl" tag="" type="erl"></codeinclude>
177
 
  </section>
178
 
 
179
 
  <section>
180
 
    <title>Matching Events Against Object Names</title>
181
 
    <p>Another solution is to name the objects using the <c><![CDATA[create/4]]></c> function. In this way, the program does not have to pass any parameters which contain object identifiers for each function call made.</p>
182
 
    <codeinclude file="examples/ex4.erl" tag="" type="erl"></codeinclude>
183
 
  </section>
184
 
 
185
 
  <section>
186
 
    <title>Matching Events Against the Data Field</title>
187
 
    <p>A third solution is to set the <c><![CDATA[data]]></c> option to some value and then match against this value. All built-in objects have an option called <c><![CDATA[data]]></c> which can be set to any Erlang term. For example, we could set the data field to a tuple <c><![CDATA[{Mod, Fun,Args}]]></c> and have the receiving function make an <c><![CDATA[apply]]></c> on the contents of the data field whenever certain events arrive.</p>
188
 
    <codeinclude file="examples/ex5.erl" tag="" type="erl"></codeinclude>
189
 
  </section>
190
 
 
191
 
  <section>
192
 
    <title>Experimenting with Events</title>
193
 
    <p>A good way of learning how events work is to write a short demo program like the one shown below and test how different events work.</p>
194
 
    <codeinclude file="examples/ex6.erl" tag="" type="erl"></codeinclude>
195
 
  </section>
196
 
</chapter>
197