diff options
| -rw-r--r-- | ChangeLog | 26 | ||||
| -rw-r--r-- | Makefile.am | 5 | ||||
| -rw-r--r-- | configure.ac | 23 | ||||
| -rw-r--r-- | docs/.cvsignore | 3 | ||||
| -rw-r--r-- | docs/Makefile.am | 52 | ||||
| -rw-r--r-- | docs/common.xsl | 20 | ||||
| -rw-r--r-- | docs/devhelp.xsl | 154 | ||||
| -rw-r--r-- | docs/html.xsl | 288 | ||||
| -rw-r--r-- | docs/pdf-style.xsl | 11 | ||||
| -rw-r--r-- | docs/pdf.xsl | 259 | ||||
| -rw-r--r-- | docs/ref-html-style.xsl | 52 | ||||
| -rw-r--r-- | docs/reference/.cvsignore | 2 | ||||
| -rw-r--r-- | docs/reference/pygobject-classes.xml | 20 | ||||
| -rw-r--r-- | docs/reference/pygobject-constants.xml | 495 | ||||
| -rw-r--r-- | docs/reference/pygobject-functions.xml | 1373 | ||||
| -rw-r--r-- | docs/reference/pygobject-gboxed.xml | 68 | ||||
| -rw-r--r-- | docs/reference/pygobject-ginterface.xml | 38 | ||||
| -rw-r--r-- | docs/reference/pygobject-gpointer.xml | 42 | ||||
| -rw-r--r-- | docs/reference/pygobject-maincontext.xml | 152 | ||||
| -rw-r--r-- | docs/reference/pygobject-mainloop.xml | 202 | ||||
| -rw-r--r-- | docs/reference/pygobject-ref.xml | 154 | ||||
| -rw-r--r-- | docs/reference/pygobject.xml | 867 |
22 files changed, 4305 insertions, 1 deletions
@@ -1,3 +1,29 @@ +2006-07-12 Johan Dahlin <jdahlin@async.com.br> + + * Makefile.am: + * configure.ac: + * docs/.cvsignore: + * docs/Makefile.am: + * docs/common.xsl: + * docs/devhelp.xsl: + * docs/html.xsl: + * docs/pdf-style.xsl: + * docs/pdf.xsl: + * docs/ref-html-style.xsl: + * docs/reference/.cvsignore: + * docs/reference/pygobject-classes.xml: + * docs/reference/pygobject-constants.xml: + * docs/reference/pygobject-functions.xml: + * docs/reference/pygobject-gboxed.xml: + * docs/reference/pygobject-ginterface.xml: + * docs/reference/pygobject-gpointer.xml: + * docs/reference/pygobject-maincontext.xml: + * docs/reference/pygobject-mainloop.xml: + * docs/reference/pygobject-ref.xml: + * docs/reference/pygobject.xml: + Import GObject part of John Finlay's PyGTK Reference Manual, copy + over infrastructure from the pygtk-web module. + 2006-07-12 Gustavo J. A. M. Carneiro <gjc@inescporto.pt> * configure.ac: Post-release version bump to 2.11.1. diff --git a/Makefile.am b/Makefile.am index 0677490..da49dba 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,6 +1,9 @@ AUTOMAKE_OPTIONS = 1.7 -SUBDIRS = gobject . examples tests +SUBDIRS = gobject examples tests +if ENABLE_DOCS + SUBDIRS += docs +endif PLATFORM_VERSION = 2.0 diff --git a/configure.ac b/configure.ac index ea6f22d..d317d75 100644 --- a/configure.ac +++ b/configure.ac @@ -70,6 +70,28 @@ AC_ARG_ENABLE(thread, AC_HELP_STRING([--disable-thread], [Disable pygobject threading support]),, enable_thread=yes) +dnl Building documentation +AC_ARG_ENABLE(docs, + AC_HELP_STRING([--disable-docs], [Disable documentation building]),, + enable_docs=yes) +if test "${enable_docs}" != no; then + dnl + dnl Check for xsltproc + dnl + AC_PATH_PROG([XSLTPROC], [xsltproc]) + if test -z "$XSLTPROC"; then + enable_docs=no + fi + + dnl check for DocBook DTD and stylesheets in the local catalog. + dnl JH_CHECK_XML_CATALOG([-//OASIS//DTD DocBook XML V4.1.2//EN], + dnl [DocBook XML DTD V4.1.2],,enable_docs=no) + dnl JH_CHECK_XML_CATALOG([http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl], + dnl [DocBook XSL Stylesheets],,enable_docs=no) +fi + +AM_CONDITIONAL(ENABLE_DOCS, test x$enable_docs != xno) + AM_CHECK_PYMOD(thread,,,enable_thread=no) AC_MSG_CHECKING(whether to enable threading in pygobject) @@ -105,6 +127,7 @@ JH_ADD_CFLAG([-fno-strict-aliasing]) AC_CONFIG_FILES( Makefile pygobject-2.0.pc + docs/Makefile gobject/Makefile examples/Makefile tests/Makefile diff --git a/docs/.cvsignore b/docs/.cvsignore new file mode 100644 index 0000000..5508282 --- /dev/null +++ b/docs/.cvsignore @@ -0,0 +1,3 @@ +Makefile +Makefile.in +html diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 0000000..1c4917e --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,52 @@ +SUBDIRS = + +REF_VERSION = $(PYGOBJECT_MAJOR_VERSION).$(PYGOBJECT_MINOR_VERSION) + +XSLFILES = \ + common.xsl \ + devhelp.xsl \ + html.xsl \ + ref-html-style.xsl \ + pdf-style.xsl \ + pdf.xsl + +XMLFILES = \ + reference/pygobject-ref.xml \ + reference/pygobject-classes.xml \ + reference/pygobject-constants.xml \ + reference/pygobject-functions.xml \ + reference/pygobject-gboxed.xml \ + reference/pygobject-ginterface.xml \ + reference/pygobject-gpointer.xml \ + reference/pygobject-maincontext.xml \ + reference/pygobject-mainloop.xml + +HTMLdir = $(datadir)/devhelp/books/pygobject-$(REF_VERSION) +HTML_DATA = \ + html/class-gobjectgboxed.html \ + html/class-gobjectginterface.html \ + html/class-gobjectgpointer.html \ + html/class-gobject.html \ + html/class-gobjectmaincontext.html \ + html/class-gobjectmainloop.html \ + html/gobject-class-reference.html \ + html/gobject-constants.html \ + html/gobject-functions.html \ + html/index.html \ + html/index.sgml \ + html/pygobject-$(REF_VERSION).devhelp + +BUILT_SOURCES = $(HTML_DATA) +CLEANFILES = $(HTML_DATA) + +%.html: reference ${XMLFILES} ${XSLFILES} + xsltproc --nonet --xinclude -o html/ \ + --stringparam gtkdoc.bookname "pygobject-$(REF_VERSION)" \ + --stringparam gtkdoc.version ${REF_VERSION} \ + ref-html-style.xsl reference/pygobject-ref.xml + +pdf: reference ${XMLFILES} ${XSLFILES} + xsltproc --nonet --xinclude -o pygobject-ref.fo pdf-style.xsl \ + reference/pygobject-ref.xml + pdfxmltex pygobject-ref.fo >output </dev/null + diff --git a/docs/common.xsl b/docs/common.xsl new file mode 100644 index 0000000..cb4a7d2 --- /dev/null +++ b/docs/common.xsl @@ -0,0 +1,20 @@ +<?xml version='1.0'?> <!--*- mode: xml -*--> +<!DOCTYPE xsl:stylesheet [ +]> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0'> + +<xsl:template match="parameter"> + <xsl:choose> + <xsl:when test="@role = 'keyword'"> + <xsl:call-template name="inline.boldmonoseq"/> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="inline.italicmonoseq"/> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + + +</xsl:stylesheet> diff --git a/docs/devhelp.xsl b/docs/devhelp.xsl new file mode 100644 index 0000000..b329a4c --- /dev/null +++ b/docs/devhelp.xsl @@ -0,0 +1,154 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0' + xmlns="http://www.devhelp.net/book" + exclude-result-prefixes="#default"> + + <xsl:template name="generate.devhelp"> + <xsl:call-template name="write.chunk"> + <xsl:with-param name="filename"> + <xsl:choose> + <xsl:when test="$gtkdoc.bookname"> + <xsl:value-of select="$gtkdoc.bookname"/> + </xsl:when> + <xsl:otherwise> + <xsl:text>book</xsl:text> + </xsl:otherwise> + </xsl:choose> + <xsl:text>.devhelp</xsl:text> + </xsl:with-param> + <xsl:with-param name="method" select="'xml'"/> + <xsl:with-param name="indent" select="'yes'"/> + <xsl:with-param name="encoding" select="'utf-8'"/> + <xsl:with-param name="content"> + <xsl:call-template name="devhelp"/> + </xsl:with-param> + </xsl:call-template> + </xsl:template> + + <xsl:template name="devhelp"> + <xsl:variable name="title"> + <xsl:apply-templates select="." mode="generate.devhelp.toc.title.mode"/> + </xsl:variable> + <xsl:variable name="link"> + <xsl:call-template name="href.target"/> + </xsl:variable> + <xsl:variable name="author"> + <xsl:if test="articleinfo|bookinfo"> + <xsl:apply-templates mode="generate.devhelp.authors" + select="articleinfo|bookinfo"/> + </xsl:if> + </xsl:variable> + <xsl:variable name="toc.nodes" select="part|reference|preface|chapter| + appendix|article|bibliography| + glossary|index|refentry| + bridgehead|sect1"/> + + <book title="{$title}" link="{$link}" author="{$author}" name="{$gtkdoc.bookname}"> + <xsl:if test="$toc.nodes"> + <chapters> + <xsl:apply-templates select="$toc.nodes" + mode="generate.devhelp.toc.mode"/> + </chapters> + </xsl:if> + <functions> + <xsl:apply-templates select="//refsect1" + mode="generate.devhelp.constructor.index.mode"/> + <xsl:apply-templates select="//refsect2" + mode="generate.devhelp.index.mode"/> + </functions> + </book> + </xsl:template> + + <xsl:template match="*" mode="generate.devhelp.toc.mode"> + <xsl:variable name="title"> + <xsl:apply-templates select="." mode="generate.devhelp.toc.title.mode"/> + </xsl:variable> + <xsl:variable name="target"> + <xsl:variable name="anchor" select="title/anchor"/> + <xsl:choose> + <xsl:when test="$anchor"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="$anchor"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="href.target"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <sub name="{$title}" link="{$target}"> + <xsl:apply-templates select="section|sect1| + refentry|refsect| + bridgehead|part|chapter" + mode="generate.devhelp.toc.mode"/> + </sub> + </xsl:template> + + <xsl:template match="*" mode="generate.devhelp.index.mode"> + <xsl:variable name="title" select="title"/> + <xsl:variable name="anchor" select="title/anchor"/> + <xsl:variable name="target"> + <xsl:choose> + <xsl:when test="$anchor"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="$anchor"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="href.target"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <function name="{$title}" link="{$target}"/> + </xsl:template> + + <xsl:template match="*" mode="generate.devhelp.constructor.index.mode"> + <xsl:variable name="title" select="title"/> + <xsl:variable name="anchor" select="title/anchor"/> + <xsl:variable name="target"> + <xsl:choose> + <xsl:when test="$anchor"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="$anchor"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="href.target"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="$title='Constructor'"> + <xsl:variable name ="constructor" select="programlisting//methodname"/> + <function name="{$constructor}" link="{$target}"/> + </xsl:if> + </xsl:template> + + <!-- get title --> + <xsl:template match="article" mode="generate.devhelp.toc.title.mode"> + <xsl:value-of select="articleinfo/title"/> + </xsl:template> + <xsl:template match="book" mode="generate.devhelp.toc.title.mode"> + <xsl:value-of select="bookinfo/title"/> + </xsl:template> + <xsl:template match="refentry" mode="generate.devhelp.toc.title.mode"> + <xsl:value-of select="refnamediv/refname"/> + </xsl:template> + <xsl:template match="*" mode="generate.devhelp.toc.title.mode"> + <xsl:value-of select="title"/> + </xsl:template> + + <!-- generate list of authors ... --> + <xsl:template match="articleinfo|bookinfo" mode="generate.devhelp.authors"> + <xsl:for-each select="authorgroup/author"> + <xsl:value-of select="firstname"/> + <xsl:text> </xsl:text> + <xsl:value-of select="surname"/> + <xsl:if test="not(last())"> + <xsl:text>, </xsl:text> + </xsl:if> + </xsl:for-each> + </xsl:template> + +</xsl:stylesheet> diff --git a/docs/html.xsl b/docs/html.xsl new file mode 100644 index 0000000..350f183 --- /dev/null +++ b/docs/html.xsl @@ -0,0 +1,288 @@ +<?xml version='1.0'?> <!--*- mode: xml -*--> +<!DOCTYPE xsl:stylesheet [ +<!ENTITY RE " "> +<!ENTITY nbsp " "> +]> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0'> + +<xsl:param name="shade.verbatim" select="1"/> +<xsl:param name="use.id.as.filename" select="1"/> +<xsl:param name="chunk.fast" select="1"/> +<xsl:param name="chunker.output.encoding" select="'utf-8'"/> + +<xsl:attribute-set name="shade.verbatim.style"> + <xsl:attribute name="border">0</xsl:attribute> + <xsl:attribute name="bgcolor">#E0E0E0</xsl:attribute> + <xsl:attribute name="width">100%</xsl:attribute> +</xsl:attribute-set> + +<xsl:param name="linenumbering.extension" select="1"/> +<xsl:param name="variablelist.as.table" select="1"/> + +<xsl:template match="blockquote"> + <div class="{local-name(.)}"> + <xsl:if test="@lang or @xml:lang"> + <xsl:call-template name="language.attribute"/> + </xsl:if> + <xsl:call-template name="anchor"/> + + <xsl:choose> + <xsl:when test="attribution"> + <table border="0" width="100%" + cellspacing="0" cellpadding="0" class="blockquote" + summary="Block quote"> + <tr> + <td width="10%" valign="top"> </td> + <td width="80%" valign="top"> + <xsl:apply-templates select="child::*[local-name(.)!='attribution']"/> + </td> + <td width="10%" valign="top"> </td> + </tr> + <tr> + <td colspan="2" align="right" valign="top"> + <xsl:text>--</xsl:text> + <xsl:apply-templates select="attribution"/> + </td> + <td width="10%" valign="top"> </td> + </tr> + </table> + </xsl:when> + <xsl:when test="@role = 'properties' or @role = 'prototypes'"> + <xsl:choose> + <xsl:when test="$shade.verbatim != 0"> + <table width="100%" xsl:use-attribute-sets="shade.verbatim.style"> + <tr> + <td valign="top"> + <xsl:apply-templates select="child::*[local-name(.)!='attribution']"/> + </td> + </tr> + </table> + </xsl:when> + <xsl:otherwise> + <table width="100%" border="0"> + <tr> + <td valign="top"> + <xsl:apply-templates select="child::*[local-name(.)!='attribution']"/> + </td> + </tr> + </table> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:otherwise> + <blockquote class="{local-name(.)}"> + <xsl:apply-templates/> + </blockquote> + </xsl:otherwise> + </xsl:choose> + </div> +</xsl:template> + + <!-- support for Python language for synopsises --> + <xsl:template match="classsynopsis + |fieldsynopsis + |methodsynopsis + |constructorsynopsis + |destructorsynopsis"> + <xsl:param name="language"> + <xsl:choose> + <xsl:when test="@language"> + <xsl:value-of select="@language"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$default-classsynopsis-language"/> + </xsl:otherwise> + </xsl:choose> + </xsl:param> + <xsl:choose> + <xsl:when test="$language='python'"> + <xsl:apply-templates select="." mode="python"/> + </xsl:when> + <xsl:otherwise> + <xsl:apply-imports/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template match="classsynopsis" mode="python"> + <table bgcolor="#D0E0F0" width="100%"> + <tr><td> + <pre class="{name(.)}"> + <xsl:text>class </xsl:text> + <xsl:apply-templates select="ooclass[1]" mode="python"/> + <xsl:if test="ooclass[position() > 1]"> + <xsl:text>(</xsl:text> + <xsl:apply-templates select="ooclass[position() > 1]" mode="python"/> <xsl:text>)</xsl:text> + </xsl:if> + <xsl:text>:&RE;</xsl:text> + + <xsl:apply-templates select="constructorsynopsis + |destructorsynopsis + |fieldsynopsis + |methodsynopsis + |classsynopsisinfo" mode="python"/> + </pre></td></tr></table> + </xsl:template> + + <xsl:template match="classsynopsisinfo" mode="python"> + <xsl:apply-templates mode="python"/> + </xsl:template> + + <xsl:template match="ooclass|oointerface|ooexception" mode="python"> + <xsl:if test="position() > 1"> + <xsl:text>, </xsl:text> + </xsl:if> + <span class="{name(.)}"> + <xsl:apply-templates mode="python"/> + </span> + </xsl:template> + + <xsl:template match="modifier" mode="python"> + <span class="{name(.)}"> + <xsl:apply-templates mode="python"/> + <xsl:text> </xsl:text> + </span> + </xsl:template> + + <xsl:template match="classname" mode="python"> + <xsl:if test="name(preceding-sibling::*[1]) = 'classname'"> + <xsl:text>, </xsl:text> + </xsl:if> + <span class="{name(.)}"> + <xsl:apply-templates mode="python"/> + </span> + </xsl:template> + + <xsl:template match="interfacename" mode="python"> + <xsl:if test="name(preceding-sibling::*[1]) = 'interfacename'"> + <xsl:text>, </xsl:text> + </xsl:if> + <span class="{name(.)}"> + <xsl:apply-templates mode="python"/> + </span> + </xsl:template> + + <xsl:template match="exceptionname" mode="python"> + <xsl:if test="name(preceding-sibling::*[1]) = 'exceptionname'"> + <xsl:text>, </xsl:text> + </xsl:if> + <span class="{name(.)}"> + <xsl:apply-templates mode="python"/> + </span> + </xsl:template> + + <xsl:template match="fieldsynopsis" mode="python"> + <code class="{name(.)}"> + <xsl:text> </xsl:text> + <xsl:apply-templates mode="python"/> + </code> + <xsl:call-template name="synop-break"/> + </xsl:template> + + <xsl:template match="type" mode="python"> + <span class="{name(.)}"> + <xsl:apply-templates mode="python"/> + <xsl:text> </xsl:text> + </span> + </xsl:template> + + <xsl:template match="varname" mode="python"> + <span class="{name(.)}"> + <xsl:apply-templates mode="python"/> + <xsl:text> </xsl:text> + </span> + </xsl:template> + + <xsl:template match="initializer" mode="python"> + <span class="{name(.)}"> + <xsl:text>=</xsl:text> + <xsl:apply-templates mode="python"/> + </span> + </xsl:template> + + <xsl:template match="void" mode="python"> + <span class="{name(.)}"> + <xsl:text>void </xsl:text> + </span> + </xsl:template> + + <xsl:template match="methodname" mode="python"> + <span class="{name(.)}"> + <xsl:apply-templates mode="python"/> + </span> + </xsl:template> + + <xsl:template match="methodparam" mode="python"> + <xsl:if test="position() > 1"> + <xsl:text>, </xsl:text> + </xsl:if> + <span class="{name(.)}"> + <xsl:apply-templates mode="python"/> + </span> + </xsl:template> + + <xsl:template mode="python" + match="destructorsynopsis|methodsynopsis"> + + <code class="{name(.)}"> + <xsl:text> def </xsl:text> + <xsl:apply-templates select="methodname" mode="python"/> + <xsl:text>(</xsl:text> + <xsl:apply-templates select="methodparam" mode="python"/> + <xsl:text>)</xsl:text> + </code> + <xsl:call-template name="synop-break"/> + </xsl:template> + + <xsl:template mode="python" + match="constructorsynopsis"> + + <code class="{name(.)}"> + <xsl:text> </xsl:text> + <xsl:apply-templates select="methodname" mode="python"/> + <xsl:text>(</xsl:text> + <xsl:apply-templates select="methodparam" mode="python"/> + <xsl:text>)</xsl:text> + </code> + <xsl:call-template name="synop-break"/> + </xsl:template> + +<!-- this was the original parameter python mode styling + <xsl:template match="parameter" mode="python"> + <span class="{name(.)}"> + <xsl:apply-templates mode="python"/> + </span> + </xsl:template> +--> + + <!-- hack --> + <xsl:template match="link" mode="python"> + <xsl:apply-templates select="."/> + </xsl:template> + + <xsl:template match="parameter" mode="python"> + <span class="{name(.)}"> + <xsl:choose> + <xsl:when test="@role = 'keyword'"> + <xsl:call-template name="inline.boldmonoseq"/> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="inline.italicmonoseq"/> + </xsl:otherwise> + </xsl:choose> + </span> +</xsl:template> + +<xsl:template match="variablelist"> + <table border="0" width="100%" bgcolor="#FFECCE"> + <col align="left" valign="top" width="0*"> + </col> + <tbody> + <xsl:apply-templates select="varlistentry" mode="varlist-table"/> + </tbody> + </table> +</xsl:template> + +</xsl:stylesheet> diff --git a/docs/pdf-style.xsl b/docs/pdf-style.xsl new file mode 100644 index 0000000..d4a8e02 --- /dev/null +++ b/docs/pdf-style.xsl @@ -0,0 +1,11 @@ +<?xml version='1.0'?> <!--*- mode: xml -*--> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0'> +<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/> +<xsl:include href="common.xsl"/> +<xsl:include href="pdf.xsl"/> + +<xsl:param name="section.autolabel" select="1"/> +<xsl:param name="section.label.includes.component.label" select="1"/> + +</xsl:stylesheet> diff --git a/docs/pdf.xsl b/docs/pdf.xsl new file mode 100644 index 0000000..013bfd0 --- /dev/null +++ b/docs/pdf.xsl @@ -0,0 +1,259 @@ +<?xml version='1.0'?> +<!DOCTYPE xsl:stylesheet [ +<!ENTITY RE " "> +<!ENTITY nbsp " "> +]> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:fo="http://www.w3.org/1999/XSL/Format" + version='1.0'> + +<xsl:param name="body.margin.top">0.5in</xsl:param> + +<xsl:template name="is.graphic.extension"> + <xsl:param name="ext"></xsl:param> + <xsl:if test="$ext = 'png' + or $ext = 'pdf' + or $ext = 'jpeg' + or $ext = 'gif' + or $ext = 'tif' + or $ext = 'tiff' + or $ext = 'bmp'">1</xsl:if> +</xsl:template> + + <!-- support for Python language for synopsises --> + <xsl:template match="classsynopsis + |fieldsynopsis + |methodsynopsis + |constructorsynopsis + |destructorsynopsis"> + <xsl:param name="language"> + <xsl:choose> + <xsl:when test="@language"> + <xsl:value-of select="@language"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$default-classsynopsis-language"/> + </xsl:otherwise> + </xsl:choose> + </xsl:param> + <xsl:choose> + <xsl:when test="$language='python'"> + <xsl:apply-templates select="." mode="python"/> + </xsl:when> + <xsl:otherwise> + <xsl:apply-imports/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template match="classsynopsis" mode="python"> + <fo:block wrap-option='no-wrap' + white-space-collapse='false' + linefeed-treatment="preserve" + xsl:use-attribute-sets="monospace.verbatim.properties" + background-color="#E0E0E0"> + <xsl:text>class </xsl:text> + <xsl:apply-templates select="ooclass[1]" mode="python"/> + <xsl:if test="ooclass[position() > 1]"> + <xsl:text>(</xsl:text> + <xsl:apply-templates select="ooclass[position() > 1]" mode="python"/> + <xsl:text>)</xsl:text> + </xsl:if> + <xsl:text> :</xsl:text> + + <xsl:apply-templates select="constructorsynopsis + |destructorsynopsis + |fieldsynopsis + |methodsynopsis + |classsynopsisinfo" mode="python"/> + + </fo:block> + <xsl:text>&RE;</xsl:text> + </xsl:template> + + <xsl:template match="classsynopsisinfo" mode="python"> + <xsl:apply-templates mode="python"/> + </xsl:template> + + <xsl:template match="ooclass|oointerface|ooexception" mode="python"> + <xsl:if test="position() > 1"> + <xsl:text>, </xsl:text> + </xsl:if> + <xsl:apply-templates mode="python"/> + </xsl:template> + + <xsl:template match="modifier" mode="python"> + <xsl:apply-templates mode="python"/> + <xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="classname" mode="python"> + <xsl:if test="name(preceding-sibling::*[1]) = 'classname'"> + <xsl:text>, </xsl:text> + </xsl:if> + <xsl:apply-templates mode="python"/> + </xsl:template> + + <xsl:template match="interfacename" mode="python"> + <xsl:if test="name(preceding-sibling::*[1]) = 'interfacename'"> + <xsl:text>, </xsl:text> + </xsl:if> + <xsl:apply-templates mode="python"/> + </xsl:template> + + <xsl:template match="exceptionname" mode="python"> + <xsl:if test="name(preceding-sibling::*[1]) = 'exceptionname'"> + <xsl:text>, </xsl:text> + </xsl:if> + <xsl:apply-templates mode="python"/> + </xsl:template> + + <xsl:template match="fieldsynopsis" mode="python"> + <fo:block wrap-option='no-wrap' + white-space-collapse='false' + linefeed-treatment="preserve" + xsl:use-attribute-sets="monospace.verbatim.properties"> + <xsl:text> </xsl:text> + <xsl:apply-templates mode="python"/> + <xsl:call-template name="synop-break"/> + </fo:block> + </xsl:template> + + <xsl:template match="type" mode="python"> + <xsl:apply-templates mode="python"/> + <xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="varname" mode="python"> + <xsl:apply-templates mode="python"/> + <xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="initializer" mode="python"> + <xsl:text>=</xsl:text> + <xsl:apply-templates mode="python"/> + </xsl:template> + + <xsl:template match="void" mode="python"> + <xsl:text>void </xsl:text> + </xsl:template> + + <xsl:template match="methodname" mode="python"> + <xsl:apply-templates mode="python"/> + </xsl:template> + + <xsl:template match="methodparam" mode="python"> + <xsl:if test="position() > 1"> + <xsl:text>, </xsl:text> + </xsl:if> + <xsl:apply-templates mode="python"/> + </xsl:template> + + <xsl:template mode="python" + match="destructorsynopsis|methodsynopsis"> + + <fo:block wrap-option='no-wrap' + white-space-collapse='false' + linefeed-treatment="preserve" + xsl:use-attribute-sets="monospace.verbatim.properties"> + <xsl:text> def </xsl:text> + <xsl:apply-templates select="methodname" mode="python"/> + <xsl:text>(</xsl:text> + <xsl:apply-templates select="methodparam" mode="python"/> + <xsl:text>)</xsl:text> +<!-- <xsl:call-template name="synop-break"/> --> + </fo:block> + </xsl:template> + + <xsl:template mode="python" + match="constructorsynopsis"> + <fo:block wrap-option='no-wrap' + white-space-collapse='false' + linefeed-treatment="preserve" + xsl:use-attribute-sets="monospace.verbatim.properties"> + <xsl:text> </xsl:text> + <xsl:apply-templates select="methodname" mode="python"/> + <xsl:text>(</xsl:text> + <xsl:apply-templates select="methodparam" mode="python"/> + <xsl:text>)</xsl:text> + </fo:block> + </xsl:template> + + <!-- hack --> + <xsl:template match="link" mode="python"> + <xsl:apply-templates select="."/> + </xsl:template> + +<!-- +<xsl:template match="variablelist" mode="vl.as.blocks"> + <xsl:variable name="id"> + <xsl:call-template name="object.id"/> + </xsl:variable> + + <xsl:if test="title"> + <xsl:apply-templates select="title" mode="list.title.mode"/> + </xsl:if> + + <fo:block id="{$id}" + xsl:use-attribute-sets="list.block.spacing" + background-color="#FFECCE"> + <xsl:apply-templates mode="vl.as.blocks"/> + </fo:block> +</xsl:template> +--> + +<!-- +<xsl:template match="variablelist"> + <fo:table border="0" + width="100%" + background-color="#FFECCE" + table-layout="fixed"> + <fo:table-column + align="left" + column-width="20%" + column-number="1"> + </fo:table-column> + <fo:table-column + align="left" + column-width="80%" + column-number="2"> + </fo:table-column> + <fo:table-body> + <xsl:apply-templates select="varlistentry"/> + </fo:table-body> + </fo:table> +</xsl:template> + +<xsl:template match="varlistentry"> + <fo:table-row> + <fo:table-cell> + <fo:block + background-color="#FFECCE"> + <xsl:apply-templates select="term"/> + </fo:block> + </fo:table-cell> + <fo:table-cell> + <fo:block + background-color="#FFECCE"> + <xsl:apply-templates select="listitem"/> + </fo:block> + </fo:table-cell> + </fo:table-row> +</xsl:template> + +<xsl:template match="varlistentry/term"> + <xsl:apply-templates/> + <xsl:text>, </xsl:text> +</xsl:template> + +<xsl:template match="varlistentry/term[position()=last()]" priority="2"> + <xsl:apply-templates/> +</xsl:template> + +<xsl:template match="varlistentry/listitem"> + <xsl:apply-templates/> +</xsl:template> +--> + +</xsl:stylesheet> diff --git a/docs/ref-html-style.xsl b/docs/ref-html-style.xsl new file mode 100644 index 0000000..124a117 --- /dev/null +++ b/docs/ref-html-style.xsl @@ -0,0 +1,52 @@ +<?xml version='1.0'?> <!--*- mode: xml -*--> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0'> +<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/> +<xsl:include href="common.xsl"/> +<xsl:include href="html.xsl"/> +<xsl:include href="devhelp.xsl"/> + + <!-- ========================================================= --> + <!-- template to create the index.sgml anchor index --> + + <xsl:template name="generate.index"> + <xsl:call-template name="write.text.chunk"> + <xsl:with-param name="filename" select="'index.sgml'"/> + <xsl:with-param name="content"> + <!-- check all anchor and refentry elements --> + <xsl:apply-templates select="//anchor|//refentry" + mode="generate.index.mode"/> + </xsl:with-param> + <xsl:with-param name="encoding" select="'utf-8'"/> + </xsl:call-template> + </xsl:template> + + <xsl:template match="*" mode="generate.index.mode"> + <xsl:if test="not(@href)"> + <xsl:text><ANCHOR id="</xsl:text> + <xsl:value-of select="@id"/> + <xsl:text>" href="</xsl:text> + <xsl:if test="$gtkdoc.bookname"> + <xsl:value-of select="$gtkdoc.bookname"/> + <xsl:text>/</xsl:text> + </xsl:if> + <xsl:call-template name="href.target"/> + <xsl:text>"> + </xsl:text> + </xsl:if> + </xsl:template> + + <xsl:param name="gtkdoc.version" select="''"/> + <xsl:param name="gtkdoc.bookname" select="''"/> + + <xsl:param name="refentry.generate.name" select="0"/> + <xsl:param name="refentry.generate.title" select="1"/> + <xsl:param name="chapter.autolabel" select="0"/> + + <xsl:template match="book|article"> + <xsl:apply-imports/> + <xsl:call-template name="generate.devhelp"/> + <xsl:call-template name="generate.index"/> + </xsl:template> + +</xsl:stylesheet> diff --git a/docs/reference/.cvsignore b/docs/reference/.cvsignore new file mode 100644 index 0000000..a7ec807 --- /dev/null +++ b/docs/reference/.cvsignore @@ -0,0 +1,2 @@ +*.html +pygobject.devhelp diff --git a/docs/reference/pygobject-classes.xml b/docs/reference/pygobject-classes.xml new file mode 100644 index 0000000..e4b488f --- /dev/null +++ b/docs/reference/pygobject-classes.xml @@ -0,0 +1,20 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<chapter id="gobject-class-reference" + xmlns:xi="http://www.w3.org/2001/XInclude"> + +<title>The gobject Class Reference</title> + +<!-- GOBJECT CLASSES --> + +<xi:include href="pygobject.xml"/> +<xi:include href="pygobject-gboxed.xml"/> +<xi:include href="pygobject-gpointer.xml"/> +<xi:include href="pygobject-ginterface.xml"/> +<xi:include href="pygobject-maincontext.xml"/> +<xi:include href="pygobject-mainloop.xml"/> +<xi:include href="pygobject-functions.xml"/> +<xi:include href="pygobject-constants.xml"/> + +</chapter> diff --git a/docs/reference/pygobject-constants.xml b/docs/reference/pygobject-constants.xml new file mode 100644 index 0000000..894c8ae --- /dev/null +++ b/docs/reference/pygobject-constants.xml @@ -0,0 +1,495 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="gobject-constants"> + <refnamediv> + <refname>gobject Constants</refname> + <refpurpose>the built-in constants of the gobject module</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <programlisting> +<xref linkend="gobject-io-condition-constants" endterm="gobject-io-condition-constants-title"></xref> +<xref linkend="gobject-param-constants" endterm="gobject-param-constants-title"></xref> +<xref linkend="gobject-priority-constants" endterm="gobject-priority-constants-title"></xref> +<xref linkend="gobject-signal-constants" endterm="gobject-signal-constants-title"></xref> +<xref linkend="gobject-spawn-flag-constants" endterm="gobject-spawn-flag-constants-title"></xref> +<xref linkend="gobject-type-constants" endterm="gobject-type-constants-title"></xref> +<xref linkend="gobject-version-constants" endterm="gobject-version-constants-title"></xref> +</programlisting> + + </refsect1> + + <refsect1 id="gobject-constants-description"> + <title>Description</title> + + <refsect2 id="gobject-io-condition-constants"> + <title id="gobject-io-condition-constants-title">GObject IO Condition Constants</title> + + <para>The IO Condition constants are a set of bit-flags that specify a +condition to watch for on an event source.</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.IO_IN</literal></term> + <listitem> + <simpara>There is data to read</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_OUT</literal></term> + <listitem> + <simpara>Data can be written (without blocking).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_PRI</literal></term> + <listitem> + <simpara>There is urgent data to read.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_ERR</literal></term> + <listitem> + <simpara>Error condition.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_HUP</literal></term> + <listitem> + <simpara>Hung up (the connection has been broken, usually for + pipes and sockets).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_NVAL</literal></term> + <listitem> + <simpara>Invalid request. The file descriptor is not + open.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="gobject-param-constants"> + <title id="gobject-param-constants-title">GObject Param Flag Constants</title> + + <para>The Param Flag constants are a set of bit-flags that specify +certain aspects of parameters that can be configured.</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.PARAM_READABLE</literal></term> + <listitem> + <simpara>The parameter is readable</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PARAM_WRITABLE</literal></term> + <listitem> + <simpara>The parameter is writable</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PARAM_CONSTRUCT</literal></term> + <listitem> + <simpara>The parameter will be set upon object + construction</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PARAM_CONSTRUCT_ONLY</literal></term> + <listitem> + <simpara>The parameter will only be set upon object + construction</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PARAM_LAX_VALIDATION</literal></term> + <listitem> + <simpara>Upon parameter conversion strict validation is not + required</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="gobject-priority-constants"> + <title id="gobject-priority-constants-title">GObject Priority Constants</title> + + <para>The Priority constants specify </para> + + <variablelist> + <varlistentry> + <term><literal>gobject.PRIORITY_HIGH</literal></term> + <listitem> + <simpara>Use this for high priority event sources.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PRIORITY_DEFAULT</literal></term> + <listitem> + <simpara>Use this for default priority event sources. This + priority is used when adding timeout functions with the <link + linkend="function-gobject--timeout-add"><function>gobject.timeout_add</function>()</link> + function. This priority is also used for events from the X + server.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PRIORITY_HIGH_IDLE</literal></term> + <listitem> + <simpara>Use this for high priority idle functions. For example, + gobject.PRIORITY_HIGH_IDLE + 10 is used for resizing operations; + and, gobject.PRIORITY_HIGH_IDLE + 20, for redrawing + operations. (This is done to ensure that any pending resizes are + processed before any pending redraws, so that widgets are not + redrawn twice unnecessarily.)</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PRIORITY_DEFAULT_IDLE</literal></term> + <listitem> + <simpara>Use this for default priority idle functions. This + priority is used when adding idle functions with the <link + linkend="function-gobject--idle-add"><function>gobject.idle_add</function>()</link> + function.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PRIORITY_LOW</literal></term> + <listitem> + <simpara>Use this for very low priority background + tasks.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="gobject-signal-constants"> + <title id="gobject-signal-constants-title">GObject Signal Flag Constants</title> + + <para>The Signal Flag constants are a set of bit-flags that specify a +signal's behavior. The overall signal description outlines how especially +the <literal>RUN</literal> flags control the stages of a signal +emission.</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_FIRST</literal></term> + <listitem> + <simpara>Invoke the object method handler in the first emission + stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_LAST</literal></term> + <listitem> + <simpara>Invoke the object method handler in the third emission + stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_CLEANUP</literal></term> + <listitem> + <simpara>Invoke the object method handler in the last emission + stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_NO_RECURSE</literal></term> + <listitem> + <simpara>Signals being emitted for an object while currently + being in emission for this very object will not be emitted + recursively, but instead cause the first emission to be + restarted.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_DETAILED</literal></term> + <listitem> + <simpara>This signal supports "::detail" appendices to the + signal name upon handler connections and emissions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_ACTION</literal></term> + <listitem> + <simpara>Action signals are signals that may freely be emitted + on alive objects from user code via the <link + linkend="method-gobject--emit"><methodname>gobject.emit</methodname>()</link> + method and friends, without the need of being embedded into + extra code that performs pre or post emission adjustments on the + object. They can also be thought of as object methods which can + be called generically by third-party code.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_NO_HOOKS</literal></term> + <listitem> + <simpara>No emissions hooks are supported for this + signal.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="gobject-spawn-flag-constants"> + <title id="gobject-spawn-flag-constants-title">GObject Spawn Flag Constants</title> + + <para>The Spawn Flag constants are a set of bit-flags that can be +passed to the <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +function.</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.SPAWN_LEAVE_DESCRIPTORS_OPEN</literal></term> + <listitem> + <simpara>the parent's open file descriptors will be inherited by +the child; otherwise all descriptors except stdin/stdout/stderr will be +closed before calling <function>exec</function>() in the child.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal></term> + <listitem> + <simpara>the child will not be automatically reaped; you must +call <function>waitpid</function>() or handle <literal>SIGCHLD</literal> +yourself, or the child will become a zombie.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_SEARCH_PATH</literal></term> + <listitem> + <simpara><parameter>argv</parameter>[0] need not be an absolute +path, it will be looked for in the user's <envar>PATH</envar>.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_STDOUT_TO_DEV_NULL</literal></term> + <listitem> + <simpara>the child's standard output will be discarded, instead +of going to the same location as the parent's standard output.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_STDERR_TO_DEV_NULL</literal></term> + <listitem> + <simpara>the child's standard error will be discarded.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_CHILD_INHERITS_STDIN</literal></term> + <listitem> + <simpara>the child will inherit the parent's standard input (by +default, the child's standard input is attached to /dev/null).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_FILE_AND_ARGV_ZERO</literal></term> + <listitem> + <simpara>the first element of <parameter>argv</parameter> is the +file to execute, while the remaining elements are the actual argument vector +to pass to the file. Normally <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +uses <parameter>argv</parameter>[0] as the file to execute, and passes all +of <parameter>argv</parameter> to the child.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="gobject-type-constants"> + <title id="gobject-type-constants-title">GObject Built-in Type Constants</title> + + <para>The Built-in Type constants specify the pre-defined types used +by gobject.</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.TYPE_INVALID</literal></term> + <listitem> + <simpara>An invalid type, used as error return value in some + functions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_NONE</literal></term> + <listitem> + <simpara>A fundamental type indicating no type.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_INTERFACE</literal></term> + <listitem> + <simpara>The fundamental type from which all interfaces are + derived.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_CHAR</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a + character. This maps to a string in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_UCHAR</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an unsigned + character. This maps to a string in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_BOOLEAN</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a True or False + value. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_INT</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an + integer. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_UINT</literal></term> + <listitem> + <simpara>he fundamental type corresponding to an unsigned + integer. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_LONG</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a long + integer. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_ULONG</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an unsigned + integer. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_INT64</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an long long + integer. This maps to a long integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_UINT64</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an unsigned long + long integer. This maps to a long integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_ENUM</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an enumeration + type. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_FLAGS</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a flag + type. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_FLOAT</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a floating point + number. This maps to a float in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_DOUBLE</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a double + floating point number. This maps to a float in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_STRING</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a string.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_POINTER</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a pointer to an + anonymous type. This has no corresponding Python type.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_BOXED</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a boxed object + type.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_PARAM</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a GParamSpec + type.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_OBJECT</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a GObject + type.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_PYOBJECT</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a Python Object + type.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="gobject-version-constants"> + <title id="gobject-version-constants-title">GObject Version Constants</title> + + <para>The Version constants specify the version of +<literal>GLIB</literal> used by PyGTK as a 3-tuple containing the major, +minor and patch release numbers.</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.glib_version</literal></term> + <listitem> + <simpara>A 3-tuple containing (major, minor, patch) release + numbers.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-functions.xml b/docs/reference/pygobject-functions.xml new file mode 100644 index 0000000..6a18676 --- /dev/null +++ b/docs/reference/pygobject-functions.xml @@ -0,0 +1,1373 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="gobject-functions"> + <refnamediv> + <refname>gobject Functions</refname> + <refpurpose>miscellaneous functions</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <programlisting> +<methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-name">gobject.type_name</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-from-name">gobject.type_from_name</link></methodname> + <methodparam><parameter>type_name</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-parent">gobject.type_parent</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-is-a">gobject.type_is_a</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>parent_type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-children">gobject.type_children</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-interfaces">gobject.type_interfaces</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-register">gobject.type_register</link></methodname> + <methodparam><parameter>class</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-new">gobject.signal_new</link></methodname> + <methodparam><parameter>signal_name</parameter></methodparam> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>flags</parameter></methodparam> + <methodparam><parameter>return_type</parameter></methodparam> + <methodparam><parameter>param_types</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-list-names">gobject.signal_list_names</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-list-ids">gobject.signal_list_ids</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-lookup">gobject.signal_lookup</link></methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-name">gobject.signal_name</link></methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-query1">gobject.signal_query</link></methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-query2">gobject.signal_query</link></methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--list-properties">gobject.list_properties</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--new">gobject.new</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--idle-add">gobject.idle_add</link></methodname> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--timeout-add">gobject.timeout_add</link></methodname> + <methodparam><parameter>interval</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--io-add-watch">gobject.io_add_watch</link></methodname> + <methodparam><parameter>fd</parameter></methodparam> + <methodparam><parameter>condition</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--source-remove">gobject.source_remove</link></methodname> + <methodparam><parameter>tag</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--main-context-default">gobject.main_context_default</link></methodname> + <methodparam></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--markup-escape-text">gobject.markup_escape_text</link></methodname> + <methodparam><parameter role="keyword">text</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gobject--child-watch-add">gobject.child_watch_add</link></methodname> + <methodparam><parameter role="keyword">pid</parameter></methodparam> + <methodparam><parameter role="keyword">function</parameter></methodparam> + <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">priority</parameter><initializer>gobject.PRIORITY_DEFAULT</initializer></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--spawn-async">gobject.spawn_async</link></methodname> + <methodparam><parameter role="keyword">argv</parameter></methodparam> + <methodparam><parameter role="keyword">envp</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">working_directory</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">child_setup</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_input</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_output</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_error</parameter><initializer>None</initializer></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--get-current-time">gobject.get_current_time</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--main-depth">gobject.main_depth</link></methodname> + </methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para>These functions are part of the <literal>PyGTK</literal> gobject +module but are not directly associated with a specific class.</para> + + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gobject--type-name"> + <title>gobject.type_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_name</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_name</function>() function returns +the unique name that is assigned to the specified +<parameter>type</parameter>. <parameter>type</parameter> can be a GObject +type, type ID or instance. This function raises a TypeError exception +if <parameter>type</parameter> isn't a <literal>PyGTK</literal> type.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-from-name"> + <title>gobject.type_from_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_from_name</methodname> + <methodparam><parameter>type_name</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type_name</parameter> :</term> + <listitem><simpara>a string containing the name of a +type</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the type ID named +<parameter>type_name</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_from_name</function>() function +returns the type ID of the <literal>PyGTK</literal> type with the name +specified by <parameter>type_name</parameter>. This function raises a +RuntimeError exception if no type matches +<parameter>type_name</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-parent"> + <title>gobject.type_parent</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_parent</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the parent type ID</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_parent</function>() function returns +the direct parent type ID of the specified <parameter>type</parameter>. +<parameter>type</parameter> can be a GObject type, type ID or instance. If +<parameter>type</parameter> has no parent, i.e. is a fundamental type, the +RuntimeError exception is raised. </para> + + </refsect2> + + <refsect2 id="function-gobject--type-is-a"> + <title>gobject.type_is_a</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_is_a</methodname> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>parent_type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>parent_type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if +<parameter>parent_type</parameter> is an ancestor of +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_is_a</function>() function returns +<literal>TRUE</literal> if the specified <parameter>type</parameter> is a +descendant of the type specified by <parameter>parent_type</parameter>. This +function also returns <literal>TRUE</literal> if +<parameter>parent_type</parameter> is an interface and +<parameter>type</parameter> conforms to it.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-children"> + <title>gobject.type_children</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_children</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the child types of +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_children</function>() function +returns a list containing the child types of the specified +<parameter>type</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-interfaces"> + <title>gobject.type_interfaces</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_interfaces</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the interface types supported by +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_interfaces</function>() function +returns a list of the interface types supported by +<parameter>type</parameter>. <parameter>type</parameter> can be a GObject +type, type ID or instance. This function returns a RuntimeError exception if +type is not a valid type or has no interfaces.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-register"> + <title>gobject.type_register</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_register</methodname> + <methodparam><parameter>class</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>class</parameter> :</term> + <listitem><simpara>a Python class that is a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_register</function>() function +registers the specified Python <parameter>class</parameter> as a PyGTK type. +class must be a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link>. The function generates a name for the new type.</para> + + </refsect2> + + <refsect2 id="function-gobject--signal-new"> + <title>gobject.signal_new</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_new</methodname> + <methodparam><parameter>signal_name</parameter></methodparam> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>flags</parameter></methodparam> + <methodparam><parameter>return_type</parameter></methodparam> + <methodparam><parameter>param_types</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>signal_name</parameter> :</term> + <listitem><simpara>a string containing the name of the +signal</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>the object type that the signal is associated +with</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>the signal flags</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>return_type</parameter> :</term> + <listitem><simpara>the return type of the signal +handler</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>param_types</parameter> :</term> + <listitem><simpara>the parameter types passed to the signal +handler</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a unique integer signal ID</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.signal_new</function>() function registers +a signal with the specified <parameter>signal_name</parameter> for the +specified object <parameter>type</parameter>. The value of +<parameter>flags</parameter> is a combination of:</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_FIRST</literal></term> + <listitem> + <simpara>Invoke the object method handler in the first emission +stage. </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_LAST</literal></term> + <listitem> + <simpara>Invoke the object method handler in the third emission +stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_CLEANUP</literal></term> + <listitem> + <simpara>Invoke the object method handler in the last emission +stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_NO_RECURSE</literal></term> + <listitem> + <simpara>Signals being emitted for an object while currently +being in emission for this very object will not be emitted recursively, but +instead cause the first emission to be restarted.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_DETAILED</literal></term> + <listitem> + <simpara>This signal supports "::detail" appendixes to the +signal name upon handler connections and emissions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_ACTION</literal></term> + <listitem> + <simpara>Action signals are signals that may freely be emitted +on alive objects from user code via <link +linkend="method-gobject--emit"><methodname>gobject.emit()</methodname>()</link> +and friends, without the need of being embedded into extra code that +performs pre or post emission adjustments on the object. They can also be +thought of as generically callable object methods.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_NO_HOOKS</literal></term> + <listitem> + <simpara> No emissions hooks are supported for this +signal.</simpara> + </listitem> + </varlistentry> + </variablelist> + + <para><parameter>return_type</parameter> is the type of the return +value from a signal handler and may be a gobject type, type ID or instance. +The <parameter>param_types</parameter> parameter is a list of additional +types that are passed to the signal handler. Each parameter type may be +specified as a gobject type, type ID or instance. For example, to add a +signal to the gtk.Window type called "my-signal" that calls a handler with a +gtk.Button widget and an integer value and a return value that is a +boolean, use:</para> + + <programlisting> + gobject.signal_new("my_signal", gtk.Window, gobject.SIGNAL_RUN_LAST, gobject.TYPE_BOOLEAN, (gtk.Button, gobject.TYPE_INT)) +</programlisting> + + </refsect2> + + <refsect2 id="function-gobject--signal-list-names"> + <title>gobject.signal_list_names</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_list_names</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the signal names supported by +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.signal_list_names</function>() function +returns a list of the names of the signals that are supported by the +specified GObject <parameter>type</parameter></para> + + <note> + <para>The type keyword is available in PyGTK 2.6 and above.</para> + </note> + + </refsect2> + + <refsect2 id="function-gobject--signal-list-ids"> + <title>gobject.signal_list_ids</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_list_ids</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the signal ids supported by +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_list_ids</function>() function +returns a list of the integer ids of the signals that are supported by the +GObject specified by <parameter>type</parameter></para> + + </refsect2> + + <refsect2 id="function-gobject--signal-lookup"> + <title>gobject.signal_lookup</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_lookup</methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">name</parameter> :</term> + <listitem><simpara>the name of a signal for +<parameter>type</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the integer id of a signal supported by +<parameter>type</parameter></simpara> or 0.</listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_lookup</function>() function +returns the id of the signal with the name specified by +<parameter>name</parameter> that is supported by the GObject specified +specified by<parameter>type</parameter>. 0 is returned if the signal is not +found.</para> + + </refsect2> + + <refsect2 id="function-gobject--signal-name"> + <title>gobject.signal_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_name</methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">signal_id</parameter> :</term> + <listitem><simpara>an integer signal id</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the name of the signal or +<literal>None</literal>.</simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_name</function>() function returns +the name of the signal that has the signal id specified by +<parameter>id</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--signal-query1"> + <title>gobject.signal_query</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_query</methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">name</parameter> :</term> + <listitem><simpara>the name of a signal for +<parameter>type</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 6-tuple containing signal information or +<literal>None</literal></simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_query</function>() function returns +a 6-tuple containing information about the signal with the name specified by +<parameter>name</parameter> that is supported by the GObject specified by +<parameter>type</parameter>. If the signal is not found +<literal>None</literal> is returned.</para> + + <para>The signal information 6-tuple contains:</para> + + <itemizedlist> + <listitem> + <simpara>the integer signal id</simpara> + </listitem> + <listitem> + <simpara>the signal name</simpara> + </listitem> + <listitem> + <simpara>the GType that the signal is registered for</simpara> + </listitem> + <listitem> + <simpara>the signal flags (see the <xref +linkend="gobject-signal-constants" +endterm="gobject-signal-constants-title"></xref>)</simpara> + </listitem> + <listitem> + <simpara>the GType of the return from the signal callback +function</simpara> + </listitem> + <listitem> + <simpara>a tuple containing the GTypes of the parameters that are +passed to the signal callback function. Note that these may not correspond +exactly to the <literal>PyGTK</literal> signal callback parameters.</simpara> + </listitem> + </itemizedlist> + + </refsect2> + + <refsect2 id="function-gobject--signal-query2"> + <title>gobject.signal_query</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_query</methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">signal_id</parameter> :</term> + <listitem><simpara>the integer id of a signal</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 6-tuple containing signal information or +<literal>None</literal></simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_query</function>() function returns +a 6-tuple containing information about the signal with the id specified by +<parameter>signal_id</parameter>. If the signal is not found +<literal>None</literal> is returned.</para> + + <para>The signal information 6-tuple contains:</para> + + <itemizedlist> + <listitem> + <simpara>the integer signal id</simpara> + </listitem> + <listitem> + <simpara>the signal name</simpara> + </listitem> + <listitem> + <simpara>the GType that the signal is registered for</simpara> + </listitem> + <listitem> + <simpara>the signal flags (see the <xref +linkend="gobject-signal-constants" +endterm="gobject-signal-constants-title"></xref>)</simpara> + </listitem> + <listitem> + <simpara>the GType of the return from the signal callback +function</simpara> + </listitem> + <listitem> + <simpara>a tuple containing the GTypes of the parameters that are +passed to the signal callback function. Note that these may not correspond +exactly to the <literal>PyGTK</literal> signal callback parameters.</simpara> + </listitem> + </itemizedlist> + + </refsect2> + + <refsect2 id="function-gobject--list-properties"> + <title>gobject.list_properties</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.list_properties</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the properties (as GParam objects) +supported by <parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.list_properties</function>() function +returns a list of the properties (as GParam objects) supported by +<parameter>type</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--new"> + <title>gobject.new</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.new</methodname> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>zero or more property-value +pairs</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new object if the specified +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.new</function>() function returns a new +object of the specified <parameter>type</parameter>. type must specify a +type that is a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link>. A +TypeError exception is raised if <parameter>type</parameter> specifies an +abstract class or a type that is not a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link>. A set +of property-value pairs may be specified to set the value of the object's +properties.</para> + + </refsect2> + + <refsect2 id="function-gobject--idle-add"> + <title>gobject.idle_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.idle_add</methodname> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a function to call when +<literal>PyGTK</literal> is idle</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>optionals arguments to be passed to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.idle_add</function>() function adds a +function (specified by <parameter>callback</parameter>) to be called +whenever there are no higher priority events pending to the default main +loop. The function is given the default idle priority, +<literal>gobject.PRIORITY_DEFAULT_IDLE</literal>. Additional arguments to +pass to <parameter>callback</parameter> can be specified after +<parameter>callback</parameter>. The idle priority can be specified as a +keyword-value pair with the keyword "priority". If +<parameter>callback</parameter> returns <literal>FALSE</literal> it is +automatically removed from the list of event sources and will not be called +again.</para> + + </refsect2> + + <refsect2 id="function-gobject--timeout-add"> + <title>gobject.timeout_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.timeout_add</methodname> + <methodparam><parameter>interval</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>interval</parameter> :</term> + <listitem><simpara>the time between calls to the function, in +milliseconds </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>the function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>zero or more arguments that will be passed to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID of the event +source</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.timeout_add</function>() function sets a +function (specified by <parameter>callback</parameter>) to be called at +regular intervals (specified by <parameter>interval</parameter>, with the +default priority, <literal>gobject.PRIORITY_DEFAULT</literal>. Additional +arguments to pass to <parameter>callback</parameter> can be specified after +<parameter>callback</parameter>. The idle priority may be specified as a +keyword-value pair with the keyword "priority".</para> + + <para>The function is called repeatedly until it returns +<literal>FALSE</literal>, at which point the timeout is automatically +destroyed and the function will not be called again. The first call to the +function will be at the end of the first interval. Note that timeout +functions may be delayed, due to the processing of other event sources. Thus +they should not be relied on for precise timing. After each call to the +timeout function, the time of the next timeout is recalculated based on the +current time and the given interval (it does not try to 'catch up' time lost +in delays).</para> + + </refsect2> + + <refsect2 id="function-gobject--io-add-watch"> + <title>gobject.io_add_watch</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.io_add_watch</methodname> + <methodparam><parameter>fd</parameter></methodparam> + <methodparam><parameter>condition</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter> :</term> + <listitem><simpara>a Python file object or an integer file +descriptor ID</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>condition</parameter> :</term> + <listitem><simpara>a condition mask</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional arguments to pass to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID of the event source</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.io_add_watch</function>() function +arranges for the file (specified by <parameter>fd</parameter>) to be +monitored by the main loop for the specified +<parameter>condition</parameter>. <parameter>fd</parameter> may be a Python +file object or an integer file descriptor. The value of condition is a +combination of:</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.IO_IN</literal></term> + <listitem> + <simpara>There is data to read.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_OUT</literal></term> + <listitem> + <simpara>Data can be written (without blocking). </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_PRI</literal></term> + <listitem> + <simpara>There is urgent data to read.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_ERR</literal></term> + <listitem> + <simpara>Error condition.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_HUP</literal></term> + <listitem> + <simpara>Hung up (the connection has been broken, usually for +pipes and sockets).</simpara> + </listitem> + </varlistentry> + </variablelist> + + <para>Additional arguments to pass to <parameter>callback</parameter> +can be specified after <parameter>callback</parameter>. The idle priority +may be specified as a keyword-value pair with the keyword "priority". The +signature of the callback function is:</para> + + <programlisting> + def callback(source, cb_condition, ...) +</programlisting> + + <para>where <parameter>source</parameter> is +<parameter>fd</parameter>, the file descriptor; +<parameter>cb_condition</parameter> is the condition that triggered the +signal; and, <parameter>...</parameter> are the zero or more arguments that +were passed to the <function>gobject.io_add_watch</function>() +function.</para> + + <para>If the callback function returns <literal>FALSE</literal> it +will be automatically removed from the list of event sources and will not be +called again. If it returns <literal>TRUE</literal> it will be called again +when the condition is matched.</para> + + </refsect2> + + <refsect2 id="function-gobject--source-remove"> + <title>gobject.source_remove</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.source_remove</methodname> + <methodparam><parameter>tag</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>tag</parameter> :</term> + <listitem><simpara>an integer ID</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if the event source was +removed</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.source_remove</function>() function +removes the event source specified by tag (as returned by the <link +linkend="function-gobject--idle-add"><function>gobject.idle_add</function>()</link>, +<link +linkend="function-gobject--timeout-add"><function>gobject.timeout_add</function></link>() +and <link +linkend="function-gobject--io-add-watch"><function>gobject.io_add_watch</function>()</link> +functions)</para> + + </refsect2> + + <refsect2 id="function-gobject--main-context-default"> + <title>gobject.main_context_default</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.main_context_default</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the default gobject.MainContext +object</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.main_context_default</function>() function +returns the default gobject.MainContext object.</para> + + </refsect2> + + <refsect2 id="function-gobject--markup-escape-text"> + <title>gobject.markup_escape_text</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.markup_escape_text</methodname> + <methodparam><parameter>text</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>text</parameter> :</term> + <listitem><simpara>the UTF-8 string to be +escaped</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the escaped text</simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>gobject.markup_escape_text</function>() function +escapes the string specified by <parameter>text</parameter> so that the +markup parser will parse it verbatim. Less than, greater than, ampersand, +etc. are replaced with the corresponding entities. This function would +typically be used when writing out a file to be parsed with the markup +parser.</para> + + <para>Note that this function doesn't protect whitespace and line +endings from being processed according to the XML rules for normalization of +line endings and attribute values.</para> + + </refsect2> + + <refsect2 id="function-gobject--child-watch-add"> + <title>gobject.child_watch_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.child_watch_add</methodname> + <methodparam><parameter role="keyword">pid</parameter></methodparam> + <methodparam><parameter role="keyword">function</parameter></methodparam> + <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">priority</parameter><initializer>gobject.PRIORITY_DEFAULT</initializer></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><parameter role="keyword">pid</parameter> :</term> + <listitem><simpara>process id of a child process to watch</simpara></listitem> + </varlistentry> + <varlistentry><term><parameter role="keyword">function</parameter> :</term> + <listitem><simpara>the function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>the optional data to pass to +<parameter>function</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">priority</parameter> :</term> + <listitem><simpara>the priority of the idle source - one of the +<xref linkend="gobject-priority-constants" +endterm="gobject-priority-constants-title"></xref></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the id of event source.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.child_watch_add</function>() function sets +the function specified by <parameter>function</parameter> to be called with +the user data specified by <parameter>data</parameter> when the child +indicated by <parameter>pid</parameter> exits. The signature for the +callback is:</para> + + <programlisting> +def callback(pid, condition, user_data) +</programlisting> + + <para>where <parameter>pid</parameter> is is the child process id, +<parameter>condition</parameter> is the status information about the child +process and <parameter>user_data</parameter> is <parameter>data</parameter> +PyGTK supports only a single callback per process id.</para> + + </refsect2> + + <refsect2 id="function-gobject--spawn-async"> + <title>gobject.spawn_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.spawn_async</methodname> + <methodparam><parameter role="keyword">argv</parameter></methodparam> + <methodparam><parameter role="keyword">envp</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">working_directory</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">child_setup</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_input</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_output</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_error</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><parameter role="keyword">argv</parameter> :</term> + <listitem><simpara>a sequence of strings containing the arguments +of the child process</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">envp</parameter> :</term> + <listitem><simpara>the child's environment or +<literal>None</literal> to inherit the parent's +environment.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">working_directory</parameter> :</term> + <listitem><simpara>the child's current working directory, or +<literal>None</literal> to inherit parent's</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">flags</parameter> :</term> + <listitem><simpara>flags from the <xref +linkend="gobject-spawn-flag-constants" +endterm="gobject-spawn-flag-constants-title"></xref>.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">child_setup</parameter> :</term> + <listitem><simpara>a function to run in the child just before +calling <function>exec</function>()</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>the user data for the +<parameter>child_setup</parameter> function</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_input</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stdin</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_output</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stdout</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_error</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stderr</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 4-tuple containing the child's process id and +the stdin, stdout and stderr file descriptor integers.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.spawn_async</function>() function executes +a child program asynchronously (your program will not block waiting for the +child to exit). The child program is specified by the only argument that +must be provided, <parameter>argv</parameter>. <parameter>argv</parameter> +should be a sequence of strings, to be passed as the argument vector for the +child. The first string in <parameter>argv</parameter> is of course the name +of the program to execute. By default, the name of the program must be a +full path; the <envar>PATH</envar> shell variable will only be searched if +you pass the <literal>gobject.SPAWN_SEARCH_PATH</literal> flag in +<parameter>flags</parameter>. The function returns a 4-tuple containing the +child's process id and the file descriptors for the child's stdin, stdout +and stderr. The stdin, stdout and stderr file descriptors are returned only +ofthe corresponding <parameter>standard_input</parameter>, +<parameter>standard_output</parameter> or +<parameter>standard_error</parameter> params are +<literal>TRUE</literal>.</para> + + <para>On Windows, the low-level child process creation API +(<function>CreateProcess</function>()) doesn't use argument vectors, but a +command line. The C runtime library's <function>spawn*</function>() family +of functions (which <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +eventually calls) paste the argument vector elements into a command line, +and the C runtime startup code does a corresponding reconstruction of an +argument vector from the command line, to be passed to +<function>main</function>(). Complications arise when you have argument +vector elements that contain spaces of double quotes. The +<function>spawn*</function>() functions don't do any quoting or escaping, +but on the other hand the startup code does do unquoting and unescaping in +order to enable receiving arguments with embedded spaces or double +quotes. To work around this asymmetry, the <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +function will do quoting and escaping on argument vector elements that need +it before calling the C runtime <function>spawn</function>() +function.</para> + + <para><parameter>envp</parameter> is a sequence of strings, where each + string has the form <literal>KEY=VALUE</literal>. This will become the + child's environment. If <parameter>envp</parameter> is + <parameter>None</parameter> or not specified, the child inherits its + parent's environment.</para> + + <para><parameter>flags</parameter> should be the bitwise +<literal>OR</literal> of the <xref linkend="gobject-spawn-flag-constants" +endterm="gobject-spawn-flag-constants-title"></xref> you want to affect the +function's behaviour. The <literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal> +flag means that the child will not automatically be reaped; you must use a +GChildWatch source to be notified about the death of the child +process. Eventually you must call g_spawn_close_pid() on the child_pid, in +order to free resources which may be associated with the child process. (On +Unix, using a GChildWatch source is equivalent to calling +<function>waitpid</function>() or handling the <literal>SIGCHLD</literal> +signal manually. On Windows, calling g_spawn_close_pid() is equivalent to +calling <function>CloseHandle</function>() on the process handle +returned).</para> + + <para><literal>gobject.SPAWN_LEAVE_DESCRIPTORS_OPEN</literal> means +that the parent's open file descriptors will be inherited by the child; +otherwise all descriptors except stdin/stdout/stderr will be closed before +calling <function>exec</function>() in the +child. <literal>gobject.SPAWN_SEARCH_PATH</literal> means that +<parameter>argv</parameter>[0] need not be an absolute path, it will be +looked for in the user's +<envar>PATH</envar>. <literal>gobject.SPAWN_STDOUT_TO_DEV_NULL</literal> +means that the child's standard output will be discarded, instead of going +to the same location as the parent's standard output. If you use this flag, +<parameter>standard_output</parameter> must be +<literal>None</literal>. <literal>gobject.SPAWN_STDERR_TO_DEV_NULL</literal> +means that the child's standard error will be discarded, instead of going to +the same location as the parent's standard error. If you use this flag, +<parameter>standard_error</parameter> must be +<literal>None</literal>. <literal>gobject.SPAWN_CHILD_INHERITS_STDIN</literal> +means that the child will inherit the parent's standard input (by default, +the child's standard input is attached to +<filename>/dev/null</filename>). If you use this flag, +<parameter>standard_input</parameter> must be +<literal>None</literal>. <literal>gobject.SPAWN_FILE_AND_ARGV_ZERO</literal> +means that the first element of <parameter>argv</parameter> is the file to +execute, while the remaining elements are the actual argument vector to pass +to the file. Normally the <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +function uses <parameter>argv</parameter>[0] as the file to execute, and +passes all of <parameter>argv</parameter> to the child.</para> + + <para><parameter>child_setup</parameter> and +<parameter>user_data</parameter> are a function and user data. On POSIX +platforms, the function is called in the child after GLib has performed all +the setup it plans to perform (including creating pipes, closing file +descriptors, etc.) but before calling <function>exec</function>(). That is, +<parameter>child_setup</parameter> is called just before calling +<function>exec</function>() in the child. Obviously actions taken in this +function will only affect the child, not the parent. On Windows, there is no +separate <function>fork</function>() and <function>exec</function>() +functionality. Child processes are created and run right away with one API +call, +<function>CreateProcess</function>(). <parameter>child_setup</parameter> is +called in the parent process just before creating the child process. You +should carefully consider what you do in <parameter>child_setup</parameter> +if you intend your software to be portable to Windows.</para> + + <para>The returned child process id can be used to send signals to the +child, or to wait for the child if you specified the +<literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal> flag. On Windows, child +pid will be returned only if you specified the +<literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal> flag.</para> + + <para>The caller of the <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +must close any returned file descriptors when they are no longer in +use.</para> + + <para>If <parameter>standard_input</parameter> is +<literal>None</literal>, the child's standard input is attached to +<filename>/dev/null</filename> unless +<literal>gobject.SPAWN_CHILD_INHERITS_STDIN</literal> is set.</para> + + <para>If <parameter>standard_error</parameter> is +<literal>None</literal>, the child's standard error goes to the same +location as the parent's standard error unless +<literal>gobject.SPAWN_STDERR_TO_DEV_NULL</literal> is set.</para> + + <para>If <parameter>standard_output</parameter> is +<literal>None</literal>, the child's standard output goes to the same +location as the parent's standard output unless +<literal>gobject.SPAWN_STDOUT_TO_DEV_NULL</literal> is set.</para> + + <para>If an error occurs, the gobject.GError exception will be +raised.</para> + + </refsect2> + + <refsect2 id="function-gobject--get-current-time"> + <title>gobject.get_current_time</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.get_current_time</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the current time as the number of seconds and +microseconds from the epoch.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>gobject.get_current_time</function>() function +reurns the current time of day as the number of seconds and microseconds +from the epoch.</para> + + </refsect2> + + <refsect2 id="function-gobject--main-depth"> + <title>gobject.main_depth</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.main_depth</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>he depth of the stack of calls to the main +context.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>main_depth</function>() function returns the depth +of the stack of calls in the main context. That is, when called from the +toplevel, it gives 0. When called from within a callback from the <link +linkend="method-gobjectmaincontext--iteration"><methodname>gobject.MainContext.iteration</methodname>()</link> +method (or the <link +linkend="method-gobjectmainloop--run"><methodname>gobject.MainLoop.run</methodname>()</link> +method, etc.) it returns 1. When called from within a callback to a +recursive call to the <link +linkend="method-gobjectmaincontext--iteration"><methodname>gobject.MainContext.iteration</methodname>()</link> +method), it returns 2. And so forth.</para> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-gboxed.xml b/docs/reference/pygobject-gboxed.xml new file mode 100644 index 0000000..f7f2438 --- /dev/null +++ b/docs/reference/pygobject-gboxed.xml @@ -0,0 +1,68 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gobjectgboxed"> + <refnamediv> + <refname>gobject.GBoxed</refname> + <refpurpose>an object containing an opaque chunk of data</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>gobject.GBoxed</classname></ooclass> +<methodsynopsis language="python"> + <methodname><link linkend="method-gobjectgboxed--copy">copy</link></methodname> + </methodsynopsis> +</classsynopsis> + +</refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectgboxed">gobject.GBoxed</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para><link +linkend="class-gobjectgboxed"><classname>gobject.GBoxed</classname></link> +is an abstract base class that encapsulates an opaque chunk of data to +provide an object-oriented interface and a type that is registered with the +<literal>GLIB</literal> type system. A boxed type is registered with +functions that provide for the copying and freeing of the underlying data +structure - this allows PyGTK to encapsulate these as Python objects.</para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gobjectgboxed--copy"> + <title>gobject.GBoxed.copy</title> + + <programlisting><methodsynopsis language="python"> + <methodname>copy</methodname> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a copy of the <link + linkend="class-gobjectgboxed"><classname>gobject.GBoxed</classname></link> + object</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>copy</methodname>() method makes and returns a copy of the boxed object.</para> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-ginterface.xml b/docs/reference/pygobject-ginterface.xml new file mode 100644 index 0000000..1b29ddf --- /dev/null +++ b/docs/reference/pygobject-ginterface.xml @@ -0,0 +1,38 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gobjectginterface"> + <refnamediv> + <refname>gobject.GInterface</refname> + + <refpurpose>an object representing a GInterface</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>gobject.GInterface</classname></ooclass> +</classsynopsis> + +</refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para><link +linkend="class-gobjectginterface"><classname>gobject.GInterface</classname></link> +is an abstract base class that encapsulates a GInterface.</para> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-gpointer.xml b/docs/reference/pygobject-gpointer.xml new file mode 100644 index 0000000..da16954 --- /dev/null +++ b/docs/reference/pygobject-gpointer.xml @@ -0,0 +1,42 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gobjectgpointer"> + <refnamediv> + <refname>gobject.GPointer</refname> + + <refpurpose>an object containing a completely opaque chunk of + data</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>gobject.GPointer</classname></ooclass> +</classsynopsis> + +</refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectgpointer">gobject.GPointer</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para><link +linkend="class-gobjectgpointer"><classname>gobject.GPointer</classname></link> +is an abstract base class that encapsulates an opaque chunk of data and +registers it with the <literal>GLIB</literal> type system. A pointer type +has no methods and generic ways of copying and freeing the data. It +shouldn't be used in PyGTK.</para> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-maincontext.xml b/docs/reference/pygobject-maincontext.xml new file mode 100644 index 0000000..129197a --- /dev/null +++ b/docs/reference/pygobject-maincontext.xml @@ -0,0 +1,152 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gobjectmaincontext"> + <refnamediv> + <refname>gobject.MainContext</refname> + + <refpurpose>an object representing a set of event sources to be handled +in a <link +linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link>.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>gobject.MainContext</classname></ooclass> +<constructorsynopsis language="python"> + <methodname><link linkend="constructor-gobjectmaincontext">gobject.MainContext</link></methodname> + </constructorsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-gobjectmaincontext--iteration">iteration</link></methodname> + <methodparam><parameter>may_block</parameter></methodparam> + </methodsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-gobjectmaincontext--pending">pending</link></methodname> + </methodsynopsis> +</classsynopsis> + +</refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectmaincontext">gobject.MainContext</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para>A <link +linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> +represents a set of event sources that can be run in a single thread. File +descriptors (plain files, pipes or sockets) and timeouts are the standard +event sources for <literal>GTK</literal> and <literal>PyGTK</literal> though +others can be added. Each event source is assigned a priority. The default +priority, <literal>gobject.PRIORITY_DEFAULT</literal>, is 0. Values less +than 0 denote higher priorities. Values greater than 0 denote lower +priorities. Events from high priority sources are always processed before +events from lower priority sources. Single iterations of a <link +linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> +can be run with the <link +linkend="method-gobjectmaincontext--iteration"><methodname>iteration</methodname>()</link> +method.</para> + + </refsect1> + + <refsect1 id="constructor-gobjectmaincontext"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gobject.MainContext</methodname> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new <link + linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> + object.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>Creates a new <link +linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> +object.</para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gobjectmaincontext--iteration"> + <title>gobject.MainContext.iteration</title> + + <programlisting><methodsynopsis language="python"> + <methodname>iteration</methodname> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>may_block</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> the call may block + waiting for an event.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if events were + dispatched.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>iteration</methodname>() method runs a single +iteration. This involves:</para> + + <itemizedlist> + <listitem> + <simpara>checking to see if any associated event sources are ready +to be processed;</simpara> + </listitem> + <listitem> + <simpara>then if no events sources are ready and +<parameter>may_block</parameter> is <literal>TRUE</literal>, waiting for a +source to become ready;</simpara> + </listitem> + <listitem> + <simpara>and finally, dispatching the highest priority events +sources that are ready</simpara> + </listitem> + </itemizedlist> + + <para>Note that even when <parameter>may_block</parameter> is +<literal>TRUE</literal>, it is still possible for +<methodname>iteration</methodname>() to return <literal>FALSE</literal>, +since the the wait may be interrupted for other reasons than an event source +becoming ready.</para> + + </refsect2> + + <refsect2 id="method-gobjectmaincontext--pending"> + <title>gobject.MainContext.pending</title> + + <programlisting><methodsynopsis language="python"> + <methodname>pending</methodname> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if events are + pending.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>pending</methodname>() method checks if any +associated sources have pending events.</para> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-mainloop.xml b/docs/reference/pygobject-mainloop.xml new file mode 100644 index 0000000..d90f534 --- /dev/null +++ b/docs/reference/pygobject-mainloop.xml @@ -0,0 +1,202 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gobjectmainloop"> + <refnamediv> + <refname>gobject.MainLoop</refname> + + <refpurpose>an object representing the main event loop of a PyGTK + application.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>gobject.MainLoop</classname></ooclass> +<constructorsynopsis language="python"> + <methodname><link linkend="constructor-gobjectmainloop">gobject.MainLoop</link></methodname> + <methodparam><parameter>context</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter>is_running</parameter><initializer>0</initializer></methodparam> + </constructorsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-gobjectmainloop--get-context">get_context</link></methodname> + </methodsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-gobjectmainloop--is-running">is_running</link></methodname> + </methodsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-gobjectmainloop--quit">quit</link></methodname> + </methodsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-gobjectmainloop--run">run</link></methodname> + </methodsynopsis> +</classsynopsis> + +</refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectmainloop">gobject.MainLoop</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para><link +linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link> +represents a main event loop. A <link +linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link> +is created with the <link +linkend="constructor-gobjectmainloop">gobject.MainLoop</link>() +constructor. After adding the initial event sources, the <link +linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link> +method is called. This continuously checks for new events from each of the +event sources and dispatches them. Finally, the processing of an event from +one of the sources leads to a call to the <link +linkend="method-gobjectmainloop--quit"><methodname>quit</methodname>()</link> +method to exit the main loop, and the <link +linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link> +method returns.</para> + + <para>It is possible to create new instances of <link +linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link> +recursively. This is often used in <literal>PyGTK</literal> applications +when showing modal dialog boxes. Note that event sources are associated with +a particular <link +linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>, +and will be checked and dispatched for all main loops associated with that +<link +linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>.</para> + + <para><literal>PyGTK</literal> contains wrappers of some of these +functions, e.g. the <link +linkend="function-gtk--main"><function>gtk.main</function>()</link>, <link +linkend="function-gtk--main-quit"><function>gtk.main_quit</function>()</link> +and <link +linkend="function-gtk--events-pending"><function>gtk.events_pending</function>()</link> +functions.</para> + + </refsect1> + + <refsect1 id="constructor-gobjectmainloop"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gobject.MainLoop</methodname> + <methodparam><parameter>context</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter>is_running</parameter><initializer>None</initializer></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>context</parameter> :</term> + <listitem><simpara>a <link + linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> + or <literal>None</literal> to use the default + context.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>is_running</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> indicates that the + loop is running. This is not very important since calling the <link + linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link> + method will set this to <literal>TRUE</literal> + anyway.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new <link + linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link> + object.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>Creates a new <link +linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link> +object.</para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gobjectmainloop--get-context"> + <title>gobject.MainLoop.get_context</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_context</methodname> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the <link + linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> + the mainloop is associated with</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>get_context</methodname>() method returns the +<link +linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> +that the mainloop was created with.</para> + + </refsect2> + + <refsect2 id="method-gobjectmainloop--is-running"> + <title>gobject.MainLoop.is_running</title> + + <programlisting><methodsynopsis language="python"> + <methodname>is_running</methodname> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if the mainloop is + currently being run.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>is_running</methodname>() method checks to see +if the mainloop is currently being run via the <link +linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link> +method.</para> + + </refsect2> + + <refsect2 id="method-gobjectmainloop--quit"> + <title>gobject.MainLoop.quit</title> + + <programlisting><methodsynopsis language="python"> + <methodname>quit</methodname> + </methodsynopsis></programlisting> + + <para>The <methodname>quit</methodname>() method stops the mainloop +from running. Any subsequent calls to the <link +linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link> +method will return immediately.</para> + + </refsect2> + + <refsect2 id="method-gobjectmainloop--run"> + <title>gobject.MainLoop.run</title> + + <programlisting><methodsynopsis language="python"> + <methodname>run</methodname> + </methodsynopsis></programlisting> + + <para>The <methodname>run</methodname>() method runs a mainloop until +the <link +linkend="method-gobjectmainloop--quit"><methodname>quit</methodname>()</link> +method is called. If this is called for the thread of the loop's <link +linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>, +it will process events from the loop, otherwise it will simply wait.</para> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-ref.xml b/docs/reference/pygobject-ref.xml new file mode 100644 index 0000000..4b43cce --- /dev/null +++ b/docs/reference/pygobject-ref.xml @@ -0,0 +1,154 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" +"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +]> +<book id="pygtk-reference" xmlns:xi="http://www.w3.org/2001/XInclude"> + <bookinfo> + <pubdate>July 6, 2006</pubdate> + <title>PyGObject Reference Manual</title> + <edition>PyGObject Reference Manual version 2.9.0 for PyGTK 2.9.x</edition> + <releaseinfo>Version 2.9.0</releaseinfo> + <authorgroup> + <author> + <firstname>John</firstname> + <surname>Finlay</surname> + </author> + </authorgroup> + <abstract> + <para>This reference describes the classes of the python gobject +module.</para> + </abstract> +<!-- <revhistory> + <revision> + <revnumber>2.9.0</revnumber> + <date>July 7, 2006</date> + <revremark>Release covering PyGTK 2.9.x (GTK+ 2.9)</revremark> + </revision> + <revision> + <revnumber>2.8.2</revnumber> + <date>October 7, 2005</date> + <revremark>Release covering PyGTK 2.8.x (GTK+ 2.8)</revremark> + </revision> + <revision> + <revnumber>2.8.1</revnumber> + <date>September 17, 2005</date> + <revremark>Release covering PyGTK 2.8.x (GTK+ 2.8)</revremark> + </revision> + <revision> + <revnumber>2.8.0</revnumber> + <date>September 7, 2005</date> + <revremark>Release covering PyGTK 2.8.x (GTK+ 2.8)</revremark> + </revision> + <revision> + <revnumber>2.6.0</revnumber> + <date>April 10, 2005</date> + <revremark>First release covering PyGTK 2.6.x (GTK+ 2.6)</revremark> + </revision> + <revision> + <revnumber>2.5.2</revnumber> + <date>March 5, 2005</date> + </revision> + <revision> + <revnumber>2.5.1</revnumber> + <date>December 23, 2004</date> + <revremark>First release covering PyGTK 2.5.1 (GTK+ 2.6)</revremark> + </revision> + <revision> + <revnumber>2.5.0</revnumber> + <date>November 15, 2004</date> + <revremark>First release covering PyGTK 2.5.x</revremark> + </revision> + <revision> + <revnumber>2.4.11</revnumber> + <date>October 3, 2004</date> + </revision> + <revision> + <revnumber>2.4.10</revnumber> + <date>August 11, 2004</date> + </revision> + <revision> + <revnumber>2.4.9</revnumber> + <date>August 3, 2004</date> + </revision> + <revision> + <revnumber>2.4.8</revnumber> + <date>July 1, 2004</date> + </revision> + <revision> + <revnumber>2.4.7</revnumber> + <date>May 19, 2004</date> + </revision> + <revision> + <revnumber>2.4.6</revnumber> + <date>May 17, 2004</date> + </revision> + <revision> + <revnumber>2.4.4</revnumber> + <date>May 5, 2004</date> + </revision> + <revision> + <revnumber>2.4.2</revnumber> + <date>April 29, 2004</date> + </revision> + <revision> + <revnumber>2.4.0</revnumber> + <date>April 27, 2004</date> + <revremark>First release covering PyGTK 2.2 and 2.4</revremark> + </revision> + <revision> + <revnumber>1.9</revnumber> + <date>January 28, 2004</date> + </revision> + <revision> + <revnumber>1.8</revnumber> + <date>October 7, 2003</date> + </revision> + <revision> + <revnumber>1.7</revnumber> + <date>August 23, 2003</date> + </revision> + <revision> + <revnumber>1.6</revnumber> + <date>July 20, 2003</date> + </revision> + <revision> + <revnumber>1.5</revnumber> + <date>July 17, 2003</date> + </revision> + <revision> + <revnumber>1.4</revnumber> + <date>July 16, 2003</date> + </revision> + <revision> + <revnumber>1.3</revnumber> + <date>July 15, 2003</date> + </revision> + <revision> + <revnumber>1.2</revnumber> + <date>July 12, 2003</date> + </revision> + <revision> + <revnumber>1.1</revnumber> + <date>July 11, 2003</date> + </revision> + <revision> + <revnumber>1.0</revnumber> + <date>July 2, 2003</date> + <revremark>First release for PyGTK 2.0</revremark> + </revision> + </revhistory>--> + </bookinfo> + <toc> + </toc> + + <!-- <xi:include href="pygtk-introduction.xml"/> --> + + <xi:include href="pygobject-classes.xml"/> +<!-- +<appendix id="pygtk-ref-changelog"> +<title>ChangeLog</title> + <xi:include href="ChangeLog.xml"/> +</appendix> + --> + +</book> diff --git a/docs/reference/pygobject.xml b/docs/reference/pygobject.xml new file mode 100644 index 0000000..fd75829 --- /dev/null +++ b/docs/reference/pygobject.xml @@ -0,0 +1,867 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<refentry id="class-gobject"> + <refmeta> + <refentrytitle>gobject.GObject</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>PyGTK Docs</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>gobject.GObject</refname> + <refpurpose>the base class</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>gobject.GObject</classname></ooclass> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--get-property">get_property</link></methodname> + <methodparam><parameter>property_name</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--set-property">set_property</link></methodname> + <methodparam><parameter>property_name</parameter></methodparam> + <methodparam><parameter>value</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--freeze-notify">freeze_notify</link></methodname> + <methodparam></methodparam> </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--notify">notify</link></methodname> + <methodparam><parameter>property_name</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--thaw-notify">thaw_notify</link></methodname> + <methodparam></methodparam> </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--get-data">get_data</link></methodname> + <methodparam><parameter>key</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--set-data">set_data</link></methodname> + <methodparam><parameter>key</parameter></methodparam> + <methodparam><parameter>data</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--connect">connect</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--connect-after">connect_after</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--connect-object">connect_object</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--connect-object-after">connect_object_after</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--disconnect">disconnect</link></methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--handler-disconnect">handler_disconnect</link></methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--handler-is-connected">handler_is_connected</link></methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--handler-block">handler_block</link></methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--handler-unblock">handler_unblock</link></methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--emit">emit</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--stop-emission">stop_emission</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--emit-stop-by-name">emit_stop_by_name</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--chain">chain</link></methodname> + <methodparam></methodparam> </methodsynopsis> +</classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Attributes</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <?dbhtml cellpadding="5"?> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + + <row valign="top"> + <entry>"__doc__"</entry> + <entry>Read</entry> + <entry>The documentation for the object type. Uses + "__gdoc__" if no specific documentation set.</entry> + </row> + <row valign="top"> + <entry>"__gdoc__"</entry> + <entry>Read</entry> + <entry>The generated documentation for the underlying GObject + type.</entry> + </row> + <row valign="top"> + <entry>"__gtype__"</entry> + <entry>Read</entry> + <entry>The underlying GObject type.</entry> + </row> + <row valign="top"> + <entry>"__grefcount__"</entry> + <entry>Read</entry> + <entry>The reference count for the underlying GObject.</entry> + </row> + + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1 id="signal-prototypes-gobject"> + <title>gobject.GObject Signal Prototypes</title> + + + <variablelist> + <varlistentry> + <term>"<link linkend="signal-gobject--notify">notify</link>"</term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>gobject</parameter></methodparam> + <methodparam><parameter>property_spec</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Description</title> + <para>The <link + linkend="class-gobject"><classname>gobject.GObject</classname></link> + class is the base class providing the common attributes and methods for + the PyGTK classes. The <link + linkend="class-gobject"><classname>gobject.GObject</classname></link> + class is not a user interface widget class.</para> + + <para>The <link + linkend="class-gobject"><classname>gobject.GObject</classname></link> + class provides the signal management methods, the object property access + methods and the object data management methods.</para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gobject--get-property"> + <title>gobject.GObject.get_property</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_property</methodname> + <methodparam><parameter>property_name</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>property_name</parameter> :</term> + <listitem><simpara>a string containing the property name for the +GObject</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a Python object containing the value of the +property</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>get_property</methodname>() method returns the +value of the property specified by <parameter>property_name</parameter> or +None if there is no value associated with the property.</para> + <para>The <exceptionname>TypeError</exceptionname> exception is raised +if the property name is not registered with the object class.</para> + + </refsect2> + + <refsect2 id="method-gobject--set-property"> + <title>gobject.GObject.set_property</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_property</methodname> + <methodparam><parameter>property_name</parameter></methodparam> + <methodparam><parameter>value</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>property_name</parameter> :</term> + <listitem><simpara>a string containing the property +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>a Python object containing the property value +to be set</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>set_property</methodname>() method sets the +property specified by <parameter>property_name</parameter> to the specified +<parameter>value</parameter>.</para> + <para>The <exceptionname>TypeError</exceptionname> exception is raised +if the property name is not registered with the object class or if the value +specified could not be converted to the property type.</para> + + </refsect2> + + <refsect2 id="method-gobject--freeze-notify"> + <title>gobject.GObject.freeze_notify</title> + + <programlisting><methodsynopsis language="python"> + <methodname>freeze_notify</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <para>The <methodname>freeze_notify</methodname>() method freezes the +object's property-changed notification queue so that "notify" signals are +blocked until the <methodname>thaw_notify</methodname>() method is +called.</para> + + </refsect2> + + <refsect2 id="method-gobject--notify"> + <title>gobject.GObject.notify</title> + + <programlisting><methodsynopsis language="python"> + <methodname>notify</methodname> + <methodparam><parameter>property_name</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>property_name</parameter> :</term> + <listitem><simpara>a string containing a property +name</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>notify</methodname>() method causes the "notify" +signal for the property specified by <parameter>property_name</parameter> to +be emitted.</para> + + </refsect2> + + <refsect2 id="method-gobject--thaw-notify"> + <title>gobject.GObject.thaw_notify</title> + + <programlisting><methodsynopsis language="python"> + <methodname>thaw_notify</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <para>The <methodname>thaw_notify</methodname>() method thaws the +object's property-changed notification queue so that "notify" signals are +emitted.</para> + + </refsect2> + + <refsect2 id="method-gobject--get-data"> + <title>gobject.GObject.get_data</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_data</methodname> + <methodparam><parameter>key</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>key</parameter> :</term> + <listitem><simpara>a string used as the key</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a Python object containing the associated +data</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>get_data</methodname>() method returns the +Python object associated with the specified <parameter>key</parameter> or +None if there is no data associated with the <parameter>key</parameter> or +if there is no key associated with the object.</para> + + </refsect2> + + <refsect2 id="method-gobject--set-data"> + <title>gobject.GObject.set_data</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_data</methodname> + <methodparam><parameter>key</parameter></methodparam> + <methodparam><parameter>data</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>key</parameter> :</term> + <listitem><simpara>a string used as a key</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>data</parameter> :</term> + <listitem><simpara>a Python object that is the value to be +associated with the key</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>set_data</methodname>() method associates the +specified Python object (<parameter>data</parameter>) with +<parameter>key</parameter>.</para> + + </refsect2> + + <refsect2 id="method-gobject--connect"> + <title>gobject.GObject.connect</title> + + <programlisting><methodsynopsis language="python"> + <methodname>connect</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional optional +parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>connect</methodname>() method adds a function or +method (<parameter>handler</parameter>)to the end of the list of signal +handlers for the named <parameter>detailed_signal</parameter> but before the +default class signal handler. An optional set of parameters may be specified +after the <parameter>handler</parameter> parameter. These will all be passed +to the signal handler when invoked.</para> + <para>For example if a function handler was connected to a signal +using:</para> + <programlisting> + handler_id = object.connect("signal_name", handler, arg1, arg2, arg3) +</programlisting> + <para>The handler should be defined as:</para> + <programlisting> + def handler(object, arg1, arg2, arg3): +</programlisting> + <para>A method handler connected to a signal using:</para> + <programlisting> + handler_id = object.connect("signal_name", self.handler, arg1, arg2) +</programlisting> + <para>requires an additional argument when defined:</para> + <programlisting> + def handler(self, object, arg1, arg2) +</programlisting> + <para>A <exceptionname>TypeError</exceptionname> exception is raised +if <parameter>detailed_signal</parameter> identifies a signal name that is +not associated with the object.</para> + + </refsect2> + + <refsect2 id="method-gobject--connect-after"> + <title>gobject.GObject.connect_after</title> + + <programlisting><methodsynopsis language="python"> + <methodname>connect_after</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional optional +parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>connect_after</methodname>() method is similar +to the <methodname>connect</methodname>() method except that the +<parameter>handler</parameter> is added to the signal handler list after the +default class signal handler. Otherwise the details of +<parameter>handler</parameter> definition and invocation are the +same.</para> + + </refsect2> + + <refsect2 id="method-gobject--connect-object"> + <title>gobject.GObject.connect_object</title> + + <programlisting><methodsynopsis language="python"> + <methodname>connect_object</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + <methodparam><parameter>gobject</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>gobject</parameter> :</term> + <listitem><simpara>a GObject</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>connect_object</methodname>() method is the same +as the <methodname>connect</methodname>() method except that the +<parameter>handler</parameter> is invoked with the specified +<parameter>gobject</parameter> in place of the object invoking the +<methodname>connect_object</methodname>() method. For example, a call with a +function handler:</para> + <programlisting> + handler_id = object("signal_name", handler, gobject) +</programlisting> + <para>will cause the <parameter>handler</parameter> to be invoked +as:</para> + <programlisting> + handler(gobject) +</programlisting> + <para>Likewise a method handler will be invoked as:</para> + <programlisting> + self.handler(gobject) +</programlisting> + <para>This can be helpful in invoking PyGTK widget methods that +require no arguments except the widget itself (e.g. +<methodname>widget.destroy</methodname>()) by using the class method as the +handler. For example, a Button "clicked" signal can be set up to invoke the +Window <methodname>destroy</methodname>() method as:</para> + + <programlisting> + handler_id = button.connect_object("clicked", Window.destroy, window) +</programlisting> + + <para>When the button is clicked the handler is invoked as:</para> + + <programlisting> + Window.destroy(window) +</programlisting> + + <para>which is the same as:</para> + + <programlisting> + window.destroy() +</programlisting> + + <para>Additional arguments may be passed to the handler as with the +<methodname>connect</methodname>() method handler invocations.</para> + + </refsect2> + + <refsect2 id="method-gobject--connect-object-after"> + <title>gobject.GObject.connect_object_after</title> + + <programlisting><methodsynopsis language="python"> + <methodname>connect_object_after</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>gobject</parameter> :</term> + <listitem><simpara>a GObject</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>connect_object_after</methodname>() method is +similar to the <methodname>connect_object</methodname>() method except that +the <parameter>handler</parameter> is added to the signal handler list after +the default class signal handler. Otherwise the details of +<parameter>handler</parameter> definition and invocation are the +same.</para> + + </refsect2> + + <refsect2 id="method-gobject--disconnect"> + <title>gobject.GObject.disconnect</title> + + <programlisting><methodsynopsis language="python"> + <methodname>disconnect</methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>handler_id</parameter> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>disconnect</methodname>() method removes the +signal handler with the specified <parameter>handler_id</parameter> from the +list of signal handlers for the object.</para> + + </refsect2> + + <refsect2 id="method-gobject--handler-disconnect"> + <title>gobject.GObject.handler_disconnect</title> + + <programlisting><methodsynopsis language="python"> + <methodname>handler_disconnect</methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>handler_id</parameter> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>handler_disconnect</methodname>() method removes +the signal handler with the specified <parameter>handler_id</parameter> from +the list of signal handlers for the object.</para> + + </refsect2> + + <refsect2 id="method-gobject--handler-is-connected"> + <title>gobject.GObject.handler_is_connected</title> + + <programlisting><methodsynopsis language="python"> + <methodname>handler_is_connected</methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>handler_id</parameter> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if the signal handler +is connected to the object.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>handler_is_connected</methodname>() method +returns <literal>TRUE</literal> if the signal handler with the specified +<parameter>handler_id</parameter> is connected to the object.</para> + + </refsect2> + + <refsect2 id="method-gobject--handler-block"> + <title>gobject.GObject.handler_block</title> + + <programlisting><methodsynopsis language="python"> + <methodname>handler_block</methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>handler_id</parameter> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>handler_block</methodname>() method blocks the +signal handler with the specified <parameter>handler_id</parameter> from +being invoked until it is unblocked.</para> + + </refsect2> + + <refsect2 id="method-gobject--handler-unblock"> + <title>gobject.GObject.handler_unblock</title> + + <programlisting><methodsynopsis language="python"> + <methodname>handler_unblock</methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>handler_id</parameter> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>handler_unblock</methodname>() method unblocks +the signal handler with the specified <parameter>handler_id</parameter> +thereby allowing it to be invoked when the associated signal is +emitted.</para> + + </refsect2> + + <refsect2 id="method-gobject--emit"> + <title>gobject.GObject.emit</title> + + <programlisting><methodsynopsis language="python"> + <methodname>emit</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a PyObject*</simpara></listitem> + </varlistentry> + </variablelist> + <para>The <methodname>emit</methodname>() method causes the object to +emit the signal specified by <parameter>detailed_signal</parameter>. The +additional parameters must match the number and type of the required signal +handler parameters. In most cases no additional parameters are needed. for +example:</para> + <programlisting> + button.emit("clicked") +</programlisting> + <para>is all that is required to emit the "clicked" signal for a +button. The most common case requiring additional parameters occurs when +emitting an event signal; for example:</para> + <programlisting> + button.emit("button_press_event", event) +</programlisting> + + </refsect2> + + <refsect2 id="method-gobject--stop-emission"> + <title>gobject.GObject.stop_emission</title> + + <programlisting><methodsynopsis language="python"> + <methodname>stop_emission</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>stop_emission</methodname>() method stops the +current emission of the signal specified by +<parameter>detailed_signal</parameter>. Any signal handlers in the list +still to be run will not be invoked.</para> + + </refsect2> + + <refsect2 id="method-gobject--emit-stop-by-name"> + <title>gobject.GObject.emit_stop_by_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>emit_stop_by_name</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>emit_stop_by_name</methodname>() method stops +the current emission of the signal specified by +<parameter>detailed_signal</parameter>. Any signal handlers in the list +still to be run will not be invoked.</para> + + </refsect2> + + <refsect2 id="method-gobject--chain"> + <title>gobject.GObject.chain</title> + + <programlisting><methodsynopsis language="python"> + <methodname>chain</methodname> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a Python object</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The chain() method does something.</para> + + </refsect2> + + </refsect1> + + <refsect1> + <title>Signals</title> + + <refsect2 id="signal-gobject--notify"> + <title>The GObject "notify" Signal</title> + + <programlisting><methodsynopsis language="python"> + <methodname>callback</methodname> + <methodparam><parameter>gobject</parameter></methodparam> + <methodparam><parameter>property_spec</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>gobject</parameter> :</term> + <listitem><simpara>the gobject that received the +signal</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>property_spec</parameter> :</term> + <listitem><simpara>the <link linkend="class-gobjectgparamspec"><classname>gobject.GParamSpec</classname></link> of the property that was +changed</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_param1</parameter> :</term> + <listitem><simpara>the first user parameter (if any) specified +with the <link +linkend="method-gobject--connect"><methodname>connect</methodname>()</link> +method</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional user parameters (if +any)</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The "notify" signal is emitted on a gobject when one of its +properties has been changed. Note that getting this signal doesn't guarantee +that the value of the property has actually changed, it may also be emitted +when the setter for the property is called to reinstate the previous +value. For example to be notified of the change of the title of a <link +linkend="class-gtkwindow"><classname>gtk.Window</classname></link> you could +connect to the "notify" signal similar to:</para> + + <programlisting> + window.connect("notify::title", callback) +</programlisting> + + </refsect2> + + </refsect1> + +</refentry> |