From 70cc4b9479943ec95d3b95b1786b79c9bfd2cce0 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Wed, 24 Apr 2013 11:24:11 -0400 Subject: Update annotations from glib git --- gir/gio-2.0.c | 238 +++++++++++++++++++++++++++++++++++++++++++++++++++--- gir/glib-2.0.c | 48 +++++++---- gir/gobject-2.0.c | 31 +++++++ 3 files changed, 290 insertions(+), 27 deletions(-) (limited to 'gir') diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index d78bfdc6..5a92d00c 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -260,6 +260,13 @@ */ +/** + * GBytesIcon:bytes: + * + * The bytes containing the icon. + */ + + /** * GCancellable::cancelled: * @cancellable: a #GCancellable. @@ -4017,6 +4024,19 @@ */ +/** + * SECTION:gbytesicon + * @short_description: An icon stored in memory as a #GBytes + * @include: gio/gio.h + * @see_also: #GIcon, #GLoadableIcon, #GBytes + * + * #GBytesIcon specifies an image held in memory in a common format (usually + * png) to be used as icon. + * + * Since: 2.38 + */ + + /** * SECTION:gcancellable * @short_description: Thread-safe Operation Cancellation Stack @@ -5247,12 +5267,22 @@ * * To check if two #GIcons are equal, see g_icon_equal(). * - * For serializing a #GIcon, use g_icon_to_string() and - * g_icon_new_for_string(). + * For serializing a #GIcon, use g_icon_serialize() and + * g_icon_deserialize(). + * + * If you want to consume #GIcon (for example, in a toolkit) you must + * be prepared to handle at least the three following cases: + * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make + * sense to have fast-paths for other cases (like handling #GdkPixbuf + * directly, for example) but all compliant #GIcon implementations + * outside of GIO must implement #GLoadableIcon. * * If your application or library provides one or more #GIcon - * implementations you need to ensure that each #GType is registered - * with the type system prior to calling g_icon_new_for_string(). + * implementations you need to ensure that your new implementation also + * implements #GLoadableIcon. Additionally, you must provide an + * implementation of g_icon_serialize() that gives a result that is + * understood by g_icon_deserialize(), yielding one of the built-in icon + * types. */ @@ -7641,7 +7671,7 @@ * @include: gio/gio.h * * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load - * their certificate information from a file. It is in interface which + * their certificate information from a file. It is an interface which * TLS library specific subtypes implement. * * Since: 2.30 @@ -8547,6 +8577,38 @@ */ +/** + * g_action_parse_detailed_name: + * @detailed_name: a detailed action name + * @action_name: (out): the action name + * @target_value: (out): the target value, or %NULL for no target + * @error: a pointer to a %NULL #GError, or %NULL + * + * Parses a detailed action name into its separate name and target + * components. + * + * Detailed action names can have three formats. + * + * The first format is used to represent an action name with no target + * value and consists of just an action name containing no whitespace + * nor the characters ':', '(' or ')'. For example: "app.action". + * + * The second format is used to represent an action with a string-typed + * target value. The action name and target value are separated by a + * double colon ("::"). For example: "app.action::target". + * + * The third format is used to represent an action with an + * arbitrarily-typed target value. The target value follows the action + * name, surrounded in parens. For example: "app.action(42)". The + * target value is parsed using g_variant_parse(). If a tuple-typed + * value is desired, it must be specified in the same way, resulting in + * two sets of parens, for example: "app.action((1,2,3))". + * + * Returns: %TRUE if successful, else %FALSE with @error set + * Since: 2.38 + */ + + /** * g_app_info_add_supports_type: * @appinfo: a #GAppInfo. @@ -9493,6 +9555,25 @@ */ +/** + * g_application_mark_busy: + * @application: a #GApplication + * + * Increases the busy count of @application. + * + * Use this function to indicate that the application is busy, for instance + * while a long running operation is pending. + * + * The busy state will be exposed to other processes, so a session shell will + * use that information to indicate the state to the user (e.g. with a + * spinner). + * + * To cancel the busy indication, use g_application_unmark_busy(). + * + * Since: 2.38 + */ + + /** * g_application_new: * @application_id: (allow-none): the application id @@ -9769,6 +9850,22 @@ */ +/** + * g_application_unmark_busy: + * @application: a #GApplication + * + * Decreases the busy count of @application. + * + * When the busy count reaches zero, the new state will be propagated + * to other processes. + * + * This function must only be called to cancel the effect of a previous + * call to g_application_mark_busy(). + * + * Since: 2.38 + */ + + /** * g_async_initable_init_async: * @initable: a #GAsyncInitable. @@ -10500,6 +10597,28 @@ */ +/** + * g_bytes_icon_get_bytes: + * @icon: a #GIcon. + * + * Gets the #GBytes associated with the given @icon. + * + * Returns: (transfer none): a #GBytes, or %NULL. + * Since: 2.38 + */ + + +/** + * g_bytes_icon_new: + * @bytes: a #GBytes. + * + * Creates a new icon for a bytes. + * + * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given @bytes, or %NULL on error. + * Since: 2.38 + */ + + /** * g_cancellable_cancel: * @cancellable: a #GCancellable object. @@ -12963,6 +13082,11 @@ * tracking the name owner of the well-known name and use that when * processing the received signal. * + * If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or + * %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is + * interpreted as part of a namespace or path. The first argument + * of a signal is matched against that part as specified by D-Bus. + * * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe(). * Since: 2.26 */ @@ -17097,6 +17221,7 @@ * Finishes deleting a file started with g_file_delete_async(). * * Virtual: delete_file_finish + * Returns: %TRUE if the file was deleted. %FALSE otherwise. * Since: 2.34 */ @@ -18716,6 +18841,36 @@ */ +/** + * g_file_make_directory_async: + * @file: input #GFile + * @io_priority: the I/O priority of the request + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function + * + * Asynchronously creates a directory. + * + * Virtual: make_directory_async + * Since: 2.38 + */ + + +/** + * g_file_make_directory_finish: + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL + * + * Finishes an asynchronous directory creation, started with + * g_file_make_directory_async(). + * + * Virtual: make_directory_finish + * Returns: %TRUE on successful directory creation, %FALSE otherwise. + * Since: 2.38 + */ + + /** * g_file_make_directory_with_parents: * @file: input #GFile @@ -20196,7 +20351,38 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * + * Virtual: trash + * Returns: %TRUE on successful trash, %FALSE otherwise. + */ + + +/** + * g_file_trash_async: + * @file: input #GFile + * @io_priority: the I/O priority of the request + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function + * + * Asynchronously sends @file to the Trash location, if possible. + * + * Virtual: trash_async + * Since: 2.38 + */ + + +/** + * g_file_trash_finish: + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL + * + * Finishes an asynchronous file trashing operation, started with + * g_file_trash_async(). + * + * Virtual: trash_finish * Returns: %TRUE on successful trash, %FALSE otherwise. + * Since: 2.38 */ @@ -22632,14 +22818,8 @@ * * Sets the "action" and possibly the "target" attribute of @menu_item. * - * If @detailed_action contains a double colon ("::") then it is used as - * a separator between an action name and a target string. In this - * case, this call is equivalent to calling - * g_menu_item_set_action_and_target() with the part before the "::" and - * with a string-type #GVariant containing the part following the "::". - * - * If @detailed_action doesn't contain "::" then the action is set to - * the given string (verbatim) and the target value is unset. + * The format of @detailed_action is the same format parsed by + * g_action_parse_detailed_name(). * * See g_menu_item_set_action_and_target() or * g_menu_item_set_action_and_target_value() for more flexible (but @@ -22652,6 +22832,28 @@ */ +/** + * g_menu_item_set_icon: + * @menu_item: a #GMenuItem + * @icon: a #GIcon, or %NULL + * + * Sets (or unsets) the icon on @menu_item. + * + * This call is the same as calling g_icon_serialize() and using the + * result as the value to g_menu_item_set_attribute_value() for + * %G_MENU_ATTRIBUTE_ICON. + * + * This API is only intended for use with "noun" menu items; things like + * bookmarks or applications in an "Open With" menu. Don't use it on + * menu items corresponding to verbs (eg: stock icons for 'Save' or + * 'Quit'). + * + * If @icon is %NULL then the icon is unset. + * + * Since: 2.38 + */ + + /** * g_menu_item_set_label: * @menu_item: a #GMenuItem @@ -23031,6 +23233,16 @@ */ +/** + * g_menu_remove_all: + * @menu: a #GMenu + * + * Removes all items in the menu. + * + * Since: 2.38 + */ + + /** * g_mount_can_eject: * @mount: a #GMount. diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index dc98af0d..7cf2ffa0 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -1898,7 +1898,7 @@ /** * GTimeZone: * - * #GDateTime is an opaque structure whose members cannot be accessed + * #GTimeZone is an opaque structure whose members cannot be accessed * directly. * * Since: 2.26 @@ -9827,9 +9827,9 @@ * @bookmark: a #GBookmarkFile * @uri: a valid URI * @name: an application's name - * @exec: (allow-none): location for the command line of the application, or %NULL - * @count: (allow-none): return location for the registration count, or %NULL - * @stamp: (allow-none): return location for the last registration time, or %NULL + * @exec: (allow-none) (out): return location for the command line of the application, or %NULL + * @count: (allow-none) (out): return location for the registration count, or %NULL + * @stamp: (allow-none) (out): return location for the last registration time, or %NULL * @error: return location for a #GError, or %NULL * * Gets the registration informations of @app_name for the bookmark for @@ -9855,7 +9855,7 @@ * g_bookmark_file_get_applications: * @bookmark: a #GBookmarkFile * @uri: a valid URI - * @length: (allow-none): return location of the length of the returned list, or %NULL + * @length: (allow-none) (out): return location of the length of the returned list, or %NULL * @error: return location for a #GError, or %NULL * * Retrieves the names of the applications that have registered the @@ -9864,7 +9864,7 @@ * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. * Since: 2.12 */ @@ -9889,7 +9889,7 @@ * g_bookmark_file_get_groups: * @bookmark: a #GBookmarkFile * @uri: a valid URI - * @length: (allow-none): return location for the length of the returned string, or %NULL + * @length: (allow-none) (out): return location for the length of the returned string, or %NULL * @error: return location for a #GError, or %NULL * * Retrieves the list of group names of the bookmark for @uri. @@ -9900,7 +9900,7 @@ * The returned array is %NULL terminated, so @length may optionally * be %NULL. * - * Returns: a newly allocated %NULL-terminated array of group names. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of group names. Use g_strfreev() to free it. * Since: 2.12 */ @@ -9909,8 +9909,8 @@ * g_bookmark_file_get_icon: * @bookmark: a #GBookmarkFile * @uri: a valid URI - * @href: (allow-none): return location for the icon's location or %NULL - * @mime_type: (allow-none): return location for the icon's MIME type or %NULL + * @href: (allow-none) (out): return location for the icon's location or %NULL + * @mime_type: (allow-none) (out): return location for the icon's MIME type or %NULL * @error: return location for a #GError or %NULL * * Gets the icon of the bookmark for @uri. @@ -10007,13 +10007,13 @@ /** * g_bookmark_file_get_uris: * @bookmark: a #GBookmarkFile - * @length: (allow-none): return location for the number of returned URIs, or %NULL + * @length: (allow-none) (out): return location for the number of returned URIs, or %NULL * * Returns all URIs of the bookmarks in the bookmark file @bookmark. * The array of returned URIs will be %NULL-terminated, so @length may * optionally be %NULL. * - * Returns: a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. * Since: 2.12 */ @@ -10412,7 +10412,7 @@ /** * g_bookmark_file_to_data: * @bookmark: a #GBookmarkFile - * @length: (allow-none): return location for the length of the returned string, or %NULL + * @length: (allow-none) (out): return location for the length of the returned string, or %NULL * @error: return location for a #GError, or %NULL * * This function outputs @bookmark as a string. @@ -32283,7 +32283,7 @@ * * A reference is taken on @bytes. * - * Returns: a new #GVariant with a floating reference + * Returns: (transfer none): a new #GVariant with a floating reference * Since: 2.36 */ @@ -32531,6 +32531,26 @@ */ +/** + * g_variant_new_take_string: (skip) + * @string: a normal utf8 nul-terminated string + * + * Creates a string #GVariant with the contents of @string. + * + * @string must be valid utf8. + * + * This function consumes @string. g_free() will be called on @string + * when it is no longer required. + * + * You must not modify or access @string in any other way after passing + * it to this function. It is even possible that @string is immediately + * freed. + * + * Returns: (transfer none): a floating reference to a new string #GVariant instance + * Since: 2.38 + */ + + /** * g_variant_new_tuple: * @children: (array length=n_children): the items to make the tuple out of diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 05d5ee09..3f568826 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -2697,6 +2697,19 @@ */ +/** + * g_param_get_default_value: + * @param: a #GParamSpec + * + * Gets the default value of @param as a pointer to a #GValue. + * + * The #GValue will remain value for the life of @param. + * + * Returns: a pointer to a #GValue which must not be modified + * Since: 2.38 + */ + + /** * g_param_spec_boolean: * @name: canonical name of the property specified @@ -4319,6 +4332,24 @@ */ +/** + * g_type_class_get_instance_private_offset: (skip) + * @g_class: a #GTypeClass + * + * Gets the offset of the private data for instances of @g_class. + * + * This is how many bytes you should add to the instance pointer of a + * class in order to get the private data for the type represented by + * @g_class. + * + * You can only call this function after you have registered a private + * data area for @g_class using g_type_class_add_private(). + * + * Returns: the offset, in bytes + * Since: 2.38 + */ + + /** * g_type_class_peek: * @type: Type ID of a classed type. -- cgit v1.2.1