Commit f584679c authored by Colin Walters's avatar Colin Walters Committed by Tristan Van Berkom

Merge in Gdk-custom.c introspection annotations

The Gdk-custom.c file in gir-repository contained a number of
introspection annotations.  Merge those into the GDK source files.

Some documentation was moved from the tmpl/ files to accomodate
the addition of annotations.

https://bugzilla.gnome.org/show_bug.cgi?id=592279
parent 41342b23
......@@ -228,15 +228,11 @@ Specifies how an axis of a device is used.
<!-- ##### FUNCTION gdk_device_get_state ##### -->
<para>
Gets the current state of a device.
</para>
@device: a #GdkDevice.
@window: a #GdkWindow.
@axes: an array of doubles to store the values of the axes of @device in,
or %NULL.
@mask: location to store the modifiers, or %NULL.
@device:
@window:
@axes:
@mask:
<!-- ##### FUNCTION gdk_device_get_history ##### -->
......
......@@ -77,76 +77,15 @@ for the new pixmap. Can be %NULL, if the depth is given.
<!-- ##### FUNCTION gdk_pixmap_create_from_xpm ##### -->
<para>
Create a pixmap from a XPM file.
</para>
@drawable: a #GdkDrawable, used to determine default values
for the new pixmap.
@mask: a pointer to a place to store a bitmap representing
the transparency mask of the XPM file. Can be %NULL,
in which case transparency will be ignored.
@transparent_color: the color to be used for the pixels
that are transparent in the input file. Can be %NULL,
in which case a default color will be used.
@filename: the filename of a file containing XPM data.
@Returns: the #GdkPixmap
<!-- ##### FUNCTION gdk_pixmap_colormap_create_from_xpm ##### -->
<para>
Create a pixmap from a XPM file using a particular colormap.
</para>
@drawable: a #GdkDrawable, used to determine default values
for the new pixmap. Can be %NULL if @colormap is given.
@colormap: the #GdkColormap that the new pixmap will be use.
If omitted, the colormap for @window will be used.
@mask: a pointer to a place to store a bitmap representing
the transparency mask of the XPM file. Can be %NULL,
in which case transparency will be ignored.
@transparent_color: the color to be used for the pixels
that are transparent in the input file. Can be %NULL,
in which case a default color will be used.
@filename: the filename of a file containing XPM data.
@Returns: the #GdkPixmap.
<!-- ##### FUNCTION gdk_pixmap_create_from_xpm_d ##### -->
<para>
Create a pixmap from data in XPM format.
</para>
@drawable: a #GdkDrawable, used to determine default values
for the new pixmap.
@mask: Pointer to a place to store a bitmap representing
the transparency mask of the XPM file. Can be %NULL,
in which case transparency will be ignored.
@transparent_color: This color will be used for the pixels
that are transparent in the input file. Can be %NULL
in which case a default color will be used.
@data: Pointer to a string containing the XPM data.
@Returns: the #GdkPixmap
<!-- ##### FUNCTION gdk_pixmap_colormap_create_from_xpm_d ##### -->
<para>
Create a pixmap from data in XPM format using a particular
colormap.
</para>
@drawable: a #GdkDrawable, used to determine default values
for the new pixmap. Can be %NULL if @colormap is given.
@colormap: the #GdkColormap that the new pixmap will be use.
If omitted, the colormap for @window will be used.
@mask: a pointer to a place to store a bitmap representing
the transparency mask of the XPM file. Can be %NULL,
in which case transparency will be ignored.
@transparent_color: the color to be used for the pixels
that are transparent in the input file. Can be %NULL,
in which case a default color will be used.
@data: Pointer to a string containing the XPM data.
@Returns: the #GdkPixmap.
<!-- ##### MACRO gdk_pixmap_ref ##### -->
......
......@@ -338,9 +338,10 @@ gdk_display_open_default_libgtk_only (void)
return display;
}
/*
*--------------------------------------------------------------
* gdk_init_check
/**
* gdk_init_check:
* @argc: (inout):
* @argv: (array length=argc) (inout):
*
* Initialize the library for use.
*
......@@ -359,7 +360,6 @@ gdk_display_open_default_libgtk_only (void)
*
*--------------------------------------------------------------
*/
gboolean
gdk_init_check (int *argc,
char ***argv)
......@@ -369,6 +369,12 @@ gdk_init_check (int *argc,
return gdk_display_open_default_libgtk_only () != NULL;
}
/**
* gdk_init:
* @argc: (inout):
* @argv: (array length=argc) (inout):
*/
void
gdk_init (int *argc, char ***argv)
{
......
......@@ -318,8 +318,8 @@ gdk_color_get_type (void)
/**
* gdk_color_parse:
* @spec: the string specifying the color.
* @color: the #GdkColor to fill in
*
* @color: (out): the #GdkColor to fill in
*
* Parses a textual specification of a color and fill in the
* <structfield>red</structfield>, <structfield>green</structfield>,
* and <structfield>blue</structfield> fields of a #GdkColor
......
......@@ -466,12 +466,12 @@ _gdk_display_enable_motion_hints (GdkDisplay *display)
/**
* gdk_display_get_pointer:
* @display: a #GdkDisplay
* @screen: location to store the screen that the
* @screen: (allow-none): location to store the screen that the
* cursor is on, or %NULL.
* @x: location to store root window X coordinate of pointer, or %NULL.
* @y: location to store root window Y coordinate of pointer, or %NULL.
* @mask: location to store current modifier mask, or %NULL
*
* @x: (out): location to store root window X coordinate of pointer, or %NULL.
* @y: (out): location to store root window Y coordinate of pointer, or %NULL.
* @mask: (out): location to store current modifier mask, or %NULL
*
* Gets the current location of the pointer and the current modifier
* mask for a given display.
*
......@@ -567,17 +567,17 @@ gdk_window_real_window_get_pointer (GdkDisplay *display,
/**
* gdk_display_get_window_at_pointer:
* @display: a #GdkDisplay
* @win_x: return location for x coordinate of the pointer location relative
* @win_x: (out) (allow-none): return location for x coordinate of the pointer location relative
* to the window origin, or %NULL
* @win_y: return location for y coordinate of the pointer location relative
* @win_y: (out) (allow-none): return location for y coordinate of the pointer location relative
& to the window origin, or %NULL
*
*
* Obtains the window underneath the mouse pointer, returning the location
* of the pointer in that window in @win_x, @win_y for @screen. Returns %NULL
* of the pointer in that window in @win_x, @win_y for @screen. Returns %NULL
* if the window under the mouse pointer is not known to GDK (for example,
* belongs to another application).
*
* Returns: the window under the mouse pointer, or %NULL
*
* Returns: (transfer none): the window under the mouse pointer, or %NULL
*
* Since: 2.2
**/
......
......@@ -147,11 +147,12 @@ gdk_display_manager_get_property (GObject *object,
}
}
/**
/**
* gdk_display_manager_get:
* @returns: the singleton #GdkDisplayManager object.
*
* Returns the global #GdkDisplayManager singleton; gdk_parse_pargs(),
* Gets the singleton #GdkDisplayManager object.
*
* Returns: (transfer none): The global #GdkDisplayManager singleton; gdk_parse_pargs(),
* gdk_init(), or gdk_init_check() must have been called first.
*
* Since: 2.2
......@@ -171,9 +172,9 @@ gdk_display_manager_get (void)
* gdk_display_manager_get_default_display:
* @display_manager: a #GdkDisplayManager
*
* Gets the default #GdkDisplay.
*
* Returns: a #GdkDisplay, or %NULL if there is no default
* Gets the default #GdkDisplay.
*
* Returns: (transfer none): a #GdkDisplay, or %NULL if there is no default
* display.
*
* Since: 2.2
......@@ -190,8 +191,8 @@ gdk_display_manager_get_default_display (GdkDisplayManager *display_manager)
* Gets the default #GdkDisplay. This is a convenience
* function for
* <literal>gdk_display_manager_get_default_display (gdk_display_manager_get ())</literal>.
*
* Returns: a #GdkDisplay, or %NULL if there is no default
*
* Returns: (transfer none): a #GdkDisplay, or %NULL if there is no default
* display.
*
* Since: 2.2
......@@ -207,8 +208,8 @@ gdk_display_get_default (void)
*
* Gets the default screen for the default display. (See
* gdk_display_get_default ()).
*
* Returns: a #GdkScreen, or %NULL if there is no default display.
*
* Returns: (transfer none): a #GdkScreen, or %NULL if there is no default display.
*
* Since: 2.2
*/
......
......@@ -37,11 +37,11 @@
* should be ignored, since it is put up by the drag source as an icon.
* @x_root: the x position of the pointer in root coordinates.
* @y_root: the y position of the pointer in root coordinates.
* @dest_window: location to store the destination window in.
* @protocol: location to store the DND protocol in.
*
* @dest_window: (out): location to store the destination window in.
* @protocol: (out): location to store the DND protocol in.
*
* Finds the destination window and DND protocol to use at the
* given pointer position.
* given pointer position.
*
* This function is called by the drag source to obtain the
* @dest_window and @protocol parameters for gdk_drag_motion().
......
......@@ -142,12 +142,12 @@ gdk_drawable_get_data (GdkDrawable *drawable,
/**
* gdk_drawable_get_size:
* @drawable: a #GdkDrawable
* @width: location to store drawable's width, or %NULL
* @height: location to store drawable's height, or %NULL
* @width: (out): location to store drawable's width, or %NULL
* @height: (out): location to store drawable's height, or %NULL
*
* Fills *@width and *@height with the size of @drawable.
* @width or @height can be %NULL if you only want the other one.
*
*
* On the X11 platform, if @drawable is a #GdkWindow, the returned
* size is the size reported in the most-recently-processed configure
* event, rather than the current size on the X server.
......
......@@ -145,16 +145,19 @@ void gdk_device_set_key (GdkDevice *device,
void gdk_device_set_axis_use (GdkDevice *device,
guint index_,
GdkAxisUse use);
void gdk_device_get_state (GdkDevice *device,
GdkWindow *window,
gdouble *axes,
GdkModifierType *mask);
gboolean gdk_device_get_history (GdkDevice *device,
GdkWindow *window,
guint32 start,
guint32 stop,
GdkTimeCoord ***events,
gint *n_events);
void gdk_device_free_history (GdkTimeCoord **events,
gint n_events);
gboolean gdk_device_get_axis (GdkDevice *device,
......
......@@ -121,12 +121,12 @@ gdk_keymap_init (GdkKeymap *keymap)
/**
* gdk_keyval_convert_case:
* @symbol: a keyval
* @lower: return location for lowercase version of @symbol
* @upper: return location for uppercase version of @symbol
* @lower: (out): return location for lowercase version of @symbol
* @upper: (out): return location for uppercase version of @symbol
*
* Obtains the upper- and lower-case versions of the keyval @symbol.
* Examples of keyvals are #GDK_a, #GDK_Enter, #GDK_F1, etc.
*
*
**/
void
gdk_keyval_convert_case (guint symbol,
......
......@@ -672,6 +672,24 @@ gdk_pixmap_colormap_new_from_pixbuf (GdkColormap *colormap,
return pixmap;
}
/**
* gdk_pixmap_colormap_create_from_xpm:
* @drawable: a #GdkDrawable, used to determine default values
* for the new pixmap. Can be %NULL if @colormap is given.
* @colormap: the #GdkColormap that the new pixmap will be use.
* If omitted, the colormap for @window will be used.
* @mask: a pointer to a place to store a bitmap representing
* the transparency mask of the XPM file. Can be %NULL,
* in which case transparency will be ignored.
* @transparent_color: the color to be used for the pixels
* that are transparent in the input file. Can be %NULL,
* in which case a default color will be used.
* @filename: the filename of a file containing XPM data.
*
* Create a pixmap from a XPM file using a particular colormap.
*
* Returns: (transfer none): the #GdkPixmap.
*/
GdkPixmap*
gdk_pixmap_colormap_create_from_xpm (GdkDrawable *drawable,
GdkColormap *colormap,
......@@ -700,6 +718,22 @@ gdk_pixmap_colormap_create_from_xpm (GdkDrawable *drawable,
return pixmap;
}
/**
* gdk_pixmap_create_from_xpm:
* @drawable: a #GdkDrawable, used to determine default values
* for the new pixmap.
* @mask: (out) a pointer to a place to store a bitmap representing
* the transparency mask of the XPM file. Can be %NULL,
* in which case transparency will be ignored.
* @transparent_color: the color to be used for the pixels
* that are transparent in the input file. Can be %NULL,
* in which case a default color will be used.
* @filename: the filename of a file containing XPM data.
*
* Create a pixmap from a XPM file.
*
* Returns: (transfer none): the #GdkPixmap
*/
GdkPixmap*
gdk_pixmap_create_from_xpm (GdkDrawable *drawable,
GdkBitmap **mask,
......@@ -710,6 +744,23 @@ gdk_pixmap_create_from_xpm (GdkDrawable *drawable,
transparent_color, filename);
}
/**
* gdk_pixmap_colormap_create_from_xpm_d:
* @drawable: a #GdkDrawable, used to determine default values
* for the new pixmap. Can be %NULL if @colormap is given.
* @colormap: the #GdkColormap that the new pixmap will be use.
* If omitted, the colormap for @window will be used.
* @mask: a pointer to a place to store a bitmap representing
* the transparency mask of the XPM file. Can be %NULL,
* in which case transparency will be ignored.
* @transparent_color: the color to be used for the pixels
* that are transparent in the input file. Can be %NULL,
* in which case a default color will be used.
* @data: Pointer to a string containing the XPM data.
*
* Create a pixmap from data in XPM format using a particular
* colormap.
*/
GdkPixmap*
gdk_pixmap_colormap_create_from_xpm_d (GdkDrawable *drawable,
GdkColormap *colormap,
......@@ -738,6 +789,22 @@ gdk_pixmap_colormap_create_from_xpm_d (GdkDrawable *drawable,
return pixmap;
}
/**
* gdk_pixmap_create_from_xpm_d:
* @drawable: a #GdkDrawable, used to determine default values
* for the new pixmap.
* @mask: (out): Pointer to a place to store a bitmap representing
* the transparency mask of the XPM file. Can be %NULL,
* in which case transparency will be ignored.
* @transparent_color: This color will be used for the pixels
* that are transparent in the input file. Can be %NULL
* in which case a default color will be used.
* @data: Pointer to a string containing the XPM data.
*
* Create a pixmap from data in XPM format.
*
* Returns: (transfer none): the #GdkPixmap.
*/
GdkPixmap*
gdk_pixmap_create_from_xpm_d (GdkDrawable *drawable,
GdkBitmap **mask,
......
......@@ -226,7 +226,7 @@ gdk_region_get_clipbox (const GdkRegion *region,
/**
* gdk_region_get_rectangles:
* @region: a #GdkRegion
* @rectangles: return location for an array of rectangles
* @rectangles: (array length=n_rectangles) (transfer container): return location for an array of rectangles
* @n_rectangles: length of returned array
*
* Obtains the area covered by the region as a list of rectangles.
......
......@@ -1256,7 +1256,7 @@ sync_native_window_stack_position (GdkWindow *window)
/**
* gdk_window_new:
* @parent: a #GdkWindow, or %NULL to create the window as a child of
* @parent: (allow-none): a #GdkWindow, or %NULL to create the window as a child of
* the default root window for the default display.
* @attributes: attributes of the new window
* @attributes_mask: mask indicating which fields in @attributes are valid
......@@ -1266,7 +1266,7 @@ sync_native_window_stack_position (GdkWindow *window)
* more details. Note: to use this on displays other than the default
* display, @parent must be specified.
*
* Return value: the new #GdkWindow
* Return value: (transfer none): the new #GdkWindow
**/
GdkWindow*
gdk_window_new (GdkWindow *parent,
......@@ -3456,12 +3456,12 @@ gdk_window_get_offsets (GdkWindow *window,
/**
* gdk_window_get_internal_paint_info:
* @window: a #GdkWindow
* @real_drawable: location to store the drawable to which drawing should be
* @real_drawable: (out): location to store the drawable to which drawing should be
* done.
* @x_offset: location to store the X offset between coordinates in @window,
* @x_offset: (out): location to store the X offset between coordinates in @window,
* and the underlying window system primitive coordinates for
* *@real_drawable.
* @y_offset: location to store the Y offset between coordinates in @window,
* @y_offset: (out): location to store the Y offset between coordinates in @window,
* and the underlying window system primitive coordinates for
* *@real_drawable.
*
......@@ -6199,18 +6199,18 @@ gdk_window_constrain_size (GdkGeometry *geometry,
/**
* gdk_window_get_pointer:
* @window: a #GdkWindow
* @x: return location for X coordinate of pointer or %NULL to not
* @x: (out) (allow-none): return location for X coordinate of pointer or %NULL to not
* return the X coordinate
* @y: return location for Y coordinate of pointer or %NULL to not
* @y: (out) (allow-none): return location for Y coordinate of pointer or %NULL to not
* return the Y coordinate
* @mask: return location for modifier mask or %NULL to not return the
* @mask: (out) (allow-none): return location for modifier mask or %NULL to not return the
* modifier mask
*
* Obtains the current pointer position and modifier state.
* The position is given in coordinates relative to the upper left
* corner of @window.
*
* Return value: the window containing the pointer (as with
* Return value: (transfer none): the window containing the pointer (as with
* gdk_window_at_pointer()), or %NULL if the window containing the
* pointer isn't known to GDK
**/
......@@ -6259,8 +6259,8 @@ gdk_window_get_pointer (GdkWindow *window,
/**
* gdk_window_at_pointer:
* @win_x: return location for origin of the window under the pointer
* @win_y: return location for origin of the window under the pointer
* @win_x: (out) (allow-none): return location for origin of the window under the pointer
* @win_y: (out) (allow-none): return location for origin of the window under the pointer
*
* Obtains the window underneath the mouse pointer, returning the
* location of that window in @win_x, @win_y. Returns %NULL if the
......@@ -6271,7 +6271,7 @@ gdk_window_get_pointer (GdkWindow *window,
* NOTE: For multihead-aware widgets or applications use
* gdk_display_get_window_at_pointer() instead.
*
* Return value: window under the mouse pointer
* Return value: (transfer none): window under the mouse pointer
**/
GdkWindow*
gdk_window_at_pointer (gint *win_x,
......
......@@ -1035,8 +1035,8 @@ gdk_display_get_default_cursor_size (GdkDisplay *display)
/**
* gdk_display_get_maximal_cursor_size:
* @display: a #GdkDisplay
* @width: the return location for the maximal cursor width
* @height: the return location for the maximal cursor height
* @width: (out): the return location for the maximal cursor width
* @height: (out): the return location for the maximal cursor height
*
* Gets the maximal size to use for cursors on @display.
*
......
......@@ -3170,11 +3170,11 @@ drag_context_find_window_cache (GdkDragContext *context,
* @screen: the screen where the destination window is sought.
* @x_root: the x position of the pointer in root coordinates.
* @y_root: the y position of the pointer in root coordinates.
* @dest_window: location to store the destination window in.
* @protocol: location to store the DND protocol in.
*
* @dest_window: (out): location to store the destination window in.
* @protocol: (out): location to store the DND protocol in.
*
* Finds the destination window and DND protocol to use at the
* given pointer position.
* given pointer position.
*
* This function is called by the drag source to obtain the
* @dest_window and @protocol parameters for gdk_drag_motion().
......
......@@ -858,6 +858,16 @@ _gdk_device_get_history (GdkDevice *device,
return FALSE;
}
/**
* gdk_device_get_state:
* @device: a #GdkDevice.
* @window: a #GdkWindow.
* @axes: an array of doubles to store the values of the axes of @device in,
* or %NULL.
* @mask: location to store the modifiers, or %NULL.
*
* Gets the current state of a device.
*/
void
gdk_device_get_state (GdkDevice *device,
GdkWindow *window,
......
......@@ -243,7 +243,7 @@ impl_coord_in_window (GdkWindow *window,
* @window: the window with respect to which which the event coordinates will be reported
* @start: starting timestamp for range of events to return
* @stop: ending timestamp for the range of events to return
* @events: location to store a newly-allocated array of #GdkTimeCoord, or %NULL
* @events: (array length=n_events) (out) (transfer none): location to store a newly-allocated array of #GdkTimeCoord, or %NULL
* @n_events: location to store the length of @events, or %NULL
*
* Obtains the motion history for a device; given a starting and
......@@ -351,6 +351,13 @@ _gdk_device_allocate_history (GdkDevice *device,
return result;
}
/**
* gdk_device_free_history:
* @events: (inout) (transfer none): an array of #GdkTimeCoord.
* @n_events: the length of the array.
*
* Frees an array of #GdkTimeCoord that was returned by gdk_device_get_history().
*/
void
gdk_device_free_history (GdkTimeCoord **events,
gint n_events)
......
......@@ -834,11 +834,11 @@ gdk_keymap_get_caps_lock_state (GdkKeymap *keymap)
/**
* gdk_keymap_get_entries_for_keyval:
* @keymap: a #GdkKeymap, or %NULL to use the default keymap
* @keymap: (allow-none): a #GdkKeymap, or %NULL to use the default keymap
* @keyval: a keyval, such as %GDK_a, %GDK_Up, %GDK_Return, etc.
* @keys: return location for an array of #GdkKeymapKey
* @n_keys: return location for number of elements in returned array
*
* @keys: (out): return location for an array of #GdkKeymapKey
* @n_keys: (out): return location for number of elements in returned array
*
* Obtains a list of keycode/group/level combinations that will
* generate @keyval. Groups and levels are two kinds of keyboard mode;
* in general, the level determines whether the top or bottom symbol
......@@ -984,10 +984,10 @@ gdk_keymap_get_entries_for_keyval (GdkKeymap *keymap,
/**
* gdk_keymap_get_entries_for_keycode:
* @keymap: a #GdkKeymap or %NULL to use the default keymap
* @keymap: (allow-none): a #GdkKeymap or %NULL to use the default keymap
* @hardware_keycode: a keycode
* @keys: return location for array of #GdkKeymapKey, or %NULL
* @keyvals: return location for array of keyvals, or %NULL
* @keys: (out): return location for array of #GdkKeymapKey, or %NULL
* @keyvals: (out): return location for array of keyvals, or %NULL
* @n_entries: length of @keys and @keyvals
*
* Returns the keyvals bound to @hardware_keycode.
......@@ -1409,14 +1409,14 @@ translate_keysym (GdkKeymapX11 *keymap_x11,
/**
* gdk_keymap_translate_keyboard_state:
* @keymap: a #GdkKeymap, or %NULL to use the default
* @keymap: (allow-none): a #GdkKeymap, or %NULL to use the default
* @hardware_keycode: a keycode
* @state: a modifier state
* @state: a modifier state
* @group: active keyboard group
* @keyval: return location for keyval, or %NULL
* @effective_group: return location for effective group, or %NULL
* @level: return location for level, or %NULL
* @consumed_modifiers: return location for modifiers that were used to
* @keyval: (out) (allow-none): return location for keyval, or %NULL
* @effective_group: (out) (allow-none): return location for effective group, or %NULL
* @level: (out) (allow-none): return location for level, or %NULL
* @consumed_modifiers: (out) (allow-none): return location for modifiers that were used to
* determine the group or level, or %NULL
*
* Translates the contents of a #GdkEventKey into a keyval, effective
......
......@@ -214,9 +214,9 @@ gdk_screen_get_number (GdkScreen *screen)
* gdk_screen_get_root_window:
* @screen: a #GdkScreen
*
* Gets the root window of @screen.
*
* Returns: the root window
* Gets the root window of @screen.
*
* Returns: (transfer none): the root window
*
* Since: 2.2
**/
......
......@@ -466,8 +466,8 @@ gdk_visual_get_best_with_both (gint depth,
/**
* gdk_query_depths:
* @depths: return location for available depths
* @count: return location for number of available depths
* @depths: (out) (array): return location for available depths
* @count: (out): return location for number of available depths
*
* This function returns the available bit depths for the default
* screen. It's equivalent to listing the visuals
......
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