Commit 38d2458f authored by Evan Nemerson's avatar Evan Nemerson Committed by Matthias Clasen

gdk: add many missing (nullable) return value annotations

https://bugzilla.gnome.org/show_bug.cgi?id=729834
parent 9187b6ba
......@@ -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)
......
......@@ -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
*/
......
......@@ -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)
......
......@@ -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
**/
......
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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
**/
......
......@@ -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 *
......
......@@ -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)
......
......@@ -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
*/
......
......@@ -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,
......
......@@ -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
**/
......
......@@ -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)
......
......@@ -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,
......
......@@ -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
**/
......
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