Examples

Transfer

   1 /**
   2  * mylib_get_constant1:
   3  *
   4  * Returns: (transfer full): a constant, free when you used it
   5  */
   6 gchar *
   7 mylib_get_constant1 (void) 
   8 {
   9    return g_strdup("a constant");
  10 }

   1 /**
   2  * mylib_get_constant2:
   3  *
   4  * Returns: (transfer none): another constant
   5  */
   6 const gchar *
   7 mylib_get_string2 (void) 
   8 {
   9    return "another constant";
  10 }

   1 /**
   2  * mylib_get_string_list1:
   3  *
   4  * Returns: (element-type utf8) (transfer full): list of constants,
   5  *          free the list with g_slist_free and the elements with g_free when done.
   6  */
   7 GSList *
   8 mylib_get_string_list1 (void) 
   9 {
  10    GSList *l = NULL;
  11    l = g_slist_append (l, g_strdup ("foo"));
  12    l = g_slist_append (l, g_strdup ("bar"));
  13    return l;
  14 }

   1 /**
   2  * mylib_get_string_list2:
   3  *
   4  * Returns: (element-type utf8) (transfer container): list of constants
   5  *          free the list with g_slist_free when done. 
   6  */
   7 GSList *
   8 mylib_get_string_list2 (void) 
   9 {
  10    GSList *l = NULL;
  11    l = g_slist_append (l, "foo");
  12    l = g_slist_append (l, "bar");
  13    return l;
  14 }

Array length

   1 /**
   2  * gtk_list_store_set_column_types: 
   3  * @store: a #GtkListStore
   4  * @n_columns: Length of @types
   5  * @types: (array length=n_columns): List of types
   6  */
   7 void
   8 gtk_list_store_set_column_types (GtkListStore *list_store,
   9                                  gint          n_columns,
  10                                  GType        *types);

Nullable parameters

   1 /**
   2  * gtk_link_button_new_with_label: 
   3  * @uri: A URI
   4  * @label: (allow-none): A piece of text or NULL
   5  */
   6 GtkWidget *
   7 gtk_link_button_new_with_label (const gchar *uri,
   8                                 const gchar *label);

'out' parameters

   1 /**
   2  * g_file_get_contents:
   3  * @filename: name of a file to read contents from, in the GLib file name encoding
   4  * @contents: (out): location to store an allocated string, use g_free() to free the returned string
   5  * @length: (out) (allow-none): location to store length in bytes of the contents, or NULL
   6  * @error: return location for a GError, or NULL
   7  *
   8  * [...]
   9  *
  10  * Returns: TRUE on success, FALSE if an error occurred
  11  */
  12 gboolean g_file_get_contents (const gchar *filename,
  13                               gchar **contents,
  14                               gsize *length,
  15                               GError **error);
  16 
  17 /* this is valid because length has allow-none */
  18 g_file_get_contents ("/etc/motd", &motd, NULL, &error); // VALID
  19 /* but this is not valid, according to those annotations */
  20 g_file_get_contents ("/etc/motd", NULL, NULL, &error); // NOT VALID
  21 

G(S)List contained types

   1 /**
   2  * gtk_container_get_children: 
   3  * @container: A #GtkContainer
   4  *
   5  * Returns: (element-type Gtk.Widget) (transfer container): List of #GtkWidget
   6  */
   7 GList*
   8 gtk_container_get_children (GtkContainer *container);

Direction

   1 /**
   2  * gtk_widget_get_size_request: 
   3  * @width: (out): Int to store width in
   4  * @height: (out): Int to store height in
   5  */

Out parameters

This is a callee-allocates example; the (out) annotation automatically infers this from the fact that there's a double indirection on a structure parameter.

   1 typedef struct _FooSubObj FooSubObj
   2 
   3 /**
   4  * foo_obj_get_sub_obj:
   5  * @obj: A #FooObj
   6  * @subobj: (out): A #FooSubObj
   7  *
   8  * Get a sub object.
   9  */
  10 void
  11 foo_obj_get_sub_obj (FooObj     *obj,
  12                      FooSubObj **subobj)
  13 {
  14   *subobj = foo_sub_object_new ();
  15 }

This is a caller-allocates example; the (out) annotation automatically infers this from the fact that there's only a single indirection on a structure parameter.

   1 typedef struct _FooIter FooIter;
   2 
   3 /**
   4  * foo_obj_get_iter:
   5  * @obj: A #FooObj
   6  * @iter: (out): An iterator, will be initialized
   7  *
   8  * Get an iterator.
   9  */
  10 void
  11 foo_obj_get_iter (FooObj *obj,
  12                   FooIter *iter)
  13 {
  14   iter->state = 0;
  15 }

Rename to

Rename to is an advisory annotation. It's not required to fulfill the advisory when generating or making a language binding. The way it is currently implemented, if you rename a function to a name already in use, it will remove the other binding. This is useful to eliminate unwanted/deprecated functions from the binding.

Another (currently unimplemented) use for the rename annotation would be overloading; for example, overloading of constructors or, like in this example, overloading a method to be both an asynchronous and a synchronous one (depending on the amount and what kind of parameters).

   1 /**
   2  * my_type_perform_async: (rename-to my_type_perform)
   3  * @self: The this ptr
   4  * @data: data
   5  * @callback: callback when async operation finished
   6  * @user_data: user_data for @callback
   7  *
   8  * Asynchronously perform
   9  **/
  10 void
  11 my_type_perform_async (MyType *self, gpointer data,
  12                        GFunc callback,
  13                        gpointer user_data);
  14 
  15 /**
  16  * my_type_perform:
  17  * @self: The this ptr
  18  * @data: data
  19  *
  20  * Perform
  21  **/
  22 void
  23 my_type_perform (MyType *self, gpointer data);

In a language supporting method overloading, because we advised to rename to perform, and because we have another perform already, this could be bound like this:

   1 class MyType {
   2   public void perform (Pointer data) { }
   3   public void perform (Pointer data, GFunc callback, Pointer user_data) { }
   4 }

However, currently the generated gir/typelib will only contain information about my_type_perform_async, which will shadow (ie, remove) the binding of my_type_perform.

Attributes

Attributes are arbitrary key/value pairs that can be attached to almost any item including classes, methods, signals, properties, parameters and return values. These attributes appear in both the .gir and the .typelib files. Attributes can serve as a mechanism for software higher in the toolchain. Attributes are name-spaced using dot as a separator. At least one dot must appear in the key name.

   1 /**
   2  * my_frobnicator_poke_path: (attributes gdbus.method PokePath)
   3  * @frobnicator: A #MyFrobnicator
   4  * @object_path: (gdbus.signature o): An object path.
   5  *
   6  * Manipulate an object path.
   7  *
   8  * Returns: (gdbus.signature o): A new object path. Free with g_free().
   9  */
  10 gchar *
  11 my_frobnicator_poke_path (MyFrobnicator *frobnicator,
  12                           const gchar   *object_path)

Constants

   1 /**
   2  * MY_CONSTANT: (value 100)
   3  * A constant.
   4  */
   5 #define MY_CONSTANT 10 * 10
   6 

Projects/GTK+/DocumentationSyntax/Annotations/Examples (last edited 2014-02-09 14:04:04 by WilliamJonMcCann)