From 3bd20fd42ba96ab19ea217d7b224c766d00cc06a Mon Sep 17 00:00:00 2001 From: Johan Dahlin Date: Wed, 12 Jul 2006 23:06:52 +0000 Subject: Import GObject part of John Finlay's PyGTK Reference Manual, copy over * 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. --- ChangeLog | 26 + Makefile.am | 5 +- configure.ac | 23 + docs/.cvsignore | 3 + docs/Makefile.am | 52 ++ docs/common.xsl | 20 + docs/devhelp.xsl | 154 ++++ docs/html.xsl | 288 +++++++ docs/pdf-style.xsl | 11 + docs/pdf.xsl | 259 ++++++ docs/ref-html-style.xsl | 52 ++ docs/reference/.cvsignore | 2 + docs/reference/pygobject-classes.xml | 20 + docs/reference/pygobject-constants.xml | 495 +++++++++++ docs/reference/pygobject-functions.xml | 1373 ++++++++++++++++++++++++++++++ docs/reference/pygobject-gboxed.xml | 68 ++ docs/reference/pygobject-ginterface.xml | 38 + docs/reference/pygobject-gpointer.xml | 42 + docs/reference/pygobject-maincontext.xml | 152 ++++ docs/reference/pygobject-mainloop.xml | 202 +++++ docs/reference/pygobject-ref.xml | 154 ++++ docs/reference/pygobject.xml | 867 +++++++++++++++++++ 22 files changed, 4305 insertions(+), 1 deletion(-) create mode 100644 docs/.cvsignore create mode 100644 docs/Makefile.am create mode 100644 docs/common.xsl create mode 100644 docs/devhelp.xsl create mode 100644 docs/html.xsl create mode 100644 docs/pdf-style.xsl create mode 100644 docs/pdf.xsl create mode 100644 docs/ref-html-style.xsl create mode 100644 docs/reference/.cvsignore create mode 100644 docs/reference/pygobject-classes.xml create mode 100644 docs/reference/pygobject-constants.xml create mode 100644 docs/reference/pygobject-functions.xml create mode 100644 docs/reference/pygobject-gboxed.xml create mode 100644 docs/reference/pygobject-ginterface.xml create mode 100644 docs/reference/pygobject-gpointer.xml create mode 100644 docs/reference/pygobject-maincontext.xml create mode 100644 docs/reference/pygobject-mainloop.xml create mode 100644 docs/reference/pygobject-ref.xml create mode 100644 docs/reference/pygobject.xml diff --git a/ChangeLog b/ChangeLog index 6976aae..f317205 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,29 @@ +2006-07-12 Johan Dahlin + + * 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 * 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 + + + + + + + + + + + + + + + + + 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 @@ + + + + + + + + + + + + book + + + .devhelp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + , + + + + + 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 @@ + + + +]> + + + + + + + + + + 0 + #E0E0E0 + 100% + + + + + + +
+ + + + + + + + + + + + + + + + + +
  + +  
+ -- + +  
+ + + + + + + + +
+ +
+ + + + + + +
+ +
+ + + + +
+ +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
+ 
+      class 
+      
+      
+        (
+                )
+      
+      :&RE;
+
+      
+
+ + + + + + + + + , + + + + + + + + + +   + + + + + + , + + + + + + + + + , + + + + + + + + + , + + + + + + + + +      + + + + + + + + +   + + + + + + +   + + + + + + = + + + + + + + void  + + + + + + + + + + + + , + + + + + + + + + + def + + ( + + ) + + + + + + + + + + ( + + ) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + 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 @@ + + + + + + + + + + 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 @@ + + + +]> + + + +0.5in + + + + 1 + + + + + + + + + + + + + + + + + + + + + + + + + + + class + + + ( + + ) + +  : + + + + + &RE; + + + + + + + + + , + + + + + + +   + + + + + , + + + + + + + , + + + + + + + , + + + + + + +      + + + + + + + +   + + + + +   + + + + = + + + + + void  + + + + + + + + + , + + + + + + + + def + + ( + + ) + + + + + + + + + ( + + ) + + + + + + + + + + + + + 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 @@ + + + + + + + + + + + + + + + + + + + + + + + + <ANCHOR id=" + + " href=" + + + / + + + "> + + + + + + + + + + + + + + + + + + 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 @@ + + + + +The gobject Class Reference + + + + + + + + + + + + + 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 @@ + + + + + + gobject Constants + the built-in constants of the gobject module + + + + Synopsis + + + + + + + + + + + + + + + Description + + + GObject IO Condition Constants + + The IO Condition constants are a set of bit-flags that specify a +condition to watch for on an event source. + + + + gobject.IO_IN + + There is data to read + + + + gobject.IO_OUT + + Data can be written (without blocking). + + + + gobject.IO_PRI + + There is urgent data to read. + + + + gobject.IO_ERR + + Error condition. + + + + gobject.IO_HUP + + Hung up (the connection has been broken, usually for + pipes and sockets). + + + + gobject.IO_NVAL + + Invalid request. The file descriptor is not + open. + + + + + + + + GObject Param Flag Constants + + The Param Flag constants are a set of bit-flags that specify +certain aspects of parameters that can be configured. + + + + gobject.PARAM_READABLE + + The parameter is readable + + + + gobject.PARAM_WRITABLE + + The parameter is writable + + + + gobject.PARAM_CONSTRUCT + + The parameter will be set upon object + construction + + + + gobject.PARAM_CONSTRUCT_ONLY + + The parameter will only be set upon object + construction + + + + gobject.PARAM_LAX_VALIDATION + + Upon parameter conversion strict validation is not + required + + + + + + + + GObject Priority Constants + + The Priority constants specify + + + + gobject.PRIORITY_HIGH + + Use this for high priority event sources. + + + + gobject.PRIORITY_DEFAULT + + Use this for default priority event sources. This + priority is used when adding timeout functions with the gobject.timeout_add() + function. This priority is also used for events from the X + server. + + + + gobject.PRIORITY_HIGH_IDLE + + 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.) + + + + gobject.PRIORITY_DEFAULT_IDLE + + Use this for default priority idle functions. This + priority is used when adding idle functions with the gobject.idle_add() + function. + + + + gobject.PRIORITY_LOW + + Use this for very low priority background + tasks. + + + + + + + + GObject Signal Flag Constants + + The Signal Flag constants are a set of bit-flags that specify a +signal's behavior. The overall signal description outlines how especially +the RUN flags control the stages of a signal +emission. + + + + gobject.SIGNAL_RUN_FIRST + + Invoke the object method handler in the first emission + stage. + + + + gobject.SIGNAL_RUN_LAST + + Invoke the object method handler in the third emission + stage. + + + + gobject.SIGNAL_RUN_CLEANUP + + Invoke the object method handler in the last emission + stage. + + + + gobject.SIGNAL_NO_RECURSE + + 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. + + + + gobject.SIGNAL_DETAILED + + This signal supports "::detail" appendices to the + signal name upon handler connections and emissions. + + + + gobject.SIGNAL_ACTION + + Action signals are signals that may freely be emitted + on alive objects from user code via the gobject.emit() + 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. + + + + gobject.SIGNAL_NO_HOOKS + + No emissions hooks are supported for this + signal. + + + + + + + + GObject Spawn Flag Constants + + The Spawn Flag constants are a set of bit-flags that can be +passed to the gobject.spawn_async() +function. + + + + gobject.SPAWN_LEAVE_DESCRIPTORS_OPEN + + the parent's open file descriptors will be inherited by +the child; otherwise all descriptors except stdin/stdout/stderr will be +closed before calling exec() in the child. + + + + gobject.SPAWN_DO_NOT_REAP_CHILD + + the child will not be automatically reaped; you must +call waitpid() or handle SIGCHLD +yourself, or the child will become a zombie. + + + + gobject.SPAWN_SEARCH_PATH + + argv[0] need not be an absolute +path, it will be looked for in the user's PATH. + + + + gobject.SPAWN_STDOUT_TO_DEV_NULL + + the child's standard output will be discarded, instead +of going to the same location as the parent's standard output. + + + + gobject.SPAWN_STDERR_TO_DEV_NULL + + the child's standard error will be discarded. + + + + gobject.SPAWN_CHILD_INHERITS_STDIN + + the child will inherit the parent's standard input (by +default, the child's standard input is attached to /dev/null). + + + + gobject.SPAWN_FILE_AND_ARGV_ZERO + + the first element of argv is the +file to execute, while the remaining elements are the actual argument vector +to pass to the file. Normally gobject.spawn_async() +uses argv[0] as the file to execute, and passes all +of argv to the child. + + + + + + + + GObject Built-in Type Constants + + The Built-in Type constants specify the pre-defined types used +by gobject. + + + + gobject.TYPE_INVALID + + An invalid type, used as error return value in some + functions. + + + + gobject.TYPE_NONE + + A fundamental type indicating no type. + + + + gobject.TYPE_INTERFACE + + The fundamental type from which all interfaces are + derived. + + + + gobject.TYPE_CHAR + + The fundamental type corresponding to a + character. This maps to a string in Python. + + + + gobject.TYPE_UCHAR + + The fundamental type corresponding to an unsigned + character. This maps to a string in Python. + + + + gobject.TYPE_BOOLEAN + + The fundamental type corresponding to a True or False + value. This maps to an integer in Python. + + + + gobject.TYPE_INT + + The fundamental type corresponding to an + integer. This maps to an integer in Python. + + + + gobject.TYPE_UINT + + he fundamental type corresponding to an unsigned + integer. This maps to an integer in Python. + + + + gobject.TYPE_LONG + + The fundamental type corresponding to a long + integer. This maps to an integer in Python. + + + + gobject.TYPE_ULONG + + The fundamental type corresponding to an unsigned + integer. This maps to an integer in Python. + + + + gobject.TYPE_INT64 + + The fundamental type corresponding to an long long + integer. This maps to a long integer in Python. + + + + gobject.TYPE_UINT64 + + The fundamental type corresponding to an unsigned long + long integer. This maps to a long integer in Python. + + + + gobject.TYPE_ENUM + + The fundamental type corresponding to an enumeration + type. This maps to an integer in Python. + + + + gobject.TYPE_FLAGS + + The fundamental type corresponding to a flag + type. This maps to an integer in Python. + + + + gobject.TYPE_FLOAT + + The fundamental type corresponding to a floating point + number. This maps to a float in Python. + + + + gobject.TYPE_DOUBLE + + The fundamental type corresponding to a double + floating point number. This maps to a float in Python. + + + + gobject.TYPE_STRING + + The fundamental type corresponding to a string. + + + + gobject.TYPE_POINTER + + The fundamental type corresponding to a pointer to an + anonymous type. This has no corresponding Python type. + + + + gobject.TYPE_BOXED + + The fundamental type corresponding to a boxed object + type. + + + + gobject.TYPE_PARAM + + The fundamental type corresponding to a GParamSpec + type. + + + + gobject.TYPE_OBJECT + + The fundamental type corresponding to a GObject + type. + + + + gobject.TYPE_PYOBJECT + + The fundamental type corresponding to a Python Object + type. + + + + + + + + GObject Version Constants + + The Version constants specify the version of +GLIB used by PyGTK as a 3-tuple containing the major, +minor and patch release numbers. + + + + gobject.glib_version + + A 3-tuple containing (major, minor, patch) release + numbers. + + + + + + + + + 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 @@ + + + + + + gobject Functions + miscellaneous functions + + + + Synopsis + + + + gobject.type_name + type + + gobject.type_from_name + type_name + + gobject.type_parent + type + + gobject.type_is_a + type + parent_type + + gobject.type_children + type + + gobject.type_interfaces + type + + gobject.type_register + class + + gobject.signal_new + signal_name + type + flags + return_type + param_types + + gobject.signal_list_names + type + + gobject.signal_list_ids + type + + gobject.signal_lookup + name + type + + gobject.signal_name + signal_id + + gobject.signal_query + name + type + + gobject.signal_query + signal_id + + gobject.list_properties + type + + gobject.new + type + ... + + gobject.idle_add + callback + ... + + gobject.timeout_add + interval + callback + ... + + gobject.io_add_watch + fd + condition + callback + ... + + gobject.source_remove + tag + + gobject.main_context_default + + + gobject.markup_escape_text + text + + gobject.child_watch_add + pid + function + dataNone + prioritygobject.PRIORITY_DEFAULT + + gobject.spawn_async + argv + envpNone + working_directoryNone + flags0 + child_setupNone + user_dataNone + standard_inputNone + standard_outputNone + standard_errorNone + + gobject.get_current_time + + gobject.main_depth + + + + + + Description + + These functions are part of the PyGTK gobject +module but are not directly associated with a specific class. + + + + + Functions + + + gobject.type_name + + + gobject.type_name + type + + + + type : + a GObject type, type ID or +instance + + + Returns : + + + + + The gobject.type_name() function returns +the unique name that is assigned to the specified +type. type can be a GObject +type, type ID or instance. This function raises a TypeError exception +if type isn't a PyGTK type. + + + + + gobject.type_from_name + + + gobject.type_from_name + type_name + + + + type_name : + a string containing the name of a +type + + + Returns : + the type ID named +type_name + + + + The gobject.type_from_name() function +returns the type ID of the PyGTK type with the name +specified by type_name. This function raises a +RuntimeError exception if no type matches +type_name. + + + + + gobject.type_parent + + + gobject.type_parent + type + + + + type : + a GObject type, type ID or +instance + + + Returns : + the parent type ID + + + + The gobject.type_parent() function returns +the direct parent type ID of the specified type. +type can be a GObject type, type ID or instance. If +type has no parent, i.e. is a fundamental type, the +RuntimeError exception is raised. + + + + + gobject.type_is_a + + + gobject.type_is_a + type + parent_type + + + + type : + a GObject type, type ID or +instance + + + parent_type : + a GObject type, type ID or +instance + + + Returns : + TRUE if +parent_type is an ancestor of +type + + + + The gobject.type_is_a() function returns +TRUE if the specified type is a +descendant of the type specified by parent_type. This +function also returns TRUE if +parent_type is an interface and +type conforms to it. + + + + + gobject.type_children + + + gobject.type_children + type + + + + type : + a GObject type, type ID or +instance + + + Returns : + a list of the child types of +type + + + + The gobject.type_children() function +returns a list containing the child types of the specified +type. + + + + + gobject.type_interfaces + + + gobject.type_interfaces + type + + + + type : + a GObject type, type ID or +instance + + + Returns : + a list of the interface types supported by +type + + + + The gobject.type_interfaces() function +returns a list of the interface types supported by +type. type 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. + + + + + gobject.type_register + + + gobject.type_register + class + + + + class : + a Python class that is a descendant of gobject.GObject + + + + The gobject.type_register() function +registers the specified Python class as a PyGTK type. +class must be a descendant of gobject.GObject. The function generates a name for the new type. + + + + + gobject.signal_new + + + gobject.signal_new + signal_name + type + flags + return_type + param_types + + + + signal_name : + a string containing the name of the +signal + + + type : + the object type that the signal is associated +with + + + flags : + the signal flags + + + return_type : + the return type of the signal +handler + + + param_types : + the parameter types passed to the signal +handler + + + Returns : + a unique integer signal ID + + + + The gobject.signal_new() function registers +a signal with the specified signal_name for the +specified object type. The value of +flags is a combination of: + + + + gobject.SIGNAL_RUN_FIRST + + Invoke the object method handler in the first emission +stage. + + + + gobject.SIGNAL_RUN_LAST + + Invoke the object method handler in the third emission +stage. + + + + gobject.SIGNAL_RUN_CLEANUP + + Invoke the object method handler in the last emission +stage. + + + + gobject.SIGNAL_NO_RECURSE + + 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. + + + + gobject.SIGNAL_DETAILED + + This signal supports "::detail" appendixes to the +signal name upon handler connections and emissions. + + + + gobject.SIGNAL_ACTION + + Action signals are signals that may freely be emitted +on alive objects from user code via gobject.emit()() +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. + + + + gobject.SIGNAL_NO_HOOKS + + No emissions hooks are supported for this +signal. + + + + + return_type is the type of the return +value from a signal handler and may be a gobject type, type ID or instance. +The param_types 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: + + + gobject.signal_new("my_signal", gtk.Window, gobject.SIGNAL_RUN_LAST, gobject.TYPE_BOOLEAN, (gtk.Button, gobject.TYPE_INT)) + + + + + + gobject.signal_list_names + + + gobject.signal_list_names + type + + + + type : + a GObject type, type ID or +instance + + + Returns : + a list of the signal names supported by +type + + + + The gobject.signal_list_names() function +returns a list of the names of the signals that are supported by the +specified GObject type + + + The type keyword is available in PyGTK 2.6 and above. + + + + + + gobject.signal_list_ids + + + gobject.signal_list_ids + type + + + + type : + a GObject type, type ID or +instance + + + Returns : + a list of the signal ids supported by +type + + + + + This method is available in PyGTK 2.6 and above. + + + The gobject.signal_list_ids() function +returns a list of the integer ids of the signals that are supported by the +GObject specified by type + + + + + gobject.signal_lookup + + + gobject.signal_lookup + name + type + + + + name : + the name of a signal for +type + + + type : + a GObject type, type ID or +instance + + + Returns : + the integer id of a signal supported by +type or 0. + + + + + This method is available in PyGTK 2.6 and above. + + + The gobject.signal_lookup() function +returns the id of the signal with the name specified by +name that is supported by the GObject specified +specified bytype. 0 is returned if the signal is not +found. + + + + + gobject.signal_name + + + gobject.signal_name + signal_id + + + + signal_id : + an integer signal id + + + Returns : + the name of the signal or +None. + + + + + This method is available in PyGTK 2.6 and above. + + + The gobject.signal_name() function returns +the name of the signal that has the signal id specified by +id. + + + + + gobject.signal_query + + + gobject.signal_query + name + type + + + + name : + the name of a signal for +type + + + type : + a GObject type, type ID or +instance + + + Returns : + a 6-tuple containing signal information or +None + + + + + This method is available in PyGTK 2.6 and above. + + + The gobject.signal_query() function returns +a 6-tuple containing information about the signal with the name specified by +name that is supported by the GObject specified by +type. If the signal is not found +None is returned. + + The signal information 6-tuple contains: + + + + the integer signal id + + + the signal name + + + the GType that the signal is registered for + + + the signal flags (see the ) + + + the GType of the return from the signal callback +function + + + 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 PyGTK signal callback parameters. + + + + + + + gobject.signal_query + + + gobject.signal_query + signal_id + + + + signal_id : + the integer id of a signal + + + Returns : + a 6-tuple containing signal information or +None + + + + + This method is available in PyGTK 2.6 and above. + + + The gobject.signal_query() function returns +a 6-tuple containing information about the signal with the id specified by +signal_id. If the signal is not found +None is returned. + + The signal information 6-tuple contains: + + + + the integer signal id + + + the signal name + + + the GType that the signal is registered for + + + the signal flags (see the ) + + + the GType of the return from the signal callback +function + + + 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 PyGTK signal callback parameters. + + + + + + + gobject.list_properties + + + gobject.list_properties + type + + + + type : + a GObject type, type ID or +instance + + + Returns : + a list of the properties (as GParam objects) +supported by type + + + + The gobject.list_properties() function +returns a list of the properties (as GParam objects) supported by +type. + + + + + gobject.new + + + gobject.new + type + ... + + + + type : + a GObject type, type ID or +instance + + + ... : + zero or more property-value +pairs + + + Returns : + a new object if the specified +type + + + + The gobject.new() function returns a new +object of the specified type. type must specify a +type that is a descendant of gobject.GObject. A +TypeError exception is raised if type specifies an +abstract class or a type that is not a descendant of gobject.GObject. A set +of property-value pairs may be specified to set the value of the object's +properties. + + + + + gobject.idle_add + + + gobject.idle_add + callback + ... + + + + callback : + a function to call when +PyGTK is idle + + + ... : + optionals arguments to be passed to +callback + + + Returns : + an integer ID + + + + The gobject.idle_add() function adds a +function (specified by callback) to be called +whenever there are no higher priority events pending to the default main +loop. The function is given the default idle priority, +gobject.PRIORITY_DEFAULT_IDLE. Additional arguments to +pass to callback can be specified after +callback. The idle priority can be specified as a +keyword-value pair with the keyword "priority". If +callback returns FALSE it is +automatically removed from the list of event sources and will not be called +again. + + + + + gobject.timeout_add + + + gobject.timeout_add + interval + callback + ... + + + + interval : + the time between calls to the function, in +milliseconds + + + callback : + the function to call + + + ... : + zero or more arguments that will be passed to +callback + + + Returns : + an integer ID of the event +source + + + + The gobject.timeout_add() function sets a +function (specified by callback) to be called at +regular intervals (specified by interval, with the +default priority, gobject.PRIORITY_DEFAULT. Additional +arguments to pass to callback can be specified after +callback. The idle priority may be specified as a +keyword-value pair with the keyword "priority". + + The function is called repeatedly until it returns +FALSE, 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). + + + + + gobject.io_add_watch + + + gobject.io_add_watch + fd + condition + callback + ... + + + + fd : + a Python file object or an integer file +descriptor ID + + + condition : + a condition mask + + + callback : + a function to call + + + ... : + additional arguments to pass to +callback + + + Returns : + an integer ID of the event source + + + + The gobject.io_add_watch() function +arranges for the file (specified by fd) to be +monitored by the main loop for the specified +condition. fd may be a Python +file object or an integer file descriptor. The value of condition is a +combination of: + + + + gobject.IO_IN + + There is data to read. + + + + gobject.IO_OUT + + Data can be written (without blocking). + + + + gobject.IO_PRI + + There is urgent data to read. + + + + gobject.IO_ERR + + Error condition. + + + + gobject.IO_HUP + + Hung up (the connection has been broken, usually for +pipes and sockets). + + + + + Additional arguments to pass to callback +can be specified after callback. The idle priority +may be specified as a keyword-value pair with the keyword "priority". The +signature of the callback function is: + + + def callback(source, cb_condition, ...) + + + where source is +fd, the file descriptor; +cb_condition is the condition that triggered the +signal; and, ... are the zero or more arguments that +were passed to the gobject.io_add_watch() +function. + + If the callback function returns FALSE it +will be automatically removed from the list of event sources and will not be +called again. If it returns TRUE it will be called again +when the condition is matched. + + + + + gobject.source_remove + + + gobject.source_remove + tag + + + + tag : + an integer ID + + + Returns : + TRUE if the event source was +removed + + + + The gobject.source_remove() function +removes the event source specified by tag (as returned by the gobject.idle_add(), +gobject.timeout_add() +and gobject.io_add_watch() +functions) + + + + + gobject.main_context_default + + + gobject.main_context_default + + + + + Returns : + the default gobject.MainContext +object + + + + The gobject.main_context_default() function +returns the default gobject.MainContext object. + + + + + gobject.markup_escape_text + + + gobject.markup_escape_text + text + + + + text : + the UTF-8 string to be +escaped + + + Returns : + the escaped text + + + + + This function is available in PyGTK 2.8 and above. + + + The gobject.markup_escape_text() function +escapes the string specified by text 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. + + 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. + + + + + gobject.child_watch_add + + + gobject.child_watch_add + pid + function + dataNone + prioritygobject.PRIORITY_DEFAULT + + + + pid : + process id of a child process to watch + + function : + the function to call + + + data : + the optional data to pass to +function + + + priority : + the priority of the idle source - one of the + + + + Returns : + the id of event source. + + + + This function is available in PyGTK 2.6 and above. + + + The gobject.child_watch_add() function sets +the function specified by function to be called with +the user data specified by data when the child +indicated by pid exits. The signature for the +callback is: + + +def callback(pid, condition, user_data) + + + where pid is is the child process id, +condition is the status information about the child +process and user_data is data +PyGTK supports only a single callback per process id. + + + + + gobject.spawn_async + + + gobject.spawn_async + argv + envpNone + working_directoryNone + flags0 + child_setupNone + user_dataNone + standard_inputNone + standard_outputNone + standard_errorNone + + + + argv : + a sequence of strings containing the arguments +of the child process + + + envp : + the child's environment or +None to inherit the parent's +environment. + + + working_directory : + the child's current working directory, or +None to inherit parent's + + + flags : + flags from the . + + + child_setup : + a function to run in the child just before +calling exec() + + + user_data : + the user data for the +child_setup function + + + standard_input : + if TRUE return the file +descriptor for the child's stdin + + + standard_output : + if TRUE return the file +descriptor for the child's stdout + + + standard_error : + if TRUE return the file +descriptor for the child's stderr + + + Returns : + a 4-tuple containing the child's process id and +the stdin, stdout and stderr file descriptor integers. + + + + This function is available in PyGTK 2.6 and above. + + + The gobject.spawn_async() 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, argv. argv +should be a sequence of strings, to be passed as the argument vector for the +child. The first string in argv is of course the name +of the program to execute. By default, the name of the program must be a +full path; the PATH shell variable will only be searched if +you pass the gobject.SPAWN_SEARCH_PATH flag in +flags. 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 standard_input, +standard_output or +standard_error params are +TRUE. + + On Windows, the low-level child process creation API +(CreateProcess()) doesn't use argument vectors, but a +command line. The C runtime library's spawn*() family +of functions (which gobject.spawn_async() +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 +main(). Complications arise when you have argument +vector elements that contain spaces of double quotes. The +spawn*() 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 gobject.spawn_async() +function will do quoting and escaping on argument vector elements that need +it before calling the C runtime spawn() +function. + + envp is a sequence of strings, where each + string has the form KEY=VALUE. This will become the + child's environment. If envp is + None or not specified, the child inherits its + parent's environment. + + flags should be the bitwise +OR of the you want to affect the +function's behaviour. The gobject.SPAWN_DO_NOT_REAP_CHILD +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 +waitpid() or handling the SIGCHLD +signal manually. On Windows, calling g_spawn_close_pid() is equivalent to +calling CloseHandle() on the process handle +returned). + + gobject.SPAWN_LEAVE_DESCRIPTORS_OPEN 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 exec() in the +child. gobject.SPAWN_SEARCH_PATH means that +argv[0] need not be an absolute path, it will be +looked for in the user's +PATH. gobject.SPAWN_STDOUT_TO_DEV_NULL +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, +standard_output must be +None. gobject.SPAWN_STDERR_TO_DEV_NULL +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, +standard_error must be +None. gobject.SPAWN_CHILD_INHERITS_STDIN +means that the child will inherit the parent's standard input (by default, +the child's standard input is attached to +/dev/null). If you use this flag, +standard_input must be +None. gobject.SPAWN_FILE_AND_ARGV_ZERO +means that the first element of argv is the file to +execute, while the remaining elements are the actual argument vector to pass +to the file. Normally the gobject.spawn_async() +function uses argv[0] as the file to execute, and +passes all of argv to the child. + + child_setup and +user_data 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 exec(). That is, +child_setup is called just before calling +exec() in the child. Obviously actions taken in this +function will only affect the child, not the parent. On Windows, there is no +separate fork() and exec() +functionality. Child processes are created and run right away with one API +call, +CreateProcess(). child_setup is +called in the parent process just before creating the child process. You +should carefully consider what you do in child_setup +if you intend your software to be portable to Windows. + + The returned child process id can be used to send signals to the +child, or to wait for the child if you specified the +gobject.SPAWN_DO_NOT_REAP_CHILD flag. On Windows, child +pid will be returned only if you specified the +gobject.SPAWN_DO_NOT_REAP_CHILD flag. + + The caller of the gobject.spawn_async() +must close any returned file descriptors when they are no longer in +use. + + If standard_input is +None, the child's standard input is attached to +/dev/null unless +gobject.SPAWN_CHILD_INHERITS_STDIN is set. + + If standard_error is +None, the child's standard error goes to the same +location as the parent's standard error unless +gobject.SPAWN_STDERR_TO_DEV_NULL is set. + + If standard_output is +None, the child's standard output goes to the same +location as the parent's standard output unless +gobject.SPAWN_STDOUT_TO_DEV_NULL is set. + + If an error occurs, the gobject.GError exception will be +raised. + + + + + gobject.get_current_time + + + gobject.get_current_time + + + + Returns : + the current time as the number of seconds and +microseconds from the epoch. + + + + This function is available in PyGTK 2.8 and above. + + + The gobject.get_current_time() function +reurns the current time of day as the number of seconds and microseconds +from the epoch. + + + + + gobject.main_depth + + + gobject.main_depth + + + + Returns : + he depth of the stack of calls to the main +context. + + + + This function is available in PyGTK 2.8 and above. + + + The main_depth() 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 gobject.MainContext.iteration() +method (or the gobject.MainLoop.run() +method, etc.) it returns 1. When called from within a callback to a +recursive call to the gobject.MainContext.iteration() +method), it returns 2. And so forth. + + + + + + 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 @@ + + + + + + gobject.GBoxed + an object containing an opaque chunk of data + + + + Synopsis + + + gobject.GBoxed + + copy + + + + + + + Ancestry + ++-- gobject.GBoxed + + + + + + Description + + gobject.GBoxed +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 +GLIB 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. + + + + + Methods + + + gobject.GBoxed.copy + + + copy + + + + Returns : + a copy of the gobject.GBoxed + object + + + + The copy() method makes and returns a copy of the boxed object. + + + + + + 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 @@ + + + + + + gobject.GInterface + + an object representing a GInterface + + + + Synopsis + + + gobject.GInterface + + + + + + Ancestry + ++-- gobject.GInterface + + + + + + Description + + gobject.GInterface +is an abstract base class that encapsulates a GInterface. + + + + 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 @@ + + + + + + gobject.GPointer + + an object containing a completely opaque chunk of + data + + + + Synopsis + + + gobject.GPointer + + + + + + Ancestry + ++-- gobject.GPointer + + + + + + Description + + gobject.GPointer +is an abstract base class that encapsulates an opaque chunk of data and +registers it with the GLIB type system. A pointer type +has no methods and generic ways of copying and freeing the data. It +shouldn't be used in PyGTK. + + + + 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 @@ + + + + + + gobject.MainContext + + an object representing a set of event sources to be handled +in a gobject.MainLoop. + + + + Synopsis + + + gobject.MainContext + + gobject.MainContext + + + iteration + may_block + + + pending + + + + + + + Ancestry + ++-- gobject.MainContext + + + + + + Description + + A gobject.MainContext +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 GTK and PyGTK though +others can be added. Each event source is assigned a priority. The default +priority, gobject.PRIORITY_DEFAULT, 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 gobject.MainContext +can be run with the iteration() +method. + + + + + Constructor + + + gobject.MainContext + + + + Returns : + a new gobject.MainContext + object. + + + + Creates a new gobject.MainContext +object. + + + + + Methods + + + gobject.MainContext.iteration + + + iteration + + + + may_block : + if TRUE the call may block + waiting for an event. + + + Returns : + TRUE if events were + dispatched. + + + + The iteration() method runs a single +iteration. This involves: + + + + checking to see if any associated event sources are ready +to be processed; + + + then if no events sources are ready and +may_block is TRUE, waiting for a +source to become ready; + + + and finally, dispatching the highest priority events +sources that are ready + + + + Note that even when may_block is +TRUE, it is still possible for +iteration() to return FALSE, +since the the wait may be interrupted for other reasons than an event source +becoming ready. + + + + + gobject.MainContext.pending + + + pending + + + + Returns : + TRUE if events are + pending. + + + + The pending() method checks if any +associated sources have pending events. + + + + + + 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 @@ + + + + + + gobject.MainLoop + + an object representing the main event loop of a PyGTK + application. + + + + Synopsis + + + gobject.MainLoop + + gobject.MainLoop + contextNone + is_running0 + + + get_context + + + is_running + + + quit + + + run + + + + + + + Ancestry + ++-- gobject.MainLoop + + + + + + Description + + gobject.MainLoop +represents a main event loop. A gobject.MainLoop +is created with the gobject.MainLoop() +constructor. After adding the initial event sources, the run() +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 quit() +method to exit the main loop, and the run() +method returns. + + It is possible to create new instances of gobject.MainLoop +recursively. This is often used in PyGTK applications +when showing modal dialog boxes. Note that event sources are associated with +a particular gobject.MainContext, +and will be checked and dispatched for all main loops associated with that +gobject.MainContext. + + PyGTK contains wrappers of some of these +functions, e.g. the gtk.main(), gtk.main_quit() +and gtk.events_pending() +functions. + + + + + Constructor + + + gobject.MainLoop + contextNone + is_runningNone + + + + context : + a gobject.MainContext + or None to use the default + context. + + + is_running : + if TRUE indicates that the + loop is running. This is not very important since calling the run() + method will set this to TRUE + anyway. + + + Returns : + a new gobject.MainLoop + object. + + + + Creates a new gobject.MainLoop +object. + + + + + Methods + + + gobject.MainLoop.get_context + + + get_context + + + + Returns : + the gobject.MainContext + the mainloop is associated with + + + + The get_context() method returns the +gobject.MainContext +that the mainloop was created with. + + + + + gobject.MainLoop.is_running + + + is_running + + + + Returns : + TRUE if the mainloop is + currently being run. + + + + The is_running() method checks to see +if the mainloop is currently being run via the run() +method. + + + + + gobject.MainLoop.quit + + + quit + + + The quit() method stops the mainloop +from running. Any subsequent calls to the run() +method will return immediately. + + + + + gobject.MainLoop.run + + + run + + + The run() method runs a mainloop until +the quit() +method is called. If this is called for the thread of the loop's gobject.MainContext, +it will process events from the loop, otherwise it will simply wait. + + + + + + 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 @@ + + + + + July 6, 2006 + PyGObject Reference Manual + PyGObject Reference Manual version 2.9.0 for PyGTK 2.9.x + Version 2.9.0 + + + John + Finlay + + + + This reference describes the classes of the python gobject +module. + + + + + + + + + + + + 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 @@ + + + + + gobject.GObject + 3 + PyGTK Docs + + + + gobject.GObject + the base class + + + + Synopsis + + + gobject.GObject + + get_property + property_name + + + set_property + property_name + value + + + freeze_notify + + + notify + property_name + + + thaw_notify + + + get_data + key + + + set_data + key + data + + + connect + detailed_signal + handler + + + connect_after + detailed_signal + handler + + + connect_object + detailed_signal + handler + + + connect_object_after + detailed_signal + handler + + + disconnect + handler_id + + + handler_disconnect + handler_id + + + handler_is_connected + handler_id + + + handler_block + handler_id + + + handler_unblock + handler_id + + + emit + detailed_signal + + + stop_emission + detailed_signal + + + emit_stop_by_name + detailed_signal + + + chain + + + + + + + Ancestry + ++-- gobject.GObject + + + + + + Attributes + +
+ + + + + + + + + + "__doc__" + Read + The documentation for the object type. Uses + "__gdoc__" if no specific documentation set. + + + "__gdoc__" + Read + The generated documentation for the underlying GObject + type. + + + "__gtype__" + Read + The underlying GObject type. + + + "__grefcount__" + Read + The reference count for the underlying GObject. + + + + + +
+ + + + + gobject.GObject Signal Prototypes + + + + + "notify" + + callback + gobject + property_spec + user_param1 + ... + + + + + + + + + Description + The gobject.GObject + class is the base class providing the common attributes and methods for + the PyGTK classes. The gobject.GObject + class is not a user interface widget class. + + The gobject.GObject + class provides the signal management methods, the object property access + methods and the object data management methods. + + + + + Methods + + + gobject.GObject.get_property + + + get_property + property_name + + + + property_name : + a string containing the property name for the +GObject + + + Returns : + a Python object containing the value of the +property + + + + The get_property() method returns the +value of the property specified by property_name or +None if there is no value associated with the property. + The TypeError exception is raised +if the property name is not registered with the object class. + + + + + gobject.GObject.set_property + + + set_property + property_name + value + + + + property_name : + a string containing the property +name + + + value : + a Python object containing the property value +to be set + + + + The set_property() method sets the +property specified by property_name to the specified +value. + The TypeError 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. + + + + + gobject.GObject.freeze_notify + + + freeze_notify + + + + The freeze_notify() method freezes the +object's property-changed notification queue so that "notify" signals are +blocked until the thaw_notify() method is +called. + + + + + gobject.GObject.notify + + + notify + property_name + + + + property_name : + a string containing a property +name + + + + The notify() method causes the "notify" +signal for the property specified by property_name to +be emitted. + + + + + gobject.GObject.thaw_notify + + + thaw_notify + + + + The thaw_notify() method thaws the +object's property-changed notification queue so that "notify" signals are +emitted. + + + + + gobject.GObject.get_data + + + get_data + key + + + + key : + a string used as the key + + + Returns : + a Python object containing the associated +data + + + + The get_data() method returns the +Python object associated with the specified key or +None if there is no data associated with the key or +if there is no key associated with the object. + + + + + gobject.GObject.set_data + + + set_data + key + data + + + + key : + a string used as a key + + + data : + a Python object that is the value to be +associated with the key + + + + The set_data() method associates the +specified Python object (data) with +key. + + + + + gobject.GObject.connect + + + connect + detailed_signal + handler + ... + + + + detailed_signal : + a string containing the signal +name + + + handler : + a Python function or method +object. + + + ... : + additional optional +parameters + + + Returns : + an integer identifier + + + + The connect() method adds a function or +method (handler)to the end of the list of signal +handlers for the named detailed_signal but before the +default class signal handler. An optional set of parameters may be specified +after the handler parameter. These will all be passed +to the signal handler when invoked. + For example if a function handler was connected to a signal +using: + + handler_id = object.connect("signal_name", handler, arg1, arg2, arg3) + + The handler should be defined as: + + def handler(object, arg1, arg2, arg3): + + A method handler connected to a signal using: + + handler_id = object.connect("signal_name", self.handler, arg1, arg2) + + requires an additional argument when defined: + + def handler(self, object, arg1, arg2) + + A TypeError exception is raised +if detailed_signal identifies a signal name that is +not associated with the object. + + + + + gobject.GObject.connect_after + + + connect_after + detailed_signal + handler + ... + + + + detailed_signal : + a string containing the signal +name + + + handler : + a Python function or method +object + + + ... : + additional optional +parameters + + + Returns : + an integer handler +identifier + + + + The connect_after() method is similar +to the connect() method except that the +handler is added to the signal handler list after the +default class signal handler. Otherwise the details of +handler definition and invocation are the +same. + + + + + gobject.GObject.connect_object + + + connect_object + detailed_signal + handler + gobject + + + + detailed_signal : + a string containing the signal +name + + + handler : + a Python function or method +object + + + gobject : + a GObject + + + Returns : + an integer handler +identifier + + + + The connect_object() method is the same +as the connect() method except that the +handler is invoked with the specified +gobject in place of the object invoking the +connect_object() method. For example, a call with a +function handler: + + handler_id = object("signal_name", handler, gobject) + + will cause the handler to be invoked +as: + + handler(gobject) + + Likewise a method handler will be invoked as: + + self.handler(gobject) + + This can be helpful in invoking PyGTK widget methods that +require no arguments except the widget itself (e.g. +widget.destroy()) by using the class method as the +handler. For example, a Button "clicked" signal can be set up to invoke the +Window destroy() method as: + + + handler_id = button.connect_object("clicked", Window.destroy, window) + + + When the button is clicked the handler is invoked as: + + + Window.destroy(window) + + + which is the same as: + + + window.destroy() + + + Additional arguments may be passed to the handler as with the +connect() method handler invocations. + + + + + gobject.GObject.connect_object_after + + + connect_object_after + detailed_signal + handler + + + + detailed_signal : + a string containing the signal +name + + + handler : + a Python function or method +object + + + gobject : + a GObject + + + Returns : + an integer handler +identifier + + + + The connect_object_after() method is +similar to the connect_object() method except that +the handler is added to the signal handler list after +the default class signal handler. Otherwise the details of +handler definition and invocation are the +same. + + + + + gobject.GObject.disconnect + + + disconnect + handler_id + + + + handler_id : + an integer handler +identifier + + + + The disconnect() method removes the +signal handler with the specified handler_id from the +list of signal handlers for the object. + + + + + gobject.GObject.handler_disconnect + + + handler_disconnect + handler_id + + + + handler_id : + an integer handler +identifier + + + + The handler_disconnect() method removes +the signal handler with the specified handler_id from +the list of signal handlers for the object. + + + + + gobject.GObject.handler_is_connected + + + handler_is_connected + handler_id + + + + handler_id : + an integer handler +identifier + + + Returns : + TRUE if the signal handler +is connected to the object. + + + + The handler_is_connected() method +returns TRUE if the signal handler with the specified +handler_id is connected to the object. + + + + + gobject.GObject.handler_block + + + handler_block + handler_id + + + + handler_id : + an integer handler +identifier + + + + The handler_block() method blocks the +signal handler with the specified handler_id from +being invoked until it is unblocked. + + + + + gobject.GObject.handler_unblock + + + handler_unblock + handler_id + + + + handler_id : + an integer handler +identifier + + + + The handler_unblock() method unblocks +the signal handler with the specified handler_id +thereby allowing it to be invoked when the associated signal is +emitted. + + + + + gobject.GObject.emit + + + emit + detailed_signal + ... + + + + detailed_signal : + a string containing the signal +name + + + ... : + additional parameters + + + Returns : + a PyObject* + + + The emit() method causes the object to +emit the signal specified by detailed_signal. 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: + + button.emit("clicked") + + 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: + + button.emit("button_press_event", event) + + + + + + gobject.GObject.stop_emission + + + stop_emission + detailed_signal + + + + detailed_signal : + a string containing the signal +name + + + + The stop_emission() method stops the +current emission of the signal specified by +detailed_signal. Any signal handlers in the list +still to be run will not be invoked. + + + + + gobject.GObject.emit_stop_by_name + + + emit_stop_by_name + detailed_signal + + + + detailed_signal : + a string containing the signal +name + + + + The emit_stop_by_name() method stops +the current emission of the signal specified by +detailed_signal. Any signal handlers in the list +still to be run will not be invoked. + + + + + gobject.GObject.chain + + + chain + ... + + + + ... : + additional parameters + + + Returns : + a Python object + + + + The chain() method does something. + + + + + + + Signals + + + The GObject "notify" Signal + + + callback + gobject + property_spec + user_param1 + ... + + + + + gobject : + the gobject that received the +signal + + + property_spec : + the gobject.GParamSpec of the property that was +changed + + + user_param1 : + the first user parameter (if any) specified +with the connect() +method + + + ... : + additional user parameters (if +any) + + + + 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 gtk.Window you could +connect to the "notify" signal similar to: + + + window.connect("notify::title", callback) + + + + + + + -- cgit