gobject Functions — miscellaneous functions
def gobject.type_name(
type
)def gobject.type_from_name(
type_name
)def gobject.type_parent(
type
)def gobject.type_is_a(
type
,parent_type
)def gobject.type_children(
type
)def gobject.type_interfaces(
type
)def gobject.type_register(
class
)def gobject.signal_new(
signal_name
,type
,flags
,return_type
,param_types
)def gobject.signal_list_names(
type
)def gobject.signal_list_ids(
type
)def gobject.signal_lookup(
name
,type
)def gobject.signal_name(
signal_id
)def gobject.signal_query(
name
,type
)def gobject.signal_query(
signal_id
)def gobject.list_properties(
type
)def gobject.new(
type
,...
)def gobject.idle_add(
callback
,...
)def gobject.timeout_add(
interval
,callback
,...
)def gobject.io_add_watch(
fd
,condition
,callback
,...
)def gobject.source_remove(
tag
)def gobject.main_context_default()
def gobject.markup_escape_text(
text
)def gobject.child_watch_add(
pid
,function
,data
=None,priority
=gobject.PRIORITY_DEFAULT)def gobject.spawn_async(
argv
,envp
=None,working_directory
=None,flags
=0,child_setup
=None,user_data
=None,standard_input
=None,standard_output
=None,standard_error
=None)def gobject.get_current_time()
def gobject.main_depth()
def gobject.threads_init()
def gobject.signal_accumulator_true_handled()
def gobject.add_emission_hook(
type
,name
,callback
,...
)def gobject.remove_emission_hook(
type
,name
,hook_id
)def gobject._install_metaclass(
metaclass
)def gobject.filename_display_name(
filename
)def gobject.filename_display_basename(
filename
)def gobject.filename_from_utf8(
utf8string
)
These functions are part of the PyGTK
gobject
module but are not directly associated with a specific class.
def gobject.type_name(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.
def gobject.type_from_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
.
def gobject.type_parent(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.
def gobject.type_is_a(type
, parent_type
)
| a GObject type, type ID or instance |
| 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.
def gobject.type_children(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
.
def gobject.type_interfaces(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.
def gobject.type_register(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.
def gobject.signal_new(signal_name
, type
, flags
, return_type
, param_types
)
| a string containing the name of the signal |
| the object type that the signal is associated with |
| the signal flags |
| the return type of the signal handler |
| 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:
| Invoke the object method handler in the first emission stage. |
| Invoke the object method handler in the third emission stage. |
| Invoke the object method handler in the last emission stage. |
| 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. |
| This signal supports "::detail" appendixes to the signal name upon handler connections and emissions. |
| 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. |
| 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))
def gobject.signal_list_names(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.
def gobject.signal_list_ids(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
def gobject.signal_lookup(name
, type
)
| the name of a signal for
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.
def gobject.signal_name(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
.
def gobject.signal_query(name
, type
)
| the name of a signal for
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:
PyGTK
signal callback parameters. def gobject.signal_query(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:
PyGTK
signal callback parameters. def gobject.list_properties(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
.
def gobject.new(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.
def gobject.idle_add(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.
def gobject.timeout_add(interval
, callback
, ...
)
| the time between calls to the function, in milliseconds |
| 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).
def gobject.io_add_watch(fd
, condition
, callback
, ...
)
| a Python file object or an integer file descriptor ID |
| a condition mask |
| 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:
| There is data to read. |
| Data can be written (without blocking). |
| There is urgent data to read. |
| Error condition. |
| 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.
def gobject.source_remove(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)
def gobject.main_context_default()
Returns : | the default gobject.MainContext object |
The gobject.main_context_default
() function
returns the default gobject.MainContext object.
def gobject.markup_escape_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.
def gobject.child_watch_add(pid
, function
, data
=None, priority
=gobject.PRIORITY_DEFAULT)
| process id of a child process to watch |
| the function to call |
| the optional data to pass to
function |
| the priority of the idle source - one of the GObject Priority Constants |
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.
def gobject.spawn_async(argv
, envp
=None, working_directory
=None, flags
=0, child_setup
=None, user_data
=None, standard_input
=None, standard_output
=None, standard_error
=None)
| a sequence of strings containing the arguments of the child process |
| the child's environment or
None to inherit the parent's
environment. |
| the child's current working directory, or
None to inherit parent's |
| flags from the GObject Spawn Flag Constants. |
| a function to run in the child just before
calling exec () |
| the user data for the
child_setup function |
| if TRUE return the file
descriptor for the child's stdin |
| if TRUE return the file
descriptor for the child's stdout |
| 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 GObject Spawn Flag Constants 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.
def 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.
def 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.
def gobject.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 gobject module. This function is
different than the gtk.gdk.threads_init
()
def gobject.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.
def gobject.add_emission_hook(type
, name
, callback
, ...
)
type : | a Python GObject instance or type |
name : | a signal name |
callback : | a function |
... : | zero or more extra arguments that will be passed to callback. |
Returns : | the hook id, for later use with gobject.signal_remove_emission_hook () |
This function is available in PyGTK 2.8 and above.
The add_emission_hook
() function adds an
emission hook for the signal specified by name
,
which will get called for any emission of that signal, independent of
the instance. This is possible only for signals which don't have the
gobject.SIGNAL_NO_HOOKS
flag set.
def gobject.remove_emission_hook(type
, name
, hook_id
)
type : | a Python GObject instance or type |
name : | a signal name |
hook_id : | the id of the emission hook as returned by the
gobject.add_emission_hook ())
function. |
Returns : |
This function is available in PyGTK 2.8 and above.
The remove_emission_hook
() function deletes
an emission hook.
def gobject._install_metaclass(metaclass
)
metaclass : |
This function is available in PyGTK 2.10 and above.
The _install_metaclass
() function installs
the metaclass specified by metaclass
.
def 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.
def 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.
def 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.