~ubuntu-branches/ubuntu/raring/gtk+2.0/raring-proposed

<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> <a class="link" href="gtk-Signals.html#gtk-signal-new" title="gtk_signal_new ()">gtk_signal_new</a> (<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

<em class="parameter"><code><a class="link" href="gtk-Signals.html#GtkSignalRunType" title="enum GtkSignalRunType"><span class="type">GtkSignalRunType</span></a> signal_flags</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> object_type</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> function_offset</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#GSignalCMarshaller"><span class="type">GSignalCMarshaller</span></a> marshaller</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> return_val</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> n_args</code></em>,

<em class="parameter"><code>...</code></em>);

<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> <a class="link" href="gtk-Signals.html#gtk-signal-newv" title="gtk_signal_newv ()">gtk_signal_newv</a> (<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

<em class="parameter"><code><a class="link" href="gtk-Signals.html#GtkSignalRunType" title="enum GtkSignalRunType"><span class="type">GtkSignalRunType</span></a> signal_flags</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> object_type</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> function_offset</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#GSignalCMarshaller"><span class="type">GSignalCMarshaller</span></a> marshaller</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> return_val</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> n_args</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> *args</code></em>);

#define <a class="link" href="gtk-Signals.html#gtk-signal-lookup" title="gtk_signal_lookup()">gtk_signal_lookup</a> (name,

object_type)

#define <a class="link" href="gtk-Signals.html#gtk-signal-name" title="gtk_signal_name()">gtk_signal_name</a> (signal_id)

<span class="returnvalue">void</span> <a class="link" href="gtk-Signals.html#gtk-signal-emit" title="gtk_signal_emit ()">gtk_signal_emit</a> (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> signal_id</code></em>,

<em class="parameter"><code>...</code></em>);

<span class="returnvalue">void</span> <a class="link" href="gtk-Signals.html#gtk-signal-emit-by-name" title="gtk_signal_emit_by_name ()">gtk_signal_emit_by_name</a> (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

<em class="parameter"><code>...</code></em>);

<span class="returnvalue">void</span> <a class="link" href="gtk-Signals.html#gtk-signal-emitv" title="gtk_signal_emitv ()">gtk_signal_emitv</a> (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> signal_id</code></em>,

<em class="parameter"><code><a class="link" href="gtk-Types.html#GtkArg" title="struct GtkArg"><span class="type">GtkArg</span></a> *args</code></em>);

<span class="returnvalue">void</span> <a class="link" href="gtk-Signals.html#gtk-signal-emitv-by-name" title="gtk_signal_emitv_by_name ()">gtk_signal_emitv_by_name</a> (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

<em class="parameter"><code><a class="link" href="gtk-Types.html#GtkArg" title="struct GtkArg"><span class="type">GtkArg</span></a> *args</code></em>);

#define <a class="link" href="gtk-Signals.html#gtk-signal-emit-stop" title="gtk_signal_emit_stop()">gtk_signal_emit_stop</a> (object,

signal_id)

<span class="returnvalue">void</span> <a class="link" href="gtk-Signals.html#gtk-signal-emit-stop-by-name" title="gtk_signal_emit_stop_by_name ()">gtk_signal_emit_stop_by_name</a> (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>);

#define <a class="link" href="gtk-Signals.html#gtk-signal-connect" title="gtk_signal_connect()">gtk_signal_connect</a> (object,

name,

func,

func_data)

#define <a class="link" href="gtk-Signals.html#gtk-signal-connect-after" title="gtk_signal_connect_after()">gtk_signal_connect_after</a> (object,

name,

func,

func_data)

#define <a class="link" href="gtk-Signals.html#gtk-signal-connect-object" title="gtk_signal_connect_object()">gtk_signal_connect_object</a> (object,

name,

func,

slot_object)

#define <a class="link" href="gtk-Signals.html#gtk-signal-connect-object-after" title="gtk_signal_connect_object_after()">gtk_signal_connect_object_after</a> (object,

name,

func,

slot_object)

<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gulong"><span class="returnvalue">gulong</span></a> <a class="link" href="gtk-Signals.html#gtk-signal-connect-full" title="gtk_signal_connect_full ()">gtk_signal_connect_full</a> (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> func</code></em>,

<em class="parameter"><code><a class="link" href="gtk-Types.html#GtkCallbackMarshal" title="GtkCallbackMarshal ()"><span class="type">GtkCallbackMarshal</span></a> unsupported</code></em>,

100

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,

101

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> destroy_func</code></em>,

102

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> object_signal</code></em>,

103

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> after</code></em>);

104

<span class="returnvalue">void</span> <a class="link" href="gtk-Signals.html#gtk-signal-connect-while-alive" title="gtk_signal_connect_while_alive ()">gtk_signal_connect_while_alive</a> (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

105

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

106

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> func</code></em>,

107

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> func_data</code></em>,

108

<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *alive_object</code></em>);

109

<span class="returnvalue">void</span> <a class="link" href="gtk-Signals.html#gtk-signal-connect-object-while-alive" title="gtk_signal_connect_object_while_alive ()">gtk_signal_connect_object_while_alive</a>

110

(<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

111

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

112

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> func</code></em>,

113

<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *alive_object</code></em>);

114

#define <a class="link" href="gtk-Signals.html#gtk-signal-disconnect" title="gtk_signal_disconnect()">gtk_signal_disconnect</a> (object,

115

handler_id)

116

#define <a class="link" href="gtk-Signals.html#gtk-signal-disconnect-by-func" title="gtk_signal_disconnect_by_func()">gtk_signal_disconnect_by_func</a> (object,

117

func,

118

data)

119

#define <a class="link" href="gtk-Signals.html#gtk-signal-disconnect-by-data" title="gtk_signal_disconnect_by_data()">gtk_signal_disconnect_by_data</a> (object,

120

data)

121

#define <a class="link" href="gtk-Signals.html#gtk-signal-handler-block" title="gtk_signal_handler_block()">gtk_signal_handler_block</a> (object,

122

handler_id)

123

#define <a class="link" href="gtk-Signals.html#gtk-signal-handler-block-by-func" title="gtk_signal_handler_block_by_func()">gtk_signal_handler_block_by_func</a> (object,

124

func,

125

data)

126

#define <a class="link" href="gtk-Signals.html#gtk-signal-handler-block-by-data" title="gtk_signal_handler_block_by_data()">gtk_signal_handler_block_by_data</a> (object,

127

data)

128

#define <a class="link" href="gtk-Signals.html#gtk-signal-handler-unblock" title="gtk_signal_handler_unblock()">gtk_signal_handler_unblock</a> (object,

129

handler_id)

130

#define <a class="link" href="gtk-Signals.html#gtk-signal-handler-unblock-by-func" title="gtk_signal_handler_unblock_by_func()">gtk_signal_handler_unblock_by_func</a> (object,

131

func,

132

data)

133

#define <a class="link" href="gtk-Signals.html#gtk-signal-handler-unblock-by-data" title="gtk_signal_handler_unblock_by_data()">gtk_signal_handler_unblock_by_data</a> (object,

134

data)

135

#define <a class="link" href="gtk-Signals.html#gtk-signal-handler-pending" title="gtk_signal_handler_pending()">gtk_signal_handler_pending</a> (object,

136

signal_id,

137

may_be_blocked)

138

#define <a class="link" href="gtk-Signals.html#gtk-signal-handler-pending-by-func" title="gtk_signal_handler_pending_by_func()">gtk_signal_handler_pending_by_func</a> (object,

139

signal_id,

140

may_be_blocked,

141

func,

142

data)

143

#define <a class="link" href="gtk-Signals.html#gtk-signal-default-marshaller" title="gtk_signal_default_marshaller">gtk_signal_default_marshaller</a>

144

</pre>

145

</div>

146

147

<a name="gtk-Signals.description"></a><h2>Description</h2>

148

<p>

149

The GTK+ signal system merely proxies the GLib signal system now. For future

150

usage, direct use of the <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html">GSignal</a> API is recommended, this avoids significant

151

performance hits where <a class="link" href="gtk-Types.html#GtkArg" title="struct GtkArg"><span class="type">GtkArg</span></a> structures have to be converted into <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a>s.

152

</p>

153

154

<a name="idp22519232"></a><h3>What are signals?</h3>

155

<p>

156

Signals are a way to get notification when something happens

157

and to customize object behavior according to the

158

user's needs.

159

Every <em class="wordasword">signal</em> is uniquely identified by a name,

160

"class_name::signal_name", where signal_name might be something like

161

"clicked" and class_name might be "GtkButton". Note that some other class

162

may also define a "clicked" callback, so long as it doesn't derive from

163

<a class="link" href="GtkButton.html" title="GtkButton"><span class="type">GtkButton</span></a>.

164

</p>

165

<p>

166

When they are created, they are also assigned a unique positive integer,

167

the signal id (1 is the first signal id- 0 is used to flag an error).

168

Each is also tied to an array of types that describes

169

the prototype of the function pointer(s) (handlers) you may

170

connect to the signal. Finally, every signal has

171

a default handler that is given by a function pointer

172

in its class structure: it is run by default whenever the

173

signal is emitted. (It is possible that a signal will

174

be emitted and a user-defined handler will prevent the default handler

175

from being run.)

176

</p>

177

<p>

178

Signals are used by everyone, but they are only

179

created on a per class basis -- so you should not call

180

call <a class="link" href="gtk-Signals.html#gtk-signal-new" title="gtk_signal_new ()"><code class="function">gtk_signal_new()</code></a> unless you are writing

181

a new <a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> type. However, if you want to make a new signal

182

for an existing type, you may use <code class="function">gtk_object_class_user_signal_new()</code>

183

to create a signal that doesn't correspond to a class's builtin

184

methods.

185

</p>

186

</div>

187

<hr>

188

189

<a name="idp24066448"></a><h3>How are signals used?</h3>

190

<p>

191

There are two basic actions in the signal handling game.

192

If you want notification of an event, you must <span class="emphasis"><em>connect</em></span>

193

a function pointer and a data pointer to that signal; the data pointer

194

will be passed as the last argument to the function (so long as you

195

are using the default marshalling functions).

196

You will receive a connection id, a unique positive integer

197

corresponding to that attachment.

198

</p>

199

<p>

200

Functions that want to notify the user of certain actions,

201

<span class="emphasis"><em>emit</em></span> signals.

202

</p>

203

</div>

204

<hr>

205

206

<a name="idp24069472"></a><h3>Basic Terminology</h3>

207

208

209

210

<col>

211

</colgroup>

212

<tbody>

213

<tr>

214

<td><p><span class="term">signal</span></p></td>

215

<td><p>A class method, e.g. GtkButton::clicked.

216

More precisely it is a unique class-branch/signal-name pair.

217

This means you may not define a signal handler for a class which

218

derives from <a class="link" href="GtkButton.html" title="GtkButton"><span class="type">GtkButton</span></a> that is called clicked,

219

but it is okay to share signals names if they are separate in

220

the class tree.

221

</p></td>

222

</tr>

223

<tr>

224

<td><p><span class="term">default handler</span></p></td>

225

<td><p>The object's internal method which is invoked

226

when the signal is emitted.</p></td>

227

</tr>

228

<tr>

229

<td><p><span class="term">user-defined handler</span></p></td>

230

<td>

231

<p>A function pointer and data connected

232

to a signal (for a particular object).</p>

233

<p>There are really two types: those which are connected

234

normally, and those which are connected by one

235

of the connect_after functions. The connect_after handlers

236

are always run after the default handler.</p>

237

<p>Many toolkits refer to these as <em class="wordasword">callbacks</em>.</p>

238

</td>

239

</tr>

240

<tr>

241

<td><p><span class="term">emission</span></p></td>

242

<td><p>the whole process of emitting a signal,

243

including the invocation of all

244

the different handler types mentioned above.</p></td>

245

</tr>

246

<tr>

247

<td><p><span class="term">signal id</span></p></td>

248

<td><p>The unique positive (nonzero) integer

249

used to identify a signal. It can be used instead of

250

a name to many functions for a slight performance

251

improvement.</p></td>

252

</tr>

253

<tr>

254

<td><p><span class="term">connection id</span></p></td>

255

<td><p>The unique positive (nonzero) integer

256

used to identify the connection of a user-defined handler

257

to a signal. Notice that it is allowed to connect the

258

same function-pointer/user-data pair twice, so

259

there is no guarantee that a function-pointer/user-data

260

maps to a unique connection id.

261

</p></td>

262

</tr>

263

</tbody>

264

</table></div>

265

</div>

266

<hr>

267

268

<a name="idp20981808"></a><h3>A brief note on how they work.</h3>

269

<p>

270

The functions responsible for translating an array of <a href="gtk-Types.html#GtkArg"><span class="type">GtkArgs</span></a>

271

to your C compiler's normal semantics are called Marshallers.

272

They are identified by

273

gtk_marshal_<em class="replaceable"><code>return_value</code></em>__<em class="replaceable"><code>parameter_list</code></em>()

274

for example a C function returning a gboolean and taking a gint

275

can be invoked by using <code class="function">gtk_marshal_BOOL__INT()</code>.

276

Not all possibly combinations of return/params are available,

277

of course, so if you are writing a <a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> with parameters

278

you might have to write a marshaller.

279

</p>

280

</div>

281

</div>

282

283

<a name="gtk-Signals.details"></a><h2>Details</h2>

284

285

<a name="GTK-SIGNAL-OFFSET:CAPS"></a><h3>GTK_SIGNAL_OFFSET</h3>

286

<pre class="programlisting">#define GTK_SIGNAL_OFFSET G_STRUCT_OFFSET

287

</pre>

288

289

<h3 class="title">Warning</h3>

290

<p><code class="literal">GTK_SIGNAL_OFFSET</code> is deprecated and should not be used in newly-written code.</p>

291

</div>

292

<p>

293

Use in place of <code class="function"><code class="function">offsetof()</code></code>, which is used if it exists.

294

</p>

295

</div>

296

<hr>

297

298

<a name="GtkSignalRunType"></a><h3>enum GtkSignalRunType</h3>

299

<pre class="programlisting">typedef enum {

300

GTK_RUN_FIRST = G_SIGNAL_RUN_FIRST,

301

GTK_RUN_LAST = G_SIGNAL_RUN_LAST,

302

GTK_RUN_BOTH = (GTK_RUN_FIRST | GTK_RUN_LAST),

303

GTK_RUN_NO_RECURSE = G_SIGNAL_NO_RECURSE,

304

GTK_RUN_ACTION = G_SIGNAL_ACTION,

305

GTK_RUN_NO_HOOKS = G_SIGNAL_NO_HOOKS

306

} GtkSignalRunType;

307

</pre>

308

309

<h3 class="title">Warning</h3>

310

<p><code class="literal">GtkSignalRunType</code> is deprecated and should not be used in newly-written code.</p>

311

</div>

312

<p>

313

These configure the signal's emission. They control

314

whether the signal can be emitted recursively on an object

315

and

316

whether to run the default method before or after the user-defined handlers.

317

</p>

318

319

320

321

<col>

322

</colgroup>

323

<tbody>

324

<tr>

325

<td><p><span class="term">GTK_RUN_FIRST</span></p></td>

326

<td><p>Run the default handler before the connected user-defined

327

handlers.

328

</p></td>

329

</tr>

330

<tr>

331

332

<td><p>Run the default handler after the connected

333

user-defined handlers.

334

(Handlers registered as "after" always run after the default handler though)

335

</p></td>

336

</tr>

337

<tr>

338

339

<td><p>Run the default handler twice,

340

once before the user-defined handlers,

341

and

342

once after.

343

</p></td>

344

</tr>

345

<tr>

346

<td><p><span class="term">GTK_RUN_NO_RECURSE</span></p></td>

347

<td>

348

<p>Whether to prevent a handler or hook

349

from reemitting the signal from within itself.

350

Attempts to

351

emit the signal while it is running will result in the signal

352

emission being restarted once it is done with the current processing.

353

</p>

354

<p>

355

You must be

356

careful to avoid having two handlers endlessly reemitting signals,

357

<code class="function">gtk_signal_n_emissions()</code> can be helpful.

358

</p>

359

</td>

360

</tr>

361

<tr>

362

<td><p><span class="term">GTK_RUN_ACTION</span></p></td>

363

<td><p>The signal is an action you can

364

invoke without any particular setup or cleanup.

365

The signal is treated no differently, but some

366

other code can determine if the signal is appropriate to

367

delegate to user control. For example, key binding sets

368

only allow bindings of ACTION signals to keystrokes.

369

</p></td>

370

</tr>

371

<tr>

372

<td><p><span class="term">GTK_RUN_NO_HOOKS</span></p></td>

373

<td><p>This prevents the connection of emission hooks

374

to the signal.

375

</p></td>

376

</tr>

377

</tbody>

378

</table></div>

379

</div>

380

<hr>

381

382

<a name="gtk-signal-new"></a><h3>gtk_signal_new ()</h3>

383

<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> gtk_signal_new (<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

384

<em class="parameter"><code><a class="link" href="gtk-Signals.html#GtkSignalRunType" title="enum GtkSignalRunType"><span class="type">GtkSignalRunType</span></a> signal_flags</code></em>,

385

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> object_type</code></em>,

386

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> function_offset</code></em>,

387

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#GSignalCMarshaller"><span class="type">GSignalCMarshaller</span></a> marshaller</code></em>,

388

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> return_val</code></em>,

389

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> n_args</code></em>,

390

391

392

<h3 class="title">Warning</h3>

393

<p><code class="literal">gtk_signal_new</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-new"><code class="function">g_signal_new()</code></a> instead.</p>

394

</div>

395

<p>

396

Creates a new signal type. (This is usually done in the

397

class initializer.)

398

</p>

399

400

401

402

<col>

403

</colgroup>

404

<tbody>

405

<tr>

406

407

<td>the event name for the signal, e.g. "clicked".</td>

408

</tr>

409

<tr>

410

<td><p><span class="term"><em class="parameter"><code>signal_flags</code></em> :</span></p></td>

411

<td>a combination of <span class="type">GTK_RUN</span> flags

412

specifying detail of when the default handler is to be invoked.

413

You should at least specify <span class="type">GTK_RUN_FIRST</span>

414

or <span class="type">GTK_RUN_LAST</span>.</td>

415

</tr>

416

<tr>

417

<td><p><span class="term"><em class="parameter"><code>object_type</code></em> :</span></p></td>

418

<td>the type of object this signal pertains to.

419

It will also pertain to derivers of this type automatically.</td>

420

</tr>

421

<tr>

422

<td><p><span class="term"><em class="parameter"><code>function_offset</code></em> :</span></p></td>

423

<td>How many bytes the function pointer is in

424

the class structure for this type. Used to invoke a class

425

method generically.</td>

426

</tr>

427

<tr>

428

<td><p><span class="term"><em class="parameter"><code>marshaller</code></em> :</span></p></td>

429

<td>the function to translate between an array

430

of GtkArgs and the native calling convention. Usually they

431

are identified just by the type of arguments they take:

432

for example, <code class="function">gtk_marshal_BOOL__STRING()</code> describes a marshaller

433

which takes a string and returns a boolean value.</td>

434

</tr>

435

<tr>

436

<td><p><span class="term"><em class="parameter"><code>return_val</code></em> :</span></p></td>

437

<td>the type of return value, or <span class="type">GTK_TYPE_NONE</span> for a signal

438

without a return value.</td>

439

</tr>

440

<tr>

441

442

<td>the number of parameter the handlers may take.</td>

443

</tr>

444

<tr>

445

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

446

<td>the signal id.</td>

447

</tr>

448

</tbody>

449

</table></div>

450

</div>

451

<hr>

452

453

<a name="gtk-signal-newv"></a><h3>gtk_signal_newv ()</h3>

454

<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> gtk_signal_newv (<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

455

<em class="parameter"><code><a class="link" href="gtk-Signals.html#GtkSignalRunType" title="enum GtkSignalRunType"><span class="type">GtkSignalRunType</span></a> signal_flags</code></em>,

456

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> object_type</code></em>,

457

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> function_offset</code></em>,

458

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#GSignalCMarshaller"><span class="type">GSignalCMarshaller</span></a> marshaller</code></em>,

459

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> return_val</code></em>,

460

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> n_args</code></em>,

461

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> *args</code></em>);</pre>

462

463

<h3 class="title">Warning</h3>

464

<p><code class="literal">gtk_signal_newv</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-newv"><code class="function">g_signal_newv()</code></a> instead.</p>

465

</div>

466

<p>

467

Creates a new signal type. (This is usually done in a

468

class initializer.)

469

</p>

470

<p>

471

This function take the types as an array, instead of a list

472

following the arguments. Otherwise the same as <a class="link" href="gtk-Signals.html#gtk-signal-new" title="gtk_signal_new ()"><code class="function">gtk_signal_new()</code></a>.

473

</p>

474

475

476

477

<col>

478

</colgroup>

479

<tbody>

480

<tr>

481

482

<td>the name of the signal to create.</td>

483

</tr>

484

<tr>

485

<td><p><span class="term"><em class="parameter"><code>signal_flags</code></em> :</span></p></td>

486

<td>see <a class="link" href="gtk-Signals.html#gtk-signal-new" title="gtk_signal_new ()"><code class="function">gtk_signal_new()</code></a>.</td>

487

</tr>

488

<tr>

489

<td><p><span class="term"><em class="parameter"><code>object_type</code></em> :</span></p></td>

490

<td>the type of <a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> to associate the signal with.</td>

491

</tr>

492

<tr>

493

<td><p><span class="term"><em class="parameter"><code>function_offset</code></em> :</span></p></td>

494

<td>how many bytes the function pointer is in

495

the class structure for this type.</td>

496

</tr>

497

<tr>

498

<td><p><span class="term"><em class="parameter"><code>return_val</code></em> :</span></p></td>

499

<td>the type of the return value, or <span class="type">GTK_TYPE_NONE</span> if

500

you don't want a return value.</td>

501

</tr>

502

<tr>

503

504

<td>the number of parameters to the user-defined handlers.</td>

505

</tr>

506

<tr>

507

508

<td>an array of <a class="link" href="gtk-Types.html#GtkType" title="GtkType"><span class="type">GtkType</span></a>s, describing the prototype to

509

the callbacks.</td>

510

</tr>

511

<tr>

512

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

513

<td>the signal id.</td>

514

</tr>

515

</tbody>

516

</table></div>

517

</div>

518

<hr>

519

520

<a name="gtk-signal-lookup"></a><h3>gtk_signal_lookup()</h3>

521

<pre class="programlisting">#define gtk_signal_lookup(name,object_type)</pre>

522

523

<h3 class="title">Warning</h3>

524

<p><code class="literal">gtk_signal_lookup</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-lookup"><code class="function">g_signal_lookup()</code></a> instead.</p>

525

</div>

526

<p>

527

Given the name of the signal and the type of object it connects

528

to, get the signal's identifying integer. Emitting the signal

529

by number is somewhat faster than using the name each time.

530

</p>

531

<p>

532

It also tries the ancestors of the given type.

533

</p>

534

535

536

537

<col>

538

</colgroup>

539

<tbody>

540

<tr>

541

542

<td>the signal's name, e.g. clicked.</td>

543

</tr>

544

<tr>

545

<td><p><span class="term"><em class="parameter"><code>object_type</code></em> :</span></p></td>

546

<td>the type that the signal operates on, e.g. <span class="type">GTK_TYPE_BUTTON</span>.</td>

547

</tr>

548

<tr>

549

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

550

<td>the signal's identifying number, or 0 if no signal was found.</td>

551

</tr>

552

</tbody>

553

</table></div>

554

</div>

555

<hr>

556

557

<a name="gtk-signal-name"></a><h3>gtk_signal_name()</h3>

558

<pre class="programlisting">#define gtk_signal_name(signal_id)</pre>

559

560

<h3 class="title">Warning</h3>

561

<p><code class="literal">gtk_signal_name</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-name"><code class="function">g_signal_name()</code></a> instead.</p>

562

</div>

563

<p>

564

Given the signal's identifier, finds its name.

565

</p>

566

<p>

567

Two different signals may have the same name, if they have differing types.

568

</p>

569

570

571

572

<col>

573

</colgroup>

574

<tbody>

575

<tr>

576

<td><p><span class="term"><em class="parameter"><code>signal_id</code></em> :</span></p></td>

577

<td>the signal's identifying number.</td>

578

</tr>

579

<tr>

580

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

581

<td>the signal name, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if the signal number was invalid.</td>

582

</tr>

583

</tbody>

584

</table></div>

585

</div>

586

<hr>

587

588

<a name="gtk-signal-emit"></a><h3>gtk_signal_emit ()</h3>

589

<pre class="programlisting"><span class="returnvalue">void</span> gtk_signal_emit (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

590

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> signal_id</code></em>,

591

592

593

<h3 class="title">Warning</h3>

594

<p><code class="literal">gtk_signal_emit</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-emit"><code class="function">g_signal_emit()</code></a> instead.</p>

595

</div>

596

<p>

597

Emits a signal. This causes the default handler and user-defined

598

handlers to be run.

599

</p>

600

<p>

601

Here is what <a class="link" href="gtk-Signals.html#gtk-signal-emit" title="gtk_signal_emit ()"><code class="function">gtk_signal_emit()</code></a> does:

602

</p>

603

<p>

604

1. Calls the default handler and the user-connected handlers.

605

The default handler will be called first if

606

<span class="type">GTK_RUN_FIRST</span> is set, and last if <span class="type">GTK_RUN_LAST</span> is set.

607

</p>

608

<p>

609

2. Calls all handlers connected with the "after" flag set.

610

</p>

611

612

613

614

<col>

615

</colgroup>

616

<tbody>

617

<tr>

618

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

619

<td>the object that emits the signal.</td>

620

</tr>

621

<tr>

622

<td><p><span class="term"><em class="parameter"><code>signal_id</code></em> :</span></p></td>

623

<td>the signal identifier.</td>

624

</tr>

625

</tbody>

626

</table></div>

627

</div>

628

<hr>

629

630

<a name="gtk-signal-emit-by-name"></a><h3>gtk_signal_emit_by_name ()</h3>

631

<pre class="programlisting"><span class="returnvalue">void</span> gtk_signal_emit_by_name (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

632

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

633

634

635

<h3 class="title">Warning</h3>

636

<p><code class="literal">gtk_signal_emit_by_name</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-emit-by-name"><code class="function">g_signal_emit_by_name()</code></a> instead.</p>

637

</div>

638

<p>

639

Emits a signal. This causes the default handler and user-connected

640

handlers to be run.

641

</p>

642

643

644

645

<col>

646

</colgroup>

647

<tbody>

648

<tr>

649

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

650

<td>the object that emits the signal.</td>

651

</tr>

652

<tr>

653

654

<td>the name of the signal.</td>

655

</tr>

656

</tbody>

657

</table></div>

658

</div>

659

<hr>

660

661

<a name="gtk-signal-emitv"></a><h3>gtk_signal_emitv ()</h3>

662

<pre class="programlisting"><span class="returnvalue">void</span> gtk_signal_emitv (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

663

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> signal_id</code></em>,

664

<em class="parameter"><code><a class="link" href="gtk-Types.html#GtkArg" title="struct GtkArg"><span class="type">GtkArg</span></a> *args</code></em>);</pre>

665

666

<h3 class="title">Warning</h3>

667

<p><code class="literal">gtk_signal_emitv</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-emitv"><code class="function">g_signal_emitv()</code></a> instead.</p>

668

</div>

669

<p>

670

Emits a signal. This causes the default handler and user-connected

671

handlers to be run. This differs from <a class="link" href="gtk-Signals.html#gtk-signal-emit" title="gtk_signal_emit ()"><code class="function">gtk_signal_emit()</code></a> by taking

672

an array of GtkArgs instead of using C's varargs mechanism.

673

</p>

674

675

676

677

<col>

678

</colgroup>

679

<tbody>

680

<tr>

681

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

682

<td>the object to emit the signal to.</td>

683

</tr>

684

<tr>

685

<td><p><span class="term"><em class="parameter"><code>signal_id</code></em> :</span></p></td>

686

<td>the signal identifier.</td>

687

</tr>

688

<tr>

689

690

<td>an array of GtkArgs, one for each parameter,

691

followed by one which is a pointer to the return type.</td>

692

</tr>

693

</tbody>

694

</table></div>

695

</div>

696

<hr>

697

698

<a name="gtk-signal-emitv-by-name"></a><h3>gtk_signal_emitv_by_name ()</h3>

699

<pre class="programlisting"><span class="returnvalue">void</span> gtk_signal_emitv_by_name (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

700

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

701

<em class="parameter"><code><a class="link" href="gtk-Types.html#GtkArg" title="struct GtkArg"><span class="type">GtkArg</span></a> *args</code></em>);</pre>

702

703

<h3 class="title">Warning</h3>

704

<p><code class="literal">gtk_signal_emitv_by_name</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-emitv"><code class="function">g_signal_emitv()</code></a> and <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-lookup"><code class="function">g_signal_lookup()</code></a> instead.</p>

705

</div>

706

<p>

707

Emits a signal by name. This causes the default handler and user-connected

708

handlers to be run. This differs from <a class="link" href="gtk-Signals.html#gtk-signal-emit" title="gtk_signal_emit ()"><code class="function">gtk_signal_emit()</code></a> by taking

709

an array of GtkArgs instead of using C's varargs mechanism.

710

</p>

711

712

713

714

<col>

715

</colgroup>

716

<tbody>

717

<tr>

718

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

719

<td>the object to emit the signal to.</td>

720

</tr>

721

<tr>

722

723

<td>the name of the signal.</td>

724

</tr>

725

<tr>

726

727

<td>an array of GtkArgs, one for each parameter,

728

followed by one which is a pointer to the return type.</td>

729

</tr>

730

</tbody>

731

</table></div>

732

</div>

733

<hr>

734

735

<a name="gtk-signal-emit-stop"></a><h3>gtk_signal_emit_stop()</h3>

736

<pre class="programlisting">#define gtk_signal_emit_stop(object,signal_id)</pre>

737

738

<h3 class="title">Warning</h3>

739

<p><code class="literal">gtk_signal_emit_stop</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-stop-emission"><code class="function">g_signal_stop_emission()</code></a> instead.</p>

740

</div>

741

<p>

742

This function aborts a signal's current emission.

743

</p>

744

<p>

745

It will prevent the default method from running,

746

if the signal was <span class="type">GTK_RUN_LAST</span> and you connected

747

normally (i.e. without the "after" flag).

748

</p>

749

<p>

750

It will print a warning if used on a signal which

751

isn't being emitted.

752

</p>

753

754

755

756

<col>

757

</colgroup>

758

<tbody>

759

<tr>

760

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

761

<td>the object whose signal handlers you wish to stop.</td>

762

</tr>

763

<tr>

764

<td><p><span class="term"><em class="parameter"><code>signal_id</code></em> :</span></p></td>

765

<td>the signal identifier, as returned by <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-lookup"><code class="function">g_signal_lookup()</code></a>.</td>

766

</tr>

767

</tbody>

768

</table></div>

769

</div>

770

<hr>

771

772

<a name="gtk-signal-emit-stop-by-name"></a><h3>gtk_signal_emit_stop_by_name ()</h3>

773

<pre class="programlisting"><span class="returnvalue">void</span> gtk_signal_emit_stop_by_name (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

774

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>);</pre>

775

776

<h3 class="title">Warning</h3>

777

<p><code class="literal">gtk_signal_emit_stop_by_name</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-stop-emission-by-name"><code class="function">g_signal_stop_emission_by_name()</code></a> instead.</p>

778

</div>

779

<p>

780

This function aborts a signal's current emission.

781

</p>

782

<p>

783

It is just like <a class="link" href="gtk-Signals.html#gtk-signal-emit-stop" title="gtk_signal_emit_stop()"><code class="function">gtk_signal_emit_stop()</code></a>

784

except it will lookup the signal id for you.

785

</p>

786

787

788

789

<col>

790

</colgroup>

791

<tbody>

792

<tr>

793

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

794

<td>the object whose signal handlers you wish to stop.</td>

795

</tr>

796

<tr>

797

798

<td>the name of the signal you wish to stop.</td>

799

</tr>

800

</tbody>

801

</table></div>

802

</div>

803

<hr>

804

805

<a name="gtk-signal-connect"></a><h3>gtk_signal_connect()</h3>

806

<pre class="programlisting">#define gtk_signal_connect(object,name,func,func_data)</pre>

807

808

<h3 class="title">Warning</h3>

809

<p><code class="literal">gtk_signal_connect</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect"><code class="function">g_signal_connect()</code></a> instead.</p>

810

</div>

811

<p>

812

Attaches a function pointer and user data to a signal for

813

a particular object.

814

</p>

815

<p>

816

The <span class="type">GtkSignalFunction</span> takes a <a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> as its first parameter.

817

It will be the same object as the one you're connecting

818

the hook to. The <em class="parameter"><code>func_data</code></em> will be passed as the last parameter

819

to the hook.

820

</p>

821

<p>

822

All else being equal, signal handlers are invoked in the order

823

connected (see <a class="link" href="gtk-Signals.html#gtk-signal-emit" title="gtk_signal_emit ()"><code class="function">gtk_signal_emit()</code></a> for the other details of

824

which order things are called in).

825

</p>

826

<p>

827

Here is how one passes an integer as user data,

828

for when you just want to specify a constant int

829

as parameter to your function:

830

</p>

831

832

833

<tbody>

834

<tr>

835

<td class="listing_lines" align="right"><pre>1

836

837

838

839

840

841

842

843

844

845

846

12</pre></td>

847

<td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span><span class="normal"> </span><span class="function">button_clicked_int</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="GtkButton.html">GtkButton</a></span><span class="symbol">*</span><span class="normal"> button</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> func_data</span><span class="symbol">)</span>

848

849

<span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/glib/unstable/glib-Warnings-and-Assertions.html#g-print">g_print</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"button pressed: %d</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/glib/unstable/glib-Type-Conversion-Macros.html#GPOINTER-TO-INT:CAPS">GPOINTER_TO_INT</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">func_data</span><span class="symbol">));</span>

850

851

<span class="comment">/* By calling this function, you will make the g_print above</span>

852

<span class="comment"> * execute, printing the number passed as `to_print'. */</span>

853

<span class="keyword">static</span><span class="normal"> </span><span class="type">void</span><span class="normal"> </span><span class="function">attach_print_signal</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="GtkButton.html">GtkButton</a></span><span class="symbol">*</span><span class="normal"> button</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">gint</span><span class="normal"> to_print</span><span class="symbol">)</span>

854

855

<span class="normal"> </span><span class="function"><a href="gtk-Signals.html#gtk-signal-connect">gtk_signal_connect</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_OBJECT</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">button</span><span class="symbol">),</span><span class="normal"> </span><span class="string">"clicked"</span><span class="symbol">,</span>

856

<span class="normal"> </span><span class="function"><a href="gtk-Types.html#GTK-SIGNAL-FUNC:CAPS">GTK_SIGNAL_FUNC</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">button_clicked_int</span><span class="symbol">),</span>

857

<span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/glib/unstable/glib-Type-Conversion-Macros.html#GINT-TO-POINTER:CAPS">GINT_TO_POINTER</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">to_print</span><span class="symbol">));</span>

858

859

</tr>

860

</tbody>

861

</table>

862

</div>

863

864

865

866

867

<col>

868

</colgroup>

869

<tbody>

870

<tr>

871

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

872

<td>the object associated with the signal, e.g. if a button

873

is getting pressed, this is that button.</td>

874

</tr>

875

<tr>

876

877

<td>name of the signal.</td>

878

</tr>

879

<tr>

880

881

<td>function pointer to attach to the signal.</td>

882

</tr>

883

<tr>

884

885

<td>value to pass as to your function (through the marshaller).</td>

886

</tr>

887

<tr>

888

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

889

<td>the connection id.</td>

890

</tr>

891

</tbody>

892

</table></div>

893

</div>

894

<hr>

895

896

<a name="gtk-signal-connect-after"></a><h3>gtk_signal_connect_after()</h3>

897

<pre class="programlisting">#define gtk_signal_connect_after(object,name,func,func_data)</pre>

898

899

<h3 class="title">Warning</h3>

900

<p><code class="literal">gtk_signal_connect_after</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect-after"><code class="function">g_signal_connect_after()</code></a> instead.</p>

901

</div>

902

<p>

903

Attaches a function pointer and user data to a signal

904

so that this handler will be called after the other handlers.

905

</p>

906

907

908

909

<col>

910

</colgroup>

911

<tbody>

912

<tr>

913

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

914

<td>the object associated with the signal.</td>

915

</tr>

916

<tr>

917

918

<td>name of the signal.</td>

919

</tr>

920

<tr>

921

922

<td>function pointer to attach to the signal.</td>

923

</tr>

924

<tr>

925

926

<td>value to pass as to your function (through the marshaller).</td>

927

</tr>

928

<tr>

929

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

930

<td>the unique identifier for this attachment: the connection id.</td>

931

</tr>

932

</tbody>

933

</table></div>

934

</div>

935

<hr>

936

937

<a name="gtk-signal-connect-object"></a><h3>gtk_signal_connect_object()</h3>

938

<pre class="programlisting">#define gtk_signal_connect_object(object,name,func,slot_object)</pre>

939

940

<h3 class="title">Warning</h3>

941

<p><code class="literal">gtk_signal_connect_object</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect-swapped"><code class="function">g_signal_connect_swapped()</code></a> instead.</p>

942

</div>

943

<p>

944

This function is for registering a callback that will

945

call another object's callback. That is,

946

instead of passing the object which is responsible

947

for the event as the first parameter of the callback,

948

it is switched with the user data (so the object which emits

949

the signal will be the last parameter, which is where the

950

user data usually is).

951

</p>

952

<p>

953

This is useful for passing a standard function in as a callback.

954

For example, if you wanted a button's press to <a class="link" href="GtkWidget.html#gtk-widget-show" title="gtk_widget_show ()"><code class="function">gtk_widget_show()</code></a>

955

some widget, you could write:

956

</p>

957

958

959

<tbody>

960

<tr>

961

962

<td class="listing_code"><pre class="programlisting"><span class="function"><a href="gtk-Signals.html#gtk-signal-connect-object">gtk_signal_connect_object</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">button</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"clicked"</span><span class="symbol">,</span><span class="normal"> <a href="GtkWidget.html#gtk-widget-show">gtk_widget_show</a></span><span class="symbol">,</span><span class="normal"> window</span><span class="symbol">);</span></pre></td>

963

</tr>

964

</tbody>

965

</table>

966

</div>

967

968

969

970

971

<col>

972

</colgroup>

973

<tbody>

974

<tr>

975

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

976

<td>the object which emits the signal.</td>

977

</tr>

978

<tr>

979

980

<td>the name of the signal.</td>

981

</tr>

982

<tr>

983

984

<td>the function to callback.</td>

985

</tr>

986

<tr>

987

<td><p><span class="term"><em class="parameter"><code>slot_object</code></em> :</span></p></td>

988

<td>the object to pass as the first parameter to func.

989

(Though it pretends to take an object, you can

990

really pass any gpointer as the <span class="type">slot_object</span> .)</td>

991

</tr>

992

<tr>

993

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

994

<td>the connection id.</td>

995

</tr>

996

</tbody>

997

</table></div>

998

</div>

999

<hr>

1000

1001

<a name="gtk-signal-connect-object-after"></a><h3>gtk_signal_connect_object_after()</h3>

1002

<pre class="programlisting">#define gtk_signal_connect_object_after(object,name,func,slot_object)</pre>

1003

1004

<h3 class="title">Warning</h3>

1005

<p><code class="literal">gtk_signal_connect_object_after</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect-data"><code class="function">g_signal_connect_data()</code></a> instead, passing

1006

<code class="literal">G_CONNECT_AFTER|G_CONNECT_SWAPPED</code> as <em class="parameter"><code>connect_flags</code></em>.</p>

1007

</div>

1008

<p>

1009

Attaches a signal hook to a signal, passing in an alternate

1010

object as the first parameter, and guaranteeing

1011

that the default handler and all normal

1012

handlers are called first.

1013

</p>

1014

1015

1016

1017

<col>

1018

</colgroup>

1019

<tbody>

1020

<tr>

1021

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1022

<td>the object associated with the signal.</td>

1023

</tr>

1024

<tr>

1025

1026

<td>name of the signal.</td>

1027

</tr>

1028

<tr>

1029

1030

<td>function pointer to attach to the signal.</td>

1031

</tr>

1032

<tr>

1033

<td><p><span class="term"><em class="parameter"><code>slot_object</code></em> :</span></p></td>

1034

<td>the object to pass as the first parameter to <span class="type">func</span>.</td>

1035

</tr>

1036

<tr>

1037

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

1038

<td>the connection id.</td>

1039

</tr>

1040

</tbody>

1041

</table></div>

1042

</div>

1043

<hr>

1044

1045

<a name="gtk-signal-connect-full"></a><h3>gtk_signal_connect_full ()</h3>

1046

<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gulong"><span class="returnvalue">gulong</span></a> gtk_signal_connect_full (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

1047

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

1048

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> func</code></em>,

1049

<em class="parameter"><code><a class="link" href="gtk-Types.html#GtkCallbackMarshal" title="GtkCallbackMarshal ()"><span class="type">GtkCallbackMarshal</span></a> unsupported</code></em>,

1050

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,

1051

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> destroy_func</code></em>,

1052

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> object_signal</code></em>,

1053

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> after</code></em>);</pre>

1054

1055

<h3 class="title">Warning</h3>

1056

<p><code class="literal">gtk_signal_connect_full</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect-data"><code class="function">g_signal_connect_data()</code></a> instead.</p>

1057

</div>

1058

<p>

1059

Attaches a function pointer and user data to a signal with

1060

more control.

1061

</p>

1062

1063

1064

1065

<col>

1066

</colgroup>

1067

<tbody>

1068

<tr>

1069

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1070

<td>the object which emits the signal. For example, a button

1071

in the button press signal.</td>

1072

</tr>

1073

<tr>

1074

1075

<td>the name of the signal.</td>

1076

</tr>

1077

<tr>

1078

1079

<td>function pointer to attach to the signal.</td>

1080

</tr>

1081

<tr>

1082

1083

<td>the user data associated with the function.</td>

1084

</tr>

1085

<tr>

1086

<td><p><span class="term"><em class="parameter"><code>destroy_func</code></em> :</span></p></td>

1087

<td>function to call when this particular hook is

1088

disconnected.</td>

1089

</tr>

1090

<tr>

1091

<td><p><span class="term"><em class="parameter"><code>object_signal</code></em> :</span></p></td>

1092

<td>whether this is an object signal-- basically an "object

1093

signal" is one that wants its user_data and object fields switched,

1094

which is useful for calling functions which operate on another

1095

object primarily.</td>

1096

</tr>

1097

<tr>

1098

<td><p><span class="term"><em class="parameter"><code>after</code></em> :</span></p></td>

1099

<td>whether to invoke the user-defined handler after the signal, or to let

1100

the signal's default behavior preside (i.e. depending on <span class="type">GTK_RUN_FIRST</span>

1101

and <span class="type">GTK_RUN_LAST</span>).</td>

1102

</tr>

1103

<tr>

1104

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

1105

<td>the connection id.</td>

1106

</tr>

1107

</tbody>

1108

</table></div>

1109

</div>

1110

<hr>

1111

1112

<a name="gtk-signal-connect-while-alive"></a><h3>gtk_signal_connect_while_alive ()</h3>

1113

<pre class="programlisting"><span class="returnvalue">void</span> gtk_signal_connect_while_alive (<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

1114

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

1115

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> func</code></em>,

1116

<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> func_data</code></em>,

1117

<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *alive_object</code></em>);</pre>

1118

1119

<h3 class="title">Warning</h3>

1120

<p><code class="literal">gtk_signal_connect_while_alive</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect-object"><code class="function">g_signal_connect_object()</code></a> instead.</p>

1121

</div>

1122

<p>

1123

Attaches a function pointer and another <a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> to a signal.

1124

</p>

1125

<p>

1126

This function takes an object whose "destroy" signal

1127

should be trapped.

1128

That way, you don't have to clean up the

1129

signal handler when you destroy the object.

1130

It is a little less efficient though.

1131

</p>

1132

<p>

1133

(Instead you may call <a class="link" href="gtk-Signals.html#gtk-signal-disconnect-by-data" title="gtk_signal_disconnect_by_data()"><code class="function">gtk_signal_disconnect_by_data()</code></a>, if you want

1134

to explicitly delete all attachments to this object. This

1135

is perhaps not recommended since it could be confused

1136

with an integer masquerading as a pointer (through <a href="http://library.gnome.org/devel/glib/unstable/glib-Type-Conversion-Macros.html#GINT-TO-POINTER:CAPS"><code class="function">GINT_TO_POINTER()</code></a>).)

1137

</p>

1138

1139

1140

1141

<col>

1142

</colgroup>

1143

<tbody>

1144

<tr>

1145

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1146

<td>the object that emits the signal.</td>

1147

</tr>

1148

<tr>

1149

1150

<td>name of the signal.</td>

1151

</tr>

1152

<tr>

1153

1154

<td>function pointer to attach to the signal.</td>

1155

</tr>

1156

<tr>

1157

1158

<td>pointer to pass to func.</td>

1159

</tr>

1160

<tr>

1161

<td><p><span class="term"><em class="parameter"><code>alive_object</code></em> :</span></p></td>

1162

<td>object whose death should cause the handler connection

1163

to be destroyed.</td>

1164

</tr>

1165

</tbody>

1166

</table></div>

1167

</div>

1168

<hr>

1169

1170

<a name="gtk-signal-connect-object-while-alive"></a><h3>gtk_signal_connect_object_while_alive ()</h3>

1171

<pre class="programlisting"><span class="returnvalue">void</span> gtk_signal_connect_object_while_alive

1172

(<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *object</code></em>,

1173

<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *name</code></em>,

1174

<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> func</code></em>,

1175

<em class="parameter"><code><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> *alive_object</code></em>);</pre>

1176

1177

<h3 class="title">Warning</h3>

1178

<p><code class="literal">gtk_signal_connect_object_while_alive</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect-object"><code class="function">g_signal_connect_object()</code></a> instead, passing

1179

<code class="literal">G_CONNECT_SWAPPED</code> as <em class="parameter"><code>connect_flags</code></em>.</p>

1180

</div>

1181

<p>

1182

These signal connectors are for signals which refer to objects,

1183

so they must not be called after the object is deleted.

1184

</p>

1185

<p>

1186

Unlike <a class="link" href="gtk-Signals.html#gtk-signal-connect-while-alive" title="gtk_signal_connect_while_alive ()"><code class="function">gtk_signal_connect_while_alive()</code></a>,

1187

this swaps the object and user data, making it suitable for

1188

use with functions which primarily operate on the user data.

1189

</p>

1190

<p>

1191

This function acts just like <a class="link" href="gtk-Signals.html#gtk-signal-connect-object" title="gtk_signal_connect_object()"><code class="function">gtk_signal_connect_object()</code></a> except

1192

it traps the "destroy" signal to prevent you from having to

1193

clean up the handler.

1194

</p>

1195

1196

1197

1198

<col>

1199

</colgroup>

1200

<tbody>

1201

<tr>

1202

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1203

<td>the object associated with the signal.</td>

1204

</tr>

1205

<tr>

1206

1207

<td>name of the signal.</td>

1208

</tr>

1209

<tr>

1210

1211

<td>function pointer to attach to the signal.</td>

1212

</tr>

1213

<tr>

1214

<td><p><span class="term"><em class="parameter"><code>alive_object</code></em> :</span></p></td>

1215

<td>the user data, which must be an object, whose destruction

1216

should signal the removal of this signal.</td>

1217

</tr>

1218

</tbody>

1219

</table></div>

1220

</div>

1221

<hr>

1222

1223

<a name="gtk-signal-disconnect"></a><h3>gtk_signal_disconnect()</h3>

1224

<pre class="programlisting">#define gtk_signal_disconnect(object,handler_id)</pre>

1225

1226

<h3 class="title">Warning</h3>

1227

<p><code class="literal">gtk_signal_disconnect</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handler-disconnect"><code class="function">g_signal_handler_disconnect()</code></a> instead.</p>

1228

</div>

1229

<p>

1230

Destroys a user-defined handler connection.

1231

</p>

1232

1233

1234

1235

<col>

1236

</colgroup>

1237

<tbody>

1238

<tr>

1239

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1240

<td>the object which the handler pertains to.</td>

1241

</tr>

1242

<tr>

1243

<td><p><span class="term"><em class="parameter"><code>handler_id</code></em> :</span></p></td>

1244

<td>the connection id.</td>

1245

</tr>

1246

</tbody>

1247

</table></div>

1248

</div>

1249

<hr>

1250

1251

<a name="gtk-signal-disconnect-by-func"></a><h3>gtk_signal_disconnect_by_func()</h3>

1252

<pre class="programlisting">#define gtk_signal_disconnect_by_func(object,func,data)</pre>

1253

1254

<h3 class="title">Warning</h3>

1255

<p><code class="literal">gtk_signal_disconnect_by_func</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handlers-disconnect-by-func"><code class="function">g_signal_handlers_disconnect_by_func()</code></a> instead.</p>

1256

</div>

1257

<p>

1258

Destroys all connections for a particular object, with

1259

the given function-pointer and user-data.

1260

</p>

1261

1262

1263

1264

<col>

1265

</colgroup>

1266

<tbody>

1267

<tr>

1268

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1269

<td>the object which emits the signal.</td>

1270

</tr>

1271

<tr>

1272

1273

<td>the function pointer to search for.</td>

1274

</tr>

1275

<tr>

1276

1277

<td>the user data to search for.</td>

1278

</tr>

1279

</tbody>

1280

</table></div>

1281

</div>

1282

<hr>

1283

1284

<a name="gtk-signal-disconnect-by-data"></a><h3>gtk_signal_disconnect_by_data()</h3>

1285

<pre class="programlisting">#define gtk_signal_disconnect_by_data(object,data)</pre>

1286

1287

<h3 class="title">Warning</h3>

1288

<p><code class="literal">gtk_signal_disconnect_by_data</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handlers-disconnect-matched"><code class="function">g_signal_handlers_disconnect_matched()</code></a> instead.</p>

1289

</div>

1290

<p>

1291

Destroys all connections for a particular object, with

1292

the given user-data.

1293

</p>

1294

1295

1296

1297

<col>

1298

</colgroup>

1299

<tbody>

1300

<tr>

1301

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1302

<td>the object which emits the signal.</td>

1303

</tr>

1304

<tr>

1305

1306

<td>the user data to search for.</td>

1307

</tr>

1308

</tbody>

1309

</table></div>

1310

</div>

1311

<hr>

1312

1313

<a name="gtk-signal-handler-block"></a><h3>gtk_signal_handler_block()</h3>

1314

<pre class="programlisting">#define gtk_signal_handler_block(object,handler_id)</pre>

1315

1316

<h3 class="title">Warning</h3>

1317

<p><code class="literal">gtk_signal_handler_block</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handler-block"><code class="function">g_signal_handler_block()</code></a> instead.</p>

1318

</div>

1319

<p>

1320

Prevents a user-defined handler from being invoked. All other

1321

signal processing will go on as normal, but this particular

1322

handler will ignore it.

1323

</p>

1324

1325

1326

1327

<col>

1328

</colgroup>

1329

<tbody>

1330

<tr>

1331

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1332

<td>the object which emits the signal to block.</td>

1333

</tr>

1334

<tr>

1335

<td><p><span class="term"><em class="parameter"><code>handler_id</code></em> :</span></p></td>

1336

<td>the connection id.</td>

1337

</tr>

1338

</tbody>

1339

</table></div>

1340

</div>

1341

<hr>

1342

1343

<a name="gtk-signal-handler-block-by-func"></a><h3>gtk_signal_handler_block_by_func()</h3>

1344

<pre class="programlisting">#define gtk_signal_handler_block_by_func(object,func,data)</pre>

1345

1346

<h3 class="title">Warning</h3>

1347

<p><code class="literal">gtk_signal_handler_block_by_func</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handlers-block-by-func"><code class="function">g_signal_handlers_block_by_func()</code></a> instead.</p>

1348

</div>

1349

<p>

1350

Prevents a user-defined handler from being invoked, by reference to

1351

the user-defined handler's function pointer and user data. (It may result in

1352

multiple hooks being blocked, if you've called connect multiple times.)

1353

</p>

1354

1355

1356

1357

<col>

1358

</colgroup>

1359

<tbody>

1360

<tr>

1361

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1362

<td>the object which emits the signal to block.</td>

1363

</tr>

1364

<tr>

1365

1366

<td>the function pointer of the handler to block.</td>

1367

</tr>

1368

<tr>

1369

1370

<td>the user data of the handler to block.</td>

1371

</tr>

1372

</tbody>

1373

</table></div>

1374

</div>

1375

<hr>

1376

1377

<a name="gtk-signal-handler-block-by-data"></a><h3>gtk_signal_handler_block_by_data()</h3>

1378

<pre class="programlisting">#define gtk_signal_handler_block_by_data(object,data)</pre>

1379

1380

<h3 class="title">Warning</h3>

1381

<p><code class="literal">gtk_signal_handler_block_by_data</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handlers-block-matched"><code class="function">g_signal_handlers_block_matched()</code></a> instead.</p>

1382

</div>

1383

<p>

1384

Prevents all user-defined handlers with a certain user data from being invoked.

1385

</p>

1386

1387

1388

1389

<col>

1390

</colgroup>

1391

<tbody>

1392

<tr>

1393

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1394

<td>the object which emits the signal we want to block.</td>

1395

</tr>

1396

<tr>

1397

1398

<td>the user data of the handlers to block.</td>

1399

</tr>

1400

</tbody>

1401

</table></div>

1402

</div>

1403

<hr>

1404

1405

<a name="gtk-signal-handler-unblock"></a><h3>gtk_signal_handler_unblock()</h3>

1406

<pre class="programlisting">#define gtk_signal_handler_unblock(object,handler_id)</pre>

1407

1408

<h3 class="title">Warning</h3>

1409

<p><code class="literal">gtk_signal_handler_unblock</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handler-unblock"><code class="function">g_signal_handler_unblock()</code></a> instead.</p>

1410

</div>

1411

<p>

1412

Undoes a block, by connection id. Note that undoing a block doesn't

1413

necessarily make the hook callable, because if you block a

1414

hook twice, you must unblock it twice.

1415

</p>

1416

1417

1418

1419

<col>

1420

</colgroup>

1421

<tbody>

1422

<tr>

1423

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1424

<td>the object which emits the signal we want to unblock.</td>

1425

</tr>

1426

<tr>

1427

<td><p><span class="term"><em class="parameter"><code>handler_id</code></em> :</span></p></td>

1428

<td>the emission handler identifier, as returned by

1429

<a class="link" href="gtk-Signals.html#gtk-signal-connect" title="gtk_signal_connect()"><code class="function">gtk_signal_connect()</code></a>, etc.</td>

1430

</tr>

1431

</tbody>

1432

</table></div>

1433

</div>

1434

<hr>

1435

1436

<a name="gtk-signal-handler-unblock-by-func"></a><h3>gtk_signal_handler_unblock_by_func()</h3>

1437

<pre class="programlisting">#define gtk_signal_handler_unblock_by_func(object,func,data)</pre>

1438

1439

<h3 class="title">Warning</h3>

1440

<p><code class="literal">gtk_signal_handler_unblock_by_func</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handlers-unblock-by-func"><code class="function">g_signal_handlers_unblock_by_func()</code></a> instead.</p>

1441

</div>

1442

<p>

1443

Undoes a block, by function pointer and data.

1444

Note that undoing a block doesn't

1445

necessarily make the hook callable, because if you block a

1446

hook twice, you must unblock it twice.

1447

</p>

1448

1449

1450

1451

<col>

1452

</colgroup>

1453

<tbody>

1454

<tr>

1455

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1456

<td>the object which emits the signal we want to unblock.</td>

1457

</tr>

1458

<tr>

1459

1460

<td>the function pointer to search for.</td>

1461

</tr>

1462

<tr>

1463

1464

<td>the user data to search for.</td>

1465

</tr>

1466

</tbody>

1467

</table></div>

1468

</div>

1469

<hr>

1470

1471

<a name="gtk-signal-handler-unblock-by-data"></a><h3>gtk_signal_handler_unblock_by_data()</h3>

1472

<pre class="programlisting">#define gtk_signal_handler_unblock_by_data(object,data)</pre>

1473

1474

<h3 class="title">Warning</h3>

1475

<p><code class="literal">gtk_signal_handler_unblock_by_data</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handlers-unblock-matched"><code class="function">g_signal_handlers_unblock_matched()</code></a> instead.</p>

1476

</div>

1477

<p>

1478

Undoes block(s), to all signals for a particular object

1479

with a particular user-data pointer

1480

</p>

1481

1482

1483

1484

<col>

1485

</colgroup>

1486

<tbody>

1487

<tr>

1488

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1489

<td>the object which emits the signal we want to unblock.</td>

1490

</tr>

1491

<tr>

1492

1493

<td>the user data to search for.</td>

1494

</tr>

1495

</tbody>

1496

</table></div>

1497

</div>

1498

<hr>

1499

1500

<a name="gtk-signal-handler-pending"></a><h3>gtk_signal_handler_pending()</h3>

1501

<pre class="programlisting">#define gtk_signal_handler_pending(object,signal_id,may_be_blocked)</pre>

1502

1503

<h3 class="title">Warning</h3>

1504

<p><code class="literal">gtk_signal_handler_pending</code> is deprecated and should not be used in newly-written code. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-has-handler-pending"><code class="function">g_signal_has_handler_pending()</code></a> instead.</p>

1505

</div>

1506

<p>

1507

Returns a connection id corresponding to a given signal id and object.

1508

</p>

1509

<p>

1510

One example of when you might use this is when the arguments

1511

to the signal are difficult to compute. A class implementor

1512

may opt to not emit the signal if no one is attached anyway,

1513

thus saving the cost of building the arguments.

1514

</p>

1515

1516

1517

1518

<col>

1519

</colgroup>

1520

<tbody>

1521

<tr>

1522

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1523

<td>the object to search for the desired user-defined handler.</td>

1524

</tr>

1525

<tr>

1526

<td><p><span class="term"><em class="parameter"><code>signal_id</code></em> :</span></p></td>

1527

<td>the number of the signal to search for.</td>

1528

</tr>

1529

<tr>

1530

<td><p><span class="term"><em class="parameter"><code>may_be_blocked</code></em> :</span></p></td>

1531

<td>whether it is acceptable to return a blocked

1532

handler.</td>

1533

</tr>

1534

<tr>

1535

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

1536

<td>the connection id, if a connection was found. 0 otherwise.</td>

1537

</tr>

1538

</tbody>

1539

</table></div>

1540

</div>

1541

<hr>

1542

1543

<a name="gtk-signal-handler-pending-by-func"></a><h3>gtk_signal_handler_pending_by_func()</h3>

1544

<pre class="programlisting">#define gtk_signal_handler_pending_by_func(object,signal_id,may_be_blocked,func,data)</pre>

1545

1546

<h3 class="title">Warning</h3>

1547

<p><code class="literal">gtk_signal_handler_pending_by_func</code> is deprecated and should not be used in newly-written code.</p>

1548

</div>

1549

<p>

1550

Returns a connection id corresponding to a given signal id, object, function

1551

pointer and user data.

1552

</p>

1553

1554

1555

1556

<col>

1557

</colgroup>

1558

<tbody>

1559

<tr>

1560

<td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>

1561

<td>the object to search for the desired handler.</td>

1562

</tr>

1563

<tr>

1564

<td><p><span class="term"><em class="parameter"><code>signal_id</code></em> :</span></p></td>

1565

<td>the number of the signal to search for.</td>

1566

</tr>

1567

<tr>

1568

<td><p><span class="term"><em class="parameter"><code>may_be_blocked</code></em> :</span></p></td>

1569

<td>whether it is acceptable to return a blocked

1570

handler.</td>

1571

</tr>

1572

<tr>

1573

1574

<td>the function pointer to search for.</td>

1575

</tr>

1576

<tr>

1577

1578

<td>the user data to search for.</td>

1579

</tr>

1580

<tr>

1581

<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>

1582

<td>the connection id, if a handler was found. 0 otherwise.</td>

1583

</tr>

1584

</tbody>

1585

</table></div>

1586

</div>

1587

<hr>

1588

1589

<a name="gtk-signal-default-marshaller"></a><h3>gtk_signal_default_marshaller</h3>

1590

<pre class="programlisting">#define gtk_signal_default_marshaller g_cclosure_marshal_VOID__VOID

1591

</pre>

1592

1593

<h3 class="title">Warning</h3>

1594

<p><code class="literal">gtk_signal_default_marshaller</code> is deprecated and should not be used in newly-written code.</p>

1595

</div>

1596

<p>

1597

A marshaller that returns void and takes no extra parameters.

1598

</p>

1599

</div>

1600

</div>

1601

1602

1603

<p>

1604

</p>

1605

1606

1607

1608

<col>

1609

</colgroup>

1610

<tbody>

1611

<tr>

1612

<td><p><span class="term"><a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a></span></p></td>

1613

<td><p>The base class for things which emit signals.</p></td>

1614

</tr>

1615

<tr>

1616

<td><p><span class="term"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html">GSignal</a></span></p></td>

1617

<td><p>The GLib signal system.</p></td>

1618

</tr>

1619

</tbody>

1620

</table></div>

1621

<p>

1622

</p>

1623

</div>

1624

</div>

1625

1626

<hr>

1627

Generated by GTK-Doc V1.18.1</div>

1628

</body>

1629

</html>

b'\\ No newline at end of file'

Older »