Pileus Git - ~andy/gtk/blob - docs/developers.txt

   1 Things to care about when using/programing for GTK+
   2 ===================================================
   3
   4 This file is meant to collect some frequently triggered failures when
   5 programming for/with Gtk, having the spirit of a developers FAQ.
   6 It is also the correct place to list up things that programmers should
   7 care about in general.
   8
   9 In the hope that this text might be useful to someone,
  10
  11         - Tim Janik <timj@gimp.org>
  12           1998/02/11
  13
  14
  15 Automatic destruction of widgets on removal from parent
  16 -------------------------------------------------------
  17
  18 This is a reference counting issue, you would want to refer
  19 to refcounting.txt on it.
  20
  21
  22 What are all the widget flags about?
  23 ------------------------------------
  24
  25 Refer to the file widget_system.txt which covers widget flags and the
  26 resulting invariants in a detailed way.
  27
  28
  29 GdkWindow pointers may be NULL in GdkEvents
  30 -------------------------------------------
  31
  32 The notification nature of the signal mechanism might cause events to
  33 be emitted that have their GdkWindow pointer set to NULL.
  34 This is due to the fact that certain events need to be emitted after the
  35 real GdkWindow of a widget is not any longer pertinent.
  36 It's up to the signal handling function (application) to check for the
  37 window field of the event structure to be != NULL, if it is going to
  38 perform any operations through Gdk calls on it.
  39 Events that a likely to trigger a missing check for the window pointer
  40 currently are (and correspond to the trailing signals):
  41
  42 GDK_SELECTION_CLEAR     GtkWidget::selection_clear_event
  43 GDK_FOCUS_CHANGE        GtkWidget::focus_in_event
  44                         GtkWidget::focus_out_event
  45
  46 Events that are assured to have a valid GdkEvent.any.window field are
  47
  48 GDK_EXPOSE              GtkWidget::expose_event
  49
  50
  51 Writing Gdk functions
  52 ---------------------
  53
  54 When writing Gdk functions that operate on GdkWindow structures in any
  55 meaningful sense, that is casting to a GdkWindowPrivate structure for
  56 access to fields other then GdkWindow.user_data, the programmer is
  57 recommended to check for the GdkWindowPrivate.destroyed field to be ==
  58 FALSE, especially if the GdkWindowPrivate.xwindow field is used.
  59 Silent abortion of the Gdk function is the correct behaviour if this
  60 condition isn't met.