summaryrefslogtreecommitdiff
path: root/docs/html/pygobject-introduction.html
blob: 0f15d2f3d084e357a7596c927dfe010a4f759057 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Introduction</title><link rel="stylesheet" href="style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="PyGObject Reference Manual"><link rel="up" href="index.html" title="PyGObject Reference Manual"><link rel="prev" href="index.html" title="PyGObject Reference Manual"><link rel="next" href="glib-class-reference.html" title="PyGlibClass Reference"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Introduction</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="glib-class-reference.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="pygobject-introduction"></a>Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="pygobject-introduction.html#pygobject-reference-format">Reference Page Format</a></span></dt></dl></div><p>This document describes many of the <code class="literal">PyGObject</code>
  version 2.12 classes and their methods and associated
  functions. Deprecated classes, functions and methods have been
  specifically left out of this reference though classes that have become
  deprecated since PyGObject 2.0 have been left in but annotated with a
  deprecation warning. This document attempts to document as much of the
  <code class="literal">PyGObject</code> <code class="literal">API</code> as possible but there
  are undoubtedly errors and omissions. If you discover any of these please
  file a bug report at <a class="ulink" href="http://bugzilla.gnome.org" target="_top">bugzilla.gnome.org</a> for the
  <code class="literal">pygobject</code> project. Specific areas that have not been
  documented include:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">The GParamSpec class</li></ul></div><p>This reference describes the API for <code class="literal">PyGObject</code> as
  of version 2.11.0+ and assumes that the additional API changes for version
  2.12 will not be significant. There will undoubtedly be changes that are
  not reflected in this reference. The differences in the API between
  version 2.0 and previous versions are denoted in this reference with a
  Note that describes the availability of the object, constructor, method or
  function. Any of these that do not have a notation can be assumed to be
  available in all versions of PyGObject from 2.0 and up. The source code
  must be consulted if this reference and your version of
  <code class="literal">PyGObject</code> seem to differ. You are encouraged to use the
  latest version of <code class="literal">PyGObject</code> that is available. See the
  <a class="ulink" href="http://www.pygtk.org" target="_top"><code class="literal">PyGTK</code>
  homepage</a> for more information and more resources on how to use
  PyGObject as well as help in its development.</p><p> The Reference contains a chapter for each
  <code class="literal">PyGObject</code> module containing the class descriptions. The
  class descriptions are arranged alphabetically within the
  chapters. Currently there is one module chapter:</p><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term">The <code class="literal">gobject</code> module</span></p></td><td>The classes that are included in the
<code class="literal">gobject</code> module of <code class="literal">PyGObject</code> and are
accessed similar to: gobject.GObject. These classes are the base object
classes that the <code class="literal">gtk</code> and <code class="literal">gtk.gdk</code>
module classes are built on.</td></tr></tbody></table><div class="sect1" title="Reference Page Format"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pygobject-reference-format"></a>Reference Page Format</h2></div></div></div><p>Each <code class="literal">PyGObject</code> class is described in a reference
page that has a number of sections in a fixed format. Each reference page
will have a subset of the following sections:</p><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term">Name</span></p></td><td>The name and a one-line description of the
class.</td></tr><tr><td><p><span class="term">Synopsis</span></p></td><td>A synopsis of the class and its methods and
optionally a list of associated functions.</td></tr><tr><td><p><span class="term">Ancestry</span></p></td><td>The list of the parent classes of the class. This
section may not be present in all class descriptions.</td></tr><tr><td><p><span class="term">Properties</span></p></td><td>A list of the properties (internal state)
supported by the class. This section may not be present in all classes. The
property descriptions include the name, the access operations (e.g. Read,
Write), and a brief description. Properties are accessed using the <a class="link" href="class-gobject.html#method-gobject--set-property" title="gobject.GObject.set_property"><code class="methodname">gobject.set_property</code>()</a> 
and <a class="link" href="class-gobject.html#method-gobject--get-property" title="gobject.GObject.get_property"><code class="methodname">gobject.get_property</code>()</a> 
methods that are available to every <code class="literal">PyGObject</code> object. This
section may not be present in all class descriptions.</td></tr><tr><td><p><span class="term">Attributes</span></p></td><td>A set of internal object state data accessible as Python
	  attributes (e.g. object.attr). The attribute descriptions include
	  a name by which the attribute data is accessed, the access mode
	  (e.g. Read, Write), and a brief description of the attribute. Most
	  <code class="literal">PyGObject</code> classes do not support attributes so
	  this section is not present in most class descriptions.</td></tr><tr><td><p><span class="term">Signal Prototypes</span></p></td><td>A list of the signals supported by the class including
	  the signal name and a synopsis of the signal handler function
	  prototype. This section may not be present in all class
	  descriptions.</td></tr><tr><td><p><span class="term">Description</span></p></td><td>A description of the class and possibly some of
	the methods supported by the class.</td></tr><tr><td><p><span class="term">Constructor</span></p></td><td>The description of the class object constructor including
	  the synopsis with brief parameter descriptions and a description
	  of th use of the constructor. There may be more than one
	  constructor description if the constructor supports different
	  parameter lists. This section may not be present in all class
	  descriptions.</td></tr><tr><td><p><span class="term">Methods</span></p></td><td>A list of methods supported by the class. Each method
	  description includes: a synopsis of the method and its parameters
	  as well as a brief description of each parameter and return value
	  (if any); and, a description of the use of the method.</td></tr><tr><td><p><span class="term">Functions</span></p></td><td>A list of related functions. Each function description
	  includes a synopsis of the function and its parameters and return
	  value (if any), and a description of the use of the
	  function.</td></tr><tr><td><p><span class="term">Signals</span></p></td><td>A list of signals including a synopsis of the signal
	  handler prototype function with its parameters and return value
	  (if any). The signal emission conditions are briefly
	  described. This section is not present in all class descriptions;
	  specifically, the <code class="literal">gtk.gdk</code> classes do not
	  usually support signals.</td></tr></tbody></table><p>The function and method synopsis parameters are displayed in
    <span class="bold"><strong>bold</strong></span> to denote Python keyword
    parameters.  Also if the parameter is optional its default value will be
    displayed. For example the <a class="link" href="gobject-functions.html#function-gobject--signal-lookup" title="gobject.signal_lookup"><code class="function">gobject.signal_lookup</code>()</a>
    function synopsis is:</p><pre class="programlisting">
<code class="methodsynopsis">    def <span class="methodname"><a class="link" href="gobject-functions.html#function-gobject--signal-lookup" title="gobject.signal_lookup">gobject.signal_lookup</a></span>(<span class="methodparam"><span class="parameter"><strong class="parameter"><code>name</code></strong></span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>type</code></strong></span></span>)</code>
</pre><p>The parameters <em class="parameter"><code>name</code></em> and
    <em class="parameter"><code>type</code></em> are keyword parameters that can be specified
    in a call either by position or keyword (in which case position is not
    important). The following calls have the same result:</p><pre class="programlisting">
  id = gobject.signal_lookup("clicked", gtk.Button)
  id = gobject.signal_lookup("clicked", type=gtk.Button)
  id = gobject.signal_lookup(name="clicked", type=gtk.Button)
  id = gobject.signal_lookup(type=gtk.Button, name="clicked")
</pre><p>Parameters that are not keyword parameters are displayed in
<span class="emphasis"><em>italic</em></span> and must be specified positionally but may also
be optional.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="glib-class-reference.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">PyGObject Reference Manual </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> PyGlibClass Reference</td></tr></table></div></body></html>