diff options
| -rw-r--r-- | ChangeLog | 4 | ||||
| -rw-r--r-- | ChangeLog.pre-2-0 | 4 | ||||
| -rw-r--r-- | ChangeLog.pre-2-10 | 4 | ||||
| -rw-r--r-- | ChangeLog.pre-2-2 | 4 | ||||
| -rw-r--r-- | ChangeLog.pre-2-4 | 4 | ||||
| -rw-r--r-- | ChangeLog.pre-2-6 | 4 | ||||
| -rw-r--r-- | ChangeLog.pre-2-8 | 4 | ||||
| -rw-r--r-- | docs/developers.txt | 69 | ||||
| -rw-r--r-- | docs/refcounting.txt | 26 | ||||
| -rw-r--r-- | docs/widget_system.txt | 4 |
10 files changed, 98 insertions, 29 deletions
@@ -1,6 +1,8 @@ Wed Feb 11 00:18:31 1998 Tim Janik <timj@gimp.org> - * gtk/gtksignal.h: + * docs/refcounting.txt: backed out the section "Gnits to care about". + * docs/developers.txt: new file, kinda developers FAQ. + * gtk/gtksignal.c: new function gtk_signal_handler_pending() returning the id of the next handler pending for that signal or 0. put struct GtkHandler back into gtksignal.c along with diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 191f117bae..ae74e20b35 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,6 +1,8 @@ Wed Feb 11 00:18:31 1998 Tim Janik <timj@gimp.org> - * gtk/gtksignal.h: + * docs/refcounting.txt: backed out the section "Gnits to care about". + * docs/developers.txt: new file, kinda developers FAQ. + * gtk/gtksignal.c: new function gtk_signal_handler_pending() returning the id of the next handler pending for that signal or 0. put struct GtkHandler back into gtksignal.c along with diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 191f117bae..ae74e20b35 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,6 +1,8 @@ Wed Feb 11 00:18:31 1998 Tim Janik <timj@gimp.org> - * gtk/gtksignal.h: + * docs/refcounting.txt: backed out the section "Gnits to care about". + * docs/developers.txt: new file, kinda developers FAQ. + * gtk/gtksignal.c: new function gtk_signal_handler_pending() returning the id of the next handler pending for that signal or 0. put struct GtkHandler back into gtksignal.c along with diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 191f117bae..ae74e20b35 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,6 +1,8 @@ Wed Feb 11 00:18:31 1998 Tim Janik <timj@gimp.org> - * gtk/gtksignal.h: + * docs/refcounting.txt: backed out the section "Gnits to care about". + * docs/developers.txt: new file, kinda developers FAQ. + * gtk/gtksignal.c: new function gtk_signal_handler_pending() returning the id of the next handler pending for that signal or 0. put struct GtkHandler back into gtksignal.c along with diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 191f117bae..ae74e20b35 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,6 +1,8 @@ Wed Feb 11 00:18:31 1998 Tim Janik <timj@gimp.org> - * gtk/gtksignal.h: + * docs/refcounting.txt: backed out the section "Gnits to care about". + * docs/developers.txt: new file, kinda developers FAQ. + * gtk/gtksignal.c: new function gtk_signal_handler_pending() returning the id of the next handler pending for that signal or 0. put struct GtkHandler back into gtksignal.c along with diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 191f117bae..ae74e20b35 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,6 +1,8 @@ Wed Feb 11 00:18:31 1998 Tim Janik <timj@gimp.org> - * gtk/gtksignal.h: + * docs/refcounting.txt: backed out the section "Gnits to care about". + * docs/developers.txt: new file, kinda developers FAQ. + * gtk/gtksignal.c: new function gtk_signal_handler_pending() returning the id of the next handler pending for that signal or 0. put struct GtkHandler back into gtksignal.c along with diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 191f117bae..ae74e20b35 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,6 +1,8 @@ Wed Feb 11 00:18:31 1998 Tim Janik <timj@gimp.org> - * gtk/gtksignal.h: + * docs/refcounting.txt: backed out the section "Gnits to care about". + * docs/developers.txt: new file, kinda developers FAQ. + * gtk/gtksignal.c: new function gtk_signal_handler_pending() returning the id of the next handler pending for that signal or 0. put struct GtkHandler back into gtksignal.c along with diff --git a/docs/developers.txt b/docs/developers.txt new file mode 100644 index 0000000000..ee78bea4f8 --- /dev/null +++ b/docs/developers.txt @@ -0,0 +1,69 @@ +Things to care about when using/programing for GTK+ +=================================================== + +This file is meant to collect some frequently triggered failures when +programming for/with Gtk, having the spirit of a developers FAQ. +It is also the correct place to list up things that programmers should +care about in general. + +In the hope that this text might be usefull to someone, + + - Tim Janik <timj@gimp.org> + 1998/02/11 + + +Automatic destruction of widgets on removal from parent +------------------------------------------------------- + +This is a reference counting issue, you would want to refer +to refcounting.txt on it. + + +What are all the widget flags about? +------------------------------------ + +Refer to the file widget_system.txt which covers widget flags and the +resulting invariants in a detailed way. + + +GdkWindow pointers may be NULL in GdkEvents +------------------------------------------- + +The notification nature of the signal mechanism might cause events to +be emitted that have their GdkWindow pointer set to NULL. +This is due to the fact that certain events need to be emitted after the +real GdkWindow of a widget is not any longer pertinent. +It's up to the signal handling function (application) to check for the +window field of the event structure to be != NULL, if it is going to +perform any operations through Gdk calls on it. +Events that a likely to trigger a missing check for the window pointer +currently are (and correspond to the trailing signals): + +GDK_SELECTION_CLEAR GtkWidget::selection_clear_event +GDK_FOCUS_CHANGE GtkWidget::focus_in_event + GtkWidget::focus_out_event + +Events that are asured to have a valid GdkEvent.any.window field are + +GDK_EXPOSE GtkWidget::expose_event + + +gtk_widget_ref() vs. gtk_object_ref() +------------------------------------- + +The widget referencing functions gtk_widget_ref() and gtk_widget_unref() +are currently just wrappers about the corresponding referencing functions +for objects. Still you should use the widget referencing functions if you +are sure the referenced object is of type GTK_WIDGET_TYPE. + + +Writing Gdk functions +--------------------- + +When writing Gdk functions that operate on GdkWindow structures in any +maeningfull sense, that is casting to a GdkWindowPrivate structure for +access to fields other then GdkWindow.user_data, the programmer is +recommended to check for the GdkWindowPrivate.destroyed field to be == +FALSE, especially if the GdkWindowPrivate.xwindow field is used. +Silent abortion of the Gdk function is the correct behaviour if this +condition isn't met. diff --git a/docs/refcounting.txt b/docs/refcounting.txt index aa8823e225..82817d5c41 100644 --- a/docs/refcounting.txt +++ b/docs/refcounting.txt @@ -35,6 +35,10 @@ ref_count is updated accordingly. You can call gdk_window_destroy more than once on a particular GdkWindow, it will only be destroyed when it hasn't been yet. The ref_count is *always* decremented, tho. Be careful. + +Remark: When writing NO_WINDOW widgets, care should be taken about + proper referencing/unreferencing of the parent's GdkWindow + that is used by the widget. GdkPixmap --------- @@ -301,28 +305,10 @@ void gtk_menu_item_remove_submenu (GtkMenuItem *menu_item); void gtk_option_menu_remove_menu (GtkOptionMenu *option_menu); -Gnits to care about -------------------- - -On another note, though somewhat unrelated, the notification nature -of the signal mechanism might cause events to be emitted that have their -GdkWindow pointer set to NULL. This is due to the fact that certain -events need to be emitted after the real GdkWindow of a widget is not -any longer pertinent. It's up to the application to check for the window -field of the event structure to be != NULL, if it is going to perform -any operations through Gdk calls on it. -Events that a likely to trigger a missing check for the window pointer -currently are (and correspond to the trailing signals): - -GDK_SELECTION_CLEAR GtkWidget::selection_clear_event -GDK_FOCUS_CHANGE GtkWidget::focus_in_event - GtkWidget::focus_out_event - - Initial proposal: - Marius Vollmer <mvo@zagadka.ping.de> -Small fixups, "Taking care of proper referencing" and reference -counting solution for GtkMenus: +Some modifications/additions, "Taking care of proper referencing" and +reference counting solution for GtkMenus: - Tim Janik <timj@gimp.org> diff --git a/docs/widget_system.txt b/docs/widget_system.txt index 2b43d3a21c..5d1766deef 100644 --- a/docs/widget_system.txt +++ b/docs/widget_system.txt @@ -31,11 +31,11 @@ new widgets. Main outline: - Owen Taylor <owt1@cornell.edu> - 98/02/03 + 1998/02/03 Flag descriptions: - Tim Janik <timj@gimp.org> - 98/02/04 + 1998/02/04 I. Flags -------- |