/usr/share/mozart/doc/wp/node24.html is in mozart-doc 1.4.0-8ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE>5.5 Events</TITLE><LINK href="ozdoc.css" rel="stylesheet" type="text/css"></HEAD><BODY><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node23.html#section.widgets-2.menu"><< Prev</A></TD><TD><A href="node19.html">- Up -</A></TD><TD><A href="node25.html#section.widgets-2.action">Next >></A></TD></TR></TABLE><DIV id="section.widgets-2.events"><H2><A name="section.widgets-2.events">5.5 Events</A></H2><DIV class="apropos"><P class="margin">binding to events</P><P> Button widgets allow to specify an action which is invoked when the button is pressed. This is only one particular example of attaching an action to an event. The Tk toolkit allows to attach actions to any widget with the method <CODE>tkBind</CODE>. To attach an action to an event we refer to as <A name="label229"></A><EM>binding the action to the event</EM>. The action is invoked when some event occurs. Examples for events are to move the mouse pointer within a widget, or to press a mouse button when the mouse pointer is over a widget. Actions can be given arguments. The arguments depend on the type of the event, e. g., arguments can be the coordinates of the mouse pointer. </P></DIV><P> Let us look to the example from the previous section. There we created a menu widget <CODE>M1</CODE> and a toplevel widget <CODE>T</CODE>. Now we want that the menu widget is posted if the mouse button is pressed over the toplevel widget <CODE>T</CODE>. Additionally, we want the menu to get posted at the position of the mouse pointer when the mouse button was pressed. </P><DIV class="apropos"><P class="margin">event patterns</P><P> The program in <A href="node24.html#figure.widgets-2.event-menu">Figure 5.5</A> does what we want: <CODE><SPAN class="string">'<Button-1>'</SPAN></CODE> for the <CODE>event</CODE> option is the so-called <A name="label230"></A><EM>event pattern</EM>. The value for the <CODE>args</CODE> option describes that the action should invoked with two arguments. The first (second) one should be an integer giving the <I>x</I> (<I>y</I>) coordinate of the mouse pointer within the widget when the mouse button has been pressed. The <CODE>action</CODE> procedure pops up the menu widget at exactly the screen coordinates. These are computed from the coordinates of the upper left edge of the toplevel widget and the event arguments. </P><DIV id="figure.widgets-2.event-menu"><HR><P><A name="figure.widgets-2.event-menu"></A></P><A name="label232"></A><A name="label234"></A><DL class="anonymous"><DD class="code"><CODE>{W tkBind(event: <SPAN class="string">'<Button-1>'</SPAN> <BR> args: [int(x) int(y)]<BR> action: <SPAN class="keyword">proc</SPAN><SPAN class="variablename"> </SPAN>{<SPAN class="functionname">$</SPAN> X Y}<BR> TX={Tk<SPAN class="keyword">.</SPAN>returnInt winfo(rootx W)}<BR> TY={Tk<SPAN class="keyword">.</SPAN>returnInt winfo(rooty W)}<BR> <SPAN class="keyword">in</SPAN> <BR> {Tk<SPAN class="keyword">.</SPAN>send tk_popup(M1 X<SPAN class="keyword">+</SPAN>TX Y<SPAN class="keyword">+</SPAN>TY)}<BR> <SPAN class="keyword">end</SPAN>)}</CODE></DD></DL><P class="caption"><STRONG>Figure 5.5:</STRONG> Action to popup menu.</P><HR></DIV><P> </P></DIV><H3><A name="label235">5.5.1 Event Patterns</A></H3><P> An event pattern is either a string consisting of a single character, where the character must be different from the space character and <CODE><SPAN class="keyword"><</SPAN></CODE>. This event pattern matches a <CODE>KeyPress</CODE> event for that character. </P><P> Otherwise, an event pattern must be a string </P><BLOCKQUOTE class="code"><CODE><SPAN class="string">'<'</SPAN><SPAN class="keyword">#</SPAN></CODE><CODE><I>Modifier</I></CODE><CODE><SPAN class="keyword">#</SPAN><SPAN class="string">'-'</SPAN><SPAN class="keyword">#</SPAN></CODE><CODE><I>Modifier</I></CODE><CODE><SPAN class="keyword">#</SPAN><SPAN class="string">'-'</SPAN><SPAN class="keyword">#</SPAN></CODE><CODE><I>Type</I></CODE><CODE><SPAN class="keyword">#</SPAN><SPAN class="string">'-'</SPAN><SPAN class="keyword">#</SPAN></CODE><CODE><I>Detail</I></CODE><CODE><SPAN class="keyword">#</SPAN><SPAN class="string">'>'</SPAN></CODE></BLOCKQUOTE><P> where only one of either <CODE><I>Type</I></CODE> or <CODE><I>Detail</I></CODE> is mandatory. This means, for example that also </P><BLOCKQUOTE class="code"><CODE><SPAN class="string">'<'</SPAN><SPAN class="keyword">#</SPAN></CODE><CODE><I>Type</I></CODE><CODE><SPAN class="keyword">#</SPAN><SPAN class="string">'>'</SPAN></CODE></BLOCKQUOTE><P> or </P><BLOCKQUOTE class="code"><CODE><SPAN class="string">'<'</SPAN><SPAN class="keyword">#</SPAN></CODE><CODE><I>Detail</I></CODE><CODE><SPAN class="keyword">#</SPAN><SPAN class="string">'>'</SPAN></CODE></BLOCKQUOTE><P> are valid event patterns. </P><DIV class="apropos"><P class="margin">event modifiers and types</P><P> <A href="node24.html#figure.widgets-2.event-args2">Figure 5.6</A> shows common event modifiers and event types. Multiple entries separated by commas can be used as synonyms. The full set of modifiers and types is described in <A href="../tcltk/TkCmd/bind.htm"><KBD>bind</KBD></A>. </P><DIV id="figure.widgets-2.event-args2"><HR><P><A name="figure.widgets-2.event-args2"></A></P><P> </P><TABLE align="center" bgcolor="#f0f0e0" id="table.widgets-2.event"><TR valign="top"><TH colspan="5"><P>Event Modifier</P></TH></TR><TR valign="top"><TD><P><CODE>Control</CODE></P></TD><TD><P><CODE>Shift</CODE></P></TD><TD><P><CODE>Lock</CODE></P></TD><TD><P><CODE>Meta</CODE></P></TD><TD><P><CODE>Alt</CODE></P></TD></TR><TR valign="top"><TD><P><CODE>Button1</CODE>, <CODE>B1</CODE></P></TD><TD><P><CODE>Button2</CODE>, <CODE>B2</CODE></P></TD><TD><P><CODE>Button3</CODE>, <CODE>B3</CODE></P></TD><TD><P><CODE>Button4</CODE>, <CODE>B4</CODE></P></TD><TD><P><CODE>Button5</CODE>, <CODE>B5</CODE></P></TD></TR><TR valign="top"><TD><P><CODE>Double</CODE></P></TD><TD><P><CODE>Triple</CODE></P></TD><TD><P> </P></TD><TD><P> </P></TD><TD><P> </P></TD></TR></TABLE><P> </P><TABLE align="center" bgcolor="#f0f0e0"><TR valign="top"><TH><P>Event Type</P></TH><TH><P>Description</P></TH></TR><TR valign="top"><TD><P><CODE>Key</CODE>, <CODE>KeyPress</CODE></P></TD><TD><P>key has been pressed</P></TD></TR><TR valign="top"><TD><P><CODE>KeyRelease</CODE></P></TD><TD><P>key has been released</P></TD></TR><TR valign="top"><TD><P><CODE>Button</CODE>, <CODE>ButtonPress</CODE></P></TD><TD><P>mouse button has been pressed</P></TD></TR><TR valign="top"><TD><P><CODE>ButtonRelease</CODE></P></TD><TD><P>mouse button has been released</P></TD></TR><TR valign="top"><TD><P><CODE>Enter</CODE></P></TD><TD><P>mouse pointer has entered a widget</P></TD></TR><TR valign="top"><TD><P><CODE>Leave</CODE></P></TD><TD><P>mouse pointer has left a widget</P></TD></TR><TR valign="top"><TD><P><CODE>Motion</CODE></P></TD><TD><P>mouse pointer has been moved within widget</P></TD></TR></TABLE><P> </P><P class="caption"><STRONG>Figure 5.6:</STRONG> Some event modifiers and types.</P><HR></DIV><P> </P></DIV><P> For example, the event pattern </P><BLOCKQUOTE class="code"><CODE><SPAN class="string">'<Shift-Double-Button>'</SPAN></CODE></BLOCKQUOTE><P> matches the event that a mouse button is double-clicked while the shift key is pressed. </P><P> If the event is <CODE>ButtonPress</CODE> or <CODE>ButtonRelease</CODE>, <CODE><I>Detail</I></CODE> may be the number of a mouse button. The number must be between <CODE>1</CODE> and <CODE>5</CODE>, where <CODE>1</CODE> is the leftmost button. The number as detail means that only events from pressing or releasing this particular button match. If no detail is given, pressing or releasing any button matches the event. If a number is given as detail, <CODE>ButtonPress</CODE> can be omitted, e. g., <CODE><ButtonPress-1></CODE> and <CODE><1></CODE> match the same events. </P><P> If the event is <CODE>KeyPress</CODE> or <CODE>KeyRelease</CODE>, <CODE><I>Detail</I></CODE> may be the specification of a key-symbol, e. g., <CODE>comma</CODE> for the <SPAN class="key">,</SPAN> key. For more information please consult <A href="../tcltk/TkCmd/bind.htm"><KBD>bind</KBD></A>. </P><DIV id="section.widgets-2.event-args"><H3><A name="section.widgets-2.event-args">5.5.2 Event Arguments</A></H3><P> The <CODE>args</CODE> option of the <CODE>tkBind</CODE> method takes a list of argument specifications. An argument specification describes the type of the argument and the argument itself. <A href="node24.html#figure.widgets-2.event-args">Figure 5.7</A> shows the valid types and some arguments. The types mean the same as the types for the different return methods as discussed in <A href="node22.html#section.widgets-2.return">Section 5.3</A>. </P><DIV id="figure.widgets-2.event-args"><HR><P><A name="figure.widgets-2.event-args"></A></P><P> </P><TABLE align="center" bgcolor="#f0f0e0" id="table.widgets-2.event-args"><TR valign="top"><TH colspan="4"><P>Argument Type</P></TH></TR><TR valign="top"><TD><P><CODE>string(</CODE><CODE><I>A</I></CODE><CODE>)</CODE>, <CODE><I>A</I></CODE></P></TD><TD><P><CODE>atom(</CODE><CODE><I>A</I></CODE><CODE>)</CODE></P></TD><TD><P><CODE>int(</CODE><CODE><I>A</I></CODE><CODE>)</CODE></P></TD><TD><P><CODE>float(</CODE><CODE><I>A</I></CODE><CODE>)</CODE></P></TD></TR><TR valign="top"><TD><P><CODE>list(string(</CODE><CODE><I>A</I></CODE><CODE>))</CODE>, <CODE>list(</CODE><CODE><I>A</I></CODE><CODE>)</CODE></P></TD><TD><P><CODE>list(atom(</CODE><CODE><I>A</I></CODE><CODE>)</CODE></P></TD><TD><P><CODE>list(int(</CODE><CODE><I>A</I></CODE><CODE>)</CODE></P></TD><TD><P><CODE>list(float(</CODE><CODE><I>A</I></CODE><CODE>)</CODE></P></TD></TR></TABLE><P> </P><TABLE align="center" bgcolor="#f0f0e0"><TR valign="top"><TH><P>Event Argument</P></TH><TH><P>Description</P></TH></TR><TR valign="top"><TD><P><CODE>x</CODE></P></TD><TD><P>x coordinate</P></TD></TR><TR valign="top"><TD><P><CODE>y</CODE></P></TD><TD><P>y coordinate</P></TD></TR><TR valign="top"><TD><P><CODE>K</CODE></P></TD><TD><P>string describing the symbol of the key pressed</P></TD></TR><TR valign="top"><TD><P><CODE>A</CODE></P></TD><TD><P>character describing the key pressed</P></TD></TR></TABLE><P> </P><P class="caption"><STRONG>Figure 5.7:</STRONG> Event arguments.</P><HR></DIV><P> </P></DIV><H3><A name="label236">5.5.3 Invoking Actions</A></H3><P> When an event matches an event pattern to which an action has been bound by <CODE>tkBind</CODE>, a new thread is created in which the action is executed. If the action is a procedure the arity of the procedure has to be equal to the length of the argument list specified in <CODE>tkBind</CODE>. </P><P> If the action is a pair of object and message, the object is applied to message with the arguments appended. For example, after creating an event binding by </P><BLOCKQUOTE class="code"><CODE>{T tkBind(event: <SPAN class="string">'<1>'</SPAN> <BR> args: [int(x)]<BR> action: </CODE><CODE><I>O</I></CODE><CODE> <SPAN class="keyword">#</SPAN> invoke(button))}</CODE></BLOCKQUOTE><P> pressing the leftmost button at x-coordinate 42 creates a thread that executes the statement </P><BLOCKQUOTE class="code"><CODE>{</CODE><CODE><I>O</I></CODE><CODE> invoke(button 42)}</CODE></BLOCKQUOTE><P> </P><H3><A name="label237">5.5.4 Appending and Deleting Event Bindings</A></H3><P> If <CODE>tkBind</CODE> is used as before, any other existing binding for the event pattern specified is overwritten. If no action is specified any existing binding for the event pattern is deleted. </P><P> For a single event pattern there may be more than one binding. To create an event binding that does not overwrite already existing bindings, we can give the option <CODE>append</CODE> with value <CODE><SPAN class="keyword">true</SPAN></CODE>. For instance, if we do not only want to popup the menu but also to display <CODE>pop</CODE> in the Browser, we can create an additional binding by </P><DL class="anonymous"><DD class="code"><CODE>{W tkBind(event: <SPAN class="string">'<1>'</SPAN> <BR> append: <SPAN class="keyword">true</SPAN> <BR> action: <SPAN class="keyword">proc</SPAN><SPAN class="variablename"> </SPAN>{<SPAN class="functionname">$</SPAN>} {Browse pop} <SPAN class="keyword">end</SPAN>)}</CODE></DD></DL><P> </P></DIV><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node23.html#section.widgets-2.menu"><< Prev</A></TD><TD><A href="node19.html">- Up -</A></TD><TD><A href="node25.html#section.widgets-2.action">Next >></A></TD></TR></TABLE><HR><ADDRESS><A href="http://www.ps.uni-sb.de/~schulte/">Christian Schulte</A><BR><SPAN class="version">Version 1.4.0 (20110908185330)</SPAN></ADDRESS></BODY></HTML>
|