From 4caf4dc7876e81648061b0f37e31fa0c6ddcc4e8 Mon Sep 17 00:00:00 2001 From: Damon Chaplin Date: Wed, 2 Feb 2000 03:23:11 +0000 Subject: [PATCH] rearranged a bit. 2000-02-03 Damon Chaplin * gdk/gdk-sections.txt: rearranged a bit. * gdk/tmpl/event_structs.sgml: updated. * gtk/gtk-sections.txt: added INCLUDE tag for Private Info section. * gdk/tmpl/color_contexts.sgml: added note saying it is deprecated. * gdk/tmpl/dnd.sgml: added note saying read the GTK+ DnD docs. --- docs/reference/ChangeLog | 11 + docs/reference/gdk/gdk-sections.txt | 28 +- docs/reference/gdk/tmpl/color_contexts.sgml | 9 +- docs/reference/gdk/tmpl/dnd.sgml | 11 +- docs/reference/gdk/tmpl/event_structs.sgml | 340 ++++++++++++-------- docs/reference/gdk/tmpl/events.sgml | 4 +- docs/reference/gdk/tmpl/windows.sgml | 6 + docs/reference/gtk/gtk-sections.txt | 1 + 8 files changed, 253 insertions(+), 157 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 320c8cd2b2..7488baa57d 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,14 @@ +2000-02-03 Damon Chaplin + + * gdk/gdk-sections.txt: rearranged a bit. + + * gdk/tmpl/event_structs.sgml: updated. + + * gtk/gtk-sections.txt: added INCLUDE tag for Private Info section. + + * gdk/tmpl/color_contexts.sgml: added note saying it is deprecated. + * gdk/tmpl/dnd.sgml: added note saying read the GTK+ DnD docs. + 2000-02-02 Damon Chaplin * gdk/tmpl/*.sgml: ran make templates. diff --git a/docs/reference/gdk/gdk-sections.txt b/docs/reference/gdk/gdk-sections.txt index 9f84c81067..18ea372c96 100644 --- a/docs/reference/gdk/gdk-sections.txt +++ b/docs/reference/gdk/gdk-sections.txt @@ -306,6 +306,7 @@ gdk_window_add_filter gdk_window_remove_filter GdkFilterFunc GdkFilterReturn +GdkXEvent gdk_window_shape_combine_mask gdk_window_set_child_shapes gdk_window_merge_child_shapes @@ -552,27 +553,30 @@ gdk_set_show_events
Event Structures event_structs +GdkEvent + + GdkEventAny -GdkEventExpose -GdkEventNoExpose -GdkEventVisibility -GdkVisibilityState -GdkEventMotion -GdkEventButton GdkEventKey +GdkEventButton +GdkEventMotion +GdkEventExpose +GdkEventVisibility GdkEventCrossing -GdkCrossingMode -GdkNotifyType GdkEventFocus GdkEventConfigure GdkEventProperty -GdkPropertyState GdkEventSelection +GdkEventDND GdkEventProximity GdkEventClient -GdkEventDND -GdkEvent -GdkXEvent +GdkEventNoExpose + + +GdkVisibilityState +GdkCrossingMode +GdkNotifyType +GdkPropertyState
diff --git a/docs/reference/gdk/tmpl/color_contexts.sgml b/docs/reference/gdk/tmpl/color_contexts.sgml index 506b77f517..af6455024c 100644 --- a/docs/reference/gdk/tmpl/color_contexts.sgml +++ b/docs/reference/gdk/tmpl/color_contexts.sgml @@ -2,11 +2,16 @@ Color Contexts - +routines for allocating colors (deprecated). - +The #GdkColorContext type is used for allocating groups of colors. + + +It is now deprecated in favor of the gdk_colormap_*() functions described in +the Colormaps and Colors +section. diff --git a/docs/reference/gdk/tmpl/dnd.sgml b/docs/reference/gdk/tmpl/dnd.sgml index 1d7110169f..c61ad4c6f3 100644 --- a/docs/reference/gdk/tmpl/dnd.sgml +++ b/docs/reference/gdk/tmpl/dnd.sgml @@ -2,11 +2,18 @@ Drag and Drop - +functions for controlling drag and drop handling. - +These functions provide a low level interface for drag and drop. +GDK supports both the Xdnd and Motif drag and drop protocols transparently. + + +GTK+ provides a higher level abstraction based on top of these functions, +and so they are not normally needed in GTK+ applications. +See the Drag and Drop section of +the GTK+ documentation for more information. diff --git a/docs/reference/gdk/tmpl/event_structs.sgml b/docs/reference/gdk/tmpl/event_structs.sgml index 75961e8b31..b5a9d13445 100644 --- a/docs/reference/gdk/tmpl/event_structs.sgml +++ b/docs/reference/gdk/tmpl/event_structs.sgml @@ -2,11 +2,11 @@ Event Structures - +data structures specific to each type of event. - +The event structs contain data specific to each type of event in GDK. @@ -20,75 +20,81 @@ required events are received. See gtk_widget_set_events(). + + +The #GdkEvent struct contains a union of all of the event structs, +and allows access to the data fields in a number of ways. + + +The event type is always the first field in all of the event structs, and +can always be accessed with the following code, no matter what type of event +it is: + + + GdkEvent *event; + GdkEventType type; + + type = event->type; + + + + + +To access other fields of the event structs, the pointer to the event can be +cast to the appropriate event struct pointer, or the union member name can be +used. For example if the event type is %GDK_BUTTON_PRESS then the x coordinate +of the button press can be accessed with: + + + GdkEvent *event; + gdouble x; + + x = ((GdkEventButton*)event)->x; + + +or: + + + GdkEvent *event; + gdouble x; + + x = event->button.x; + + + + + Contains the fields which are common to all event structs. -Any event can safely be cast to a #GdkEventAny to access these fields. +Any event pointer can safely be cast to a pointer to a #GdkEventAny to access +these fields. @type: the type of the event. @window: the window which received the event. @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). - + - +Describes a key press or key release event. -@type: -@window: -@send_event: -@area: -@count: - - - - - - -@type: -@window: -@send_event: - - - - - - -@type: -@window: -@send_event: -@state: - - - - - - -@GDK_VISIBILITY_UNOBSCURED: -@GDK_VISIBILITY_PARTIAL: -@GDK_VISIBILITY_FULLY_OBSCURED: - - - - - - -@type: -@window: -@send_event: -@time: -@x: -@y: -@pressure: -@xtilt: -@ytilt: -@state: -@is_hint: -@source: -@deviceid: -@x_root: -@y_root: +@type: the type of the event (%GDK_KEY_RELEASE or %GDK_KEY_RELEASE). +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). +@time: the time of the event in milliseconds. +@state: a bit-mask representing the state of the modifier keys (e.g. Control, +Shift and Alt) and the pointer buttons. See #GdkModifierType. +@keyval: the key that was pressed or released. See the <gdk/gdkkeysym.h> +header file for a complete list of GDK key codes. +@length: the length of @string. +@string: a null-terminated multi-byte string containing the composed characters +resulting from the key press. When text is being input, in a GtkEntry for +example, it is these characters which should be added to the input buffer. +When using Input Methods to support +internationalized text input, the composed characters appear here after the +pre-editing has been completed. @@ -97,7 +103,7 @@ Used for button press and button release events. The %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, and %GDK_BUTTON_RELEASE. -Double and treble-clicks result in a sequence of events being received. +Double and triple-clicks result in a sequence of events being received. For double-clicks the order of events will be: %GDK_BUTTON_PRESS @@ -111,7 +117,7 @@ button press, while the second click results in a %GDK_2BUTTON_PRESS being received just after the %GDK_BUTTON_PRESS. -Treble-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS +Triple-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS is inserted after the third click. The order of the events is: %GDK_BUTTON_PRESS @@ -124,49 +130,101 @@ is inserted after the third click. The order of the events is: %GDK_BUTTON_RELEASE + +For a double click to occur, the second button press must occur within 1/4 of +a second of the first. For a triple click to occur, the third button press +must also occur within 1/2 second of the first button press. + -@type: the type of the event. +@type: the type of the event (%GDK_BUTTON_PRESS, %GDK_2BUTTON_PRESS, +%GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE). @window: the window which received the event. @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). -@time: the time of the event in milliseconds. This wraps around roughly every -50 days. +@time: the time of the event in milliseconds. @x: the x coordinate of the mouse relative to the window. @y: the y coordinate of the mouse relative to the window. @pressure: the pressure of the button press, intended for input devices such as graphics tablets. It defaults to 0.5. -@xtilt: -@ytilt: -@state: -@button: -@source: -@deviceid: +@xtilt: the horizontal tilt of the input device. Defaults to 0. +@ytilt: the vertical tilt of the input device. Defaults to 0. +@state: a bit-mask representing the state of the modifier keys (e.g. Control, +Shift and Alt) and the pointer buttons. See #GdkModifierType. +@button: the button which was pressed or released, numbered from 1 to 5. +Normally button 1 is the left mouse button, 2 is the middle button, +and 3 is the right button. On 2-button mice, the middle button can often +be simulated by pressing both mouse buttons together. +@source: the input device where the event came from, usually %GDK_SOURCE_MOUSE. +@deviceid: the input device ID, usually %GDK_CORE_POINTER but may be +different if touch screens or graphics tablets are being used. @x_root: the x coordinate of the mouse relative to the root of the screen. @y_root: the y coordinate of the mouse relative to the root of the screen. - + -@type: -@window: -@send_event: +@type: the type of the event. +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). @time: +@x: +@y: +@pressure: +@xtilt: +@ytilt: @state: -@keyval: -@length: -@string: +@is_hint: +@source: +@deviceid: +@x_root: +@y_root: + + + +Generated when all or part of a window becomes visible and needs to be +redrawn. + + +@type: the type of the event (%GDK_EXPOSE). +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). +@area: the area that needs to be redrawn. +@count: the number of contiguous %GDK_EXPOSE events following this one. +The only use for this is "exposure compression", i.e. handling all contiguous +%GDK_EXPOSE events in one go, though GDK performs some exposure compression +so this is not normally needed. + + + +Generated when the window visibility status has changed. + + +@type: the type of the event (%GDK_VISIBILITY_NOTIFY). +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). +@state: the new visibility state (%GDK_VISIBILITY_FULLY_OBSCURED, +%GDK_VISIBILITY_PARTIAL or %GDK_VISIBILITY_UNOBSCURED). + + + +Specifies the visiblity status of a window for a #GdkEventVisibility. + + +@GDK_VISIBILITY_UNOBSCURED: the window is completely visible. +@GDK_VISIBILITY_PARTIAL: the window is partially visible. +@GDK_VISIBILITY_FULLY_OBSCURED: the window is not visible at all. -@type: -@window: -@send_event: +@type: the type of the event. +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). @subwindow: -@time: +@time: the time of the event in milliseconds. @x: @y: @x_root: @@ -199,106 +257,112 @@ as graphics tablets. It defaults to 0.5. - +Describes a change of keyboard focus. -@type: -@window: -@send_event: -@in: +@type: the type of the event (%GDK_FOCUS_CHANGE). +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). +@in: TRUE if the window has gained the keyboard focus, FALSE if it has lost +the focus. - +Generated when a window size or position has changed. -@type: -@window: -@send_event: -@x: -@y: -@width: -@height: +@type: the type of the event (%GDK_CONFIGURE). +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). +@x: the new x coordinate of the window, relative to its parent. +@y: the new y coordinate of the window, relative to its parent. +@width: the new width of the window. +@height: the new height of the window. - +Describes a property change on a window. -@type: -@window: -@send_event: -@atom: -@time: -@state: +@type: the type of the event (%GDK_PROPERTY_NOTIFY). +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). +@atom: the property that was changed. +@time: the time of the event in milliseconds. +@state: whether the property was changed (%GDK_PROPERTY_NEW_VALUE) or +deleted (%GDK_PROPERTY_DELETE). - +Specifies the type of a property change for a #GdkEventProperty. -@GDK_PROPERTY_NEW_VALUE: -@GDK_PROPERTY_DELETE: +@GDK_PROPERTY_NEW_VALUE: the property value wan changed. +@GDK_PROPERTY_DELETE: the property was deleted. -@type: -@window: -@send_event: +@type: the type of the event. +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). @selection: @target: @property: @requestor: -@time: - - - - - - -@type: -@window: -@send_event: -@time: -@source: -@deviceid: - - - - - - -@type: -@window: -@send_event: -@message_type: -@data_format: +@time: the time of the event in milliseconds. -@type: -@window: -@send_event: +@type: the type of the event. +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). @context: -@time: +@time: the time of the event in milliseconds. @x_root: @y_root: - + +@type: the type of the event. +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). +@time: the time of the event in milliseconds. +@source: +@deviceid: - + - +An event sent by another client application. +@type: the type of the event (%GDK_CLIENT_EVENT). +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). +@message_type: the type of the message, which can be defined by the +application. +@data_format: the format of the data, given as the number of bits in each +data element, i.e. 8, 16, or 32. 8-bit data uses the b array of the data +union, 16-bit data uses the s array, and 32-bit data uses the l array. + + + +Generated when the area of a #GdkDrawable being copied, with gdk_draw_pixmap() +or gdk_window_copy_area(), was completely available. + + +FIXME: add more here. + + +@type: the type of the event (%GDK_NO_EXPOSE). +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). diff --git a/docs/reference/gdk/tmpl/events.sgml b/docs/reference/gdk/tmpl/events.sgml index 9a4fe5e96e..dca821ca7e 100644 --- a/docs/reference/gdk/tmpl/events.sgml +++ b/docs/reference/gdk/tmpl/events.sgml @@ -56,9 +56,7 @@ of time. Note that each click also generates a %GDK_BUTTON_PRESS event. @GDK_KEY_RELEASE: a key has been released. @GDK_ENTER_NOTIFY: the pointer has entered the window. @GDK_LEAVE_NOTIFY: the pointer has left the window. -@GDK_FOCUS_CHANGE: the keyboard focus has entered or left the window. Note that -in GTK+ keyboard focus is handled mostly within GTK+ itself, so it is usually -only toplevel windows which receive these events. +@GDK_FOCUS_CHANGE: the keyboard focus has entered or left the window. @GDK_CONFIGURE: the size, position or stacking order of the window has changed. Note that GTK+ discards these events for %GDK_WINDOW_CHILD windows. @GDK_MAP: the window has been mapped. diff --git a/docs/reference/gdk/tmpl/windows.sgml b/docs/reference/gdk/tmpl/windows.sgml index 78addd9666..5a4ddfdf67 100644 --- a/docs/reference/gdk/tmpl/windows.sgml +++ b/docs/reference/gdk/tmpl/windows.sgml @@ -365,6 +365,12 @@ Windows @GDK_FILTER_TRANSLATE: @GDK_FILTER_REMOVE: + + + + + + diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt index fe99b4d45b..aa0908cd7b 100644 --- a/docs/reference/gtk/gtk-sections.txt +++ b/docs/reference/gtk/gtk-sections.txt @@ -2916,6 +2916,7 @@ GtkSortType
gtkprivate Private Information +gtk/gtkprivate.h GtkPrivateFlags GTK_PRIVATE_FLAGS GTK_WIDGET_USER_STYLE