[gobject-introspection] How to use caller-allocates and allow-none annotations in Clutter
- From: Kouhei Sutou <kou cozmixng org>
- To: gtk-devel-list gnome org
- Subject: [gobject-introspection] How to use caller-allocates and allow-none annotations in Clutter
- Date: Mon, 07 Jan 2013 22:22:34 +0900 (JST)
Hi,
I have questions about "out caller-allocates" and
"allow-none" annotations of GObject Introspection.
I'm sending this e-mail to gtk-devel-list because
https://live.gnome.org/GObjectIntrospection introduces this
list.
I submitted a bug report to Clutter:
"child" of clutter_actor_iter_next() and _prev() misses
some GObject Introspection tags
https://bugzilla.gnome.org/show_bug.cgi?id=691217
In this bug report, I was suggested that I need to ask
GObject Introspection developers about what annotations
should be used for clutter_actor_iter_next() [*1]. I hope
that GObject Introspection developers answer my question.
[*1] http://developer.gnome.org/clutter/stable/ClutterActor.html#clutter-actor-iter-next
Here is the clutter_actor_iter_next() signature:
gboolean
clutter_actor_iter_next (ClutterActorIter *iter,
ClutterActor **child);
The "child" parameter is the target in the bug report.
The function is used like:
ClutterActorIter iter;
ClutterActor *child;
clutter_actor_iter_init (&iter, container);
while (clutter_actor_iter_next (&iter, &child))
{
/* do something with child */
}
There is two questions.
(1)
The "child" parameter is a return location and the return
location is allocated by caller. (The returned object isn't
allocated by caller.)
What annotation should be used for the case? I thought
"out caller-allocates". Is it right usage for the
annotation? Or "out" is the right annotation?
(2)
The "child" parameter can be NULL. What annotation should be
used for the case? I thought "allow-none". Is it right usage
for the annotation? Can I use "allow-none" for an out
parameter?
I found a real usage of "out caller-allocate" and
"allow-none". It is gtk_text_iter_forward_search():
http://developer.gnome.org/gtk3/stable/GtkTextIter.html#gtk-text-iter-forward-search
gboolean
gtk_text_iter_forward_search (const GtkTextIter *iter,
const gchar *str,
GtkTextSearchFlags flags,
GtkTextIter *match_start,
GtkTextIter *match_end,
const GtkTextIter *limit);
"out caller-allocate" and "allow-none" are used for
match_start and match_end:
match_start:
return location for start of match, or
NULL. [out caller-allocates][allow-none]
match_end:
return location for end of match, or
NULL. [out caller-allocates][allow-none]
Is clutter_actor_iter_next() case the same case as
gtk_text_iter_forward_search()?
Thanks,
--
kou
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]