Commit a8fb1cf1 authored by Matthias Clasen's avatar Matthias Clasen

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.
parent 2c281ef6
2001-10-17 Matthias Clasen <matthiasc@poet.de>
* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
Documentation updates.
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
......
2001-10-17 Matthias Clasen <matthiasc@poet.de>
* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
Documentation updates.
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
......
2001-10-17 Matthias Clasen <matthiasc@poet.de>
* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
Documentation updates.
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
......
2001-10-17 Matthias Clasen <matthiasc@poet.de>
* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
Documentation updates.
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
......
2001-10-17 Matthias Clasen <matthiasc@poet.de>
* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
Documentation updates.
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
......
2001-10-17 Matthias Clasen <matthiasc@poet.de>
* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
Documentation updates.
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
......
2001-10-17 Matthias Clasen <matthiasc@poet.de>
* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
Documentation updates.
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
......
2001-10-17 Matthias Clasen <matthiasc@poet.de>
* 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 <matthiasc@poet.de>
* gdk/tmpl/x_interaction.sgml: Update.
......
......@@ -369,21 +369,21 @@ Removes the X error trap installed with gdk_error_trap_push().
<!-- ##### MACRO GDK_WINDOWING_X11 ##### -->
<para>
This macro is defined if GDK is configured to use the X backend.
</para>
<!-- ##### MACRO GDK_WINDOWING_WIN32 ##### -->
<para>
This macro is defined if GDK is configured to use the Win32 backend.
</para>
<!-- ##### MACRO GDK_WINDOWING_FB ##### -->
<para>
This macro is defined if GDK is configured to use the Linux framebuffer backend.
</para>
......
......@@ -2,11 +2,33 @@
Threads
<!-- ##### SECTION Short_Description ##### -->
functions for using GDK in multi-threaded programs
<!-- ##### SECTION Long_Description ##### -->
<para>
For thread safety, GDK relies on the thread primitives in GLib,
and on the thread-safe GLib main loop.
</para>
<para>
You must call g_thread_init() before executing any other GTK+ or GDK
functions in a threaded GTK+ program.
</para>
<para>
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.)
</para>
<para>
In particular, this means, if you are writing widgets that might
be used in threaded programs, you <emphasis>must</emphasis> surround
timeouts and idle functions in this matter.
</para>
<para>
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.
</para>
<!-- ##### SECTION See_Also ##### -->
......@@ -16,35 +38,40 @@ Threads
<!-- ##### MACRO GDK_THREADS_ENTER ##### -->
<para>
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.
</para>
<!-- ##### MACRO GDK_THREADS_LEAVE ##### -->
<para>
This macro marks the end of a critical section
begun with #GDK_THREADS_ENTER.
</para>
<!-- ##### FUNCTION gdk_threads_enter ##### -->
<para>
Enters a critical region like #GDK_THREADS_ENTER.
</para>
<!-- ##### FUNCTION gdk_threads_leave ##### -->
<para>
Leaves a critical region begun with gdk_threads_enter().
</para>
<!-- ##### VARIABLE gdk_threads_mutex ##### -->
<para>
The #GMutex used to implement the critical region for
gdk_threads_enter()/gdk_threads_leave().
</para>
......@@ -382,28 +382,29 @@ Returns the X font belonging to a #GdkFont.
<!-- ##### FUNCTION gdk_x11_gc_get_xdisplay ##### -->
<para>
Returns the display of a #GdkGC.
</para>
@gc:
@Returns:
@gc: a #GdkGC.
@Returns: an Xlib <type>Display*</type>.
<!-- ##### FUNCTION gdk_x11_gc_get_xgc ##### -->
<para>
Returns the X GC of a #GdkGC.
</para>
@gc:
@Returns:
@gc: a #GdkGC.
@Returns: an Xlib <type>GC</type>.
<!-- ##### FUNCTION gdk_x11_get_default_root_xwindow ##### -->
<para>
Gets the root window of the default screen
(see gdk_x11_get_default_screen()).
</para>
@Returns:
@Returns: an Xlib <type>Window</type>.
<!-- ##### FUNCTION gdk_x11_get_default_screen ##### -->
......@@ -416,10 +417,12 @@ Returns the X font belonging to a #GdkFont.
<!-- ##### FUNCTION gdk_x11_get_default_xdisplay ##### -->
<para>
Gets the default GTK+ display.
</para>
@Returns:
@Returns: the Xlib <type>Display*</type> for the display
specified in the <option>--display</option> command line option
or the <envar>DISPLAY</envar> environment variable.
<!-- ##### FUNCTION gdk_x11_grab_server ##### -->
......@@ -434,11 +437,11 @@ gdk_x11_grab_server()/gdk_x11_ungrab_server() calls can be nested.
<!-- ##### FUNCTION gdk_x11_image_get_xdisplay ##### -->
<para>
Returns the display of a #GdkImage.
</para>
@image:
@Returns:
@drawable: a #GdkImage.
@Returns: an Xlib <type>Display*</type>.
<!-- ##### FUNCTION gdk_x11_image_get_ximage ##### -->
......
......@@ -92,7 +92,7 @@ Storing data on Clipboards.
<!-- ##### USER_FUNCTION GtkClipboardReceivedFunc ##### -->
<para>
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.
</para>
......@@ -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.
</para>
......
......@@ -7,8 +7,8 @@ Functions for controlling drag and drop handling.
<!-- ##### SECTION Long_Description ##### -->
<para>
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.
<entry>
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.</entry>
and the widget drag format and action are acceptable.</entry>
</row>
<row>
......@@ -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().
</entry>
......@@ -84,8 +84,8 @@ of the user for a drag destination site.
<!-- ##### ENUM GtkTargetFlags ##### -->
<para>
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.
</para>
<variablelist>
<varlistentry><term> %GTK_TARGET_SAME_APP </term>
......@@ -111,10 +111,10 @@ constraints on an entry in a GtkTargetTable.
<!-- ##### FUNCTION gtk_drag_dest_set ##### -->
<para>
Set a widget as a potential drop destination.
Sets a widget as a potential drop destination.
</para>
@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.
<!-- ##### FUNCTION gtk_drag_dest_set_proxy ##### -->
<para>
Set this widget as a proxy for drops to another window.
Sets this widget as a proxy for drops to another window.
</para>
@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.
<!-- ##### FUNCTION gtk_drag_dest_unset ##### -->
<para>
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.
</para>
......@@ -181,12 +181,12 @@ notification of drags.
<!-- ##### FUNCTION gtk_drag_finish ##### -->
<para>
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.
</para>
@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.
<!-- ##### FUNCTION gtk_drag_get_source_widget ##### -->
<para>
Determine the source widget for a drag.
Determines the source widget for a drag.
</para>
@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.
<!-- ##### FUNCTION gtk_drag_highlight ##### -->
<para>
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.
</para>
......@@ -236,9 +236,8 @@ is called.
<!-- ##### FUNCTION gtk_drag_unhighlight ##### -->
<para>
Remove a highlight set by gtk_drag_highlight() from
Removes a highlight set by gtk_drag_highlight() from
a widget.
is called.
</para>
@widget: a widget to remove the highlight from.
......@@ -246,7 +245,7 @@ is called.
<!-- ##### FUNCTION gtk_drag_begin ##### -->
<para>
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.
<!-- ##### FUNCTION gtk_drag_source_unset ##### -->
<para>
Undo the effects of gtk_drag_source_set().
Undoes the effects of gtk_drag_source_set().
</para>
@widget: a #GtkWidget
......
......@@ -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
......
......@@ -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,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment