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. --- docs/reference/pygobject-functions.xml | 1373 ++++++++++++++++++++++++++++++++ 1 file changed, 1373 insertions(+) create mode 100644 docs/reference/pygobject-functions.xml (limited to 'docs/reference/pygobject-functions.xml') 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. + + + + + + -- cgit