callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clean up and unify docs and formatting

Browse Source
This commit is contained in:
Matthias Clasen
2014-08-16 16:39:21 -04:00
parent d36bba293d
commit 7bec0939a8
1 changed files with 980 additions and 1065 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
gtk/gtkdnd.c
View File

@ -56,14 +56,12 @@
* @Short_description: Functions for controlling drag and drop handling
* @Title: Drag and Drop
*
* GTK+ has a rich set of functions for doing inter-process
* communication via the drag-and-drop metaphor.
* GTK+ has a rich set of functions for doing inter-process communication
* via the drag-and-drop metaphor.
*
* As well as the functions listed here, applications
* may need to use some facilities provided for
* [Selections][gtk3-Selections].
* Also, the Drag and Drop API makes use of signals
* in the #GtkWidget class.
* As well as the functions listed here, applications may need to use some
* facilities provided for [Selections][gtk3-Selections]. Also, the Drag and
* Drop API makes use of signals in the #GtkWidget class.
*/
@ -623,14 +621,12 @@ ungrab_dnd_keys (GtkWidget *widget,
#endif /* GDK_WINDOWING_X11 */
/***************************************************************
/*
* gtk_drag_release_ipc_widget:
* Releases widget retrieved with gtk_drag_get_ipc_widget ()
* arguments:
* widget: the widget to release.
* results:
***************************************************************/
* @widget: the widget to release
*
* Releases widget retrieved with gtk_drag_get_ipc_widget().
*/
static void
gtk_drag_release_ipc_widget (GtkWidget *widget)
{
@ -837,10 +833,10 @@ ensure_drag_cursor_pixbuf (int i)
static void
get_surface_size (cairo_surface_t *surface,
int *width,
int *height)
gint *width,
gint *height)
{
double x_scale, y_scale;
gdouble x_scale, y_scale;
x_scale = y_scale = 1;
@ -1103,12 +1099,12 @@ gtk_drag_update_cursor (GtkDragSourceInfo *info)
/**
* gtk_drag_get_data: (method)
* @widget: the widget that will receive the
* #GtkWidget::drag-data-received signal.
* #GtkWidget::drag-data-received signal
* @context: the drag context
* @target: the target (form of the data) to retrieve.
* @target: the target (form of the data) to retrieve
* @time_: a timestamp for retrieving the data. This will
* generally be the time received in a #GtkWidget::drag-motion"
* or #GtkWidget::drag-drop" signal.
* or #GtkWidget::drag-drop" signal
*
* Gets the data associated with a drag. When the data
* is received or the retrieval fails, GTK+ will emit a
@ -1146,7 +1142,6 @@ gtk_drag_get_data (GtkWidget *widget,
time_);
}
/**
* gtk_drag_get_source_widget: (method)
* @context: a (destination side) drag context
@ -1185,11 +1180,11 @@ gtk_drag_get_source_widget (GdkDragContext *context)
/**
* gtk_drag_finish: (method)
* @context: the drag context.
* @context: the drag context
* @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 #GtkWidget::drag-drop signal.
* @time_: the timestamp from the #GtkWidget::drag-drop signal
*
* Informs the drag source that the drop is finished, and
* that the data of the drag will no longer be required.
@ -1230,16 +1225,6 @@ gtk_drag_finish (GdkDragContext *context,
gdk_drop_finish (context, success, time);
}
/*************************************************************
* gtk_drag_highlight_draw:
* Callback for expose_event for highlighted widgets.
* arguments:
* widget:
* event:
* data:
* results:
*************************************************************/
static gboolean
gtk_drag_highlight_draw (GtkWidget *widget,
cairo_t *cr,
@ -1305,7 +1290,7 @@ gtk_drag_highlight (GtkWidget *widget)
/**
* gtk_drag_unhighlight: (method)
* @widget: a widget to remove the highlight from.
* @widget: a widget to remove the highlight from
*
* Removes a highlight set by gtk_drag_highlight() from
* a widget.
@ -1512,7 +1497,7 @@ gtk_drag_dest_unset (GtkWidget *widget)
* drag-and-drop.
*
* Returns: (transfer none): the #GtkTargetList, or %NULL if none
**/
*/
GtkTargetList*
gtk_drag_dest_get_target_list (GtkWidget *widget)
{
@ -1533,7 +1518,7 @@ gtk_drag_dest_get_target_list (GtkWidget *widget)
* Sets the target types that this widget can accept from drag-and-drop.
* The widget must first be made into a drag destination with
* gtk_drag_dest_set().
**/
*/
void
gtk_drag_dest_set_target_list (GtkWidget *widget,
GtkTargetList *target_list)
@ -1571,7 +1556,7 @@ gtk_drag_dest_set_target_list (GtkWidget *widget,
* gtk_drag_dest_set_target_list().
*
* Since: 2.6
**/
*/
void
gtk_drag_dest_add_text_targets (GtkWidget *widget)
{
@ -1598,7 +1583,7 @@ gtk_drag_dest_add_text_targets (GtkWidget *widget)
* gtk_drag_dest_set_target_list().
*
* Since: 2.6
**/
*/
void
gtk_drag_dest_add_image_targets (GtkWidget *widget)
{
@ -1625,7 +1610,7 @@ gtk_drag_dest_add_image_targets (GtkWidget *widget)
* gtk_drag_dest_set_target_list().
*
* Since: 2.6
**/
*/
void
gtk_drag_dest_add_uri_targets (GtkWidget *widget)
{
@ -1654,7 +1639,7 @@ gtk_drag_dest_add_uri_targets (GtkWidget *widget)
* actions regardless of the targets that the source offers.
*
* Since: 2.10
**/
*/
void
gtk_drag_dest_set_track_motion (GtkWidget *widget,
gboolean track_motion)
@ -1681,7 +1666,7 @@ gtk_drag_dest_set_track_motion (GtkWidget *widget,
* #GtkWidget::drag-motion events
*
* Since: 2.10
**/
*/
gboolean
gtk_drag_dest_get_track_motion (GtkWidget *widget)
{
@ -1697,17 +1682,14 @@ gtk_drag_dest_get_track_motion (GtkWidget *widget)
return FALSE;
}
/*************************************************************
/*
* _gtk_drag_dest_handle_event:
* @toplevel: Toplevel widget that received the event
* @event: the event to handle
*
* Called from widget event handling code on Drag events
* for destinations.
*
* arguments:
* toplevel: Toplevel widget that received the event
* event:
* results:
*************************************************************/
*/
void
_gtk_drag_dest_handle_event (GtkWidget *toplevel,
GdkEvent *event)
@ -1823,7 +1805,7 @@ _gtk_drag_dest_handle_event (GtkWidget *toplevel,
*
* Returns: (transfer none): first target that the source offers
* and the dest can accept, or %GDK_NONE
**/
*/
GdkAtom
gtk_drag_dest_find_target (GtkWidget *widget,
GdkDragContext *context,
@ -1962,12 +1944,6 @@ gtk_drag_selection_received (GtkWidget *widget,
gtk_drag_release_ipc_widget (widget);
}
/*************************************************************
* gtk_drag_find_widget:
* Function used to locate widgets for
* DRAG_MOTION and DROP_START events.
*************************************************************/
static gboolean
gtk_drag_find_widget (GtkWidget *widget,
GdkDragContext *context,
@ -2464,7 +2440,7 @@ gtk_drag_source_site_get_icon_helper (GtkDragSourceSite *site)
return helper;
}
/* Like GtkDragBegin, but also takes a GtkDragSourceSite,
/* Like gtk_drag_begin(), but also takes a GtkDragSourceSite,
* so that we can set the icon from the source site information
*/
static GdkDragContext *
@ -2668,18 +2644,18 @@ gtk_drag_begin_internal (GtkWidget *widget,
/**
* gtk_drag_begin_with_coordinates: (method)
* @widget: the source widget.
* @widget: the source widget
* @targets: The targets (data formats) in which the
* source can provide the data.
* @actions: A bitmask of the allowed drag actions for this drag.
* @button: The button the user clicked to start the drag.
* @event: The event that triggered the start of the drag.
* source can provide the data
* @actions: A bitmask of the allowed drag actions for this drag
* @button: The button the user clicked to start the drag
* @event: The event that triggered the start of the drag
* @x: The initial x coordinate to start dragging from, in the coordinate space
* of @widget. If -1 is passed, the coordinates are retrieved from @event or
* the current pointer position.
* the current pointer position
* @y: The initial y coordinate to start dragging from, in the coordinate space
* of @widget. If -1 is passed, the coordinates are retrieved from @event or
* the current pointer position.
* the current pointer position
*
* 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
@ -2707,10 +2683,10 @@ gtk_drag_begin_internal (GtkWidget *widget,
* (remember to free the event with gdk_event_free() when you are done).
* If you can really not pass a real event, pass #NULL instead.
*
* Returns: (transfer none): the context for this drag.
* Returns: (transfer none): the context for this drag
*
* Since: 3.10
**/
*/
GdkDragContext *
gtk_drag_begin_with_coordinates (GtkWidget *widget,
GtkTargetList *targets,
@ -2730,20 +2706,20 @@ gtk_drag_begin_with_coordinates (GtkWidget *widget,
/**
* gtk_drag_begin: (method)
* @widget: the source widget.
* @widget: the source widget
* @targets: The targets (data formats) in which the
* source can provide the data.
* @actions: A bitmask of the allowed drag actions for this drag.
* @button: The button the user clicked to start the drag.
* @event: The event that triggered the start of the drag.
* source can provide the data
* @actions: A bitmask of the allowed drag actions for this drag
* @button: The button the user clicked to start the drag
* @event: The event that triggered the start of the drag
*
* This is equivalent to gtk_drag_begin_with_coordinates(), passing -1, -1
* as coordinates.
* This function is equivalent to gtk_drag_begin_with_coordinates(),
* passing -1, -1 as coordinates.
*
* Returns: (transfer none): the context for this drag.
* Returns: (transfer none): the context for this drag
*
* Deprecated: 3.10: Use gtk_drag_begin_with_coordinates() instead.
**/
* Deprecated: 3.10: Use gtk_drag_begin_with_coordinates() instead
*/
GdkDragContext *
gtk_drag_begin (GtkWidget *widget,
GtkTargetList *targets,
@ -2763,8 +2739,8 @@ gtk_drag_begin (GtkWidget *widget,
* gtk_drag_source_set: (method)
* @widget: a #GtkWidget
* @start_button_mask: the bitmask of buttons that can start the drag
* @targets: (allow-none) (array length=n_targets): the table of targets that the drag will support,
* may be %NULL
* @targets: (allow-none) (array length=n_targets): the table of targets
* that the drag will support, may be %NULL
* @n_targets: the number of items in @targets
* @actions: the bitmask of possible actions for a drag from this widget
*
@ -2858,7 +2834,7 @@ gtk_drag_source_unset (GtkWidget *widget)
* Returns: (transfer none): the #GtkTargetList, or %NULL if none
*
* Since: 2.4
**/
*/
GtkTargetList *
gtk_drag_source_get_target_list (GtkWidget *widget)
{
@ -2881,7 +2857,7 @@ gtk_drag_source_get_target_list (GtkWidget *widget)
* gtk_drag_source_set().
*
* Since: 2.4
**/
*/
void
gtk_drag_source_set_target_list (GtkWidget *widget,
GtkTargetList *target_list)
@ -2918,7 +2894,7 @@ gtk_drag_source_set_target_list (GtkWidget *widget,
* gtk_drag_source_set_target_list().
*
* Since: 2.6
**/
*/
void
gtk_drag_source_add_text_targets (GtkWidget *widget)
{
@ -2945,7 +2921,7 @@ gtk_drag_source_add_text_targets (GtkWidget *widget)
* gtk_drag_source_set_target_list().
*
* Since: 2.6
**/
*/
void
gtk_drag_source_add_image_targets (GtkWidget *widget)
{
@ -2972,7 +2948,7 @@ gtk_drag_source_add_image_targets (GtkWidget *widget)
* gtk_drag_source_set_target_list().
*
* Since: 2.6
**/
*/
void
gtk_drag_source_add_uri_targets (GtkWidget *widget)
{
@ -2996,7 +2972,7 @@ gtk_drag_source_add_uri_targets (GtkWidget *widget)
* Sets the icon that will be used for drags from a particular widget
* 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,
GdkPixbuf *pixbuf)
@ -3022,7 +2998,7 @@ gtk_drag_source_set_icon_pixbuf (GtkWidget *widget,
* to a stock icon.
*
* Deprecated: 3.10: Use gtk_drag_source_set_icon_name() instead.
**/
*/
void
gtk_drag_source_set_icon_stock (GtkWidget *widget,
const gchar *stock_id)
@ -3047,7 +3023,7 @@ gtk_drag_source_set_icon_stock (GtkWidget *widget,
* to a themed icon. See the docs for #GtkIconTheme for more details.
*
* Since: 2.8
**/
*/
void
gtk_drag_source_set_icon_name (GtkWidget *widget,
const gchar *icon_name)
@ -3072,7 +3048,7 @@ gtk_drag_source_set_icon_name (GtkWidget *widget,
* to @icon. See the docs for #GtkIconTheme for more details.
*
* Since: 3.2
**/
*/
void
gtk_drag_source_set_icon_gicon (GtkWidget *widget,
GIcon *icon)
@ -3348,14 +3324,14 @@ set_icon_helper (GdkDragContext *context,
/**
* gtk_drag_set_icon_pixbuf: (method)
* @context: the context for a drag. (This must be called
* @context: the context for a drag (This must be called
* with a context for the source side of a drag)
* @pixbuf: the #GdkPixbuf to use as the drag icon.
* @hot_x: the X offset within @widget of the hotspot.
* @hot_y: the Y offset within @widget of the hotspot.
* @pixbuf: the #GdkPixbuf to use as the drag icon
* @hot_x: the X offset within @widget of the hotspot
* @hot_y: the Y offset within @widget of the hotspot
*
* Sets @pixbuf as the icon for a given drag.
**/
*/
void
gtk_drag_set_icon_pixbuf (GdkDragContext *context,
GdkPixbuf *pixbuf,
@ -3376,16 +3352,16 @@ gtk_drag_set_icon_pixbuf (GdkDragContext *context,
/**
* gtk_drag_set_icon_stock: (method)
* @context: the context for a drag. (This must be called
* @context: the context for a drag (This must be called
* with a context for the source side of a drag)
* @stock_id: the ID of the stock icon to use for the drag.
* @hot_x: the X offset within the icon of the hotspot.
* @hot_y: the Y offset within the icon of the hotspot.
* @stock_id: the ID of the stock icon to use for the drag
* @hot_x: the X offset within the icon of the hotspot
* @hot_y: the Y offset within the icon of the hotspot
*
* Sets the icon for a given drag from a stock ID.
*
* Deprecated: 3.10: Use gtk_drag_set_icon_name() instead.
**/
*/
void
gtk_drag_set_icon_stock (GdkDragContext *context,
const gchar *stock_id,
@ -3443,7 +3419,7 @@ _gtk_cairo_surface_extents (cairo_surface_t *surface,
/**
* gtk_drag_set_icon_surface: (method)
* @context: the context for a drag. (This must be called
* @context: the context for a drag (This must be called
* with a context for the source side of a drag)
* @surface: the surface to use as icon
*
@ -3455,7 +3431,7 @@ _gtk_cairo_surface_extents (cairo_surface_t *surface,
* cairo_surface_set_device_offset() on @surface. The mouse
* cursor will be positioned at the (0,0) coordinate of the
* surface.
**/
*/
void
gtk_drag_set_icon_surface (GdkDragContext *context,
cairo_surface_t *surface)
@ -3544,7 +3520,7 @@ gtk_drag_set_icon_surface (GdkDragContext *context,
/**
* gtk_drag_set_icon_name: (method)
* @context: the context for a drag. (This must be called
* @context: the context for a drag (This must be called
* with a context for the source side of a drag)
* @icon_name: name of icon to use
* @hot_x: the X offset of the hotspot within the icon
@ -3557,7 +3533,7 @@ gtk_drag_set_icon_surface (GdkDragContext *context,
* @hot_x and @hot_y have to be used with care.
*
* Since: 2.8
**/
*/
void
gtk_drag_set_icon_name (GdkDragContext *context,
const gchar *icon_name,
@ -3578,18 +3554,18 @@ gtk_drag_set_icon_name (GdkDragContext *context,
/**
* gtk_drag_set_icon_gicon: (method)
* @context: the context for a drag. (This must be called
* @context: the context for a drag (This must be called
* with a context for the source side of a drag)
* @icon: a #GIcon
* @hot_x: the X offset of the hotspot within the icon
* @hot_y: the Y offset of the hotspot within the icon
*
* Sets the icon for a given drag from the given @icon. See the
* documentation for gtk_drag_set_icon_name() for more details about
* using icons in drag and drop.
* Sets the icon for a given drag from the given @icon.
* See the documentation for gtk_drag_set_icon_name()
* for more details about using icons in drag and drop.
*
* Since: 3.2
**/
*/
void
gtk_drag_set_icon_gicon (GdkDragContext *context,
GIcon *icon,
@ -3610,12 +3586,12 @@ gtk_drag_set_icon_gicon (GdkDragContext *context,
/**
* gtk_drag_set_icon_default: (method)
* @context: the context for a drag. (This must be called
with a context for the source side of a drag)
* @context: the context for a drag (This must be called
* with a context for the source side of a drag)
*
* Sets the icon for a particular drag to the default
* icon.
**/
*/
void
gtk_drag_set_icon_default (GdkDragContext *context)
{
@ -3624,17 +3600,14 @@ gtk_drag_set_icon_default (GdkDragContext *context)
gtk_drag_set_icon_name (context, "text-x-generic", -2, -2);
}
/*************************************************************
/*
* _gtk_drag_source_handle_event:
* @toplevel: Toplevel widget that received the event
* @event: the event to handle
*
* Called from widget event handling code on Drag events
* for drag sources.
*
* arguments:
* toplevel: Toplevel widget that received the event
* event:
* results:
*************************************************************/
*/
void
_gtk_drag_source_handle_event (GtkWidget *widget,
GdkEvent *event)
@ -3710,15 +3683,6 @@ _gtk_drag_source_handle_event (GtkWidget *widget,
}
}
/*************************************************************
* gtk_drag_source_check_selection:
* Check if we’ve set up handlers/claimed the selection
* for a given drag. If not, add them.
* arguments:
*
* results:
*************************************************************/
static void
gtk_drag_source_check_selection (GtkDragSourceInfo *info,
GdkAtom selection,
@ -3759,16 +3723,8 @@ gtk_drag_source_check_selection (GtkDragSourceInfo *info,
TARGET_DELETE);
}
/*************************************************************
* gtk_drag_drop_finished:
* Clean up from the drag, and display snapback, if necessary.
* arguments:
* info:
* success:
* time:
* results:
*************************************************************/
/* Clean up from the drag, and display snapback, if necessary. */
static void
gtk_drag_drop_finished (GtkDragSourceInfo *info,
GtkDragResult result,
@ -3839,14 +3795,6 @@ gtk_drag_source_release_selections (GtkDragSourceInfo *info,
info->selections = NULL;
}
/*************************************************************
* gtk_drag_drop:
* Send a drop event.
* arguments:
*
* results:
*************************************************************/
static void
gtk_drag_drop (GtkDragSourceInfo *info,
guint32 time)
@ -4197,7 +4145,7 @@ gtk_drag_add_update_idle (GtkDragSourceInfo *info)
}
}
/**
/*
* gtk_drag_update:
* @info: DragSourceInfo for the drag
* @screen: new screen
@ -4207,7 +4155,7 @@ gtk_drag_add_update_idle (GtkDragSourceInfo *info)
*
* Updates the status of the drag; called when the
* cursor moves or the modifier changes
**/
*/
static void
gtk_drag_update (GtkDragSourceInfo *info,
GdkScreen *screen,
@ -4229,18 +4177,12 @@ gtk_drag_update (GtkDragSourceInfo *info,
gtk_drag_add_update_idle (info);
}
/*************************************************************
* gtk_drag_end:
* Called when the user finishes to drag, either by
/* Called when the user finishes to drag, either by
* releasing the mouse, or by pressing Esc.
* arguments:
* info: Source info for the drag
* time: Timestamp for ending the drag
* results:
*************************************************************/
*/
static void
gtk_drag_end (GtkDragSourceInfo *info, guint32 time)
gtk_drag_end (GtkDragSourceInfo *info,
guint32 time)
{
GtkWidget *source_widget = info->widget;
GdkDevice *pointer, *keyboard;
@ -4314,32 +4256,20 @@ gtk_drag_end (GtkDragSourceInfo *info, guint32 time)
}
}
/*************************************************************
* gtk_drag_cancel:
* Called on cancellation of a drag, either by the user
/* Called on cancellation of a drag, either by the user
* or programmatically.
* arguments:
* info: Source info for the drag
* time: Timestamp for ending the drag
* results:
*************************************************************/
*/
static void
gtk_drag_cancel (GtkDragSourceInfo *info, GtkDragResult result, guint32 time)
gtk_drag_cancel (GtkDragSourceInfo *info,
GtkDragResult result,
guint32 time)
{
gtk_drag_end (info, time);
gdk_drag_abort (info->context, time);
gtk_drag_drop_finished (info, result, time);
}
/*************************************************************
* gtk_drag_motion_cb:
* “motion-notify-event” callback during drag.
* arguments:
*
* results:
*************************************************************/
/* “motion-notify-event” callback during drag. */
static gboolean
gtk_drag_motion_cb (GtkWidget *widget,
GdkEventMotion *event,
@ -4365,17 +4295,10 @@ gtk_drag_motion_cb (GtkWidget *widget,
return TRUE;
}
/*************************************************************
* gtk_drag_key_cb:
* “key-press/release-event” callback during drag.
* arguments:
*
* results:
*************************************************************/
#define BIG_STEP 20
#define SMALL_STEP 1
/* “key-press/release-event” callback during drag */
static gboolean
gtk_drag_key_cb (GtkWidget *widget,
GdkEventKey *event,
@ -4503,15 +4426,7 @@ gtk_drag_grab_notify_cb (GtkWidget *widget,
}
}
/*************************************************************
* gtk_drag_button_release_cb:
* “button-release-event” callback during drag.
* arguments:
*
* results:
*************************************************************/
/* “button-release-event” callback during drag */
static gboolean
gtk_drag_button_release_cb (GtkWidget *widget,
GdkEventButton *event,
@ -4564,7 +4479,7 @@ gtk_drag_abort_timeout (gpointer data)
* should trigger the beginning of a drag-and-drop operation.
*
* Returns: %TRUE if the drag threshold has been passed.
**/
*/
gboolean
gtk_drag_check_threshold (GtkWidget *widget,
gint start_x,