~ubuntu-branches/ubuntu/precise/libglade2/precise-proposed

const <link linkend="char">char</link>* <link linkend="glade-get-widget-name">glade_get_widget_name</link> (<link linkend="GtkWidget">GtkWidget</link> *widget);

const <link linkend="gchar">gchar</link> *signal_name,

const <link linkend="gchar">gchar</link> *signal_data,

const <link linkend="gchar">gchar</link> *handler_name,

(<link linkend="GladeXML">GladeXML</link> *self,

</synopsis>

</refsynopsisdiv>

<title>Object Hierarchy</title>

+----GladeXML

</synopsis>

</refsect1>

100

<title>Description</title>

101

<para>

102

This object represents an `instantiation' of an XML interface description.

103

When one of these objects is created, the XML file is read, and the

104

interface is created. The GladeXML object then provides an interface for

105

accessing the widgets in the interface by the names assigned to them

106

inside the XML description.

107

</para>

108

109

<para>

110

The GladeXML object can also be used to connect handlers to the named

111

signals in the description. Libglade also provides an interface by which

112

it can look up the signal handler names in the program's symbol table and

113

automatically connect as many handlers up as it can that way.

114

</para>

115

</refsect1>

116

117

118

<title>Details</title>

119

120

<title><anchor id="GladeXML-struct"/>GladeXML</title>

121

<indexterm><primary>GladeXML</primary></indexterm><programlisting>typedef struct {

122

GObject parent;

123

124

char *filename;

125

} GladeXML;

126

</programlisting>

127

<para>

128

129

</para></refsect2>

130

131

<title><anchor id="GladeXMLClass"/>GladeXMLClass</title>

132

<indexterm><primary>GladeXMLClass</primary></indexterm><programlisting>typedef struct {

133

GObjectClass parent_class;

134

135

/* Virtual function: gets the appropriate gtype for the typename.*/

136

GType (* lookup_type) (GladeXML*self, const char *gtypename);

137

} GladeXMLClass;

138

</programlisting>

139

<para>

140

141

</para></refsect2>

142

143

<title><anchor id="glade-xml-new"/>glade_xml_new ()</title>

144

<indexterm><primary>glade_xml_new</primary></indexterm><programlisting><link linkend="GladeXML">GladeXML</link>* glade_xml_new (const <link linkend="char">char</link> *fname,

145

const <link linkend="char">char</link> *root,

146

const <link linkend="char">char</link> *domain);</programlisting>

147

<para>

148

Creates a new GladeXML object (and the corresponding widgets) from the

149

XML file <parameter>fname</parameter>. Optionally it will only build the interface from the

150

widget node <parameter>root</parameter> (if it is not <literal>NULL</literal>). This feature is useful if you

151

only want to build say a toolbar or menu from the XML file, but not the

152

window it is embedded in. Note also that the XML parse tree is cached

153

to speed up creating another GladeXML object for the same file</para>

154

<para>

155

156

</para><variablelist role="params">

157

<varlistentry><term><parameter>fname</parameter> :</term>

158

<listitem><simpara> the XML file name.

159

</simpara></listitem></varlistentry>

160

161

<listitem><simpara> the widget node in <parameter>fname</parameter> to start building from (or <literal>NULL</literal>)

162

</simpara></listitem></varlistentry>

163

<varlistentry><term><parameter>domain</parameter> :</term>

164

<listitem><simpara> the translation domain for the XML file (or <literal>NULL</literal> for default)

165

</simpara></listitem></varlistentry>

166

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly created GladeXML object, or NULL on failure.

167

</simpara></listitem></varlistentry>

168

</variablelist></refsect2>

169

170

<title><anchor id="glade-xml-new-from-buffer"/>glade_xml_new_from_buffer ()</title>

171

<indexterm><primary>glade_xml_new_from_buffer</primary></indexterm><programlisting><link linkend="GladeXML">GladeXML</link>* glade_xml_new_from_buffer (const <link linkend="char">char</link> *buffer,

172

173

const <link linkend="char">char</link> *root,

174

const <link linkend="char">char</link> *domain);</programlisting>

175

<para>

176

Creates a new GladeXML object (and the corresponding widgets) from the

177

buffer <parameter>buffer</parameter>. Optionally it will only build the interface from the

178

widget node <parameter>root</parameter> (if it is not <literal>NULL</literal>). This feature is useful if you

179

only want to build say a toolbar or menu from the XML document, but not the

180

window it is embedded in.</para>

181

<para>

182

183

</para><variablelist role="params">

184

<varlistentry><term><parameter>buffer</parameter> :</term>

185

<listitem><simpara> the memory buffer containing the XML document.

186

</simpara></listitem></varlistentry>

187

188

<listitem><simpara> the size of the buffer.

189

</simpara></listitem></varlistentry>

190

191

<listitem><simpara> the widget node in <parameter>buffer</parameter> to start building from (or <literal>NULL</literal>)

192

</simpara></listitem></varlistentry>

193

<varlistentry><term><parameter>domain</parameter> :</term>

194

<listitem><simpara> the translation domain to use for this interface (or <literal>NULL</literal>)

195

</simpara></listitem></varlistentry>

196

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly created GladeXML object, or NULL on failure.

197

</simpara></listitem></varlistentry>

198

</variablelist></refsect2>

199

200

<title><anchor id="glade-xml-construct"/>glade_xml_construct ()</title>

201

<indexterm><primary>glade_xml_construct</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> glade_xml_construct (<link linkend="GladeXML">GladeXML</link> *self,

202

const <link linkend="char">char</link> *fname,

203

const <link linkend="char">char</link> *root,

204

const <link linkend="char">char</link> *domain);</programlisting>

205

<para>

206

This routine can be used by bindings (such as gtk--) to help construct

207

a GladeXML object, if it is needed.</para>

208

<para>

209

210

</para><variablelist role="params">

211

212

<listitem><simpara> the GladeXML object

213

</simpara></listitem></varlistentry>

214

<varlistentry><term><parameter>fname</parameter> :</term>

215

<listitem><simpara> the XML filename

216

</simpara></listitem></varlistentry>

217

218

<listitem><simpara> the root widget node (or <literal>NULL</literal> for none)

219

</simpara></listitem></varlistentry>

220

<varlistentry><term><parameter>domain</parameter> :</term>

221

<listitem><simpara> the translation domain (or <literal>NULL</literal> for the default)

222

</simpara></listitem></varlistentry>

223

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if the construction succeeded.

224

</simpara></listitem></varlistentry>

225

</variablelist></refsect2>

226

227

<title><anchor id="glade-xml-signal-connect"/>glade_xml_signal_connect ()</title>

228

<indexterm><primary>glade_xml_signal_connect</primary></indexterm><programlisting><link linkend="void">void</link> glade_xml_signal_connect (<link linkend="GladeXML">GladeXML</link> *self,

229

const <link linkend="char">char</link> *handlername,

230

231

<para>

232

In the glade interface descriptions, signal handlers are specified for

233

widgets by name. This function allows you to connect a C function to

234

all signals in the GladeXML file with the given signal handler name.</para>

235

<para>

236

237

</para><variablelist role="params">

238

239

<listitem><simpara> the GladeXML object

240

</simpara></listitem></varlistentry>

241

<varlistentry><term><parameter>handlername</parameter> :</term>

242

<listitem><simpara> the signal handler name

243

</simpara></listitem></varlistentry>

244

245

<listitem><simpara> the signal handler function

246

</simpara></listitem></varlistentry>

247

</variablelist></refsect2>

248

249

<title><anchor id="glade-xml-signal-connect-data"/>glade_xml_signal_connect_data ()</title>

250

<indexterm><primary>glade_xml_signal_connect_data</primary></indexterm><programlisting><link linkend="void">void</link> glade_xml_signal_connect_data (<link linkend="GladeXML">GladeXML</link> *self,

251

const <link linkend="char">char</link> *handlername,

252

253

254

<para>

255

In the glade interface descriptions, signal handlers are specified for

256

widgets by name. This function allows you to connect a C function to

257

all signals in the GladeXML file with the given signal handler name.

258

</para>

259

<para>

260

It differs from glade_xml_signal_connect since it allows you to

261

specify the data parameter for the signal handler. It is also a small

262

demonstration of how to use glade_xml_signal_connect_full.</para>

263

<para>

264

265

</para><variablelist role="params">

266

267

<listitem><simpara> the GladeXML object

268

</simpara></listitem></varlistentry>

269

<varlistentry><term><parameter>handlername</parameter> :</term>

270

<listitem><simpara> the signal handler name

271

</simpara></listitem></varlistentry>

272

273

<listitem><simpara> the signal handler function

274

</simpara></listitem></varlistentry>

275

276

<listitem><simpara> the signal handler data

277

</simpara></listitem></varlistentry>

278

</variablelist></refsect2>

279

280

<title><anchor id="glade-xml-signal-autoconnect"/>glade_xml_signal_autoconnect ()</title>

281

<indexterm><primary>glade_xml_signal_autoconnect</primary></indexterm><programlisting><link linkend="void">void</link> glade_xml_signal_autoconnect (<link linkend="GladeXML">GladeXML</link> *self);</programlisting>

282

<para>

283

This function is a variation of glade_xml_signal_connect. It uses

284

gmodule's introspective features (by openning the module <literal>NULL</literal>) to

285

look at the application's symbol table. From here it tries to match

286

the signal handler names given in the interface description with

287

symbols in the application and connects the signals.

288

</para>

289

<para>

290

Note that this function will not work correctly if gmodule is not

291

supported on the platform.</para>

292

<para>

293

294

</para><variablelist role="params">

295

296

<listitem><simpara> the GladeXML object.

297

</simpara></listitem></varlistentry>

298

</variablelist></refsect2>

299

300

<title><anchor id="glade-xml-get-widget"/>glade_xml_get_widget ()</title>

301

<indexterm><primary>glade_xml_get_widget</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>* glade_xml_get_widget (<link linkend="GladeXML">GladeXML</link> *self,

302

const <link linkend="char">char</link> *name);</programlisting>

303

<para>

304

This function is used to get a pointer to the GtkWidget corresponding to

305

<parameter>name</parameter> in the interface description. You would use this if you have to do

306

anything to the widget after loading.</para>

307

<para>

308

309

</para><variablelist role="params">

310

311

<listitem><simpara> the GladeXML object.

312

</simpara></listitem></varlistentry>

313

314

<listitem><simpara> the name of the widget.

315

</simpara></listitem></varlistentry>

316

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the widget matching <parameter>name</parameter>, or <literal>NULL</literal> if none exists.

317

</simpara></listitem></varlistentry>

318

</variablelist></refsect2>

319

320

<title><anchor id="glade-xml-get-widget-prefix"/>glade_xml_get_widget_prefix ()</title>

321

<indexterm><primary>glade_xml_get_widget_prefix</primary></indexterm><programlisting><link linkend="GList">GList</link>* glade_xml_get_widget_prefix (<link linkend="GladeXML">GladeXML</link> *self,

322

const <link linkend="char">char</link> *name);</programlisting>

323

<para>

324

This function is used to get a list of pointers to the GtkWidget(s)

325

with names that start with the string <parameter>name</parameter> in the interface description.

326

You would use this if you have to do something to all of these widgets

327

after loading.</para>

328

<para>

329

330

</para><variablelist role="params">

331

332

<listitem><simpara> the GladeXML object.

333

</simpara></listitem></varlistentry>

334

335

<listitem><simpara> the name of the widget.

336

</simpara></listitem></varlistentry>

337

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A list of the widget that match <parameter>name</parameter> as the start of their

338

name, or <literal>NULL</literal> if none exists.

339

</simpara></listitem></varlistentry>

340

</variablelist></refsect2>

341

342

<title><anchor id="glade-get-widget-name"/>glade_get_widget_name ()</title>

343

<indexterm><primary>glade_get_widget_name</primary></indexterm><programlisting>const <link linkend="char">char</link>* glade_get_widget_name (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>

344

<para>

345

Used to get the name of a widget that was generated by a GladeXML object.</para>

346

<para>

347

348

</para><variablelist role="params">

349

<varlistentry><term><parameter>widget</parameter> :</term>

350

<listitem><simpara> the widget

351

</simpara></listitem></varlistentry>

352

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the name of the widget.

353

</simpara></listitem></varlistentry>

354

</variablelist></refsect2>

355

356

<title><anchor id="glade-get-widget-tree"/>glade_get_widget_tree ()</title>

357

<indexterm><primary>glade_get_widget_tree</primary></indexterm><programlisting><link linkend="GladeXML">GladeXML</link>* glade_get_widget_tree (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>

358

<para>

359

This function is used to get the GladeXML object that built this widget.</para>

360

<para>

361

362

</para><variablelist role="params">

363

<varlistentry><term><parameter>widget</parameter> :</term>

364

<listitem><simpara> the widget

365

</simpara></listitem></varlistentry>

366

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the GladeXML object that built this widget.

367

</simpara></listitem></varlistentry>

368

</variablelist></refsect2>

369

370

<title><anchor id="GladeXMLConnectFunc"/>GladeXMLConnectFunc ()</title>

371

<indexterm><primary>GladeXMLConnectFunc</primary></indexterm><programlisting><link linkend="void">void</link> (*GladeXMLConnectFunc) (const <link linkend="gchar">gchar</link> *handler_name,

372

373

const <link linkend="gchar">gchar</link> *signal_name,

374

const <link linkend="gchar">gchar</link> *signal_data,

375

376

377

378

<para>

379

This is the signature of a function used to connect signals. It is used

380

by the glade_xml_signal_connect_full and glade_xml_signal_autoconnect_full

381

functions. It is mainly intented for interpreted language bindings, but

382

could be useful where the programmer wants more control over the signal

383

connection process.</para>

384

<para>

385

386

</para><variablelist role="params">

387

<varlistentry><term><parameter>handler_name</parameter> :</term>

388

<listitem><simpara> the name of the handler function to connect.

389

</simpara></listitem></varlistentry>

390

<varlistentry><term><parameter>object</parameter> :</term>

391

<listitem><simpara> the object to connect the signal to.

392

</simpara></listitem></varlistentry>

393

<varlistentry><term><parameter>signal_name</parameter> :</term>

394

<listitem><simpara> the name of the signal.

395

</simpara></listitem></varlistentry>

396

<varlistentry><term><parameter>signal_data</parameter> :</term>

397

<listitem><simpara> the string value of the signal data given in the XML file.

398

</simpara></listitem></varlistentry>

399

<varlistentry><term><parameter>connect_object</parameter> :</term>

400

<listitem><simpara> non NULL if g_signal_connect_object should be used.

401

</simpara></listitem></varlistentry>

402

<varlistentry><term><parameter>after</parameter> :</term>

403

<listitem><simpara> TRUE if the connection should be made with g_signal_connect_after.

404

</simpara></listitem></varlistentry>

405

406

<listitem><simpara> the user data argument.

407

</simpara></listitem></varlistentry>

408

</variablelist></refsect2>

409

410

<title><anchor id="glade-xml-signal-connect-full"/>glade_xml_signal_connect_full ()</title>

411

<indexterm><primary>glade_xml_signal_connect_full</primary></indexterm><programlisting><link linkend="void">void</link> glade_xml_signal_connect_full (<link linkend="GladeXML">GladeXML</link> *self,

412

const <link linkend="gchar">gchar</link> *handler_name,

413

414

415

<para>

416

This function is similar to glade_xml_signal_connect, except that it

417

allows you to give an arbitrary function that will be used for actually

418

connecting the signals. This is mainly useful for writers of interpreted

419

language bindings, or applications where you need more control over the

420

signal connection process.</para>

421

<para>

422

423

</para><variablelist role="params">

424

425

<listitem><simpara> the GladeXML object.

426

</simpara></listitem></varlistentry>

427

<varlistentry><term><parameter>handler_name</parameter> :</term>

428

<listitem><simpara> the name of the signal handler that we want to connect.

429

</simpara></listitem></varlistentry>

430

431

<listitem><simpara> the function to use to connect the signals.

432

</simpara></listitem></varlistentry>

433

434

<listitem><simpara> arbitrary data to pass to the connect function.

435

</simpara></listitem></varlistentry>

436

</variablelist></refsect2>

437

438

<title><anchor id="glade-xml-signal-autoconnect-full"/>glade_xml_signal_autoconnect_full ()</title>

439

<indexterm><primary>glade_xml_signal_autoconnect_full</primary></indexterm><programlisting><link linkend="void">void</link> glade_xml_signal_autoconnect_full

440

(<link linkend="GladeXML">GladeXML</link> *self,

441

442

443

<para>

444

This function is similar to glade_xml_signal_connect_full, except that it

445

will try to connect all signals in the interface, not just a single

446

named handler. It can be thought of the interpeted language binding

447

version of glade_xml_signal_autoconnect, except that it does not

448

require gmodule to function correctly.</para>

449

<para>

450

451

</para><variablelist role="params">

452

453

<listitem><simpara> the GladeXML object.

454

</simpara></listitem></varlistentry>

455

456

<listitem><simpara> the function used to connect the signals.

457

</simpara></listitem></varlistentry>

458

459

<listitem><simpara> arbitrary data that will be passed to the connection function.

460

</simpara></listitem></varlistentry>

461

</variablelist></refsect2>

462

463

<title><anchor id="GladeXMLCustomWidgetHandler"/>GladeXMLCustomWidgetHandler ()</title>

464

<indexterm><primary>GladeXMLCustomWidgetHandler</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>* (*GladeXMLCustomWidgetHandler) (<link linkend="GladeXML">GladeXML</link> *xml,

465

466

467

468

469

470

471

472

<para>

473

This prototype is for a function that creates custom widgets.</para>

474

<para>

475

476

</para><variablelist role="params">

477

478

<listitem><simpara> the GladeXML object.

479

</simpara></listitem></varlistentry>

480

481

<listitem><simpara> the function name.

482

</simpara></listitem></varlistentry>

483

484

<listitem><simpara> the name of the widget to be created.

485

</simpara></listitem></varlistentry>

486

<varlistentry><term><parameter>string1</parameter> :</term>

487

<listitem><simpara> the string1 property.

488

</simpara></listitem></varlistentry>

489

<varlistentry><term><parameter>string2</parameter> :</term>

490

<listitem><simpara> the string2 property.

491

</simpara></listitem></varlistentry>

492

493

<listitem><simpara> the int1 property.

494

</simpara></listitem></varlistentry>

495

496

<listitem><simpara> the int2 property.

497

</simpara></listitem></varlistentry>

498

499

<listitem><simpara> the data passed to <link linkend="glade-set-custom-handler"><function>glade_set_custom_handler()</function></link>

500

</simpara></listitem></varlistentry>

501

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the GtkWidget.

502

</simpara></listitem></varlistentry>

503

</variablelist></refsect2>

504

505

<title><anchor id="glade-set-custom-handler"/>glade_set_custom_handler ()</title>

506

<indexterm><primary>glade_set_custom_handler</primary></indexterm><programlisting><link linkend="void">void</link> glade_set_custom_handler (<link linkend="GladeXMLCustomWidgetHandler">GladeXMLCustomWidgetHandler</link> handler,

507

508

<para>

509

Calling this function allows you to override the default behaviour

510

when a Custom widget is found in an interface. This could be used by

511

a language binding to call some other function, or to limit what

512

functions can be called to create custom widgets.</para>

513

<para>

514

515

</para><variablelist role="params">

516

<varlistentry><term><parameter>handler</parameter> :</term>

517

<listitem><simpara> the custom widget handler

518

</simpara></listitem></varlistentry>

519

520

<listitem><simpara> user data passed to the custom handler

521

</simpara></listitem></varlistentry>

522

</variablelist></refsect2>

523

524

</refsect1>

525

526

527

528

529

</refentry>

Older »