1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="highlight.min.css">
<script src="highlight.min.js"></script><script>
hljs.configure({languages: ['cpp']});
hljs.highlightAll();
</script><title>Event signals</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Programming with gtkmm 4">
<link rel="up" href="chapter-signals.html" title="Appendix B. Signals">
<link rel="prev" href="sec-binding-extra-arguments.html" title="Binding extra arguments">
<link rel="next" href="sec-exceptions-in-signal-handlers.html" title="Exceptions in signal handlers">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Event signals</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="sec-binding-extra-arguments.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<th width="60%" align="center">Appendix B. Signals</th>
<td width="20%" align="right"> <a accesskey="n" href="sec-exceptions-in-signal-handlers.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
</table>
<hr>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-eventsignals"></a>Event signals</h2></div></div></div>
<p>
Event signals are emitted as a result of some user input, for instance a key press
or a mouse motion. Usually you don't handle these events directly. Instead, you use
a subclass of <code class="classname">Gtk::EventController</code>, such as <code class="classname">Gtk::EventControllerKey</code>
or <code class="classname">Gtk::GestureClick</code>. Event controllers can be added to a
widget with <code class="methodname">Gtk::Widget::add_controller()</code>.
</p>
<p>
You might occasionally find it useful to handle events when there's something
you can't accomplish with normal signals. <code class="classname">Gtk::Button</code>,
for example, does not send mouse-pointer coordinates with its
<code class="literal">clicked</code> signal, but you could handle
<code class="methodname">Gtk::GestureClick::signal_pressed()</code> if you needed this
information. <code class="methodname">Gtk::EventControllerKey::signal_key_pressed()</code>
is often used to handle key-presses.
</p>
<p>
Some event controller signals behave slightly differently. The value returned from
the signal handler indicates whether it has fully "handled" the event. If the value
is <code class="literal">false</code> then <span class="application">gtkmm</span> will pass the event on to the next
signal handler. If the value is <code class="literal">true</code> then no other signal handlers
will need to be called.
</p>
<p>
Handling an event doesn't affect the Widget's other signals. If you handle
<code class="methodname">Gtk::GestureClick::signal_pressed()</code> for
<code class="classname">Gtk::Button</code>, you'll still be able to get the
<code class="literal">clicked</code> signal. They are emitted at (nearly) the same time.
</p>
<p>
Here's a simple example:</p>
<pre class="programlisting"><code class="code">void on_button_press(int n_press, double x, double y);
Gtk::Button button("label");
auto controller = Gtk::GestureClick::create();
controller->set_propagation_phase(Gtk::PropagationPhase::CAPTURE);
controller->signal_pressed().connect(sigc::ptr_fun(&on_button_press));
button.add_controller(controller);
</code></pre>
<p>
When the mouse is over the button and a mouse button is pressed,
<code class="methodname">on_button_press()</code> will be called.
</p>
<p>
The call to <code class="methodname">set_propagation_phase()</code> is necessary in
this case because the <code class="classname">GtkButton</code> C class adds an event
controller, handling button clicks in the capture phase. <code class="classname">GtkButton</code>
claims the event, meaning that the event is not propagated in the bubble phase,
where event controllers handle events by default.
</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="signal-handler-sequence"></a>Signal Handler sequence</h3></div></div></div>
<p>By default, signal handlers that return <span class="type">void</span> are called after
any previously-connected signal handlers. However, this can be a problem with
event signals that can stop event propagation by returning <code class="literal">true</code>.
For instance, the existing signal handlers, or the default signal handler, might return
<code class="literal">true</code> to stop other signal handlers from being called.
To specify that your signal handler should be called before the other signal handlers,
you can specify <code class="literal">false</code> for the <code class="literal">after</code> parameter.
This <code class="methodname">connect()</code> parameter is optional, if the signal handler
returns <span class="type">void</span>. For instance,
</p>
<pre class="programlisting"><code class="code">key_controller->signal_key_pressed().connect(sigc::ptr_fun(&on_mywindow_key_pressed), false);
</code></pre>
<p>The event is propagated between widgets in 3 phases.
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">Capture phase - runs from the toplevel down to the event widget.</li>
<li class="listitem">Target phase - runs only on the event widget.</li>
<li class="listitem">Bubble phase - runs from the event widget up to the toplevel.</li>
</ol></div>
<p>
</p>
<p>
The <a class="ulink" href="https://docs.gtk.org/gtk4/input-handling.html" target="_top">Input Handling</a>
chapter in the GTK documentation describes user input handling in more detail.
</p>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="sec-binding-extra-arguments.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<td width="20%" align="center"><a accesskey="u" href="chapter-signals.html"><img src="icons/up.png" alt="Up"></a></td>
<td width="40%" align="right"> <a accesskey="n" href="sec-exceptions-in-signal-handlers.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Binding extra arguments </td>
<td width="20%" align="center"><a accesskey="h" href="index.html"><img src="icons/home.png" alt="Home"></a></td>
<td width="40%" align="right" valign="top"> Exceptions in signal handlers</td>
</tr>
</table>
</div>
</body>
</html>
|
