From a8fb1cf162ecd89e09c90a4df4c1bbbf8f0b76c5 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 17 Oct 2001 21:41:47 +0000 Subject: [PATCH] Documentation updates. Updates. * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c: Documentation updates. * gtk/tmpl/gtkdnd.sgml, gtk/tmpl/gtkclipboard.sgml, gdk/tmpl/general.sgml, gdk/tmpl/threads.sgml, gdk/tmpl/x_interaction.sgml: Updates. --- ChangeLog | 5 +++ ChangeLog.pre-2-0 | 5 +++ ChangeLog.pre-2-10 | 5 +++ ChangeLog.pre-2-2 | 5 +++ ChangeLog.pre-2-4 | 5 +++ ChangeLog.pre-2-6 | 5 +++ ChangeLog.pre-2-8 | 5 +++ docs/reference/ChangeLog | 6 +++ docs/reference/gdk/tmpl/general.sgml | 6 +-- docs/reference/gdk/tmpl/threads.sgml | 41 ++++++++++++++++---- docs/reference/gdk/tmpl/x_interaction.sgml | 29 +++++++------- docs/reference/gtk/tmpl/gtkclipboard.sgml | 6 +-- docs/reference/gtk/tmpl/gtkdnd.sgml | 45 +++++++++++----------- gtk/gtkclipboard.c | 24 ++++++------ gtk/gtkdnd.c | 27 +++++++------ 15 files changed, 144 insertions(+), 75 deletions(-) diff --git a/ChangeLog b/ChangeLog index 5e87abde0c..8daf939591 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2001-10-17 Matthias Clasen + + * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c: + Documentation updates. + Wed Oct 17 15:17:20 2001 Owen Taylor * gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 5e87abde0c..8daf939591 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,8 @@ +2001-10-17 Matthias Clasen + + * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c: + Documentation updates. + Wed Oct 17 15:17:20 2001 Owen Taylor * gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 5e87abde0c..8daf939591 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,8 @@ +2001-10-17 Matthias Clasen + + * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c: + Documentation updates. + Wed Oct 17 15:17:20 2001 Owen Taylor * gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 5e87abde0c..8daf939591 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,8 @@ +2001-10-17 Matthias Clasen + + * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c: + Documentation updates. + Wed Oct 17 15:17:20 2001 Owen Taylor * gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 5e87abde0c..8daf939591 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,8 @@ +2001-10-17 Matthias Clasen + + * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c: + Documentation updates. + Wed Oct 17 15:17:20 2001 Owen Taylor * gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 5e87abde0c..8daf939591 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,8 @@ +2001-10-17 Matthias Clasen + + * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c: + Documentation updates. + Wed Oct 17 15:17:20 2001 Owen Taylor * gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 5e87abde0c..8daf939591 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,8 @@ +2001-10-17 Matthias Clasen + + * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c: + Documentation updates. + Wed Oct 17 15:17:20 2001 Owen Taylor * gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index a33a344289..98c492c516 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +2001-10-17 Matthias Clasen + + * gtk/tmpl/gtkdnd.sgml, gtk/tmpl/gtkclipboard.sgml, + gdk/tmpl/general.sgml, gdk/tmpl/threads.sgml, + gdk/tmpl/x_interaction.sgml: Updates. + 2001-10-13 Matthias Clasen * gdk/tmpl/x_interaction.sgml: Update. diff --git a/docs/reference/gdk/tmpl/general.sgml b/docs/reference/gdk/tmpl/general.sgml index 92c429a57b..3908c48299 100644 --- a/docs/reference/gdk/tmpl/general.sgml +++ b/docs/reference/gdk/tmpl/general.sgml @@ -369,21 +369,21 @@ Removes the X error trap installed with gdk_error_trap_push(). - +This macro is defined if GDK is configured to use the X backend. - +This macro is defined if GDK is configured to use the Win32 backend. - +This macro is defined if GDK is configured to use the Linux framebuffer backend. diff --git a/docs/reference/gdk/tmpl/threads.sgml b/docs/reference/gdk/tmpl/threads.sgml index 5e7e049abb..59a79ee86c 100644 --- a/docs/reference/gdk/tmpl/threads.sgml +++ b/docs/reference/gdk/tmpl/threads.sgml @@ -2,11 +2,33 @@ Threads - +functions for using GDK in multi-threaded programs - +For thread safety, GDK relies on the thread primitives in GLib, +and on the thread-safe GLib main loop. + + +You must call g_thread_init() before executing any other GTK+ or GDK +functions in a threaded GTK+ program. + + +Idles, timeouts, and input functions are executed outside +of the main GTK+ lock. So, if you need to call GTK+ +inside of such a callback, you must surround the callback +with a gdk_threads_enter()/gdk_threads_leave() pair. +(However, signals are still executed within the main +GTK+ lock.) + + +In particular, this means, if you are writing widgets that might +be used in threaded programs, you must surround +timeouts and idle functions in this matter. + + +As always, you must also surround any calls to GTK+ not made within +a signal handler with a gdk_threads_enter()/gdk_threads_leave() pair. @@ -16,35 +38,40 @@ Threads - +This macro marks the begin of a critical section +in which GDK and GTK+ functions can be called. +Only one thread at a time can be in such a critial +section. - +This macro marks the end of a critical section +begun with #GDK_THREADS_ENTER. - +Enters a critical region like #GDK_THREADS_ENTER. - +Leaves a critical region begun with gdk_threads_enter(). - +The #GMutex used to implement the critical region for +gdk_threads_enter()/gdk_threads_leave(). diff --git a/docs/reference/gdk/tmpl/x_interaction.sgml b/docs/reference/gdk/tmpl/x_interaction.sgml index 0a484e557c..9ac4d7f3f5 100644 --- a/docs/reference/gdk/tmpl/x_interaction.sgml +++ b/docs/reference/gdk/tmpl/x_interaction.sgml @@ -382,28 +382,29 @@ Returns the X font belonging to a #GdkFont. - +Returns the display of a #GdkGC. -@gc: -@Returns: +@gc: a #GdkGC. +@Returns: an Xlib Display*. - +Returns the X GC of a #GdkGC. -@gc: -@Returns: +@gc: a #GdkGC. +@Returns: an Xlib GC. - +Gets the root window of the default screen +(see gdk_x11_get_default_screen()). -@Returns: +@Returns: an Xlib Window. @@ -416,10 +417,12 @@ Returns the X font belonging to a #GdkFont. - +Gets the default GTK+ display. -@Returns: +@Returns: the Xlib Display* for the display + specified in the command line option + or the DISPLAY environment variable. @@ -434,11 +437,11 @@ gdk_x11_grab_server()/gdk_x11_ungrab_server() calls can be nested. - +Returns the display of a #GdkImage. -@image: -@Returns: +@drawable: a #GdkImage. +@Returns: an Xlib Display*. diff --git a/docs/reference/gtk/tmpl/gtkclipboard.sgml b/docs/reference/gtk/tmpl/gtkclipboard.sgml index 1fcefb4b6c..a066dd9f08 100644 --- a/docs/reference/gtk/tmpl/gtkclipboard.sgml +++ b/docs/reference/gtk/tmpl/gtkclipboard.sgml @@ -92,7 +92,7 @@ Storing data on Clipboards. - A function to be called when the results of gtk_clipboard_request_text() + A function to be called when the results of gtk_clipboard_request_contents() are received, or when the request fails. @@ -120,10 +120,10 @@ Storing data on Clipboards. A function that will be called to provide the contents of the selection. If multiple types of data were advertised, the requested type can be determined from the @info parameter or by checking the target field -of @selection_data. If the data could succesfully be converted into +of @selection_data. If the data could successfully be converted into then it should be stored into the @selection_data object by calling gtk_selection_data_set() (or related functions such -as gtk_seletion_data_get().) If no data is set, the requestor +as gtk_selection_data_set_text()). If no data is set, the requestor will be informed that the attempt to get the data failed. diff --git a/docs/reference/gtk/tmpl/gtkdnd.sgml b/docs/reference/gtk/tmpl/gtkdnd.sgml index f278e854af..5d860b9fe7 100644 --- a/docs/reference/gtk/tmpl/gtkdnd.sgml +++ b/docs/reference/gtk/tmpl/gtkdnd.sgml @@ -7,8 +7,8 @@ Functions for controlling drag and drop handling. GTK+ has a rich set of functions for doing inter-process -communication via the drag-and-drop metaphore. GTK+ -can do drag and drop (DND) via multiple protocols. +communication via the drag-and-drop metaphor. GTK+ +can do drag-and-drop (DND) via multiple protocols. The currently supported protocols are the Xdnd and Motif protocols. @@ -49,7 +49,7 @@ of the user for a drag destination site. If set for a widget, GTK+ will draw a highlight on this widget as long as a drag is over this widget - and the wiget drag format and action is accetable. + and the widget drag format and action are acceptable. @@ -59,9 +59,9 @@ of the user for a drag destination site. will check if the drag matches this widget's list of possible targets and actions. If so, GTK+ will call gtk_drag_data_get() on behalf - of the widget. Whether or not the drop is succesful, + of the widget. Whether or not the drop is successful, GTK+ will call gtk_drag_finish(). If the action - was a move, then if the drag was succesful, then + was a move, then if the drag was successful, then %TRUE will be passed for the @delete parameter to gtk_drag_finish(). @@ -84,8 +84,8 @@ of the user for a drag destination site. -The #GtkTargetFlags enumeration is used to specifies -constraints on an entry in a GtkTargetTable. +The #GtkTargetFlags enumeration is used to specify +constraints on an entry in a #GtkTargetTable. %GTK_TARGET_SAME_APP @@ -111,10 +111,10 @@ constraints on an entry in a GtkTargetTable. -Set a widget as a potential drop destination. +Sets a widget as a potential drop destination. -@widget: a widget +@widget: a #GtkWidget @flags: the flags that specify what actions GTK+ should take on behalf of a widget for drops onto that widget. The @targets and @actions fields only are used if %GTK_DEST_DEFAULT_MOTION @@ -128,7 +128,7 @@ Set a widget as a potential drop destination. -Set this widget as a proxy for drops to another window. +Sets this widget as a proxy for drops to another window. @widget: a #GtkWidget @@ -136,13 +136,13 @@ Set this widget as a proxy for drops to another window. @protocol: the drag protocol which the @proxy_window accepts (You can use gdk_drag_get_protocol() to determine this) @use_coordinates: If true, send the same coordinates to the - destination, because it is a embedded + destination, because it is an embedded subwindow. -Clear information about a drop destination set with +Clears information about a drop destination set with gtk_drag_dest_set(). The widget will no longer receive notification of drags. @@ -181,12 +181,12 @@ notification of drags. -Inform the drag source that the drop is finished, and +Informs the drag source that the drop is finished, and that the data of the drag will no longer be required. @context: the drag context. -@success: a flag indicating whether the drop was succesful +@success: a flag indicating whether the drop was successful @del: a flag indicating whether the source should delete the original data. (This should be %TRUE for a move) @time: the timestamp from the "drag_data_drop" signal. @@ -215,19 +215,19 @@ drops. -Determine the source widget for a drag. +Determines the source widget for a drag. @context: a (destination side) drag context. @Returns: if the drag is occurring within a single application, - a pointer to the source widget. Otherwise, NULL. + a pointer to the source widget. Otherwise, %NULL. -Draw a highlight around a widget. This will attach +Draws a highlight around a widget. This will attach handlers to "expose_event" and "draw", so the highlight -will continue to be displayed until gtk_drag_unhighlight +will continue to be displayed until gtk_drag_unhighlight() is called. @@ -236,9 +236,8 @@ is called. -Remove a highlight set by gtk_drag_highlight() from +Removes a highlight set by gtk_drag_highlight() from a widget. -is called. @widget: a widget to remove the highlight from. @@ -246,7 +245,7 @@ is called. -Initiate a drag on the source side. The function +Initiates a drag on the source side. The function only needs to be used when the application is starting drags itself, and is not needed when gtk_drag_source_set() is used. @@ -259,7 +258,7 @@ gtk_drag_source_set() is used. drag. @button: The button the user clicked to start the drag. @event: The event that triggered the start of the - drag. Usually + drag. @Returns: The context for this drag. @@ -384,7 +383,7 @@ widget. The widget must have a window. -Undo the effects of gtk_drag_source_set(). +Undoes the effects of gtk_drag_source_set(). @widget: a #GtkWidget diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c index 9022abb855..df2ef1d3d0 100644 --- a/gtk/gtkclipboard.c +++ b/gtk/gtkclipboard.c @@ -88,10 +88,10 @@ static GQuark clipboards_owned_key_id = 0; /** * gtk_clipboard_get: * @selection: a #GdkAtom which identifies the clipboard - * to use. A value of GDK_NONE here is the + * to use. A value of %GDK_NONE here is the * same as gdk_atom_intern ("CLIPBOARD", FALSE), * and provides the default clipboard. Another - * common value is GDK_SELECTION_PRIMARY, which + * common value is %GDK_SELECTION_PRIMARY, which * identifies the primary X selection. * * Returns the clipboard object for the given selection. @@ -99,7 +99,7 @@ static GQuark clipboards_owned_key_id = 0; * Return value: the appropriate clipboard object. If no * clipboard already exists, a new one will * be created. Once a clipboard object has - * been created, it is persistant for all time. + * been created, it is persistent for all time. **/ GtkClipboard * gtk_clipboard_get (GdkAtom selection) @@ -359,10 +359,10 @@ gtk_clipboard_set_contents (GtkClipboard *clipboard, * @n_targets: number of elements in @targets * @get_func: function to call to get the actual clipboard data * @clear_func: when the clipboard contents are set again, this function will - * be called, and get_func will not be subsequently called. + * be called, and @get_func will not be subsequently called. * @user_data: user data to pass to @get_func and @clear_func. * - * Virtually set the contents of the specified clipboard by providing + * Virtually sets the contents of the specified clipboard by providing * a list of supported formats for the clipboard data and a function * to call to get the actual data when it is requested. * @@ -395,17 +395,17 @@ gtk_clipboard_set_with_data (GtkClipboard *clipboard, * @n_targets: number of elements in @targets * @get_func: function to call to get the actual clipboard data * @clear_func: when the clipboard contents are set again, this function will - * be called, and get_func will not be subsequently called. + * be called, and @get_func will not be subsequently called. * @owner: an object that "owns" the data. This object will be passed * to the callbacks when called. * - * Virtually set the contents of the specified clipboard by providing + * Virtually sets the contents of the specified clipboard by providing * a list of supported formats for the clipboard data and a function * to call to get the actual data when it is requested. * * The difference between this function and gtk_clipboard_set_with_data * is that instead of an generic @user_data pointer, a #GObject is passed - * in. Because of this, + * in. * * Return value: %TRUE if setting the clipboard data succeeded. If setting * the clipboard data failed the provided callback functions @@ -477,7 +477,7 @@ clipboard_unset (GtkClipboard *clipboard) * gtk_clipboard_clear: * @clipboard: a #GtkClipboard * - * Clear the contents of the clipboard. Generally this should only + * Clears the contents of the clipboard. Generally this should only * be called between the time you call gtk_clipboard_set_contents(), * and when the @clear_func you supplied is called. Otherwise, the * clipboard may be owned by someone else. @@ -515,7 +515,7 @@ text_clear_func (GtkClipboard *clipboard, * @len: length of @text, in bytes, or -1, in which case * the length will be determined with strlen(). * - * Set the contents of the clipboard to the given UTF-8 string. GTK+ will + * Sets the contents of the clipboard to the given UTF-8 string. GTK+ will * make a copy of the text and take responsibility for responding * for requests for the text, and for converting the text into * the requested format. @@ -590,7 +590,7 @@ selection_received (GtkWidget *widget, * @target: an atom representing the form into which the clipboard * owner should convert the selection. * @callback: A function to call when the results are received - * (or the retrieval fails.) If the retrieval fails + * (or the retrieval fails). If the retrieval fails * the length field of @selection_data will be * negative. * @user_data: user data to pass to @callback @@ -786,7 +786,7 @@ clipboard_text_received_func (GtkClipboard *clipboard, * the data to be received using the main loop, so events, * timeouts, etc, may be dispatched during the wait. * - * Return value: a newly allocated UTF-8 string which must + * Return value: a newly-allocated UTF-8 string which must * be freed with g_free(), or %NULL if retrieving * the selection data failed. (This could happen * for various reasons, in particular if the diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c index 95a63df5e5..78210ecf10 100644 --- a/gtk/gtkdnd.c +++ b/gtk/gtkdnd.c @@ -1972,8 +1972,8 @@ gtk_drag_source_unset_icon (GtkDragSourceSite *site) * @mask: the transparency mask for an image. * * Sets the icon that will be used for drags from a particular widget - * from a pixmap/mask. GTK+ retains a reference count for the - * arguments, and will release them when they are no longer needed. + * from a pixmap/mask. GTK+ retains references for the arguments, and + * will release them when they are no longer needed. * Use gtk_drag_source_set_icon_pixbuf() instead. **/ void @@ -2012,8 +2012,8 @@ gtk_drag_source_set_icon (GtkWidget *widget, * @pixbuf: the #GdkPixbuf for the drag icon * * Sets the icon that will be used for drags from a particular widget - * from a #GdkPixbuf. GTK+ retains a reference count @pixbuf. - * and will release it when it is no longer needed. + * from a #GdkPixbuf. GTK+ retains a reference for @pixbuf and will + * release it when it is no longer needed. **/ void gtk_drag_source_set_icon_pixbuf (GtkWidget *widget, @@ -2025,8 +2025,7 @@ gtk_drag_source_set_icon_pixbuf (GtkWidget *widget, g_return_if_fail (GDK_IS_PIXBUF (pixbuf)); site = gtk_object_get_data (GTK_OBJECT (widget), "gtk-site-data"); - g_return_if_fail (site != NULL); - + g_return_if_fail (site != NULL); gdk_pixbuf_ref (pixbuf); gtk_drag_source_unset_icon (site); @@ -2038,11 +2037,11 @@ gtk_drag_source_set_icon_pixbuf (GtkWidget *widget, /** * gtk_drag_source_set_icon_stock: * @widget: a #GtkWidget - * @stock: the ID of the stock icon to use.. + * @stock: the ID of the stock icon to use * @size: size at which to render the stock icon * - * Sets the icon that will be used for drags from a particular to - * a stock icon. + * Sets the icon that will be used for drags from a particular source + * to a stock icon. **/ void gtk_drag_source_set_icon_stock (GtkWidget *widget, @@ -2199,7 +2198,7 @@ gtk_drag_set_icon_pixbuf (GdkDragContext *context, } /** - * gtk_drag_set_icon_pixbuf: + * gtk_drag_set_icon_stock: * @context: the context for a drag. (This must be called * with a context for the source side of a drag) * @stock: the ID of the stock icon to use for the drag. @@ -2230,8 +2229,8 @@ gtk_drag_set_icon_stock (GdkDragContext *context, * @hot_x: the X offset within @pixmap of the hotspot. * @hot_y: the Y offset within @pixmap of the hotspot. * - * Sets @pixmap as the icon for a given drag. GTK+ retains a - * reference count for the arguments, and will release them when + * Sets @pixmap as the icon for a given drag. GTK+ retains + * references for the arguments, and will release them when * they are no longer needed. In general, gtk_drag_set_icon_pixbuf() * will be more convenient to use. **/ @@ -2303,10 +2302,10 @@ gtk_drag_set_icon_default (GdkDragContext *context) * @hot_x: The X offset within @widget of the hotspot. * @hot_y: The Y offset within @widget of the hotspot. * - * Changes the default drag icon. GTK+ retains a reference count for the + * Changes the default drag icon. GTK+ retains references for the * arguments, and will release them when they are no longer needed. * This function is obsolete. The default icon should now be changed - * via the stock system by changing the stock pixbuf for GTK_STOCK_DND. + * via the stock system by changing the stock pixbuf for %GTK_STOCK_DND. **/ void gtk_drag_set_default_icon (GdkColormap *colormap,