[ruby-talk:00909] [Gtk-doc] Signal
From:
gotoken@... (GOTO Kentaro)
Date:
1999-11-06 08:32:31 UTC
List:
ruby-talk #909
Hi Akaishi,
I've translated chapter signal of the Ruby/GTK documentation in
<URL: http://ruby.freak.ne.jp/gtk/>.
-- gotoken
/chap Signal
#----------------------------------------------------------------------
/section Basic of signal
<p>
In Gtk, various evens such as ``a button was pressed'' or ``a window
was redisplayed'' are notified to a widget via `signal'. One can
define an event handler which invokes the action corresponding
to each events. Generally speaking, we can regard Gtk programming as
setting event handler. Signal management is so important that someone
says ``Who controls the signal controls Gtk''.
</p><p>
A signal handler is defined as follows:
</p>
<pre>
<i>object</i>.signal_connect('<i>signal_name</i>') {|<i>*args</i>|
corresponding action
}
</pre>
<p>
<i>singnal_name</i> is a string representing the kind of signal. The first
option in <i>args</i> must be specified widget on which the signal is
raise, though, the rest options depend on the type of signal.
</p><p>
`<i>signal_name</i>' is chosen from constants of each widget class (e.g.,
<code>Gtk::Widget::SIGNAL_SHOW</code>, its value is "show"). One can obtain
signal constants being defined in each classes by gtkbrows.
</p><p>
According to the class hierarchy, a signal constant in a class is
defined in also its sub classes. The following lists all signal
constants in Gtk::Widget, which is placed on the top of the other widget
classes. These signals are defined in all widget classes too.
</p>
<div>
<caption><strong>Signals defined for Gtk::Window</strong><br></caption>
<table>
<tr><td><code>name of signal</code></td> <td><i>arguments<i></tr>
<tr><td><code>destroy</code></td> <td><i>widget<i></tr>
<tr><td><code>show</code></td> <td><i>widget</i></td></tr>
<tr><td><code>hide</code></td> <td><i>widget</i></td></tr>
<tr><td><code>map</code></td> <td><i>widget</i></td></tr>
<tr><td><code>unmap</code></td> <td><i>widget</i></td></tr>
<tr><td><code>realize</code></td> <td><i>widget</i></td></tr>
<tr><td><code>unrealize</code></td> <td><i>widget</i></td></tr>
<tr><td><code>draw</code></td> <td><i>widget, area</i></td></tr>
<tr><td><code>draw_focus</code></td> <td><i>widget</i></td></tr>
<tr><td><code>draw_default</code></td> <td><i>widget</i></td></tr>
<tr><td><code>size_request</code></td> <td><i>widget, requisition</i></td></tr>
<tr><td><code>size_allocate</code></td> <td><i>widget, allocation</i></td></tr>
<tr><td><code>state_changed</code></td> <td><i>widget</i></td></tr>
<tr><td><code>install_accelerator</code></td> <td><i>widget, signal_name, key,
modifiers</i></td></tr>
<tr><td><code>remove_accelerator</code></td> <td><i>widget, signal_name</i></td
></tr>
<tr><td><code>event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>button_press_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>button_release_event</code></td> <td><i>widget, event</i></td></t
r>
<tr><td><code>motion_notify_event</code></td> <td><i>widget, event</i></td></tr
>
<tr><td><code>delete_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>destroy_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>expose_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>key_press_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>key_release_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>enter_notify_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>leave_notify_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>configure_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>focus_in_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>focus_out_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>map_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>unmap_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>property_notify_event</code></td> <td><i>widget, event</i></td></
tr>
<tr><td><code>selection_clear_event</code></td> <td><i>widget, event</i></td></
tr>
<tr><td><code>selection_request_event</code></td> <td><i>widget, event</i></td>
</tr>
<tr><td><code>selection_notify_event</code></td> <td><i>widget, event</i></td><
/tr>
<tr><td><code>drop_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>drag_begin_event</code></td> <td><i>widget, event</i></td></tr>
<tr><td><code>other_event</code></td> <td><i>widget, event</i></td></tr>
</table>
</div>
#----------------------------------------------------------------------
/section Related methods
<p>
All methods relating to signal are defined in Gtk::Object.
</p>
<dl>
<dt><b>singal_connect</b>(`<i>singal_name</i>') { block }
<dd>
<p>
<b>singal_connect</b> connects a given block as signal handler of
`<i>signal_name</i>' to the reciever. `<i>signal_name</i>' is
defined as constant which has name started by `SIGNAL_'.
Both of the following means same:
</p>
<pre>
button.signal_connect('clicked') {...}
button.signal_connect(Gtk::Button::SIGNAL_CLICKED) {...}
</pre>
<p>
One can set more than one signal to an object or an signal.
In such cases, the callback will be executed sequentially in the
other of being connection. The following will cause displaying
"Hello World" if the button is clicked.
</p>
<pre>
button.signal_connect('clicked') {
print "Hello "
}
button.signal_connect('clicked') {
print "World\n"
}
</pre>
<p>
Note that signal_connect returns a unique id number for a handler.
</p>
</dd>
<dt><b>signal_connect_after</b>(<i>signal</i>) { block }
<dd>
<p>
Similar to `<b>gtk_signal_connect</b>' except the signal handler is
connected in the "after" slot. This allows a signal handler to be
guaranteed to run after other signal handlers connected to the same
signal on the same object and after the class function associated
with the signal.
</p>
</dd>
<dt><b>signal_emit_stop</b>('<i>signal_name</i>')
<dd>
<p>
Stop the emission of the signal `<i>signal_name</i>' on the object.
Attempting to stop the emission of a signal that isn't being emitted
does nothing.
</p>
</dl>
#/write
#======================================================================
/nextfile i18n.html
/chap Internationalization
(to be written)
#----------------------------------------------------------------------
#/write
#======================================================================
/nextfile packing.html