Server : Apache/2.4.41 (Ubuntu) System : Linux absol.cf 5.4.0-198-generic #218-Ubuntu SMP Fri Sep 27 20:18:53 UTC 2024 x86_64 User : www-data ( 33) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, Directory : /usr/share/GNUstep/Documentation/Developer/Gui/ProgrammingManual/AppKit/
Upload File :
Current File : //usr/share/GNUstep/Documentation/Developer/Gui/ProgrammingManual/AppKit/eventhandling.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- (C) 2005-2006 Christopher Armstrong.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2, as published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
This documentation is provided on an "AS IS" BASIS, WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND USEFULNESS
OF THE DOCUMENTATION IS WITH YOU (THE LICENSEE). IN NO EVENT WILL THE COPYRIGHT
HOLDERS BE LIABLE FOR DAMAGES, INCLUDING ANY DIRECT, INDIRECT,
SPECIAL, GENERAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OR INABILITY TO USE THIS DOCUMENTATION (INCLUDING BUT NOT
LIMITED TO LOSS OF DATA, USE, OR PROFITS; PROCUREMENT OF SUBSTITUTE
GOODS AND SERVICES; OR BUSINESS INTERUPTION) HOWEVER CAUSED, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -->
<!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>eventhandling (Using the GNUstep AppKit 0.1)</title>
<meta name="description" content="eventhandling (Using the GNUstep AppKit 0.1)">
<meta name="keywords" content="eventhandling (Using the GNUstep AppKit 0.1)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html" rel="start" title="Top">
<link href="conceptindex.html" rel="index" title="conceptindex">
<link href="index.html" rel="up" title="Top">
<link href="tableview.html" rel="next" title="tableview">
<link href="theviewconcept.html" rel="prev" title="theviewconcept">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<span id="eventhandling"></span><div class="header">
<p>
Next: <a href="tableview.html" accesskey="n" rel="next">tableview</a>, Previous: <a href="theviewconcept.html" accesskey="p" rel="prev">theviewconcept</a>, Up: <a href="index.html" accesskey="u" rel="up">Top</a> [<a href="conceptindex.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<span id="Event-handling"></span><h2 class="chapter">8 Event handling</h2>
<p>The way events are handled and passed between objects in GNUstep requires special treatment. It is relatively simple, but generally not well documented as to how it works, and how it is used by default in GNUstep. Before reading this chapter, you may wish to reaquaint yourself with views (see <a href="controls.html#The-view-concept">The view concept</a>).
</p>
<p>Event handling can be very complex, or very simple, depending on what your trying to handle and to what extent you’re using customised components. We will try to cover some of the basic concepts you may come across in this manual, as well as give a better guide to working with NSResponder and NSEvent.
</p>
<p>We start with the target/action paridigm (which is used to implement outlets/actions in interface files), and then explain the AppKit’s underlying event handling model, which is far more powerful and of interest if you are implementing your own views. It’s also relevant to understanding how events are passed around in GNUstep (and a recommended read).
</p>
<span id="The-Responder-Chain"></span><h3 class="section">8.1 The Responder Chain</h3>
<span id="index-responder"></span>
<span id="index-responder-chain"></span>
<p>A <em>responder</em> is an object inheriting from <code>NSResponder</code>. It defines methods that are overrided by subclasses for receiving events, from simple things such as mouse clicks and keyboard presses, to more abstract events such as text selection or text modification. <code>NSView</code> inherits from <code>NSResponder</code> (and in turn <code>NSControl</code> inherits from <code>NSView</code>) so in effect, all views and controls can respond to events.
</p>
<p>Responders are linked together in a chain, whereby a top-level graphical element (usually a window) receives an event, and if it doesn’t understand it, it passes it on to higher-level graphical elements, namely views. As views can be placed inside each other, a low-level superview may pass on higher-level events to it’s more abstract children. The responder chain is the programmatic linkage between different objects. It is usually setup by GNUstep, but can be modified by the programmer.
</p>
<p>The object at the top of the focus stack in a window is usually the <em>first responder</em>, meaning that any events will be forwarded to it first, and then along the chain if necessary. You can retrieve the first responder in a window by calling <code>-firstResponder</code> against the <code>NSWindow</code> object.<a id="DOCF11" href="#FOOT11"><sup>11</sup></a>.
</p>
<p>More than responder chain may exist, but only one may be active at a time. It is called a chain, due to the way event messages are passed through successive calls to each consecutive object in the chain.
</p>
<span id="Being-a-responder"></span><h3 class="section">8.2 Being a responder</h3>
<p>A responder inherits the <code>NSResponder</code> class. As <code>NSView</code> inherits from this, all high-level graphical elements, including all controls and views are considered to be "responders". This class contains a number of methods for maintaining the the responder chain and default methods for handling certain types of events, such as keyboard, mouse and "text" events (for text-processing classes such as NSText).
</p>
<p>The first method to override is <code>-acceptsFirstResponder</code>, which returns a boolean indicating whether your class will accept first responder status. You can also override <code>-becomeFirstResponder</code> and <code>-resignFirstResponder</code> to be notified of when your class gains and loses the first responder status (respectively).
</p>
<p>The next thing to do is override the different event messages that are predefined in NSResponder, such as <code>-keyDown:</code>, <code>-mouseDragged:</code>, <code>-helpRequested:</code>, etc. What all these have in common is that they take a single <code>NSEvent</code> object argument, which contains information about the event.
</p>
<p>Action messages are messages that have a predefined syntax i.e. they take one object as a parameter, but the name of the method that implements them defines the message. These are passed along the responder chain until a responder implementing that action message is found. This is aided via the <code>-tryToPerform:with:</code> method, which is used by GNUstep to traverse the responder chain and find an object that can perform the <var>anAction</var> selector with <var>anObject</var> as a parameter.
</p>
<p>Some of the common ones include:
</p><ul>
<li> -keyDown:
</li><li> -keyUp:
</li><li> -mouseDown:
</li><li> -mouseUp:
</li><li> -mouseMoved:
</li><li> -mouseEntered:
</li><li> -mouseExited:
</li><li> -rightMouseDown:
</li><li> -rightMouseUp:
</li></ul>
<p>You can also pass your own custom selectors along responder chains, trying to find the first object that responds to a particular method name. Given an object and a selector, call <code>-tryToPerform:with:</code> on an object in the responder chain, and this method will be tried on each successive responder until one can be found that responds to the selector. If a method cannot be method, it returns <code>NO</code>.
</p>
<span id="Target_002fAction-Paridgm"></span><h3 class="section">8.3 Target/Action Paridgm</h3>
<span id="index-paridgms_002c-Target_002fAction"></span>
<p>Controls use the target/action paridgm for simple events, which only have a sender and a target.<a id="DOCF12" href="#FOOT12"><sup>12</sup></a> The <em>target</em> object is the object notified of an event. It is like a <em>sink</em> in OLE/COM programming and is referred to as the <em>receiver</em>. The <em>action</em> is an event being performed, and takes the form of a selector. The <em>sender</em> is the object generating the action. An action is passed along the responder chain until it is processed or until the end of the responder chain is reached, in which case the message is returned to the sender indicating it couldn’t be processed. Messages that are passed as such events are known as <em>action messages</em>, and these events are known as <code>action events</code>.
</p>
<p>Let us explain with a simple example. We create a button on a form as an <code>NSButton</code> that we want to inform our <code>AppController</code> object instance when it is clicked. The button object is the <em>sender</em> and the <code>AppController</code> object is the <em>target</em>. We tell the button object to call our target object using the selector <code>-browseForServer:</code>.<a id="DOCF13" href="#FOOT13"><sup>13</sup></a> This selector is the <em>action</em>.
</p>
<p>Many of these actions are predefined in the <code>NSResponder</code> class which is implemented by all views.
</p>
<p>On the other hand, things such as menu items define a number of custom such as <code>-save:</code> or <code>-print:</code>, which many, but not all AppKit classes respond to. You can define your own actions for things such as menu buttons.
</p>
<p>Using the above example of a target, sender (which we will call <var>myButton</var>) and action, we could manually setup a link between the objects as follows:
</p><div class="example">
<pre class="example">
AppController* appCont;
NSButton* myButton;
// Initialisation of button and target objects
[myButton setAction:@selector(browserForServer:)];
[myButton setTarget:appCont];
</pre></div>
<p>In the above example, whenever <var>myButton</var> is clicked, it will call the <code>invoke:</code> method on the <code>MyButtonTarget</code> instance. What you see above is what Gorm.app does when you connect an action and a target.
</p>
<p>This paradigm is used for simple event handling in classes that derive from NSControl. See see <a href="controls.html#Basic-Controls">Basic Controls</a> and see <a href="applicationmakefiles.html#Interface-Files">Interface Files</a> for more information as to how this fits together.
</p>
<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>
<h5><a id="FOOT11" href="#DOCF11">(11)</a></h3>
<p>NSWindow objects are responders as well</p>
<h5><a id="FOOT12" href="#DOCF12">(12)</a></h3>
<p>A <em>paridgm</em> is a mode of thinking, often applied to programming. You may have heard of the "object-oriented programming pardigm" or the "functional programming" paridgm.</p>
<h5><a id="FOOT13" href="#DOCF13">(13)</a></h3>
<p>The name of the selector is purely arbitrary, and can be anything you like. However, it must take one parameter, which is a reference to the sender object.</p>
</div>
<hr>
<div class="header">
<p>
Next: <a href="tableview.html" accesskey="n" rel="next">tableview</a>, Previous: <a href="theviewconcept.html" accesskey="p" rel="prev">theviewconcept</a>, Up: <a href="index.html" accesskey="u" rel="up">Top</a> [<a href="conceptindex.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
Server : Apache/2.4.41 (Ubuntu)