1
<?xml version="1.0" standalone="no"?>
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
5
<refentry id="class-gobjectmaincontext">
7
<refname>gobject.MainContext</refname>
9
<refpurpose>an object representing a set of event sources to be handled
11
linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link>.</refpurpose>
15
<title>Synopsis</title>
17
<classsynopsis language="python">
18
<ooclass><classname>gobject.MainContext</classname></ooclass>
19
<constructorsynopsis language="python">
20
<methodname><link linkend="constructor-gobjectmaincontext">gobject.MainContext</link></methodname>
21
</constructorsynopsis>
22
<methodsynopsis language="python">
23
<methodname><link linkend="method-gobjectmaincontext--iteration">iteration</link></methodname>
24
<methodparam><parameter>may_block</parameter></methodparam>
26
<methodsynopsis language="python">
27
<methodname><link linkend="method-gobjectmaincontext--pending">pending</link></methodname>
34
<title>Ancestry</title>
36
<synopsis>+-- <link linkend="class-gobjectmaincontext">gobject.MainContext</link>
42
<title>Description</title>
45
linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>
46
represents a set of event sources that can be run in a single thread. File
47
descriptors (plain files, pipes or sockets) and timeouts are the standard
48
event sources for <literal>GTK</literal> and <literal>PyGTK</literal> though
49
others can be added. Each event source is assigned a priority. The default
50
priority, <literal>gobject.PRIORITY_DEFAULT</literal>, is 0. Values less
51
than 0 denote higher priorities. Values greater than 0 denote lower
52
priorities. Events from high priority sources are always processed before
53
events from lower priority sources. Single iterations of a <link
54
linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>
55
can be run with the <link
56
linkend="method-gobjectmaincontext--iteration"><methodname>iteration</methodname>()</link>
61
<refsect1 id="constructor-gobjectmaincontext">
62
<title>Constructor</title>
64
<programlisting><constructorsynopsis language="python">
65
<methodname>gobject.MainContext</methodname>
66
</constructorsynopsis></programlisting>
69
<term><emphasis>Returns</emphasis> :</term>
70
<listitem><simpara>a new <link
71
linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>
72
object.</simpara></listitem>
76
<para>Creates a new <link
77
linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>
83
<title>Methods</title>
85
<refsect2 id="method-gobjectmaincontext--iteration">
86
<title>gobject.MainContext.iteration</title>
88
<programlisting><methodsynopsis language="python">
89
<methodname>iteration</methodname>
90
</methodsynopsis></programlisting>
93
<term><parameter>may_block</parameter> :</term>
94
<listitem><simpara>if <literal>TRUE</literal> the call may block
95
waiting for an event.</simpara></listitem>
98
<term><emphasis>Returns</emphasis> :</term>
99
<listitem><simpara><literal>TRUE</literal> if events were
100
dispatched.</simpara></listitem>
104
<para>The <methodname>iteration</methodname>() method runs a single
105
iteration. This involves:</para>
109
<simpara>checking to see if any associated event sources are ready
110
to be processed;</simpara>
113
<simpara>then if no events sources are ready and
114
<parameter>may_block</parameter> is <literal>TRUE</literal>, waiting for a
115
source to become ready;</simpara>
118
<simpara>and finally, dispatching the highest priority events
119
sources that are ready</simpara>
123
<para>Note that even when <parameter>may_block</parameter> is
124
<literal>TRUE</literal>, it is still possible for
125
<methodname>iteration</methodname>() to return <literal>FALSE</literal>,
126
since the the wait may be interrupted for other reasons than an event source
127
becoming ready.</para>
131
<refsect2 id="method-gobjectmaincontext--pending">
132
<title>gobject.MainContext.pending</title>
134
<programlisting><methodsynopsis language="python">
135
<methodname>pending</methodname>
136
</methodsynopsis></programlisting>
139
<term><emphasis>Returns</emphasis> :</term>
140
<listitem><simpara><literal>TRUE</literal> if events are
141
pending.</simpara></listitem>
145
<para>The <methodname>pending</methodname>() method checks if any
146
associated sources have pending events.</para>