Pileus Git - ~andy/gtk/blob - docs/reference/gdk/tmpl/input.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Input
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Callbacks on file descriptors
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The functions in this section are used to establish
  10 callbacks when some condition becomes true for
  11 a file descriptor. They are currently just wrappers around
  12 the <link linkend="glib-IO-Channels">IO Channel</link>
  13 facility.
  14 </para>
  15
  16 <!-- ##### SECTION See_Also ##### -->
  17 <para>
  18 <variablelist>
  19
  20 <varlistentry>
  21 <term><link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link></term>
  22 <listitem><para>The main loop in which input callbacks run.</para></listitem>
  23 </varlistentry>
  24
  25 <varlistentry>
  26 <term><link linkend="glib-IO-Channels">IO Channels</link></term>
  27 <listitem><para>A newer and more flexible way of doing IO
  28 callbacks.</para></listitem>
  29 </varlistentry>
  30
  31 </variablelist>
  32 </para>
  33
  34 <!-- ##### SECTION Stability_Level ##### -->
  35
  36
  37 <!-- ##### FUNCTION gdk_input_add_full ##### -->
  38 <para>
  39 Establish a callback when a condition becomes true on
  40 a file descriptor.
  41 </para>
  42
  43 @source: a file descriptor.
  44 @condition: the condition.
  45 @function: the callback function.
  46 @data: callback data passed to @function.
  47 @destroy: callback function to call with @data when the input
  48   handler is removed.
  49 @Returns: a tag that can later be used as an argument to
  50  gdk_input_remove().
  51
  52
  53 <!-- ##### ENUM GdkInputCondition ##### -->
  54 <para>
  55 A set of bit flags used to specify conditions for which
  56 an input callback will be triggered. The three members
  57 of this enumeration correspond to the @readfds,
  58 @writefds, and @exceptfds arguments to the
  59 <function>select</function> system call.
  60
  61 <informaltable pgwide="1" frame="none" role="enum">
  62 <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
  63 <tbody>
  64
  65 <row>
  66 <entry>GDK_INPUT_READ</entry>
  67 <entry>the file descriptor has become available for reading.
  68 (Or, as is standard in Unix, a socket or pipe was closed
  69 at the other end; this is the case if a subsequent read
  70 on the file descriptor returns a count of zero.)</entry>
  71 </row>
  72
  73 <row>
  74 <entry>GDK_INPUT_WRITE</entry>
  75 <entry>the file descriptor has become available for writing.</entry>
  76 </row>
  77
  78 <row>
  79 <entry>GDK_INPUT_EXCEPTION</entry>
  80 <entry>an exception was raised on the file descriptor.</entry>
  81 </row>
  82
  83 </tbody></tgroup></informaltable>
  84 </para>
  85
  86 @GDK_INPUT_READ:
  87 @GDK_INPUT_WRITE:
  88 @GDK_INPUT_EXCEPTION:
  89
  90 <!-- ##### USER_FUNCTION GdkInputFunction ##### -->
  91 <para>
  92 A callback function that will be called when some condition
  93 occurs.
  94 </para>
  95
  96 @data: the user data passed to gdk_input_add() or gdk_input_add_full().
  97 @source: the source where the condition occurred.
  98 @condition: the triggering condition.
  99
 100
 101 <!-- ##### USER_FUNCTION GdkDestroyNotify ##### -->
 102 <para>
 103 A callback function called when a piece of user data is
 104 no longer being stored by GDK. Will typically free the
 105 structure or object that @data points to.
 106 </para>
 107
 108 @data: the user data.
 109
 110
 111 <!-- ##### FUNCTION gdk_input_add ##### -->
 112 <para>
 113 Establish a callback when a condition becomes true on
 114 a file descriptor.
 115 </para>
 116
 117 @source: a file descriptor.
 118 @condition: the condition.
 119 @function: the callback function.
 120 @data: callback data passed to @function.
 121 @Returns: a tag that can later be used as an argument to
 122  gdk_input_remove().
 123
 124
 125 <!-- ##### FUNCTION gdk_input_remove ##### -->
 126 <para>
 127 Remove a callback added with gdk_input_add() or
 128 gdk_input_add_full().
 129 </para>
 130
 131 @tag: the tag returned when the callback was set up.
 132
 133