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/pygobject-functions.xml | 763 +-------------------------------- 1 file changed, 2 insertions(+), 761 deletions(-) (limited to 'docs/reference/pygobject-functions.xml') 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. - - - -- cgit