~ubuntu-branches/ubuntu/hardy/pygobject/hardy : revision 9

1

<?xml version="1.0" standalone="no"?>

2

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

3

"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

4

5

6

7

<refname>gobject Functions</refname>

8

<refpurpose>miscellaneous functions</refpurpose>

9

</refnamediv>

10

11

12

<title>Synopsis</title>

13

14

15

16

<methodname><link

17

linkend="function-gobject--type-name">gobject.type_name</link></methodname>

18

19

</methodsynopsis><methodsynopsis language="python">

20

<methodname><link

21

linkend="function-gobject--type-from-name">gobject.type_from_name</link></methodname>

22

23

</methodsynopsis><methodsynopsis language="python">

24

<methodname><link

25

linkend="function-gobject--type-parent">gobject.type_parent</link></methodname>

26

27

</methodsynopsis><methodsynopsis language="python">

28

<methodname><link

29

linkend="function-gobject--type-is-a">gobject.type_is_a</link></methodname>

30

31

<methodparam><parameter>parent_type</parameter></methodparam>

32

</methodsynopsis><methodsynopsis language="python">

33

<methodname><link

34

linkend="function-gobject--type-children">gobject.type_children</link></methodname>

35

36

</methodsynopsis><methodsynopsis language="python">

37

<methodname><link

38

linkend="function-gobject--type-interfaces">gobject.type_interfaces</link></methodname>

39

40

</methodsynopsis><methodsynopsis language="python">

41

<methodname><link

42

linkend="function-gobject--type-register">gobject.type_register</link></methodname>

43

<methodparam><parameter>class</parameter></methodparam>

44

</methodsynopsis><methodsynopsis language="python">

45

<methodname><link

46

linkend="function-gobject--signal-new">gobject.signal_new</link></methodname>

47

<methodparam><parameter>signal_name</parameter></methodparam>

48

49

<methodparam><parameter>flags</parameter></methodparam>

50

<methodparam><parameter>return_type</parameter></methodparam>

51

<methodparam><parameter>param_types</parameter></methodparam>

52

</methodsynopsis><methodsynopsis language="python">

53

<methodname><link

54

linkend="function-gobject--signal-list-names">gobject.signal_list_names</link></methodname>

55

56

</methodsynopsis><methodsynopsis language="python">

57

<methodname><link

58

linkend="function-gobject--signal-list-ids">gobject.signal_list_ids</link></methodname>

59

60

</methodsynopsis><methodsynopsis language="python">

61

<methodname><link

62

linkend="function-gobject--signal-lookup">gobject.signal_lookup</link></methodname>

63

64

65

</methodsynopsis><methodsynopsis language="python">

66

<methodname><link

67

linkend="function-gobject--signal-name">gobject.signal_name</link></methodname>

68

<methodparam><parameter role="keyword">signal_id</parameter></methodparam>

69

</methodsynopsis><methodsynopsis language="python">

70

<methodname><link

71

linkend="function-gobject--signal-query1">gobject.signal_query</link></methodname>

72

73

74

</methodsynopsis><methodsynopsis language="python">

75

<methodname><link

76

linkend="function-gobject--signal-query2">gobject.signal_query</link></methodname>

77

<methodparam><parameter role="keyword">signal_id</parameter></methodparam>

78

</methodsynopsis><methodsynopsis language="python">

79

<methodname><link

80

linkend="function-gobject--list-properties">gobject.list_properties</link></methodname>

81

82

</methodsynopsis><methodsynopsis language="python">

83

<methodname><link

84

linkend="function-gobject--new">gobject.new</link></methodname>

85

86

87

</methodsynopsis><methodsynopsis language="python">

88

<methodname><link

89

linkend="function-gobject--idle-add">gobject.idle_add</link></methodname>

90

<methodparam><parameter>callback</parameter></methodparam>

91

92

</methodsynopsis><methodsynopsis language="python">

93

<methodname><link

94

linkend="function-gobject--timeout-add">gobject.timeout_add</link></methodname>

95

<methodparam><parameter>interval</parameter></methodparam>

96

<methodparam><parameter>callback</parameter></methodparam>

97

98

</methodsynopsis><methodsynopsis language="python">

99

<methodname><link

100

linkend="function-gobject--io-add-watch">gobject.io_add_watch</link></methodname>

101

102

<methodparam><parameter>condition</parameter></methodparam>

103

<methodparam><parameter>callback</parameter></methodparam>

104

105

</methodsynopsis><methodsynopsis language="python">

106

<methodname><link

107

linkend="function-gobject--source-remove">gobject.source_remove</link></methodname>

108

109

</methodsynopsis><methodsynopsis language="python">

110

<methodname><link

111

linkend="function-gobject--main-context-default">gobject.main_context_default</link></methodname>

112

113

</methodsynopsis><methodsynopsis language="python">

114

<methodname><link

115

linkend="function-gobject--markup-escape-text">gobject.markup_escape_text</link></methodname>

116

117

</methodsynopsis><methodsynopsis language="python">

118

<methodname><link linkend="function-gobject--child-watch-add">gobject.child_watch_add</link></methodname>

119

120

<methodparam><parameter role="keyword">function</parameter></methodparam>

121

122

<methodparam><parameter role="keyword">priority</parameter><initializer>gobject.PRIORITY_DEFAULT</initializer></methodparam>

123

</methodsynopsis><methodsynopsis language="python">

124

<methodname><link

125

linkend="function-gobject--spawn-async">gobject.spawn_async</link></methodname>

126

127

128

<methodparam><parameter role="keyword">working_directory</parameter><initializer>None</initializer></methodparam>

129

<methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam>

130

<methodparam><parameter role="keyword">child_setup</parameter><initializer>None</initializer></methodparam>

131

132

<methodparam><parameter role="keyword">standard_input</parameter><initializer>None</initializer></methodparam>

133

<methodparam><parameter role="keyword">standard_output</parameter><initializer>None</initializer></methodparam>

134

<methodparam><parameter role="keyword">standard_error</parameter><initializer>None</initializer></methodparam>

135

</methodsynopsis><methodsynopsis language="python">

136

<methodname><link

137

linkend="function-gobject--get-current-time">gobject.get_current_time</link></methodname>

138

</methodsynopsis><methodsynopsis language="python">

139

<methodname><link

140

linkend="function-gobject--main-depth">gobject.main_depth</link></methodname>

141

</methodsynopsis></programlisting>

142

143

</refsect1>

144

145

146

<title>Description</title>

147

148

<para>These functions are part of the <literal>PyGTK</literal> gobject

149

module but are not directly associated with a specific class.</para>

150

151

</refsect1>

152

153

154

<title>Functions</title>

155

156

157

<title>gobject.type_name</title>

158

159

160

<methodname>gobject.type_name</methodname>

161

162

</methodsynopsis></programlisting>

163

164

165

166

<listitem><simpara>a GObject type, type ID or

167

instance</simpara></listitem>

168

</varlistentry>

169

170

<term><emphasis>Returns</emphasis> :</term>

171

172

</varlistentry>

173

</variablelist>

174

175

<para>The <function>gobject.type_name</function>() function returns

176

the unique name that is assigned to the specified

177

<parameter>type</parameter>. <parameter>type</parameter> can be a GObject

178

type, type ID or instance. This function raises a TypeError exception

179

if <parameter>type</parameter> isn't a <literal>PyGTK</literal> type.</para>

180

181

</refsect2>

182

183

184

<title>gobject.type_from_name</title>

185

186

187

<methodname>gobject.type_from_name</methodname>

188

189

</methodsynopsis></programlisting>

190

191

192

193

<listitem><simpara>a string containing the name of a

194

type</simpara></listitem>

195

</varlistentry>

196

197

<term><emphasis>Returns</emphasis> :</term>

198

<listitem><simpara>the type ID named

199

200

</varlistentry>

201

</variablelist>

202

203

<para>The <function>gobject.type_from_name</function>() function

204

returns the type ID of the <literal>PyGTK</literal> type with the name

205

specified by <parameter>type_name</parameter>. This function raises a

206

RuntimeError exception if no type matches

207

208

209

</refsect2>

210

211

212

<title>gobject.type_parent</title>

213

214

215

<methodname>gobject.type_parent</methodname>

216

217

</methodsynopsis></programlisting>

218

219

220

221

<listitem><simpara>a GObject type, type ID or

222

instance</simpara></listitem>

223

</varlistentry>

224

225

<term><emphasis>Returns</emphasis> :</term>

226

<listitem><simpara>the parent type ID</simpara></listitem>

227

</varlistentry>

228

</variablelist>

229

230

<para>The <function>gobject.type_parent</function>() function returns

231

the direct parent type ID of the specified <parameter>type</parameter>.

232

<parameter>type</parameter> can be a GObject type, type ID or instance. If

233

<parameter>type</parameter> has no parent, i.e. is a fundamental type, the

234

RuntimeError exception is raised. </para>

235

236

</refsect2>

237

238

239

<title>gobject.type_is_a</title>

240

241

242

<methodname>gobject.type_is_a</methodname>

243

244

<methodparam><parameter>parent_type</parameter></methodparam>

245

</methodsynopsis></programlisting>

246

247

248

249

<listitem><simpara>a GObject type, type ID or

250

instance</simpara></listitem>

251

</varlistentry>

252

253

<term><parameter>parent_type</parameter> :</term>

254

<listitem><simpara>a GObject type, type ID or

255

instance</simpara></listitem>

256

</varlistentry>

257

258

<term><emphasis>Returns</emphasis> :</term>

259

<listitem><simpara><literal>TRUE</literal> if

260

<parameter>parent_type</parameter> is an ancestor of

261

262

</varlistentry>

263

</variablelist>

264

265

<para>The <function>gobject.type_is_a</function>() function returns

266

<literal>TRUE</literal> if the specified <parameter>type</parameter> is a

267

descendant of the type specified by <parameter>parent_type</parameter>. This

268

function also returns <literal>TRUE</literal> if

269

<parameter>parent_type</parameter> is an interface and

270

<parameter>type</parameter> conforms to it.</para>

271

272

</refsect2>

273

274

275

<title>gobject.type_children</title>

276

277

278

<methodname>gobject.type_children</methodname>

279

280

</methodsynopsis></programlisting>

281

282

283

284

<listitem><simpara>a GObject type, type ID or

285

instance</simpara></listitem>

286

</varlistentry>

287

288

<term><emphasis>Returns</emphasis> :</term>

289

<listitem><simpara>a list of the child types of

290

291

</varlistentry>

292

</variablelist>

293

294

<para>The <function>gobject.type_children</function>() function

295

returns a list containing the child types of the specified

296

297

298

</refsect2>

299

300

301

<title>gobject.type_interfaces</title>

302

303

304

<methodname>gobject.type_interfaces</methodname>

305

306

</methodsynopsis></programlisting>

307

308

309

310

<listitem><simpara>a GObject type, type ID or

311

instance</simpara></listitem>

312

</varlistentry>

313

314

<term><emphasis>Returns</emphasis> :</term>

315

<listitem><simpara>a list of the interface types supported by

316

317

</varlistentry>

318

</variablelist>

319

320

<para>The <function>gobject.type_interfaces</function>() function

321

returns a list of the interface types supported by

322

<parameter>type</parameter>. <parameter>type</parameter> can be a GObject

323

type, type ID or instance. This function returns a RuntimeError exception if

324

type is not a valid type or has no interfaces.</para>

325

326

</refsect2>

327

328

329

<title>gobject.type_register</title>

330

331

332

<methodname>gobject.type_register</methodname>

333

<methodparam><parameter>class</parameter></methodparam>

334

</methodsynopsis></programlisting>

335

336

337

<term><parameter>class</parameter> :</term>

338

<listitem><simpara>a Python class that is a descendant of <link

339

linkend="class-gobject"><classname>gobject.GObject</classname></link></simpara></listitem>

340

</varlistentry>

341

</variablelist>

342

343

<para>The <function>gobject.type_register</function>() function

344

registers the specified Python <parameter>class</parameter> as a PyGTK type.

345

class must be a descendant of <link

346

linkend="class-gobject"><classname>gobject.GObject</classname></link>. The function generates a name for the new type.</para>

347

348

</refsect2>

349

350

351

<title>gobject.signal_new</title>

352

353

354

<methodname>gobject.signal_new</methodname>

355

<methodparam><parameter>signal_name</parameter></methodparam>

356

357

<methodparam><parameter>flags</parameter></methodparam>

358

<methodparam><parameter>return_type</parameter></methodparam>

359

<methodparam><parameter>param_types</parameter></methodparam>

360

</methodsynopsis></programlisting>

361

362

363

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

364

<listitem><simpara>a string containing the name of the

365

signal</simpara></listitem>

366

</varlistentry>

367

368

369

<listitem><simpara>the object type that the signal is associated

370

with</simpara></listitem>

371

</varlistentry>

372

373

<term><parameter>flags</parameter> :</term>

374

<listitem><simpara>the signal flags</simpara></listitem>

375

</varlistentry>

376

377

<term><parameter>return_type</parameter> :</term>

378

<listitem><simpara>the return type of the signal

379

handler</simpara></listitem>

380

</varlistentry>

381

382

<term><parameter>param_types</parameter> :</term>

383

<listitem><simpara>the parameter types passed to the signal

384

handler</simpara></listitem>

385

</varlistentry>

386

387

<term><emphasis>Returns</emphasis> :</term>

388

<listitem><simpara>a unique integer signal ID</simpara></listitem>

389

</varlistentry>

390

</variablelist>

391

392

<para>The <function>gobject.signal_new</function>() function registers

393

a signal with the specified <parameter>signal_name</parameter> for the

394

specified object <parameter>type</parameter>. The value of

395

<parameter>flags</parameter> is a combination of:</para>

396

397

398

399

<term><literal>gobject.SIGNAL_RUN_FIRST</literal></term>

400

401

<simpara>Invoke the object method handler in the first emission

402

stage. </simpara>

403

</listitem>

404

</varlistentry>

405

406

<term><literal>gobject.SIGNAL_RUN_LAST</literal></term>

407

408

<simpara>Invoke the object method handler in the third emission

409

stage.</simpara>

410

</listitem>

411

</varlistentry>

412

413

<term><literal>gobject.SIGNAL_RUN_CLEANUP</literal></term>

414

415

<simpara>Invoke the object method handler in the last emission

416

stage.</simpara>

417

</listitem>

418

</varlistentry>

419

420

<term><literal>gobject.SIGNAL_NO_RECURSE</literal></term>

421

422

<simpara>Signals being emitted for an object while currently

423

being in emission for this very object will not be emitted recursively, but

424

instead cause the first emission to be restarted.</simpara>

425

</listitem>

426

</varlistentry>

427

428

<term><literal>gobject.SIGNAL_DETAILED</literal></term>

429

430

<simpara>This signal supports "::detail" appendixes to the

431

signal name upon handler connections and emissions.</simpara>

432

</listitem>

433

</varlistentry>

434

435

<term><literal>gobject.SIGNAL_ACTION</literal></term>

436

437

<simpara>Action signals are signals that may freely be emitted

438

on alive objects from user code via <link

439

linkend="method-gobject--emit"><methodname>gobject.emit()</methodname>()</link>

440

and friends, without the need of being embedded into extra code that

441

performs pre or post emission adjustments on the object. They can also be

442

thought of as generically callable object methods.</simpara>

443

</listitem>

444

</varlistentry>

445

446

<term><literal>gobject.SIGNAL_NO_HOOKS</literal></term>

447

448

<simpara> No emissions hooks are supported for this

449

signal.</simpara>

450

</listitem>

451

</varlistentry>

452

</variablelist>

453

454

<para><parameter>return_type</parameter> is the type of the return

455

value from a signal handler and may be a gobject type, type ID or instance.

456

The <parameter>param_types</parameter> parameter is a list of additional

457

types that are passed to the signal handler. Each parameter type may be

458

specified as a gobject type, type ID or instance. For example, to add a

459

signal to the gtk.Window type called "my-signal" that calls a handler with a

460

gtk.Button widget and an integer value and a return value that is a

461

boolean, use:</para>

462

463

464

gobject.signal_new("my_signal", gtk.Window, gobject.SIGNAL_RUN_LAST, gobject.TYPE_BOOLEAN, (gtk.Button, gobject.TYPE_INT))

465

</programlisting>

466

467

</refsect2>

468

469

470

<title>gobject.signal_list_names</title>

471

472

473

<methodname>gobject.signal_list_names</methodname>

474

475

</methodsynopsis></programlisting>

476

477

478

479

<listitem><simpara>a GObject type, type ID or

480

instance</simpara></listitem>

481

</varlistentry>

482

483

<term><emphasis>Returns</emphasis> :</term>

484

<listitem><simpara>a list of the signal names supported by

485

486

</varlistentry>

487

</variablelist>

488

489

<para>The <function>gobject.signal_list_names</function>() function

490

returns a list of the names of the signals that are supported by the

491

specified GObject <parameter>type</parameter></para>

492

493

<note>

494

<para>The type keyword is available in PyGTK 2.6 and above.</para>

495

</note>

496

497

</refsect2>

498

499

500

<title>gobject.signal_list_ids</title>

501

502

503

<methodname>gobject.signal_list_ids</methodname>

504

505

</methodsynopsis></programlisting>

506

507

508

509

<listitem><simpara>a GObject type, type ID or

510

instance</simpara></listitem>

511

</varlistentry>

512

513

<term><emphasis>Returns</emphasis> :</term>

514

<listitem><simpara>a list of the signal ids supported by

515

516

</varlistentry>

517

</variablelist>

518

519

<note>

520

<para>This method is available in PyGTK 2.6 and above.</para>

521

</note>

522

523

<para>The <function>gobject.signal_list_ids</function>() function

524

returns a list of the integer ids of the signals that are supported by the

525

GObject specified by <parameter>type</parameter></para>

526

527

</refsect2>

528

529

530

<title>gobject.signal_lookup</title>

531

532

533

<methodname>gobject.signal_lookup</methodname>

534

535

536

</methodsynopsis></programlisting>

537

538

539

540

<listitem><simpara>the name of a signal for

541

542

</varlistentry>

543

544

545

<listitem><simpara>a GObject type, type ID or

546

instance</simpara></listitem>

547

</varlistentry>

548

549

<term><emphasis>Returns</emphasis> :</term>

550

<listitem><simpara>the integer id of a signal supported by

551

552

</varlistentry>

553

</variablelist>

554

555

<note>

556

<para>This method is available in PyGTK 2.6 and above.</para>

557

</note>

558

559

<para>The <function>gobject.signal_lookup</function>() function

560

returns the id of the signal with the name specified by

561

<parameter>name</parameter> that is supported by the GObject specified

562

specified by<parameter>type</parameter>. 0 is returned if the signal is not

563

found.</para>

564

565

</refsect2>

566

567

568

<title>gobject.signal_name</title>

569

570

571

<methodname>gobject.signal_name</methodname>

572

<methodparam><parameter role="keyword">signal_id</parameter></methodparam>

573

</methodsynopsis></programlisting>

574

575

576

<term><parameter role="keyword">signal_id</parameter> :</term>

577

<listitem><simpara>an integer signal id</simpara></listitem>

578

</varlistentry>

579

580

<term><emphasis>Returns</emphasis> :</term>

581

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

582

583

</varlistentry>

584

</variablelist>

585

586

<note>

587

<para>This method is available in PyGTK 2.6 and above.</para>

588

</note>

589

590

<para>The <function>gobject.signal_name</function>() function returns

591

the name of the signal that has the signal id specified by

592

593

594

</refsect2>

595

596

597

<title>gobject.signal_query</title>

598

599

600

<methodname>gobject.signal_query</methodname>

601

602

603

</methodsynopsis></programlisting>

604

605

606

607

<listitem><simpara>the name of a signal for

608

609

</varlistentry>

610

611

612

<listitem><simpara>a GObject type, type ID or

613

instance</simpara></listitem>

614

</varlistentry>

615

616

<term><emphasis>Returns</emphasis> :</term>

617

<listitem><simpara>a 6-tuple containing signal information or

618

619

</varlistentry>

620

</variablelist>

621

622

<note>

623

<para>This method is available in PyGTK 2.6 and above.</para>

624

</note>

625

626

<para>The <function>gobject.signal_query</function>() function returns

627

a 6-tuple containing information about the signal with the name specified by

628

<parameter>name</parameter> that is supported by the GObject specified by

629

<parameter>type</parameter>. If the signal is not found

630

<literal>None</literal> is returned.</para>

631

632

<para>The signal information 6-tuple contains:</para>

633

634

635

636

<simpara>the integer signal id</simpara>

637

</listitem>

638

639

<simpara>the signal name</simpara>

640

</listitem>

641

642

<simpara>the GType that the signal is registered for</simpara>

643

</listitem>

644

645

<simpara>the signal flags (see the <xref

646

linkend="gobject-signal-constants"

647

endterm="gobject-signal-constants-title"></xref>)</simpara>

648

</listitem>

649

650

<simpara>the GType of the return from the signal callback

651

function</simpara>

652

</listitem>

653

654

<simpara>a tuple containing the GTypes of the parameters that are

655

passed to the signal callback function. Note that these may not correspond

656

exactly to the <literal>PyGTK</literal> signal callback parameters.</simpara>

657

</listitem>

658

</itemizedlist>

659

660

</refsect2>

661

662

663

<title>gobject.signal_query</title>

664

665

666

<methodname>gobject.signal_query</methodname>

667

<methodparam><parameter role="keyword">signal_id</parameter></methodparam>

668

</methodsynopsis></programlisting>

669

670

671

<term><parameter role="keyword">signal_id</parameter> :</term>

672

<listitem><simpara>the integer id of a signal</simpara></listitem>

673

</varlistentry>

674

675

<term><emphasis>Returns</emphasis> :</term>

676

<listitem><simpara>a 6-tuple containing signal information or

677

678

</varlistentry>

679

</variablelist>

680

681

<note>

682

<para>This method is available in PyGTK 2.6 and above.</para>

683

</note>

684

685

<para>The <function>gobject.signal_query</function>() function returns

686

a 6-tuple containing information about the signal with the id specified by

687

<parameter>signal_id</parameter>. If the signal is not found

688

<literal>None</literal> is returned.</para>

689

690

<para>The signal information 6-tuple contains:</para>

691

692

693

694

<simpara>the integer signal id</simpara>

695

</listitem>

696

697

<simpara>the signal name</simpara>

698

</listitem>

699

700

<simpara>the GType that the signal is registered for</simpara>

701

</listitem>

702

703

<simpara>the signal flags (see the <xref

704

linkend="gobject-signal-constants"

705

endterm="gobject-signal-constants-title"></xref>)</simpara>

706

</listitem>

707

708

<simpara>the GType of the return from the signal callback

709

function</simpara>

710

</listitem>

711

712

<simpara>a tuple containing the GTypes of the parameters that are

713

passed to the signal callback function. Note that these may not correspond

714

exactly to the <literal>PyGTK</literal> signal callback parameters.</simpara>

715

</listitem>

716

</itemizedlist>

717

718

</refsect2>

719

720

721

<title>gobject.list_properties</title>

722

723

724

<methodname>gobject.list_properties</methodname>

725

726

</methodsynopsis></programlisting>

727

728

729

730

<listitem><simpara>a GObject type, type ID or

731

instance</simpara></listitem>

732

</varlistentry>

733

734

<term><emphasis>Returns</emphasis> :</term>

735

<listitem><simpara>a list of the properties (as GParam objects)

736

supported by <parameter>type</parameter></simpara></listitem>

737

</varlistentry>

738

</variablelist>

739

740

<para>The <function>gobject.list_properties</function>() function

741

returns a list of the properties (as GParam objects) supported by

742

743

744

</refsect2>

745

746

747

<title>gobject.new</title>

748

749

750

<methodname>gobject.new</methodname>

751

752

753

</methodsynopsis></programlisting>

754

755

756

757

<listitem><simpara>a GObject type, type ID or

758

instance</simpara></listitem>

759

</varlistentry>

760

761

762

<listitem><simpara>zero or more property-value

763

pairs</simpara></listitem>

764

</varlistentry>

765

766

<term><emphasis>Returns</emphasis> :</term>

767

<listitem><simpara>a new object if the specified

768

769

</varlistentry>

770

</variablelist>

771

772

<para>The <function>gobject.new</function>() function returns a new

773

object of the specified <parameter>type</parameter>. type must specify a

774

type that is a descendant of <link

775

linkend="class-gobject"><classname>gobject.GObject</classname></link>. A

776

TypeError exception is raised if <parameter>type</parameter> specifies an

777

abstract class or a type that is not a descendant of <link

778

linkend="class-gobject"><classname>gobject.GObject</classname></link>. A set

779

of property-value pairs may be specified to set the value of the object's

780

properties.</para>

781

782

</refsect2>

783

784

785

<title>gobject.idle_add</title>

786

787

788

<methodname>gobject.idle_add</methodname>

789

<methodparam><parameter>callback</parameter></methodparam>

790

791

</methodsynopsis></programlisting>

792

793

794

<term><parameter>callback</parameter> :</term>

795

<listitem><simpara>a function to call when

796

<literal>PyGTK</literal> is idle</simpara></listitem>

797

</varlistentry>

798

799

800

<listitem><simpara>optionals arguments to be passed to

801

<parameter>callback</parameter></simpara></listitem>

802

</varlistentry>

803

804

<term><emphasis>Returns</emphasis> :</term>

805

<listitem><simpara>an integer ID</simpara></listitem>

806

</varlistentry>

807

</variablelist>

808

809

<para>The <function>gobject.idle_add</function>() function adds a

810

function (specified by <parameter>callback</parameter>) to be called

811

whenever there are no higher priority events pending to the default main

812

loop. The function is given the default idle priority,

813

<literal>gobject.PRIORITY_DEFAULT_IDLE</literal>. Additional arguments to

814

pass to <parameter>callback</parameter> can be specified after

815

<parameter>callback</parameter>. The idle priority can be specified as a

816

keyword-value pair with the keyword "priority". If

817

<parameter>callback</parameter> returns <literal>FALSE</literal> it is

818

automatically removed from the list of event sources and will not be called

819

again.</para>

820

821

</refsect2>

822

823

824

<title>gobject.timeout_add</title>

825

826

827

<methodname>gobject.timeout_add</methodname>

828

<methodparam><parameter>interval</parameter></methodparam>

829

<methodparam><parameter>callback</parameter></methodparam>

830

831

</methodsynopsis></programlisting>

832

833

834

<term><parameter>interval</parameter> :</term>

835

<listitem><simpara>the time between calls to the function, in

836

milliseconds </simpara></listitem>

837

</varlistentry>

838

839

<term><parameter>callback</parameter> :</term>

840

<listitem><simpara>the function to call</simpara></listitem>

841

</varlistentry>

842

843

844

<listitem><simpara>zero or more arguments that will be passed to

845

<parameter>callback</parameter></simpara></listitem>

846

</varlistentry>

847

848

<term><emphasis>Returns</emphasis> :</term>

849

<listitem><simpara>an integer ID of the event

850

source</simpara></listitem>

851

</varlistentry>

852

</variablelist>

853

854

<para>The <function>gobject.timeout_add</function>() function sets a

855

function (specified by <parameter>callback</parameter>) to be called at

856

regular intervals (specified by <parameter>interval</parameter>, with the

857

default priority, <literal>gobject.PRIORITY_DEFAULT</literal>. Additional

858

arguments to pass to <parameter>callback</parameter> can be specified after

859

<parameter>callback</parameter>. The idle priority may be specified as a

860

keyword-value pair with the keyword "priority".</para>

861

862

<para>The function is called repeatedly until it returns

863

<literal>FALSE</literal>, at which point the timeout is automatically

864

destroyed and the function will not be called again. The first call to the

865

function will be at the end of the first interval. Note that timeout

866

functions may be delayed, due to the processing of other event sources. Thus

867

they should not be relied on for precise timing. After each call to the

868

timeout function, the time of the next timeout is recalculated based on the

869

current time and the given interval (it does not try to 'catch up' time lost

870

in delays).</para>

871

872

</refsect2>

873

874

875

<title>gobject.io_add_watch</title>

876

877

878

<methodname>gobject.io_add_watch</methodname>

879

880

<methodparam><parameter>condition</parameter></methodparam>

881

<methodparam><parameter>callback</parameter></methodparam>

882

883

</methodsynopsis></programlisting>

884

885

886

887

<listitem><simpara>a Python file object or an integer file

888

descriptor ID</simpara></listitem>

889

</varlistentry>

890

891

<term><parameter>condition</parameter> :</term>

892

<listitem><simpara>a condition mask</simpara></listitem>

893

</varlistentry>

894

895

<term><parameter>callback</parameter> :</term>

896

<listitem><simpara>a function to call</simpara></listitem>

897

</varlistentry>

898

899

900

<listitem><simpara>additional arguments to pass to

901

<parameter>callback</parameter></simpara></listitem>

902

</varlistentry>

903

904

<term><emphasis>Returns</emphasis> :</term>

905

<listitem><simpara>an integer ID of the event source</simpara></listitem>

906

</varlistentry>

907

</variablelist>

908

909

<para>The <function>gobject.io_add_watch</function>() function

910

arranges for the file (specified by <parameter>fd</parameter>) to be

911

monitored by the main loop for the specified

912

<parameter>condition</parameter>. <parameter>fd</parameter> may be a Python

913

file object or an integer file descriptor. The value of condition is a

914

combination of:</para>

915

916

917

918

<term><literal>gobject.IO_IN</literal></term>

919

920

<simpara>There is data to read.</simpara>

921

</listitem>

922

</varlistentry>

923

924

<term><literal>gobject.IO_OUT</literal></term>

925

926

<simpara>Data can be written (without blocking). </simpara>

927

</listitem>

928

</varlistentry>

929

930

<term><literal>gobject.IO_PRI</literal></term>

931

932

<simpara>There is urgent data to read.</simpara>

933

</listitem>

934

</varlistentry>

935

936

<term><literal>gobject.IO_ERR</literal></term>

937

938

<simpara>Error condition.</simpara>

939

</listitem>

940

</varlistentry>

941

942

<term><literal>gobject.IO_HUP</literal></term>

943

944

<simpara>Hung up (the connection has been broken, usually for

945

pipes and sockets).</simpara>

946

</listitem>

947

</varlistentry>

948

</variablelist>

949

950

<para>Additional arguments to pass to <parameter>callback</parameter>

951

can be specified after <parameter>callback</parameter>. The idle priority

952

may be specified as a keyword-value pair with the keyword "priority". The

953

signature of the callback function is:</para>

954

955

956

def callback(source, cb_condition, ...)

957

</programlisting>

958

959

<para>where <parameter>source</parameter> is

960

<parameter>fd</parameter>, the file descriptor;

961

<parameter>cb_condition</parameter> is the condition that triggered the

962

signal; and, <parameter>...</parameter> are the zero or more arguments that

963

were passed to the <function>gobject.io_add_watch</function>()

964

function.</para>

965

966

<para>If the callback function returns <literal>FALSE</literal> it

967

will be automatically removed from the list of event sources and will not be

968

called again. If it returns <literal>TRUE</literal> it will be called again

969

when the condition is matched.</para>

970

971

</refsect2>

972

973

974

<title>gobject.source_remove</title>

975

976

977

<methodname>gobject.source_remove</methodname>

978

979

</methodsynopsis></programlisting>

980

981

982

983

<listitem><simpara>an integer ID</simpara></listitem>

984

</varlistentry>

985

986

<term><emphasis>Returns</emphasis> :</term>

987

<listitem><simpara><literal>TRUE</literal> if the event source was

988

removed</simpara></listitem>

989

</varlistentry>

990

</variablelist>

991

992

<para>The <function>gobject.source_remove</function>() function

993

removes the event source specified by tag (as returned by the <link

994

linkend="function-gobject--idle-add"><function>gobject.idle_add</function>()</link>,

995

<link

996

linkend="function-gobject--timeout-add"><function>gobject.timeout_add</function></link>()

997

and <link

998

linkend="function-gobject--io-add-watch"><function>gobject.io_add_watch</function>()</link>

999

functions)</para>

1000

1001

</refsect2>

1002

1003

1004

<title>gobject.main_context_default</title>

1005

1006

1007

<methodname>gobject.main_context_default</methodname>

1008

1009

</methodsynopsis></programlisting>

1010

1011

1012

<term><emphasis>Returns</emphasis> :</term>

1013

<listitem><simpara>the default gobject.MainContext

1014

object</simpara></listitem>

1015

</varlistentry>

1016

</variablelist>

1017

1018

<para>The <function>gobject.main_context_default</function>() function

1019

returns the default gobject.MainContext object.</para>

1020

1021

</refsect2>

1022

1023

1024

<title>gobject.markup_escape_text</title>

1025

1026

1027

<methodname>gobject.markup_escape_text</methodname>

1028

1029

</methodsynopsis></programlisting>

1030

1031

1032

1033

<listitem><simpara>the UTF-8 string to be

1034

escaped</simpara></listitem>

1035

</varlistentry>

1036

1037

<term><emphasis>Returns</emphasis> :</term>

1038

<listitem><simpara>the escaped text</simpara></listitem>

1039

</varlistentry>

1040

</variablelist>

1041

1042

<note>

1043

<para>This function is available in PyGTK 2.8 and above.</para>

1044

</note>

1045

1046

<para>The <function>gobject.markup_escape_text</function>() function

1047

escapes the string specified by <parameter>text</parameter> so that the

1048

markup parser will parse it verbatim. Less than, greater than, ampersand,

1049

etc. are replaced with the corresponding entities. This function would

1050

typically be used when writing out a file to be parsed with the markup

1051

parser.</para>

1052

1053

<para>Note that this function doesn't protect whitespace and line

1054

endings from being processed according to the XML rules for normalization of

1055

line endings and attribute values.</para>

1056

1057

</refsect2>

1058

1059

1060

<title>gobject.child_watch_add</title>

1061

1062

1063

<methodname>gobject.child_watch_add</methodname>

1064

1065

<methodparam><parameter role="keyword">function</parameter></methodparam>

1066

1067

<methodparam><parameter role="keyword">priority</parameter><initializer>gobject.PRIORITY_DEFAULT</initializer></methodparam>

1068

</methodsynopsis></programlisting>

1069

1070

1071

1072

<listitem><simpara>process id of a child process to watch</simpara></listitem>

1073

</varlistentry>

1074

<varlistentry><term><parameter role="keyword">function</parameter> :</term>

1075

<listitem><simpara>the function to call</simpara></listitem>

1076

</varlistentry>

1077

1078

1079

<listitem><simpara>the optional data to pass to

1080

<parameter>function</parameter></simpara></listitem>

1081

</varlistentry>

1082

1083

<term><parameter role="keyword">priority</parameter> :</term>

1084

<listitem><simpara>the priority of the idle source - one of the

1085

<xref linkend="gobject-priority-constants"

1086

endterm="gobject-priority-constants-title"></xref></simpara></listitem>

1087

</varlistentry>

1088

1089

<term><emphasis>Returns</emphasis> :</term>

1090

<listitem><simpara>the id of event source.</simpara></listitem>

1091

</varlistentry>

1092

</variablelist>

1093

<note>

1094

<para>This function is available in PyGTK 2.6 and above.</para>

1095

</note>

1096

1097

<para>The <function>gobject.child_watch_add</function>() function sets

1098

the function specified by <parameter>function</parameter> to be called with

1099

the user data specified by <parameter>data</parameter> when the child

1100

indicated by <parameter>pid</parameter> exits. The signature for the

1101

callback is:</para>

1102

1103

1104

def callback(pid, condition, user_data)

1105

</programlisting>

1106

1107

<para>where <parameter>pid</parameter> is is the child process id,

1108

<parameter>condition</parameter> is the status information about the child

1109

process and <parameter>user_data</parameter> is <parameter>data</parameter>

1110

PyGTK supports only a single callback per process id.</para>

1111

1112

</refsect2>

1113

1114

1115

<title>gobject.spawn_async</title>

1116

1117

1118

<methodname>gobject.spawn_async</methodname>

1119

1120

1121

<methodparam><parameter role="keyword">working_directory</parameter><initializer>None</initializer></methodparam>

1122

<methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam>

1123

<methodparam><parameter role="keyword">child_setup</parameter><initializer>None</initializer></methodparam>

1124

1125

<methodparam><parameter role="keyword">standard_input</parameter><initializer>None</initializer></methodparam>

1126

<methodparam><parameter role="keyword">standard_output</parameter><initializer>None</initializer></methodparam>

1127

<methodparam><parameter role="keyword">standard_error</parameter><initializer>None</initializer></methodparam>

1128

</methodsynopsis></programlisting>

1129

1130

1131

1132

<listitem><simpara>a sequence of strings containing the arguments

1133

of the child process</simpara></listitem>

1134

</varlistentry>

1135

1136

1137

<listitem><simpara>the child's environment or

1138

<literal>None</literal> to inherit the parent's

1139

environment.</simpara></listitem>

1140

</varlistentry>

1141

1142

<term><parameter role="keyword">working_directory</parameter> :</term>

1143

<listitem><simpara>the child's current working directory, or

1144

<literal>None</literal> to inherit parent's</simpara></listitem>

1145

</varlistentry>

1146

1147

<term><parameter role="keyword">flags</parameter> :</term>

1148

<listitem><simpara>flags from the <xref

1149

linkend="gobject-spawn-flag-constants"

1150

endterm="gobject-spawn-flag-constants-title"></xref>.</simpara></listitem>

1151

</varlistentry>

1152

1153

<term><parameter role="keyword">child_setup</parameter> :</term>

1154

<listitem><simpara>a function to run in the child just before

1155

calling <function>exec</function>()</simpara></listitem>

1156

</varlistentry>

1157

1158

1159

<listitem><simpara>the user data for the

1160

<parameter>child_setup</parameter> function</simpara></listitem>

1161

</varlistentry>

1162

1163

<term><parameter role="keyword">standard_input</parameter> :</term>

1164

<listitem><simpara>if <literal>TRUE</literal> return the file

1165

descriptor for the child's stdin</simpara></listitem>

1166

</varlistentry>

1167

1168

<term><parameter role="keyword">standard_output</parameter> :</term>

1169

<listitem><simpara>if <literal>TRUE</literal> return the file

1170

descriptor for the child's stdout</simpara></listitem>

1171

</varlistentry>

1172

1173

<term><parameter role="keyword">standard_error</parameter> :</term>

1174

<listitem><simpara>if <literal>TRUE</literal> return the file

1175

descriptor for the child's stderr</simpara></listitem>

1176

</varlistentry>

1177

1178

<term><emphasis>Returns</emphasis> :</term>

1179

<listitem><simpara>a 4-tuple containing the child's process id and

1180

the stdin, stdout and stderr file descriptor integers.</simpara></listitem>

1181

</varlistentry>

1182

</variablelist>

1183

<note>

1184

<para>This function is available in PyGTK 2.6 and above.</para>

1185

</note>

1186

1187

<para>The <function>gobject.spawn_async</function>() function executes

1188

a child program asynchronously (your program will not block waiting for the

1189

child to exit). The child program is specified by the only argument that

1190

must be provided, <parameter>argv</parameter>. <parameter>argv</parameter>

1191

should be a sequence of strings, to be passed as the argument vector for the

1192

child. The first string in <parameter>argv</parameter> is of course the name

1193

of the program to execute. By default, the name of the program must be a

1194

full path; the <envar>PATH</envar> shell variable will only be searched if

1195

you pass the <literal>gobject.SPAWN_SEARCH_PATH</literal> flag in

1196

<parameter>flags</parameter>. The function returns a 4-tuple containing the

1197

child's process id and the file descriptors for the child's stdin, stdout

1198

and stderr. The stdin, stdout and stderr file descriptors are returned only

1199

ofthe corresponding <parameter>standard_input</parameter>,

1200

<parameter>standard_output</parameter> or

1201

<parameter>standard_error</parameter> params are

1202

1203

1204

<para>On Windows, the low-level child process creation API

1205

(<function>CreateProcess</function>()) doesn't use argument vectors, but a

1206

command line. The C runtime library's <function>spawn*</function>() family

1207

of functions (which <link

1208

linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link>

1209

eventually calls) paste the argument vector elements into a command line,

1210

and the C runtime startup code does a corresponding reconstruction of an

1211

argument vector from the command line, to be passed to

1212

<function>main</function>(). Complications arise when you have argument

1213

vector elements that contain spaces of double quotes. The

1214

<function>spawn*</function>() functions don't do any quoting or escaping,

1215

but on the other hand the startup code does do unquoting and unescaping in

1216

order to enable receiving arguments with embedded spaces or double

1217

quotes. To work around this asymmetry, the <link

1218

linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link>

1219

function will do quoting and escaping on argument vector elements that need

1220

it before calling the C runtime <function>spawn</function>()

1221

function.</para>

1222

1223

<para><parameter>envp</parameter> is a sequence of strings, where each

1224

string has the form <literal>KEY=VALUE</literal>. This will become the

1225

child's environment. If <parameter>envp</parameter> is

1226

<parameter>None</parameter> or not specified, the child inherits its

1227

parent's environment.</para>

1228

1229

<para><parameter>flags</parameter> should be the bitwise

1230

<literal>OR</literal> of the <xref linkend="gobject-spawn-flag-constants"

1231

endterm="gobject-spawn-flag-constants-title"></xref> you want to affect the

1232

function's behaviour. The <literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal>

1233

flag means that the child will not automatically be reaped; you must use a

1234

GChildWatch source to be notified about the death of the child

1235

process. Eventually you must call g_spawn_close_pid() on the child_pid, in

1236

order to free resources which may be associated with the child process. (On

1237

Unix, using a GChildWatch source is equivalent to calling

1238

<function>waitpid</function>() or handling the <literal>SIGCHLD</literal>

1239

signal manually. On Windows, calling g_spawn_close_pid() is equivalent to

1240

calling <function>CloseHandle</function>() on the process handle

1241

returned).</para>

1242

1243

<para><literal>gobject.SPAWN_LEAVE_DESCRIPTORS_OPEN</literal> means

1244

that the parent's open file descriptors will be inherited by the child;

1245

otherwise all descriptors except stdin/stdout/stderr will be closed before

1246

calling <function>exec</function>() in the

1247

child. <literal>gobject.SPAWN_SEARCH_PATH</literal> means that

1248

<parameter>argv</parameter>[0] need not be an absolute path, it will be

1249

looked for in the user's

1250

<envar>PATH</envar>. <literal>gobject.SPAWN_STDOUT_TO_DEV_NULL</literal>

1251

means that the child's standard output will be discarded, instead of going

1252

to the same location as the parent's standard output. If you use this flag,

1253

<parameter>standard_output</parameter> must be

1254

<literal>None</literal>. <literal>gobject.SPAWN_STDERR_TO_DEV_NULL</literal>

1255

means that the child's standard error will be discarded, instead of going to

1256

the same location as the parent's standard error. If you use this flag,

1257

<parameter>standard_error</parameter> must be

1258

<literal>None</literal>. <literal>gobject.SPAWN_CHILD_INHERITS_STDIN</literal>

1259

means that the child will inherit the parent's standard input (by default,

1260

the child's standard input is attached to

1261

<filename>/dev/null</filename>). If you use this flag,

1262

<parameter>standard_input</parameter> must be

1263

<literal>None</literal>. <literal>gobject.SPAWN_FILE_AND_ARGV_ZERO</literal>

1264

means that the first element of <parameter>argv</parameter> is the file to

1265

execute, while the remaining elements are the actual argument vector to pass

1266

to the file. Normally the <link

1267

linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link>

1268

function uses <parameter>argv</parameter>[0] as the file to execute, and

1269

passes all of <parameter>argv</parameter> to the child.</para>

1270

1271

<para><parameter>child_setup</parameter> and

1272

<parameter>user_data</parameter> are a function and user data. On POSIX

1273

platforms, the function is called in the child after GLib has performed all

1274

the setup it plans to perform (including creating pipes, closing file

1275

descriptors, etc.) but before calling <function>exec</function>(). That is,

1276

<parameter>child_setup</parameter> is called just before calling

1277

<function>exec</function>() in the child. Obviously actions taken in this

1278

function will only affect the child, not the parent. On Windows, there is no

1279

separate <function>fork</function>() and <function>exec</function>()

1280

functionality. Child processes are created and run right away with one API

1281

call,

1282

<function>CreateProcess</function>(). <parameter>child_setup</parameter> is

1283

called in the parent process just before creating the child process. You

1284

should carefully consider what you do in <parameter>child_setup</parameter>

1285

if you intend your software to be portable to Windows.</para>

1286

1287

<para>The returned child process id can be used to send signals to the

1288

child, or to wait for the child if you specified the

1289

<literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal> flag. On Windows, child

1290

pid will be returned only if you specified the

1291

<literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal> flag.</para>

1292

1293

<para>The caller of the <link

1294

linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link>

1295

must close any returned file descriptors when they are no longer in

1296

use.</para>

1297

1298

<para>If <parameter>standard_input</parameter> is

1299

<literal>None</literal>, the child's standard input is attached to

1300

<filename>/dev/null</filename> unless

1301

<literal>gobject.SPAWN_CHILD_INHERITS_STDIN</literal> is set.</para>

1302

1303

<para>If <parameter>standard_error</parameter> is

1304

<literal>None</literal>, the child's standard error goes to the same

1305

location as the parent's standard error unless

1306

<literal>gobject.SPAWN_STDERR_TO_DEV_NULL</literal> is set.</para>

1307

1308

<para>If <parameter>standard_output</parameter> is

1309

<literal>None</literal>, the child's standard output goes to the same

1310

location as the parent's standard output unless

1311

<literal>gobject.SPAWN_STDOUT_TO_DEV_NULL</literal> is set.</para>

1312

1313

<para>If an error occurs, the gobject.GError exception will be

1314

raised.</para>

1315

1316

</refsect2>

1317

1318

1319

<title>gobject.get_current_time</title>

1320

1321

1322

<methodname>gobject.get_current_time</methodname>

1323

</methodsynopsis></programlisting>

1324

1325

1326

<term><emphasis>Returns</emphasis> :</term>

1327

<listitem><simpara>the current time as the number of seconds and

1328

microseconds from the epoch.</simpara></listitem>

1329

</varlistentry>

1330

</variablelist>

1331

<note>

1332

<para>This function is available in PyGTK 2.8 and above.</para>

1333

</note>

1334

1335

<para>The <function>gobject.get_current_time</function>() function

1336

reurns the current time of day as the number of seconds and microseconds

1337

from the epoch.</para>

1338

1339

</refsect2>

1340

1341

1342

<title>gobject.main_depth</title>

1343

1344

1345

<methodname>gobject.main_depth</methodname>

1346

</methodsynopsis></programlisting>

1347

1348

1349

<term><emphasis>Returns</emphasis> :</term>

1350

<listitem><simpara>he depth of the stack of calls to the main

1351

context.</simpara></listitem>

1352

</varlistentry>

1353

</variablelist>

1354

<note>

1355

<para>This function is available in PyGTK 2.8 and above.</para>

1356

</note>

1357

1358

<para>The <function>main_depth</function>() function returns the depth

1359

of the stack of calls in the main context. That is, when called from the

1360

toplevel, it gives 0. When called from within a callback from the <link

1361

linkend="method-gobjectmaincontext--iteration"><methodname>gobject.MainContext.iteration</methodname>()</link>

1362

method (or the <link

1363

linkend="method-gobjectmainloop--run"><methodname>gobject.MainLoop.run</methodname>()</link>

1364

method, etc.) it returns 1. When called from within a callback to a

1365

recursive call to the <link

1366

linkend="method-gobjectmaincontext--iteration"><methodname>gobject.MainContext.iteration</methodname>()</link>

1367

method), it returns 2. And so forth.</para>

1368

1369

</refsect2>

1370

1371

</refsect1>

1372

1373

</refentry>