From 0b6932cf263ac3dc68640e3f59e0d83678315aea Mon Sep 17 00:00:00 2001 From: Johan Dahlin Date: Fri, 1 Aug 2008 22:52:06 +0000 Subject: Separate the glib and gobject bindings in the manual. 2008-08-02 Johan Dahlin * docs/Makefile.am: * docs/reference/pyglib-constants.xml: * docs/reference/pyglib-functions.xml: * docs/reference/pyglib-maincontext.xml: * docs/reference/pyglib-mainloop.xml: * docs/reference/pygobject-classes.xml: * docs/reference/pygobject-constants.xml: * docs/reference/pygobject-functions.xml: * docs/reference/pygobject-maincontext.xml: * docs/reference/pygobject-mainloop.xml: Separate the glib and gobject bindings in the manual. svn path=/trunk/; revision=910 --- docs/reference/pyglib-constants.xml | 222 ++++++++ docs/reference/pyglib-functions.xml | 834 +++++++++++++++++++++++++++++++ docs/reference/pyglib-maincontext.xml | 152 ++++++ docs/reference/pyglib-mainloop.xml | 202 ++++++++ docs/reference/pygobject-classes.xml | 11 +- docs/reference/pygobject-constants.xml | 105 ---- docs/reference/pygobject-functions.xml | 763 +--------------------------- docs/reference/pygobject-maincontext.xml | 152 ------ docs/reference/pygobject-mainloop.xml | 202 -------- 9 files changed, 1419 insertions(+), 1224 deletions(-) create mode 100644 docs/reference/pyglib-constants.xml create mode 100644 docs/reference/pyglib-functions.xml create mode 100644 docs/reference/pyglib-maincontext.xml create mode 100644 docs/reference/pyglib-mainloop.xml delete mode 100644 docs/reference/pygobject-maincontext.xml delete mode 100644 docs/reference/pygobject-mainloop.xml (limited to 'docs/reference') diff --git a/docs/reference/pyglib-constants.xml b/docs/reference/pyglib-constants.xml new file mode 100644 index 0000000..a879171 --- /dev/null +++ b/docs/reference/pyglib-constants.xml @@ -0,0 +1,222 @@ + + + + + + glib Constants + the built-in constants of the glib module + + + + Synopsis + + + + + + + + + + + + Description + + + Glib IO Condition Constants + + The IO Condition constants are a set of bit-flags that specify a +condition to watch for on an event source. + + + + glib.IO_IN + + There is data to read + + + + glib.IO_OUT + + Data can be written (without blocking). + + + + glib.IO_PRI + + There is urgent data to read. + + + + glib.IO_ERR + + Error condition. + + + + glib.IO_HUP + + Hung up (the connection has been broken, usually for + pipes and sockets). + + + + glib.IO_NVAL + + Invalid request. The file descriptor is not + open. + + + + + + + + Glib Priority Constants + + The Priority constants specify + + + + glib.PRIORITY_HIGH + + Use this for high priority event sources. + + + + glib.PRIORITY_DEFAULT + + Use this for default priority event sources. This + priority is used when adding timeout functions with the glib.timeout_add() + function. This priority is also used for events from the X + server. + + + + glib.PRIORITY_HIGH_IDLE + + Use this for high priority idle functions. For example, + glib.PRIORITY_HIGH_IDLE + 10 is used for resizing operations; + and, glib.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.) + + + + glib.PRIORITY_DEFAULT_IDLE + + Use this for default priority idle functions. This + priority is used when adding idle functions with the glib.idle_add() + function. + + + + glib.PRIORITY_LOW + + Use this for very low priority background + tasks. + + + + + + + + Glib Spawn Flag Constants + + The Spawn Flag constants are a set of bit-flags that can be +passed to the glib.spawn_async() +function. + + + + glib.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. + + + + glib.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. + + + + glib.SPAWN_SEARCH_PATH + + argv[0] need not be an absolute +path, it will be looked for in the user's PATH. + + + + glib.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. + + + + glib.SPAWN_STDERR_TO_DEV_NULL + + the child's standard error will be discarded. + + + + glib.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). + + + + glib.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 glib.spawn_async() +uses argv[0] as the file to execute, and passes all +of argv to the child. + + + + + + + + Glib Version Constants + The Version constants specify the version of +Glib used by PyGObject as a 3-tuple containing the major, +minor and patch release numbers. + + + + glib.glib_version + + A 3-tuple containing (major, minor, patch) release + numbers of glib. + + + + glib.pyglib_version + + A 3-tuple containing (major, minor, patch) release + numbers of the python bindings. + + + + + + + + + diff --git a/docs/reference/pyglib-functions.xml b/docs/reference/pyglib-functions.xml new file mode 100644 index 0000000..3464a80 --- /dev/null +++ b/docs/reference/pyglib-functions.xml @@ -0,0 +1,834 @@ + + + + + + glib Functions + miscellaneous functions + + + + Synopsis + + + + glib.idle_add + callback + ... + + glib.timeout_add + interval + callback + ... + + glib.io_add_watch + fd + condition + callback + ... + + glib.source_remove + tag + + glib.main_context_default + + + glib.markup_escape_text + text + + glib.child_watch_add + pid + function + dataNone + priorityglib.PRIORITY_DEFAULT + + glib.spawn_async + argv + envpNone + working_directoryNone + flags0 + child_setupNone + user_dataNone + standard_inputNone + standard_outputNone + standard_errorNone + + glib.get_current_time + + glib.main_depth + + glib.threads_init + + glib.filename_display_name + filename + + glib.filename_display_basename + filename + + glib.filename_from_utf8 + utf8string + + + + + + Description + + These functions are part of the PyGObject glib +module but are not directly associated with a specific class. + + + + + Functions + + + glib.idle_add + + + glib.idle_add + callback + ... + + + + callback : + a function to call when +PyGTK is idle + + + ... : + optionals arguments to be passed to +callback + + + Returns : + an integer ID + + + + The glib.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, +glib.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. + + + + + glib.timeout_add + + + glib.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 glib.timeout_add() function sets a +function (specified by callback) to be called at +regular intervals (specified by interval, with the +default priority, glib.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). + + + + + glib.io_add_watch + + + glib.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 glib.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: + + + + glib.IO_IN + + There is data to read. + + + + glib.IO_OUT + + Data can be written (without blocking). + + + + glib.IO_PRI + + There is urgent data to read. + + + + glib.IO_ERR + + Error condition. + + + + glib.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 glib.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. + + + + + glib.source_remove + + + glib.source_remove + tag + + + + tag : + an integer ID + + + Returns : + TRUE if the event source was +removed + + + + The glib.source_remove() function +removes the event source specified by tag (as returned by the glib.idle_add(), +glib.timeout_add() +and glib.io_add_watch() +functions) + + + + + glib.main_context_default + + + glib.main_context_default + + + + + Returns : + the default glib.MainContext +object + + + + The glib.main_context_default() function +returns the default glib.MainContext object. + + + + + glib.markup_escape_text + + + glib.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 glib.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. + + + + + glib.child_watch_add + + + glib.child_watch_add + pid + function + dataNone + priorityglib.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 glib.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. + + + + + glib.spawn_async + + + glib.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 glib.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 glib.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 glib.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 glib.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 glib.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). + + glib.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. glib.SPAWN_SEARCH_PATH means that +argv[0] need not be an absolute path, it will be +looked for in the user's +PATH. glib.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. glib.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. glib.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. glib.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 glib.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 +glib.SPAWN_DO_NOT_REAP_CHILD flag. On Windows, child +pid will be returned only if you specified the +glib.SPAWN_DO_NOT_REAP_CHILD flag. + + The caller of the glib.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 +glib.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 +glib.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 +glib.SPAWN_STDOUT_TO_DEV_NULL is set. + + If an error occurs, the glib.GError exception will be +raised. + + + + + glib.get_current_time + + + glib.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 glib.get_current_time() function +reurns the current time of day as the number of seconds and microseconds +from the epoch. + + + + + glib.main_depth + + + glib.main_depth + + + + Returns : + the 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 glib.MainContext.iteration() +method (or the glib.MainLoop.run() +method, etc.) it returns 1. When called from within a callback to a +recursive call to the glib.MainContext.iteration() +method), it returns 2. And so forth. + + + + + glib.threads_init + + + glib.threads_init + + + + + Returns : + + + + + This function is available in PyGTK 2.4 and above. + + + The threads_init() function initializes the + the use of Python threading in the glib module. This function is + different than the gtk.gdk.threads_init() + function as that function also initializes the gdk threads. + + + + + glib.signal_accumulator_true_handled + + + glib.signal_accumulator_true_handled + + + + This function is available in PyGTK 2.8 and above. + + + The signal_accumulator_true_handled() + function is only used as accumulator argument when registering + signals. + + + + + glib.filename_display_name + + + glib.filename_display_name + filename + + + + filename : + a pathname in the file name + encoding + + + Returns : + an UTF8 rendition of + filename. + + + + This function is available in PyGTK 2.10 and above. + + + The filename_display_name() function + converts a filename into a valid UTF-8 string. The conversion is not + necessarily reversible, so you should keep the original around and use + the return value of this function only for display purposes. Unlike + g_filename_to_utf8(), the result is guaranteed to be non-None even if + the filename actually isn't in the file name encoding. + + If you know the whole pathname of the file you should use the + glib.filename_display_basename() + function, since that allows location-based translation of + filenames. + + + + + glib.filename_display_basename + + + glib.filename_display_basename + filename + + + + filename : + an absolute pathname in the file name + encoding + + + Returns : + an UTF8 rendition of + filename. + + + + This function is available in PyGTK 2.10 and above. + + + The filename_display_basename() function + returns the display basename for the particular filename, guaranteed + to be valid UTF-8. The display name might not be identical to the + filename, for instance there might be problems converting it to UTF-8, + and some files can be translated in the display. + + You must pass the whole absolute pathname to this functions so + that translation of well known locations can be done. + + This function is preferred over the glib.filename_display_name() + function if you know the whole path, as it allows translation. + + + + + glib.filename_from_utf8 + + + glib.filename_from_utf8 + utf8string + + + + utf8string : + a UTF-8 encoded string. + + + Returns : + a filename encoded in the GLib filename + encoding. + + + + This function is available in PyGTK 2.10 and above. + + + The filename_from_utf8() function converts + a string from UTF-8 to the encoding GLib uses for filenames. Note that + on Windows GLib uses UTF-8 for filenames. + + + + + + diff --git a/docs/reference/pyglib-maincontext.xml b/docs/reference/pyglib-maincontext.xml new file mode 100644 index 0000000..ccb91bb --- /dev/null +++ b/docs/reference/pyglib-maincontext.xml @@ -0,0 +1,152 @@ + + + + + + glib.MainContext + + an object representing a set of event sources to be handled +in a glib.MainLoop. + + + + Synopsis + + + glib.MainContext + + glib.MainContext + + + iteration + may_block + + + pending + + + + + + + Ancestry + ++-- glib.MainContext + + + + + + Description + + A glib.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, glib.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 glib.MainContext +can be run with the iteration() +method. + + + + + Constructor + + + glib.MainContext + + + + Returns : + a new glib.MainContext + object. + + + + Creates a new glib.MainContext +object. + + + + + Methods + + + glib.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. + + + + + glib.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/pyglib-mainloop.xml b/docs/reference/pyglib-mainloop.xml new file mode 100644 index 0000000..bd12fca --- /dev/null +++ b/docs/reference/pyglib-mainloop.xml @@ -0,0 +1,202 @@ + + + + + + glib.MainLoop + + an object representing the main event loop of a PyGTK + application. + + + + Synopsis + + + glib.MainLoop + + glib.MainLoop + contextNone + is_running0 + + + get_context + + + is_running + + + quit + + + run + + + + + + + Ancestry + ++-- glib.MainLoop + + + + + + Description + + glib.MainLoop +represents a main event loop. A glib.MainLoop +is created with the glib.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 glib.MainLoop +recursively. This is often used in PyGTK applications +when showing modal dialog boxes. Note that event sources are associated with +a particular glib.MainContext, +and will be checked and dispatched for all main loops associated with that +glib.MainContext. + + PyGTK contains wrappers of some of these +functions, e.g. the gtk.main(), gtk.main_quit() +and gtk.events_pending() +functions. + + + + + Constructor + + + glib.MainLoop + contextNone + is_runningNone + + + + context : + a glib.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 glib.MainLoop + object. + + + + Creates a new glib.MainLoop +object. + + + + + Methods + + + glib.MainLoop.get_context + + + get_context + + + + Returns : + the glib.MainContext + the mainloop is associated with + + + + The get_context() method returns the +glib.MainContext +that the mainloop was created with. + + + + + glib.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. + + + + + glib.MainLoop.quit + + + quit + + + The quit() method stops the mainloop +from running. Any subsequent calls to the run() +method will return immediately. + + + + + glib.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 glib.MainContext, +it will process events from the loop, otherwise it will simply wait. + + + + + + diff --git a/docs/reference/pygobject-classes.xml b/docs/reference/pygobject-classes.xml index e4b488f..710e4b7 100644 --- a/docs/reference/pygobject-classes.xml +++ b/docs/reference/pygobject-classes.xml @@ -4,16 +4,19 @@ -The gobject Class Reference +PyGObject Class Reference - + + + + + + - - diff --git a/docs/reference/pygobject-constants.xml b/docs/reference/pygobject-constants.xml index 894c8ae..a8f9711 100644 --- a/docs/reference/pygobject-constants.xml +++ b/docs/reference/pygobject-constants.xml @@ -12,11 +12,8 @@ Synopsis - - - @@ -26,55 +23,6 @@ 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 @@ -119,59 +67,6 @@ certain aspects of parameters that can be configured. - - 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 diff --git a/docs/reference/pygobject-functions.xml b/docs/reference/pygobject-functions.xml index c0c6234..a35afec 100644 --- a/docs/reference/pygobject-functions.xml +++ b/docs/reference/pygobject-functions.xml @@ -86,63 +86,6 @@ linkend="function-gobject--new">gobject.new ... 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 - - gobject.threads_init - - gobject.signal_accumulator_true_handled gobject.remove_emission_hookgobject._install_metaclass metaclass - - gobject.filename_display_name - filename - - gobject.filename_display_basename - filename - - gobject.filename_from_utf8 - utf8string - + + @@ -816,593 +748,6 @@ 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 : - the 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. - - - gobject.threads_init @@ -1554,110 +899,6 @@ method), it returns 2. And so forth. - - gobject.filename_display_name - - - gobject.filename_display_name - filename - - - - filename : - a pathname in the file name - encoding - - - Returns : - an UTF8 rendition of - filename. - - - - This function is available in PyGTK 2.10 and above. - - - The filename_display_name() function - converts a filename into a valid UTF-8 string. The conversion is not - necessarily reversible, so you should keep the original around and use - the return value of this function only for display purposes. Unlike - g_filename_to_utf8(), the result is guaranteed to be non-None even if - the filename actually isn't in the file name encoding. - - If you know the whole pathname of the file you should use the - gobject.filename_display_basename() - function, since that allows location-based translation of - filenames. - - - - - gobject.filename_display_basename - - - gobject.filename_display_basename - filename - - - - filename : - an absolute pathname in the file name - encoding - - - Returns : - an UTF8 rendition of - filename. - - - - This function is available in PyGTK 2.10 and above. - - - The filename_display_basename() function - returns the display basename for the particular filename, guaranteed - to be valid UTF-8. The display name might not be identical to the - filename, for instance there might be problems converting it to UTF-8, - and some files can be translated in the display. - - You must pass the whole absolute pathname to this functions so - that translation of well known locations can be done. - - This function is preferred over the gobject.filename_display_name() - function if you know the whole path, as it allows translation. - - - - - gobject.filename_from_utf8 - - - gobject.filename_from_utf8 - utf8string - - - - utf8string : - a UTF-8 encoded string. - - - Returns : - a filename encoded in the GLib filename - encoding. - - - - This function is available in PyGTK 2.10 and above. - - - The filename_from_utf8() function converts - a string from UTF-8 to the encoding GLib uses for filenames. Note that - on Windows GLib uses UTF-8 for filenames. - - - diff --git a/docs/reference/pygobject-maincontext.xml b/docs/reference/pygobject-maincontext.xml deleted file mode 100644 index 129197a..0000000 --- a/docs/reference/pygobject-maincontext.xml +++ /dev/null @@ -1,152 +0,0 @@ - - - - - - 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 deleted file mode 100644 index d90f534..0000000 --- a/docs/reference/pygobject-mainloop.xml +++ /dev/null @@ -1,202 +0,0 @@ - - - - - - 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. - - - - - - -- cgit