AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-11-09 18:30:08 +00:00
Code Issues Projects Releases Wiki Activity

gdk: add many missing (nullable) return value annotations

Browse Source 
https://bugzilla.gnome.org/show_bug.cgi?id=729834
This commit is contained in:
Evan Nemerson 2014-05-08 12:55:50 -07:00 committed by Matthias Clasen
parent 9187b6bae7
commit 38d2458f53
15 changed files with 120 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
gdk/gdk.c
View File

@ -357,8 +357,9 @@ gdk_get_display (void)
* Gets the display name specified in the command line arguments passed
* to gdk_init() or gdk_parse_args(), if any.
*
* Returns: the display name, if specified explicitly, otherwise %NULL
* this string is owned by GTK+ and must not be modified or freed.
* Returns: (nullable): the display name, if specified explicitly,
* otherwise %NULL this string is owned by GTK+ and must not be
* modified or freed.
*
* Since: 2.2
*/
@ -380,8 +381,8 @@ gdk_get_display_arg_name (void)
* display has previously been set, simply returns that. An internal
* function that should not be used by applications.
*
* Returns: (transfer none): the default display, if it could be
* opened, otherwise %NULL.
* Returns: (nullable) (transfer none): the default display, if it
* could be opened, otherwise %NULL.
**/
GdkDisplay *
gdk_display_open_default_libgtk_only (void)

10
gdk/gdkcursor.c
View File

@ -264,8 +264,8 @@ gdk_cursor_new_for_display (GdkDisplay *display,
* Creates a new cursor by looking up @name in the current cursor
* theme.
*
* Returns: a new #GdkCursor, or %NULL if there is no cursor with
* the given name
* Returns: (nullable): a new #GdkCursor, or %NULL if there is no
* cursor with the given name
*
* Since: 2.8
*/
@ -423,7 +423,8 @@ gdk_cursor_get_display (GdkCursor *cursor)
* on the cursor, GDK may not be able to obtain the image data. In this
* case, %NULL is returned.
*
* Returns: (transfer full): a #GdkPixbuf representing @cursor, or %NULL
* Returns: (nullable) (transfer full): a #GdkPixbuf representing
* @cursor, or %NULL
*
* Since: 2.8
*/
@ -487,7 +488,8 @@ gdk_cursor_get_image (GdkCursor *cursor)
* on the cursor, GDK may not be able to obtain the image data. In this
* case, %NULL is returned.
*
* Returns: (transfer full): a #cairo_surface_t representing @cursor, or %NULL
* Returns: (nullable) (transfer full): a #cairo_surface_t
* representing @cursor, or %NULL
*
* Since: 3.10
*/

17
gdk/gdkdevice.c
View File

@ -505,7 +505,8 @@ gdk_device_get_position (GdkDevice *device,
* function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE,
* unless there is an ongoing grab on them, see gdk_device_grab().
*
* Returns: (transfer none): the #GdkWindow under the device position, or %NULL.
* Returns: (nullable) (transfer none): the #GdkWindow under the
* device position, or %NULL.
*
* Since: 3.0
**/
@ -554,7 +555,8 @@ gdk_device_get_window_at_position_double (GdkDevice *device,
* function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE,
* unless there is an ongoing grab on them, see gdk_device_grab().
*
* Returns: (transfer none): the #GdkWindow under the device position, or %NULL.
* Returns: (nullable) (transfer none): the #GdkWindow under the
* device position, or %NULL.
*
* Since: 3.0
**/
@ -941,7 +943,8 @@ gdk_device_get_display (GdkDevice *device)
* If @device is of type %GDK_DEVICE_TYPE_FLOATING, %NULL will be
* returned, as there is no associated device.
*
* Returns: (transfer none): The associated device, or %NULL
* Returns: (nullable) (transfer none): The associated device, or
* %NULL
*
* Since: 3.0
**/
@ -1001,10 +1004,10 @@ _gdk_device_set_associated_device (GdkDevice *device,
* the list of slave devices attached to it, otherwise it will return
* %NULL
*
* Returns: (transfer container) (element-type GdkDevice): the list of
* slave devices, or %NULL. The list must be freed with
* g_list_free(), the contents of the list are owned by GTK+
* and should not be freed.
* Returns: (nullable) (transfer container) (element-type GdkDevice):
* the list of slave devices, or %NULL. The list must be
* freed with g_list_free(), the contents of the list are
* owned by GTK+ and should not be freed.
**/
GList *
gdk_device_list_slave_devices (GdkDevice *device)

6
gdk/gdkdevicemanager.c
View File

@ -284,9 +284,9 @@ gdk_device_manager_get_property (GObject *object,
*
* Gets the #GdkDisplay associated to @device_manager.
*
* Returns: (transfer none): the #GdkDisplay to which @device_manager is
* associated to, or #NULL. This memory is owned by GDK and
* must not be freed or unreferenced.
* Returns: (nullable) (transfer none): the #GdkDisplay to which
* @device_manager is associated to, or #NULL. This memory is
* owned by GDK and must not be freed or unreferenced.
*
* Since: 3.0
**/

23
gdk/gdkdisplay.c
View File

@ -306,8 +306,9 @@ gdk_display_is_closed (GdkDisplay *display)
* Gets the next #GdkEvent to be processed for @display, fetching events from the
* windowing system if necessary.
*
* Returns: the next #GdkEvent to be processed, or %NULL if no events
* are pending. The returned #GdkEvent should be freed with gdk_event_free().
* Returns: (nullable): the next #GdkEvent to be processed, or %NULL
* if no events are pending. The returned #GdkEvent should be freed
* with gdk_event_free().
*
* Since: 2.2
**/
@ -331,9 +332,9 @@ gdk_display_get_event (GdkDisplay *display)
* not get more events from the windowing system. It only checks the events
* that have already been moved to the GDK event queue.)
*
* Returns: a copy of the first #GdkEvent on the event queue, or %NULL
* if no events are in the queue. The returned #GdkEvent should be freed with
* gdk_event_free().
* Returns: (nullable): a copy of the first #GdkEvent on the event
* queue, or %NULL if no events are in the queue. The returned
* #GdkEvent should be freed with gdk_event_free().
*
* Since: 2.2
**/
@ -585,7 +586,8 @@ gdk_display_get_pointer (GdkDisplay *display,
* if the window under the mouse pointer is not known to GDK (for example,
* belongs to another application).
*
* Returns: (transfer none): the window under the mouse pointer, or %NULL
* Returns: (nullable) (transfer none): the window under the mouse
* pointer, or %NULL
*
* Since: 2.2
*
@ -1390,8 +1392,9 @@ gdk_display_device_is_grabbed (GdkDisplay *display,
*
* Returns the #GdkDeviceManager associated to @display.
*
* Returns: (transfer none): A #GdkDeviceManager, or %NULL. This memory is
* owned by GDK and must not be freed or unreferenced.
* Returns: (nullable) (transfer none): A #GdkDeviceManager, or
* %NULL. This memory is owned by GDK and must not be freed
* or unreferenced.
*
* Since: 3.0
**/
@ -1780,8 +1783,8 @@ gdk_display_get_app_launch_context (GdkDisplay *display)
*
* Opens a display.
*
* Returns: (transfer none): a #GdkDisplay, or %NULL
* if the display could not be opened
* Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if the
* display could not be opened
*
* Since: 2.2
*/

15
gdk/gdkdisplaymanager.c
View File

@ -313,8 +313,8 @@ gdk_display_manager_get (void)
*
* Gets the default #GdkDisplay.
*
* Returns: (transfer none): a #GdkDisplay, or %NULL
* if there is no default display.
* Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if
* there is no default display.
*
* Since: 2.2
*/
@ -331,8 +331,8 @@ gdk_display_manager_get_default_display (GdkDisplayManager *manager)
* function for:
* `gdk_display_manager_get_default_display (gdk_display_manager_get ())`.
*
* Returns: (transfer none): a #GdkDisplay, or %NULL if there is no default
* display.
* Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if
* there is no default display.
*
* Since: 2.2
*/
@ -348,7 +348,8 @@ gdk_display_get_default (void)
* Gets the default screen for the default display. (See
* gdk_display_get_default ()).
*
* Returns: (transfer none): a #GdkScreen, or %NULL if there is no default display.
* Returns: (nullable) (transfer none): a #GdkScreen, or %NULL if
* there is no default display.
*
* Since: 2.2
*/
@ -411,8 +412,8 @@ gdk_display_manager_list_displays (GdkDisplayManager *manager)
*
* Opens a display.
*
* Returns: (transfer none): a #GdkDisplay, or %NULL
* if the display could not be opened
* Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if the
* display could not be opened
*
* Since: 3.0
*/

20
gdk/gdkevents.c
View File

@ -80,7 +80,8 @@ _gdk_event_emit (GdkEvent *event)
* Find the first event on the queue that is not still
* being filled in.
*
* Returns: Pointer to the list node for that event, or NULL.
* Returns: (nullable): Pointer to the list node for that event, or
* %NULL.
**/
GList*
_gdk_event_queue_find_first (GdkDisplay *display)
@ -241,7 +242,7 @@ _gdk_event_queue_remove_link (GdkDisplay *display,
* Removes and returns the first event from the event
* queue that is not still being filled in.
*
* Returns: the event, or %NULL. Ownership is transferred
* Returns: (nullable): the event, or %NULL. Ownership is transferred
* to the caller.
**/
GdkEvent*
@ -406,8 +407,9 @@ gdk_events_pending (void)
* on, fetching events from the windowing system if necessary.
* See gdk_display_get_event().
*
* Returns: the next #GdkEvent to be processed, or %NULL if no events
* are pending. The returned #GdkEvent should be freed with gdk_event_free().
* Returns: (nullable): the next #GdkEvent to be processed, or %NULL
* if no events are pending. The returned #GdkEvent should be freed
* with gdk_event_free().
**/
GdkEvent*
gdk_event_get (void)
@ -435,9 +437,9 @@ gdk_event_get (void)
* If there is an event waiting in the event queue of some open
* display, returns a copy of it. See gdk_display_peek_event().
*
* Returns: a copy of the first #GdkEvent on some event queue, or %NULL if no
* events are in any queues. The returned #GdkEvent should be freed with
* gdk_event_free().
* Returns: (nullable): a copy of the first #GdkEvent on some event
* queue, or %NULL if no events are in any queues. The returned
* #GdkEvent should be freed with gdk_event_free().
**/
GdkEvent*
gdk_event_peek (void)
@ -1509,7 +1511,7 @@ gdk_event_set_device (GdkEvent *event,
* If the event contains a “device” field, this function will return
* it, else it will return %NULL.
*
* Returns: (transfer none): a #GdkDevice, or %NULL.
* Returns: (nullable) (transfer none): a #GdkDevice, or %NULL.
*
* Since: 3.0
**/
@ -1641,7 +1643,7 @@ gdk_event_set_source_device (GdkEvent *event,
* If the event does not contain a device field, this function will
* return %NULL.
*
* Returns: (transfer none): a #GdkDevice, or %NULL.
* Returns: (nullable) (transfer none): a #GdkDevice, or %NULL.
*
* Since: 3.0
**/

10
gdk/gdkframeclock.c
View File

@ -436,7 +436,7 @@ _gdk_frame_clock_begin_frame (GdkFrameClock *frame_clock)
* for the current frame or a recent frame. The #GdkFrameTimings
* object may not yet be complete: see gdk_frame_timings_get_complete().
*
* Returns: the #GdkFrameTimings object for the specified
* Returns: (nullable): the #GdkFrameTimings object for the specified
* frame, or %NULL if it is not available. See
* gdk_frame_clock_get_history_start().
* Since: 3.8
@ -469,10 +469,10 @@ gdk_frame_clock_get_timings (GdkFrameClock *frame_clock,
*
* Gets the frame timings for the current frame.
*
* Returns: the #GdkFrameTimings for the frame currently being
* processed, or even no frame is being processed, for the
* previous frame. Before any frames have been procesed,
* returns %NULL.
* Returns: (nullable): the #GdkFrameTimings for the frame currently
* being processed, or even no frame is being processed, for the
* previous frame. Before any frames have been procesed, returns
* %NULL.
* Since: 3.8
*/
GdkFrameTimings *

6
gdk/gdkkeys.c
View File

@ -680,9 +680,9 @@ gdk_keymap_get_modifier_mask (GdkKeymap *keymap,
* `gdk/gdkkeysyms.h` header file
* but without the leading “GDK_KEY_”.
*
* Returns: (transfer none): a string containing the name of the key,
* or %NULL if @keyval is not a valid key. The string should not be
* modified.
* Returns: (nullable) (transfer none): a string containing the name
* of the key, or %NULL if @keyval is not a valid key. The string
* should not be modified.
*/
gchar *
gdk_keyval_name (guint keyval)

7
gdk/gdkoffscreenwindow.c
View File

@ -321,7 +321,8 @@ gdk_offscreen_window_get_device_state (GdkWindow *window,
* If you need to keep this around over window resizes, you need to
* add a reference to it.
*
* Returns: (transfer none): The offscreen surface, or %NULL if not offscreen
* Returns: (nullable) (transfer none): The offscreen surface, or
* %NULL if not offscreen
*/
cairo_surface_t *
gdk_offscreen_window_get_surface (GdkWindow *window)
@ -608,8 +609,8 @@ gdk_offscreen_window_set_embedder (GdkWindow *window,
*
* Gets the window that @window is embedded in.
*
* Returns: (transfer none): the embedding #GdkWindow, or %NULL
* if @window is not an mbedded offscreen window
* Returns: (nullable) (transfer none): the embedding #GdkWindow, or
* %NULL if @window is not an mbedded offscreen window
*
* Since: 2.18
*/

8
gdk/gdkpixbuf-drawable.c
View File

@ -77,8 +77,8 @@
* (In short, there are several ways this function can fail, and if it fails
* it returns %NULL; so check the return value.)
*
* Returns: (transfer full): A newly-created pixbuf with a reference
* count of 1, or %NULL on error
* Returns: (nullable) (transfer full): A newly-created pixbuf with a
* reference count of 1, or %NULL on error
*/
GdkPixbuf *
gdk_pixbuf_get_from_window (GdkWindow *src,
@ -225,8 +225,8 @@ convert_no_alpha (guchar *dest_data,
* This function will create an RGB pixbuf with 8 bits per channel.
* The pixbuf will contain an alpha channel if the @surface contains one.
*
* Returns: (transfer full): A newly-created pixbuf with a reference
* count of 1, or %NULL on error
* Returns: (nullable) (transfer full): A newly-created pixbuf with a
* reference count of 1, or %NULL on error
*/
GdkPixbuf *
gdk_pixbuf_get_from_surface (cairo_surface_t *surface,

21
gdk/gdkscreen.c
View File

@ -427,8 +427,8 @@ gdk_screen_set_font_options (GdkScreen *screen,
*
* Gets any options previously set with gdk_screen_set_font_options().
*
* Returns: the current font options, or %NULL if no default
* font options have been set.
* Returns: (nullable): the current font options, or %NULL if no
* default font options have been set.
*
* Since: 2.10
**/
@ -760,8 +760,8 @@ gdk_screen_get_monitor_height_mm (GdkScreen *screen,
* Usually something like VGA, DVI, or TV, not the actual
* product name of the display device.
*
* Returns: a newly-allocated string containing the name of the monitor,
* or %NULL if the name cannot be determined
* Returns: (nullable): a newly-allocated string containing the name
* of the monitor, or %NULL if the name cannot be determined
*
* Since: 2.14
*/
@ -899,8 +899,9 @@ gdk_screen_get_system_visual (GdkScreen * screen)
* For setting an overall opacity for a top-level window, see
* gdk_window_set_opacity().
*
* Returns: (transfer none): a visual to use for windows with an
* alpha channel or %NULL if the capability is not available.
* Returns: (nullable) (transfer none): a visual to use for windows
* with an alpha channel or %NULL if the capability is not
* available.
*
* Since: 2.8
**/
@ -974,7 +975,8 @@ gdk_screen_make_display_name (GdkScreen *screen)
* The returned window should be unrefed using g_object_unref() when
* no longer needed.
*
* Returns: (transfer full): the currently active window, or %NULL.
* Returns: (nullable) (transfer full): the currently active window,
* or %NULL.
*
* Since: 2.10
**/
@ -1006,9 +1008,8 @@ gdk_screen_get_active_window (GdkScreen *screen)
* windows it contains, so it should be freed using g_list_free() and
* its windows unrefed using g_object_unref() when no longer needed.
*
* Returns: (transfer full) (element-type GdkWindow):
* a list of #GdkWindows for the current window stack,
* or %NULL.
* Returns: (nullable): (transfer full) (element-type GdkWindow): a
* list of #GdkWindows for the current window stack, or %NULL.
*
* Since: 2.10
**/

29
gdk/gdkselection.c
View File

@ -95,14 +95,12 @@ gdk_selection_owner_set (GdkWindow *owner,
*
* Determines the owner of the given selection.
*
* Returns: (transfer none): if there is a selection owner for
* this window, and it is a window known to the current
* process, the #GdkWindow that owns the selection, otherwise
* %NULL. Note that the return value may be owned
* by a different process if a foreign window
* was previously created for that window, but
* a new foreign window will never be created by
* this call.
* Returns: (nullable) (transfer none): if there is a selection owner
* for this window, and it is a window known to the current process,
* the #GdkWindow that owns the selection, otherwise %NULL. Note
* that the return value may be owned by a different process if a
* foreign window was previously created for that window, but a new
* foreign window will never be created by this call.
*/
GdkWindow*
gdk_selection_owner_get (GdkAtom selection)
@ -179,9 +177,10 @@ gdk_selection_owner_set_for_display (GdkDisplay *display,
* process if a foreign window was previously created for that
* window, but a new foreign window will never be created by this call.
*
* Returns: (transfer none): if there is a selection owner for this window,
* and it is a window known to the current process, the #GdkWindow that
* owns the selection, otherwise %NULL.
* Returns: (nullable): (transfer none): if there is a selection owner
* for this window, and it is a window known to the current
* process, the #GdkWindow that owns the selection, otherwise
* %NULL.
*
* Since: 2.2
*/
@ -318,10 +317,10 @@ gdk_text_property_to_utf8_list_for_display (GdkDisplay *display,
* is not specified; it may be as pseudo-escape sequences
* \x{ABCD}, or it may be in some other form of approximation.
*
* Returns: the newly-allocated string, or %NULL if the
* conversion failed. (It should not fail for
* any properly formed UTF-8 string unless system
* limits like memory or file descriptors are exceeded.)
* Returns: (nullable): the newly-allocated string, or %NULL if the
* conversion failed. (It should not fail for any properly
* formed UTF-8 string unless system limits like memory or
* file descriptors are exceeded.)
**/
gchar *
gdk_utf8_to_string_target (const gchar *str)

4
gdk/gdkvisual.c
View File

@ -203,8 +203,8 @@ gdk_visual_get_best_with_type (GdkVisualType visual_type)
* Combines gdk_visual_get_best_with_depth() and
* gdk_visual_get_best_with_type().
*
* Returns: (transfer none): best visual with both @depth and
* @visual_type, or %NULL if none
* Returns: (nullable) (transfer none): best visual with both @depth
* and @visual_type, or %NULL if none
*/
GdkVisual*
gdk_visual_get_best_with_both (gint depth,

40
gdk/gdkwindow.c
View File

@ -329,8 +329,8 @@ gdk_window_class_init (GdkWindowClass *klass)
* The ::pick-embedded-child signal is emitted to find an embedded
* child at the given position.
*
* Returns: (transfer none): the #GdkWindow of the embedded child at
* @x, @y, or %NULL
* Returns: (nullable) (transfer none): the #GdkWindow of the
* embedded child at @x, @y, or %NULL
*
* Since: 2.18
*/
@ -4412,9 +4412,9 @@ gdk_window_constrain_size (GdkGeometry *geometry,
* The position is given in coordinates relative to the upper left
* corner of @window.
*
* Returns: (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
* Returns: (nullable) (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
*
* Deprecated: 3.0: Use gdk_window_get_device_position() instead.
**/
@ -4445,8 +4445,9 @@ gdk_window_get_pointer (GdkWindow *window,
* The position is given in coordinates relative to the upper left
* corner of @window.
*
* Returns: (transfer none): The window underneath @device (as with
* gdk_device_get_window_at_position()), or %NULL if the window is not known to GDK.
* Returns: (nullable) (transfer none): The window underneath @device
* (as with gdk_device_get_window_at_position()), or %NULL if the
* window is not known to GDK.
*
* Since: 3.10
**/
@ -4501,8 +4502,9 @@ gdk_window_get_device_position_double (GdkWindow *window,
*
* Use gdk_window_get_device_position_double() if you need subpixel precision.
*
* Returns: (transfer none): The window underneath @device (as with
* gdk_device_get_window_at_position()), or %NULL if the window is not known to GDK.
* Returns: (nullable) (transfer none): The window underneath @device
* (as with gdk_device_get_window_at_position()), or %NULL if the
* window is not known to GDK.
*
* Since: 3.0
**/
@ -5814,8 +5816,8 @@ gdk_window_set_background_pattern (GdkWindow *window,
* does not have its own background and reuses the parent's, %NULL is
* returned and you’ll have to query it yourself.
*
* Returns: (transfer none): The pattern to use for the background or
* %NULL to use the parent’s background.
* Returns: (nullable) (transfer none): The pattern to use for the
* background or %NULL to use the parent’s background.
*
* Since: 2.22
**/
@ -5860,10 +5862,10 @@ gdk_window_set_cursor_internal (GdkWindow *window,
* there is no custom cursor set on the specified window, and it is
* using the cursor for its parent window.
*
* Returns: (transfer none): a #GdkCursor, or %NULL. The returned
* object is owned by the #GdkWindow and should not be unreferenced
* directly. Use gdk_window_set_cursor() to unset the cursor of the
* window
* Returns: (nullable) (transfer none): a #GdkCursor, or %NULL. The
* returned object is owned by the #GdkWindow and should not be
* unreferenced directly. Use gdk_window_set_cursor() to unset the
* cursor of the window
*
* Since: 2.18
*/
@ -5940,10 +5942,10 @@ gdk_window_set_cursor (GdkWindow *window,
* there is no custom cursor set on the specified window, and it is
* using the cursor for its parent window.
*
* Returns: (transfer none): a #GdkCursor, or %NULL. The returned
* object is owned by the #GdkWindow and should not be unreferenced
* directly. Use gdk_window_set_cursor() to unset the cursor of the
* window
* Returns: (nullable) (transfer none): a #GdkCursor, or %NULL. The
* returned object is owned by the #GdkWindow and should not be
* unreferenced directly. Use gdk_window_set_cursor() to unset the
* cursor of the window
*
* Since: 3.0
**/