| 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 usefull 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 asured to have a valid GdkEvent.any.window field are |
|---|
| 47 | |
|---|
| 48 | GDK_EXPOSE GtkWidget::expose_event |
|---|
| 49 | |
|---|
| 50 | |
|---|
| 51 | gtk_widget_ref() vs. gtk_object_ref() |
|---|
| 52 | ------------------------------------- |
|---|
| 53 | |
|---|
| 54 | The widget referencing functions gtk_widget_ref() and gtk_widget_unref() |
|---|
| 55 | are currently just wrappers about the corresponding referencing functions |
|---|
| 56 | for objects. Still you should use the widget referencing functions if you |
|---|
| 57 | are sure the referenced object is of type GTK_WIDGET_TYPE. |
|---|
| 58 | |
|---|
| 59 | |
|---|
| 60 | Writing Gdk functions |
|---|
| 61 | --------------------- |
|---|
| 62 | |
|---|
| 63 | When writing Gdk functions that operate on GdkWindow structures in any |
|---|
| 64 | maeningfull sense, that is casting to a GdkWindowPrivate structure for |
|---|
| 65 | access to fields other then GdkWindow.user_data, the programmer is |
|---|
| 66 | recommended to check for the GdkWindowPrivate.destroyed field to be == |
|---|
| 67 | FALSE, especially if the GdkWindowPrivate.xwindow field is used. |
|---|
| 68 | Silent abortion of the Gdk function is the correct behaviour if this |
|---|
| 69 | condition isn't met. |
|---|
