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

   1 <!-- ##### SECTION Title ##### -->
   2 General
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 library initialization and miscellaneous functions.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 This section describes the GDK initialization functions and miscellaneous
  10 utility functions.
  11 </para>
  12
  13 <!-- ##### SECTION See_Also ##### -->
  14 <para>
  15
  16 </para>
  17
  18 <!-- ##### FUNCTION gdk_init ##### -->
  19 <para>
  20 Initializes the GDK library and connects to the X server.
  21 If initialization fails, a warning message is output and the application
  22 terminates with a call to <literal>exit(1)</literal>.
  23 </para>
  24 <para>
  25 Any arguments used by GDK are removed from the array and @argc and @argv are
  26 updated accordingly.
  27 </para>
  28 <para>
  29 GTK+ initializes GDK in gtk_init() and so this function is not usually needed
  30 by GTK+ applications.
  31 </para>
  32
  33 @argc: the number of command line arguments.
  34 @argv: the array of command line arguments.
  35
  36
  37 <!-- ##### FUNCTION gdk_init_check ##### -->
  38 <para>
  39 Initializes the GDK library and connects to the X server, returning %TRUE on
  40 success.
  41 </para>
  42 <para>
  43 Any arguments used by GDK are removed from the array and @argc and @argv are
  44 updated accordingly.
  45 </para>
  46 <para>
  47 GTK+ initializes GDK in gtk_init() and so this function is not usually needed
  48 by GTK+ applications.
  49 </para>
  50
  51 @argc: the number of command line arguments.
  52 @argv: the array of command line arguments.
  53 @Returns: %TRUE if initialization succeeded.
  54
  55
  56 <!-- ##### FUNCTION gdk_parse_args ##### -->
  57 <para>
  58
  59 </para>
  60
  61 @argc:
  62 @argv:
  63
  64
  65 <!-- ##### FUNCTION gdk_get_display_arg_name ##### -->
  66 <para>
  67
  68 </para>
  69
  70 @Returns:
  71
  72
  73 <!-- ##### FUNCTION gdk_set_locale ##### -->
  74 <para>
  75 Initializes the support for internationalization by calling the <function>setlocale()</function>
  76 system call. This function is called by gtk_set_locale() and so GTK+
  77 applications should use that instead.
  78 </para>
  79 <para>
  80 The locale to use is determined by the <envar>LANG</envar> environment variable,
  81 so to run an application in a certain locale you can do something like this:
  82 <informalexample>
  83 <programlisting>
  84   export LANG="fr"
  85   ... run application ...
  86 </programlisting>
  87 </informalexample>
  88 </para>
  89 <para>
  90 If the locale is not supported by X then it is reset to the standard "C"
  91 locale.
  92 </para>
  93
  94 @Returns: the resulting locale.
  95
  96
  97 <!-- ##### FUNCTION gdk_set_sm_client_id ##### -->
  98 <para>
  99 </para>
 100
 101 @sm_client_id:
 102
 103
 104 <!-- ##### FUNCTION gdk_exit ##### -->
 105 <para>
 106 Exits the application using the <function>exit()</function> system call.
 107 </para>
 108 <para>
 109 This routine is provided mainly for backwards compatibility, since it used to
 110 perform tasks necessary to exit the application cleanly. Those tasks are now
 111 performed in a function which is automatically called on exit (via the use
 112 of g_atexit()).
 113 </para>
 114
 115 @error_code: the error code to pass to the <function>exit()</function> call.
 116
 117
 118 <!-- ##### FUNCTION gdk_get_program_class ##### -->
 119 <para>
 120 Gets the program class. Unless the program class has explicitly
 121 been set with gdk_set_program_class() or with the <option>--class</option>
 122 commandline option, the default value is the program name (determined
 123 with g_get_prgname()) with the first character converted to uppercase.
 124 </para>
 125
 126 @Returns: the program class.
 127
 128
 129 <!-- ##### FUNCTION gdk_set_program_class ##### -->
 130 <para>
 131 Sets the program class. The X11 backend uses the program class to set
 132 the class name part of the <literal>WM_CLASS</literal> property on
 133 toplevel windows; see the ICCCM.
 134 </para>
 135
 136 @program_class: a string.
 137
 138
 139 <!-- ##### FUNCTION gdk_get_display ##### -->
 140 <para>
 141 Gets the name of the display, which usually comes from the <envar>DISPLAY</envar>
 142 environment variable or the <option>--display</option> command line option.
 143 </para>
 144
 145 @Returns: the name of the display.
 146
 147
 148 <!-- ##### FUNCTION gdk_flush ##### -->
 149 <para>
 150 Flushes the X output buffer and waits until all requests have been processed
 151 by the server. This is rarely needed by applications. It's main use is for
 152 trapping X errors with gdk_error_trap_push() and gdk_error_trap_pop().
 153 </para>
 154
 155
 156
 157 <!-- ##### FUNCTION gdk_screen_width ##### -->
 158 <para>
 159 </para>
 160
 161 @Returns:
 162
 163
 164 <!-- ##### FUNCTION gdk_screen_height ##### -->
 165 <para>
 166 </para>
 167
 168 @Returns:
 169
 170
 171 <!-- ##### FUNCTION gdk_screen_width_mm ##### -->
 172 <para>
 173 </para>
 174
 175 @Returns:
 176
 177
 178 <!-- ##### FUNCTION gdk_screen_height_mm ##### -->
 179 <para>
 180 </para>
 181
 182 @Returns:
 183
 184
 185 <!-- ##### FUNCTION gdk_pointer_grab ##### -->
 186 <para>
 187 Grabs the pointer (usually a mouse) so that all events are passed to this
 188 application until the pointer is ungrabbed with gdk_pointer_ungrab(), or
 189 the grab window becomes unviewable.
 190 This overrides any previous pointer grab by this client.
 191 </para>
 192 <para>
 193 Pointer grabs are used for operations which need complete control over mouse
 194 events, even if the mouse leaves the application.
 195 For example in GTK+ it is used for Drag and Drop, for dragging the handle in
 196 the #GtkHPaned and #GtkVPaned widgets, and for resizing columns in #GtkCList
 197 widgets.
 198 </para>
 199 <para>
 200 Note that if the event mask of an X window has selected both button press and
 201 button release events, then a button press event will cause an automatic
 202 pointer grab until the button is released.
 203 X does this automatically since most applications expect to receive button
 204 press and release events in pairs.
 205 It is equivalent to a pointer grab on the window with @owner_events set to
 206 %TRUE.
 207 </para>
 208
 209 @window: the #GdkWindow which will own the grab (the grab window).
 210 @owner_events: if %FALSE then all pointer events are reported with respect to
 211 @window and are only reported if selected by @event_mask. If %TRUE then pointer
 212 events for this application are reported as normal, but pointer events outside
 213 this application are reported with respect to @window and only if selected by
 214 @event_mask. In either mode, unreported events are discarded.
 215 @event_mask: specifies the event mask, which is used in accordance with
 216 @owner_events.
 217 @confine_to: If non-%NULL, the pointer will be confined to this
 218 window during the grab. If the pointer is outside @confine_to, it will
 219 automatically be moved to the closest edge of @confine_to and enter
 220 and leave events will be generated as necessary.
 221 @cursor: the cursor to display while the grab is active. If this is %NULL then
 222 the normal cursors are used for @window and its descendants, and the cursor
 223 for @window is used for all other windows.
 224 @time: the timestamp of the event which led to this pointer grab. This usually
 225 comes from a #GdkEventButton struct, though %GDK_CURRENT_TIME can be used if
 226 the time isn't known.
 227 @Returns: %GDK_GRAB_SUCCESS if the grab was successful.
 228
 229
 230 <!-- ##### ENUM GdkGrabStatus ##### -->
 231 <para>
 232 Returned by gdk_pointer_grab() and gdk_keyboard_grab() to indicate
 233 success or the reason for the failure of the grab attempt.
 234 </para>
 235
 236 @GDK_GRAB_SUCCESS: the resource was successfully grabbed.
 237 @GDK_GRAB_ALREADY_GRABBED: the resource is actively grabbed by another client.
 238 @GDK_GRAB_INVALID_TIME: the resource was grabbed more recently than the
 239   specified time.
 240 @GDK_GRAB_NOT_VIEWABLE: the grab window or the @confine_to window are not
 241   viewable.
 242 @GDK_GRAB_FROZEN: the resource is frozen by an active grab of another client.
 243
 244 <!-- ##### FUNCTION gdk_pointer_ungrab ##### -->
 245 <para>
 246
 247 </para>
 248
 249 @time:
 250
 251
 252 <!-- ##### FUNCTION gdk_pointer_is_grabbed ##### -->
 253 <para>
 254 </para>
 255 <para>
 256 </para>
 257
 258 @Returns:
 259
 260
 261 <!-- ##### FUNCTION gdk_set_double_click_time ##### -->
 262 <para>
 263
 264 </para>
 265
 266 @msec:
 267
 268
 269 <!-- ##### FUNCTION gdk_keyboard_grab ##### -->
 270 <para>
 271 Grabs the keyboard so that all events are passed to this
 272 application until the keyboard is ungrabbed with gdk_keyboard_ungrab().
 273 This overrides any previous keyboard grab by this client.
 274 </para>
 275
 276 @window: the #GdkWindow which will own the grab (the grab window).
 277 @owner_events: if %FALSE then all keyboard events are reported with respect to
 278 @window. If %TRUE then keyboard events for this application are reported as
 279 normal, but keyboard events outside this application are reported with respect
 280 to @window. Both key press and key release events are always reported,
 281 independant of the event mask set by the application.
 282 @time: a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is
 283 available.
 284 @Returns: %GDK_GRAB_SUCCESS if the grab was successful.
 285
 286
 287 <!-- ##### FUNCTION gdk_keyboard_ungrab ##### -->
 288 <para>
 289 </para>
 290
 291 @time:
 292
 293
 294 <!-- ##### FUNCTION gdk_beep ##### -->
 295 <para>
 296 </para>
 297
 298
 299
 300 <!-- ##### FUNCTION gdk_get_use_xshm ##### -->
 301 <para>
 302 Returns %TRUE if GDK will attempt to use the MIT-SHM shared memory extension.
 303 </para>
 304 <para>
 305 The shared memory extension is used for #GdkImage, and consequently for
 306 <link linkend="gdk-GdkRGB">GdkRGB</link>.
 307 It enables much faster drawing by communicating with the X server through
 308 SYSV shared memory calls. However, it can only be used if the X client and
 309 server are on the same machine and the server supports it.
 310 </para>
 311
 312 @Returns: %TRUE if use of the MIT shared memory extension will be attempted.
 313
 314
 315 <!-- ##### FUNCTION gdk_set_use_xshm ##### -->
 316 <para>
 317 Sets whether the use of the MIT shared memory extension should be attempted.
 318 This function is mainly for internal use. It is only safe for an application
 319 to set this to %FALSE, since if it is set to %TRUE and the server does not
 320 support the extension it may cause warning messages to be output.
 321 </para>
 322
 323 @use_xshm: %TRUE if use of the MIT shared memory extension should be attempted.
 324
 325
 326 <!-- ##### FUNCTION gdk_error_trap_push ##### -->
 327 <para>
 328 This function allows X errors to be trapped instead of the normal behavior
 329 of exiting the application. It should only be used if it is not possible to
 330 avoid the X error in any other way.
 331 </para>
 332 <example>
 333 <title>Trapping an X error.</title>
 334 <programlisting>
 335   gdk_error_trap_push (<!-- -->);
 336
 337   /* ... Call the X function which may cause an error here ... */
 338
 339   /* Flush the X queue to catch errors now. */
 340   gdk_flush (<!-- -->);
 341
 342   if (gdk_error_trap_pop (<!-- -->))
 343     {
 344       /* ... Handle the error here ... */
 345     }
 346 </programlisting>
 347 </example>
 348
 349
 350
 351 <!-- ##### FUNCTION gdk_error_trap_pop ##### -->
 352 <para>
 353 Removes the X error trap installed with gdk_error_trap_push().
 354 </para>
 355
 356 @Returns: the X error code, or 0 if no error occurred.
 357
 358
 359 <!-- ##### MACRO GDK_WINDOWING_X11 ##### -->
 360 <para>
 361 This macro is defined if GDK is configured to use the X backend.
 362 </para>
 363
 364
 365
 366 <!-- ##### MACRO GDK_WINDOWING_WIN32 ##### -->
 367 <para>
 368 This macro is defined if GDK is configured to use the Win32 backend.
 369 </para>
 370
 371
 372
 373 <!-- ##### MACRO GDK_WINDOWING_FB ##### -->
 374 <para>
 375 This macro is defined if GDK is configured to use the Linux framebuffer backend.
 376 </para>
 377
 378
 379