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 exit(1).
  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_set_locale ##### -->
  57 <para>
  58 Initializes the support for internationalization by calling the setlocale()
  59 system call. This function is called by gtk_set_locale() and so GTK+
  60 applications should use that instead.
  61 </para>
  62 <para>
  63 The locale to use is determined by the LANG environment variable,
  64 so to run an application in a certain locale you can do something like this:
  65 <informalexample>
  66 <programlisting>
  67   export LANG="fr"
  68   ... run application ...
  69 </programlisting>
  70 </informalexample>
  71 </para>
  72 <para>
  73 If the locale is not supported by X then it is reset to the standard "C"
  74 locale.
  75 </para>
  76
  77 @Returns: the resulting locale.
  78
  79
  80 <!-- ##### FUNCTION gdk_set_sm_client_id ##### -->
  81 <para>
  82 Sets the SM_CLIENT_ID property on the application's leader window so that
  83 the window manager can save the application's state using the X11R6 ICCCM
  84 session management protocol.
  85 </para>
  86 <para>
  87 The leader window is automatically created by GDK and never shown. It's only
  88 use is for session management. The WM_CLIENT_LEADER property is automatically
  89 set on all X windows created by the application to point to the leader window.
  90 </para>
  91 <para>
  92 See the X Session Management Library documentation for more information on
  93 session management and the Inter-Client Communication Conventions Manual
  94 (ICCCM) for information on the WM_CLIENT_LEADER property. (Both documents are
  95 part of the X Windows distribution.)
  96 </para>
  97
  98 @sm_client_id: the client id assigned by the session manager when the
  99 connection was opened, or NULL to remove the property.
 100
 101
 102 <!-- ##### FUNCTION gdk_exit ##### -->
 103 <para>
 104 Exits the application using the exit() system call.
 105 </para>
 106 <para>
 107 This routine is provided mainly for backwards compatability, since it used to
 108 perform tasks necessary to exit the application cleanly. Those tasks are now
 109 performed in a function which is automatically called on exit (via the use
 110 of g_atexit()).
 111 </para>
 112
 113 @error_code: the error code to pass to the exit() call.
 114
 115
 116 <!-- ##### FUNCTION gdk_get_program_class ##### -->
 117 <para>
 118 Gets the program class. Unless the program class has explicitly
 119 been set with gdk_set_program_class() or with the <option>--class</option>
 120 commandline option, the default value is the program name (determined
 121 with g_get_prgname()) with the first character converted to uppercase.
 122 </para>
 123
 124 @Returns: the program class.
 125
 126
 127 <!-- ##### FUNCTION gdk_set_program_class ##### -->
 128 <para>
 129 Sets the program class.
 130 </para>
 131
 132 @program_class: a string.
 133
 134
 135 <!-- ##### FUNCTION gdk_get_display ##### -->
 136 <para>
 137 Gets the name of the display, which usually comes from the DISPLAY
 138 environment variable or the --display command line option.
 139 </para>
 140
 141 @Returns: the name of the display.
 142
 143
 144 <!-- ##### FUNCTION gdk_flush ##### -->
 145 <para>
 146 Flushes the X output buffer and waits until all requests have been processed
 147 by the server. This is rarely needed by applications. It's main use is for
 148 trapping X errors with gdk_error_trap_push() and gdk_error_trap_pop().
 149 </para>
 150
 151
 152
 153 <!-- ##### FUNCTION gdk_screen_width ##### -->
 154 <para>
 155 Returns the width of the screen in pixels.
 156 </para>
 157
 158 @Returns: the width of the screen in pixels.
 159
 160
 161 <!-- ##### FUNCTION gdk_screen_height ##### -->
 162 <para>
 163 Returns the height of the screen in pixels.
 164 </para>
 165
 166 @Returns: the height of the screen in pixels.
 167
 168
 169 <!-- ##### FUNCTION gdk_screen_width_mm ##### -->
 170 <para>
 171 Returns the width of the screen in millimeters.
 172 Note that on many X servers this value will not be correct.
 173 </para>
 174
 175 @Returns: the width of the screen in millimeters, though it is not always
 176 correct.
 177
 178
 179 <!-- ##### FUNCTION gdk_screen_height_mm ##### -->
 180 <para>
 181 Returns the height of the screen in millimeters.
 182 Note that on many X servers this value will not be correct.
 183 </para>
 184
 185 @Returns: the height of the screen in millimeters, though it is not always
 186 correct.
 187
 188
 189 <!-- ##### FUNCTION gdk_pointer_grab ##### -->
 190 <para>
 191 Grabs the pointer (usually a mouse) so that all events are passed to this
 192 application until the pointer is ungrabbed with gdk_pointer_ungrab(), or
 193 the grab window becomes unviewable.
 194 This overrides any previous pointer grab by this client.
 195 </para>
 196 <para>
 197 Pointer grabs are used for operations which need complete control over mouse
 198 events, even if the mouse leaves the application.
 199 For example in GTK+ it is used for Drag and Drop, for dragging the handle in
 200 the #GtkHPaned and #GtkVPaned widgets, and for resizing columns in #GtkCList
 201 widgets.
 202 </para>
 203 <para>
 204 Note that if the event mask of an X window has selected both button press and
 205 button release events, then a button press event will cause an automatic
 206 pointer grab until the button is released.
 207 X does this automatically since most applications expect to receive button
 208 press and release events in pairs.
 209 It is equivalent to a pointer grab on the window with @owner_events set to
 210 TRUE.
 211 </para>
 212
 213 @window: the #GdkWindow which will own the grab (the grab window).
 214 @owner_events: if FALSE then all pointer events are reported with respect to
 215 @window and are only reported if selected by @event_mask. If TRUE then pointer
 216 events for this application are reported as normal, but pointer events outside
 217 this application are reported with respect to @window and only if selected by
 218 @event_mask. In either mode, unreported events are discarded.
 219 @event_mask: specifies the event mask, which is used in accordance with
 220 @owner_events.
 221 @confine_to: If non-%NULL, the pointer will be confined to this
 222 window during the grab. If the pointer is outside @confine_to, it will
 223 automatically be moved to the closest edge of @confine_to and enter
 224 and leave events will be generated as necessary.
 225 @cursor: the cursor to display while the grab is active. If this is NULL then
 226 the normal cursors are used for @window and its descendants, and the cursor
 227 for @window is used for all other windows.
 228 @time: the timestamp of the event which led to this pointer grab. This usually
 229 comes from a #GdkEventButton struct, though #GDK_CURRENT_TIME can be used if
 230 the time isn't known.
 231 @Returns: 0 if the grab was successful.
 232
 233
 234 <!-- ##### ENUM GdkGrabStatus ##### -->
 235 <para>
 236
 237 </para>
 238
 239 @GDK_GRAB_SUCCESS:
 240 @GDK_GRAB_ALREADY_GRABBED:
 241 @GDK_GRAB_INVALID_TIME:
 242 @GDK_GRAB_NOT_VIEWABLE:
 243 @GDK_GRAB_FROZEN:
 244
 245 <!-- ##### FUNCTION gdk_pointer_ungrab ##### -->
 246 <para>
 247 Ungrabs the pointer, if it is grabbed by this application.
 248 </para>
 249
 250 @time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is
 251 available.
 252
 253
 254 <!-- ##### FUNCTION gdk_pointer_is_grabbed ##### -->
 255 <para>
 256 Returns TRUE if the pointer is currently grabbed by this application.
 257 </para>
 258 <para>
 259 Note that the return value is not completely reliable since the X server may
 260 automatically ungrab the pointer, without informing the application, if the
 261 grab window becomes unviewable. It also does not take passive pointer grabs
 262 into account.
 263 </para>
 264
 265 @Returns: TRUE if the pointer is currently grabbed by this application.
 266 Though this value is not always correct.
 267
 268
 269 <!-- ##### FUNCTION gdk_set_double_click_time ##### -->
 270 <para>
 271
 272 </para>
 273
 274 @msec:
 275
 276
 277 <!-- ##### FUNCTION gdk_keyboard_grab ##### -->
 278 <para>
 279 Grabs the keyboard so that all events are passed to this
 280 application until the keyboard is ungrabbed with gdk_keyboard_ungrab().
 281 This overrides any previous keyboard grab by this client.
 282 </para>
 283
 284 @window: the #GdkWindow which will own the grab (the grab window).
 285 @owner_events: if FALSE then all keyboard events are reported with respect to
 286 @window. If TRUE then keyboard events for this application are reported as
 287 normal, but keyboard events outside this application are reported with respect
 288 to @window. Both key press and key release events are always reported,
 289 independant of the event mask set by the application.
 290 @time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is
 291 available.
 292 @Returns: 0 if the grab was successful.
 293
 294
 295 <!-- ##### FUNCTION gdk_keyboard_ungrab ##### -->
 296 <para>
 297 Ungrabs the keyboard, if it is grabbed by this application.
 298 </para>
 299
 300 @time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is
 301 available.
 302
 303
 304 <!-- ##### FUNCTION gdk_beep ##### -->
 305 <para>
 306 Emits a short beep.
 307 </para>
 308
 309
 310
 311 <!-- ##### FUNCTION gdk_get_use_xshm ##### -->
 312 <para>
 313 Returns TRUE if GDK will attempt to use the MIT-SHM shared memory extension.
 314 </para>
 315 <para>
 316 The shared memory extension is used for #GdkImage, and consequently for
 317 <link linkend="gdk-GdkRGB">GdkRGB</link>.
 318 It enables much faster drawing by communicating with the X server through
 319 SYSV shared memory calls. However, it can only be used if the X client and
 320 server are on the same machine and the server supports it.
 321 </para>
 322
 323 @Returns: TRUE if use of the MIT shared memory extension will be attempted.
 324
 325
 326 <!-- ##### FUNCTION gdk_set_use_xshm ##### -->
 327 <para>
 328 Sets whether the use of the MIT shared memory extension should be attempted.
 329 This function is mainly for internal use. It is only safe for an application
 330 to set this to FALSE, since if it is set to TRUE and the server does not
 331 support the extension it may cause warning messages to be output.
 332 </para>
 333
 334 @use_xshm: TRUE if use of the MIT shared memory extension should be attempted.
 335
 336
 337 <!-- ##### FUNCTION gdk_error_trap_push ##### -->
 338 <para>
 339 This function allows X errors to be trapped instead of the normal behavior
 340 of exiting the application. It should only be used if it is not possible to
 341 avoid the X error in any other way.
 342 </para>
 343 <example>
 344 <title>Trapping an X error.</title>
 345 <programlisting>
 346   gdk_error_trap_push ();
 347
 348   /* ... Call the X function which may cause an error here ... */
 349
 350   /* Flush the X queue to catch errors now. */
 351   gdk_flush ();
 352
 353   if (gdk_error_trap_pop ())
 354     {
 355       /* ... Handle the error here ... */
 356     }
 357 </programlisting>
 358 </example>
 359
 360
 361
 362 <!-- ##### FUNCTION gdk_error_trap_pop ##### -->
 363 <para>
 364 Removes the X error trap installed with gdk_error_trap_push().
 365 </para>
 366
 367 @Returns: the X error code, or 0 if no error occurred.
 368
 369
 370 <!-- ##### MACRO GDK_WINDOWING_X11 ##### -->
 371 <para>
 372 This macro is defined if GDK is configured to use the X backend.
 373 </para>
 374
 375
 376
 377 <!-- ##### MACRO GDK_WINDOWING_WIN32 ##### -->
 378 <para>
 379 This macro is defined if GDK is configured to use the Win32 backend.
 380 </para>
 381
 382
 383
 384 <!-- ##### MACRO GDK_WINDOWING_FB ##### -->
 385 <para>
 386 This macro is defined if GDK is configured to use the Linux framebuffer backend.
 387 </para>
 388
 389
 390