4 # gtk-doc - GTK DocBook documentation generator.
5 # Copyright (C) 1998 Damon Chaplin
7 # This program is free software; you can redistribute it and/or modify
8 # it under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 2 of the License, or
10 # (at your option) any later version.
12 # This program is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with this program; if not, write to the Free Software
19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
23 # This gets information about object hierarchies and signals
24 # by compiling a small C program. CFLAGS and LDFLAGS must be
25 # set appropriately before running this script.
30 push @INC, '@PACKAGE_DATA_DIR@';
31 require "gtkdoc-common.pl";
35 # name of documentation module
41 my $TYPE_INIT_FUNC="#if !GLIB_CHECK_VERSION(2,35,0)\n g_type_init();\n #endif\n g_type_class_ref(G_TYPE_OBJECT)";
42 my $QUERY_CHILD_PROPERTIES;
50 # --nogtkinit is deprecated, as it is the default now anyway.
51 %optctl = (module => \$MODULE,
52 types => \$TYPES_FILE,
53 nogtkinit => \$NO_GTK_INIT,
54 'type-init-func' => \$TYPE_INIT_FUNC,
55 'query-child-properties' => \$QUERY_CHILD_PROPERTIES,
56 'output-dir' => \$OUTPUT_DIR,
60 'ldflags' => \$LDFLAGS,
62 'verbose' => \$VERBOSE,
63 'version' => \$PRINT_VERSION,
64 'help' => \$PRINT_HELP);
66 GetOptions(\%optctl, "module=s", "types:s", "output-dir:s", "nogtkinit", "type-init-func:s", "query-child-properties:s", "cc:s", "ld:s", "run:s", "cflags:s", "ldflags:s", "verbose", "version", "help");
69 # Do nothing. This just avoids a warning.
70 # the option is not used anymore
84 gtkdoc-scangobj version @VERSION@ - introspect g-objects
86 --module=MODULE_NAME Name of the doc module being parsed
87 --types=FILE The name of the file to store the types in
88 --type-init-func=FUNC The init function to call instead of g_type_init()
89 --query-child-properties=FUNC A function that returns a list of child
90 properties for a class
91 --output-dir=DIRNAME The directory where the results are stored
92 --cc=COMPILER The compiler to use
93 --ld=LINKER The linker to use
94 --run=RUN Command for running the scanner
95 --cflags=CFLAGS Compiler flags
96 --ldflags=LDFLAGS Linker flags
97 --verbose Print extra output while processing
98 --version Print the version of this program
99 --help Print this help
104 $OUTPUT_DIR = $OUTPUT_DIR ? $OUTPUT_DIR : ".";
106 $TYPES_FILE = $TYPES_FILE ? $TYPES_FILE : "$OUTPUT_DIR/$MODULE.types";
108 open (TYPES, $TYPES_FILE) || die "Cannot open $TYPES_FILE: $!\n";
109 open (OUTPUT, ">$MODULE-scan.c") || die "Cannot open $MODULE-scan.c: $!\n";
111 my $old_signals_filename = "$OUTPUT_DIR/$MODULE.signals";
112 my $new_signals_filename = "$OUTPUT_DIR/$MODULE.signals.new";
113 my $old_hierarchy_filename = "$OUTPUT_DIR/$MODULE.hierarchy";
114 my $new_hierarchy_filename = "$OUTPUT_DIR/$MODULE.hierarchy.new";
115 my $old_interfaces_filename = "$OUTPUT_DIR/$MODULE.interfaces";
116 my $new_interfaces_filename = "$OUTPUT_DIR/$MODULE.interfaces.new";
117 my $old_prerequisites_filename = "$OUTPUT_DIR/$MODULE.prerequisites";
118 my $new_prerequisites_filename = "$OUTPUT_DIR/$MODULE.prerequisites.new";
119 my $old_args_filename = "$OUTPUT_DIR/$MODULE.args";
120 my $new_args_filename = "$OUTPUT_DIR/$MODULE.args.new";
122 # write a C program to scan the types
130 } elsif (/^gnome_keyring_item_info_get_type$/) {
131 # HACK: This isn't really a GObject type so skip it.
143 $ntypes = @types + 1;
150 #include <glib-object.h>
155 print OUTPUT $includes;
158 print OUTPUT "extern GType $_ (void);\n";
162 if ($QUERY_CHILD_PROPERTIES) {
164 extern GParamSpec** $QUERY_CHILD_PROPERTIES (gpointer class, guint *n_properties);
170 #ifdef GTK_IS_WIDGET_CLASS
173 GType object_types[$ntypes];
176 get_object_types (void)
178 gpointer g_object_class;
183 print OUTPUT " object_types[i++] = $_ ();\n";
189 /* reference the GObjectClass to initialize the param spec pool
190 * potentially needed by interfaces. See http://bugs.gnome.org/571820 */
191 g_object_class = g_type_class_ref (G_TYPE_OBJECT);
193 /* Need to make sure all the types are loaded in and initialize
194 * their signals and properties.
196 for (i=0; object_types[i]; i++)
198 if (G_TYPE_IS_CLASSED (object_types[i]))
199 g_type_class_ref (object_types[i]);
200 if (G_TYPE_IS_INTERFACE (object_types[i]))
201 g_type_default_interface_ref (object_types[i]);
204 g_type_class_unref (g_object_class);
210 * This uses GObject type functions to output signal prototypes and the object
214 /* The output files */
215 const gchar *signals_filename = "$new_signals_filename";
216 const gchar *hierarchy_filename = "$new_hierarchy_filename";
217 const gchar *interfaces_filename = "$new_interfaces_filename";
218 const gchar *prerequisites_filename = "$new_prerequisites_filename";
219 const gchar *args_filename = "$new_args_filename";
222 static void output_signals (void);
223 static void output_object_signals (FILE *fp,
225 static void output_object_signal (FILE *fp,
226 const gchar *object_class_name,
228 static const gchar * get_type_name (GType type,
229 gboolean * is_pointer);
230 static void output_object_hierarchy (void);
231 static void output_hierarchy (FILE *fp,
235 static void output_object_interfaces (void);
236 static void output_interfaces (FILE *fp,
239 static void output_interface_prerequisites (void);
240 static void output_prerequisites (FILE *fp,
243 static void output_args (void);
244 static void output_object_args (FILE *fp, GType object_type);
247 main (int argc, char *argv[])
254 output_object_hierarchy ();
255 output_object_interfaces ();
256 output_interface_prerequisites ();
264 output_signals (void)
269 fp = fopen (signals_filename, "w");
272 g_warning ("Couldn't open output file: %s : %s", signals_filename, g_strerror(errno));
276 for (i = 0; object_types[i]; i++)
277 output_object_signals (fp, object_types[i]);
283 compare_signals (const void *a, const void *b)
285 const guint *signal_a = a;
286 const guint *signal_b = b;
288 return strcmp (g_signal_name (*signal_a), g_signal_name (*signal_b));
291 /* This outputs all the signals of one object. */
293 output_object_signals (FILE *fp, GType object_type)
295 const gchar *object_class_name;
296 guint *signals, n_signals;
299 if (G_TYPE_IS_INSTANTIATABLE (object_type) ||
300 G_TYPE_IS_INTERFACE (object_type))
303 object_class_name = g_type_name (object_type);
305 signals = g_signal_list_ids (object_type, &n_signals);
306 qsort (signals, n_signals, sizeof (guint), compare_signals);
308 for (sig = 0; sig < n_signals; sig++)
310 output_object_signal (fp, object_class_name, signals[sig]);
317 /* This outputs one signal. */
319 output_object_signal (FILE *fp,
320 const gchar *object_name,
323 GSignalQuery query_info;
324 const gchar *type_name, *ret_type, *object_arg, *arg_name;
325 gchar *pos, *object_arg_lower;
329 gint param_num, widget_num, event_num, callback_num;
331 gchar signal_name[128];
334 /* g_print ("Object: %s Signal: %u\\n", object_name, signal_id);*/
337 widget_num = event_num = callback_num = 0;
339 g_signal_query (signal_id, &query_info);
341 /* Output the signal object type and the argument name. We assume the
342 type is a pointer - I think that is OK. We remove "Gtk" or "Gnome" and
343 convert to lower case for the argument name. */
345 sprintf (pos, "%s ", object_name);
348 /* Try to come up with a sensible variable name for the first arg
349 * It chops off 2 know prefixes :/ and makes the name lowercase
350 * It should replace lowercase -> uppercase with '_'
351 * GFileMonitor -> file_monitor
352 * GIOExtensionPoint -> extension_point
353 * GtkTreeView -> tree_view
354 * if 2nd char is upper case too
355 * search for first lower case and go back one char
357 * search for next upper case
359 if (!strncmp (object_name, "Gtk", 3))
360 object_arg = object_name + 3;
361 else if (!strncmp (object_name, "Gnome", 5))
362 object_arg = object_name + 5;
364 object_arg = object_name;
366 object_arg_lower = g_ascii_strdown (object_arg, -1);
367 sprintf (pos, "*%s\\n", object_arg_lower);
369 if (!strncmp (object_arg_lower, "widget", 6))
371 g_free(object_arg_lower);
373 /* Convert signal name to use underscores rather than dashes '-'. */
374 strncpy (signal_name, query_info.signal_name, 127);
375 signal_name[127] = '\\0';
376 for (i = 0; signal_name[i]; i++)
378 if (signal_name[i] == '-')
379 signal_name[i] = '_';
382 /* Output the signal parameters. */
383 for (param = 0; param < query_info.n_params; param++)
385 type_name = get_type_name (query_info.param_types[param] & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer);
387 /* Most arguments to the callback are called "arg1", "arg2", etc.
388 GtkWidgets are called "widget", "widget2", ...
389 GtkCallbacks are called "callback", "callback2", ... */
390 if (!strcmp (type_name, "GtkWidget"))
393 arg_num = &widget_num;
395 else if (!strcmp (type_name, "GtkCallback")
396 || !strcmp (type_name, "GtkCCallback"))
398 arg_name = "callback";
399 arg_num = &callback_num;
404 arg_num = ¶m_num;
406 sprintf (pos, "%s ", type_name);
409 if (!arg_num || *arg_num == 0)
410 sprintf (pos, "%s%s\\n", is_pointer ? "*" : " ", arg_name);
412 sprintf (pos, "%s%s%i\\n", is_pointer ? "*" : " ", arg_name,
426 /* We use one-character flags for simplicity. */
427 if (query_info.signal_flags & G_SIGNAL_RUN_FIRST)
429 if (query_info.signal_flags & G_SIGNAL_RUN_LAST)
431 if (query_info.signal_flags & G_SIGNAL_RUN_CLEANUP)
433 if (query_info.signal_flags & G_SIGNAL_NO_RECURSE)
435 if (query_info.signal_flags & G_SIGNAL_DETAILED)
437 if (query_info.signal_flags & G_SIGNAL_ACTION)
439 if (query_info.signal_flags & G_SIGNAL_NO_HOOKS)
443 /* Output the return type and function name. */
444 ret_type = get_type_name (query_info.return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer);
447 "<SIGNAL>\\n<NAME>%s::%s</NAME>\\n<RETURNS>%s%s</RETURNS>\\n<FLAGS>%s</FLAGS>\\n%s</SIGNAL>\\n\\n",
448 object_name, query_info.signal_name, ret_type, is_pointer ? "*" : "", flags, buffer);
452 /* Returns the type name to use for a signal argument or return value, given
453 the GtkType from the signal info. It also sets is_pointer to TRUE if the
454 argument needs a '*' since it is a pointer. */
456 get_type_name (GType type, gboolean * is_pointer)
458 const gchar *type_name;
461 type_name = g_type_name (type);
475 /* These all have normal C type names so they are OK. */
479 /* A GtkString is really a gchar*. */
485 /* We use a gint for both of these. Hopefully a subtype with a decent
486 name will be registered and used instead, as GTK+ does itself. */
490 /* The boxed type shouldn't be used itself, only subtypes. Though we
491 return 'gpointer' just in case. */
495 /* A GParam is really a GParamSpec*. */
499 #if GLIB_CHECK_VERSION (2, 25, 9)
509 /* For all GObject subclasses we can use the class name with a "*",
510 e.g. 'GtkWidget *'. */
511 if (g_type_is_a (type, G_TYPE_OBJECT))
514 /* Also catch non GObject root types */
515 if (G_TYPE_IS_CLASSED (type))
518 /* All boxed subtypes will be pointers as well. */
519 /* Exception: GStrv */
520 if (g_type_is_a (type, G_TYPE_BOXED) &&
521 !g_type_is_a (type, G_TYPE_STRV))
524 /* All pointer subtypes will be pointers as well. */
525 if (g_type_is_a (type, G_TYPE_POINTER))
528 /* But enums are not */
529 if (g_type_is_a (type, G_TYPE_ENUM) ||
530 g_type_is_a (type, G_TYPE_FLAGS))
537 /* This outputs the hierarchy of all objects which have been initialized,
538 i.e. by calling their XXX_get_type() initialization function. */
540 output_object_hierarchy (void)
545 GType root_types[$ntypes] = { G_TYPE_INVALID, };
547 fp = fopen (hierarchy_filename, "w");
550 g_warning ("Couldn't open output file: %s : %s", hierarchy_filename, g_strerror(errno));
553 output_hierarchy (fp, G_TYPE_OBJECT, 0);
554 output_hierarchy (fp, G_TYPE_INTERFACE, 0);
556 for (i=0; object_types[i]; i++) {
557 root = object_types[i];
558 while ((type = g_type_parent (root))) {
561 if ((root != G_TYPE_OBJECT) && (root != G_TYPE_INTERFACE)) {
562 for (j=0; root_types[j]; j++) {
563 if (root == root_types[j]) {
564 root = G_TYPE_INVALID; break;
568 root_types[j] = root;
569 output_hierarchy (fp, root, 0);
577 /* This is called recursively to output the hierarchy of a object. */
579 output_hierarchy (FILE *fp,
590 for (i = 0; i < level; i++)
592 fprintf (fp, "%s\\n", g_type_name (type));
594 children = g_type_children (type, &n_children);
596 for (i=0; i < n_children; i++)
597 output_hierarchy (fp, children[i], level + 1);
602 static void output_object_interfaces (void)
607 fp = fopen (interfaces_filename, "w");
610 g_warning ("Couldn't open output file: %s : %s", interfaces_filename, g_strerror(errno));
613 output_interfaces (fp, G_TYPE_OBJECT);
615 for (i = 0; object_types[i]; i++)
617 if (!g_type_parent (object_types[i]) &&
618 (object_types[i] != G_TYPE_OBJECT) &&
619 G_TYPE_IS_INSTANTIATABLE (object_types[i]))
621 output_interfaces (fp, object_types[i]);
628 output_interfaces (FILE *fp,
632 GType *children, *interfaces;
633 guint n_children, n_interfaces;
638 interfaces = g_type_interfaces (type, &n_interfaces);
640 if (n_interfaces > 0)
642 fprintf (fp, "%s", g_type_name (type));
643 for (i=0; i < n_interfaces; i++)
644 fprintf (fp, " %s", g_type_name (interfaces[i]));
649 children = g_type_children (type, &n_children);
651 for (i=0; i < n_children; i++)
652 output_interfaces (fp, children[i]);
657 static void output_interface_prerequisites (void)
661 fp = fopen (prerequisites_filename, "w");
664 g_warning ("Couldn't open output file: %s : %s", prerequisites_filename, g_strerror(errno));
667 output_prerequisites (fp, G_TYPE_INTERFACE);
672 output_prerequisites (FILE *fp,
675 #if GLIB_CHECK_VERSION(2,1,0)
677 GType *children, *prerequisites;
678 guint n_children, n_prerequisites;
683 prerequisites = g_type_interface_prerequisites (type, &n_prerequisites);
685 if (n_prerequisites > 0)
687 fprintf (fp, "%s", g_type_name (type));
688 for (i=0; i < n_prerequisites; i++)
689 fprintf (fp, " %s", g_type_name (prerequisites[i]));
692 g_free (prerequisites);
694 children = g_type_children (type, &n_children);
696 for (i=0; i < n_children; i++)
697 output_prerequisites (fp, children[i]);
709 fp = fopen (args_filename, "w");
712 g_warning ("Couldn't open output file: %s : %s", args_filename, g_strerror(errno));
716 for (i = 0; object_types[i]; i++) {
717 output_object_args (fp, object_types[i]);
724 compare_param_specs (const void *a, const void *b)
726 GParamSpec *spec_a = *(GParamSpec **)a;
727 GParamSpec *spec_b = *(GParamSpec **)b;
729 return strcmp (g_param_spec_get_name (spec_a), g_param_spec_get_name (spec_b));
732 /* Its common to have unsigned properties restricted
733 * to the signed range. Therefore we make this look
734 * a bit nicer by spelling out the max constants.
737 /* Don't use "==" with floats, it might trigger a gcc warning. */
738 #define GTKDOC_COMPARE_FLOAT(x, y) (x <= y && x >= y)
741 describe_double_constant (gdouble value)
745 if (GTKDOC_COMPARE_FLOAT (value, G_MAXDOUBLE))
746 desc = g_strdup ("G_MAXDOUBLE");
747 else if (GTKDOC_COMPARE_FLOAT (value, G_MINDOUBLE))
748 desc = g_strdup ("G_MINDOUBLE");
749 else if (GTKDOC_COMPARE_FLOAT (value, -G_MAXDOUBLE))
750 desc = g_strdup ("-G_MAXDOUBLE");
751 else if (GTKDOC_COMPARE_FLOAT (value, G_MAXFLOAT))
752 desc = g_strdup ("G_MAXFLOAT");
753 else if (GTKDOC_COMPARE_FLOAT (value, G_MINFLOAT))
754 desc = g_strdup ("G_MINFLOAT");
755 else if (GTKDOC_COMPARE_FLOAT (value, -G_MAXFLOAT))
756 desc = g_strdup ("-G_MAXFLOAT");
758 /* make sure floats are output with a decimal dot irrespective of
759 * current locale. Use formatd since we want human-readable numbers
760 * and do not need the exact same bit representation when deserialising */
761 desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
762 g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g", value);
769 describe_signed_constant (gsize size, gint64 value)
775 if (sizeof (int) == 2) {
776 if (value == G_MAXINT)
777 desc = g_strdup ("G_MAXINT");
778 else if (value == G_MININT)
779 desc = g_strdup ("G_MININT");
783 if (sizeof (int) == 4) {
784 if (value == G_MAXINT)
785 desc = g_strdup ("G_MAXINT");
786 else if (value == G_MININT)
787 desc = g_strdup ("G_MININT");
789 if (value == G_MAXLONG)
790 desc = g_strdup ("G_MAXLONG");
791 else if (value == G_MINLONG)
792 desc = g_strdup ("G_MINLONG");
795 if (value == G_MAXINT64)
796 desc = g_strdup ("G_MAXINT64");
797 else if (value == G_MININT64)
798 desc = g_strdup ("G_MININT64");
804 desc = g_strdup_printf ("%" G_GINT64_FORMAT, value);
810 describe_unsigned_constant (gsize size, guint64 value)
816 if (sizeof (int) == 2) {
817 if (value == (guint64)G_MAXINT)
818 desc = g_strdup ("G_MAXINT");
819 else if (value == G_MAXUINT)
820 desc = g_strdup ("G_MAXUINT");
824 if (sizeof (int) == 4) {
825 if (value == (guint64)G_MAXINT)
826 desc = g_strdup ("G_MAXINT");
827 else if (value == G_MAXUINT)
828 desc = g_strdup ("G_MAXUINT");
830 if (value == (guint64)G_MAXLONG)
831 desc = g_strdup ("G_MAXLONG");
832 else if (value == G_MAXULONG)
833 desc = g_strdup ("G_MAXULONG");
836 if (value == G_MAXINT64)
837 desc = g_strdup ("G_MAXINT64");
838 else if (value == G_MAXUINT64)
839 desc = g_strdup ("G_MAXUINT64");
845 desc = g_strdup_printf ("%" G_GUINT64_FORMAT, value);
851 describe_type (GParamSpec *spec)
857 if (G_IS_PARAM_SPEC_CHAR (spec))
859 GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec);
861 lower = describe_signed_constant (sizeof(gchar), pspec->minimum);
862 upper = describe_signed_constant (sizeof(gchar), pspec->maximum);
863 if (pspec->minimum == G_MININT8 && pspec->maximum == G_MAXINT8)
864 desc = g_strdup ("");
865 else if (pspec->minimum == G_MININT8)
866 desc = g_strdup_printf ("<= %s", upper);
867 else if (pspec->maximum == G_MAXINT8)
868 desc = g_strdup_printf (">= %s", lower);
870 desc = g_strdup_printf ("[%s,%s]", lower, upper);
874 else if (G_IS_PARAM_SPEC_UCHAR (spec))
876 GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec);
878 lower = describe_unsigned_constant (sizeof(guchar), pspec->minimum);
879 upper = describe_unsigned_constant (sizeof(guchar), pspec->maximum);
880 if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT8)
881 desc = g_strdup ("");
882 else if (pspec->minimum == 0)
883 desc = g_strdup_printf ("<= %s", upper);
884 else if (pspec->maximum == G_MAXUINT8)
885 desc = g_strdup_printf (">= %s", lower);
887 desc = g_strdup_printf ("[%s,%s]", lower, upper);
891 else if (G_IS_PARAM_SPEC_INT (spec))
893 GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec);
895 lower = describe_signed_constant (sizeof(gint), pspec->minimum);
896 upper = describe_signed_constant (sizeof(gint), pspec->maximum);
897 if (pspec->minimum == G_MININT && pspec->maximum == G_MAXINT)
898 desc = g_strdup ("");
899 else if (pspec->minimum == G_MININT)
900 desc = g_strdup_printf ("<= %s", upper);
901 else if (pspec->maximum == G_MAXINT)
902 desc = g_strdup_printf (">= %s", lower);
904 desc = g_strdup_printf ("[%s,%s]", lower, upper);
908 else if (G_IS_PARAM_SPEC_UINT (spec))
910 GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec);
912 lower = describe_unsigned_constant (sizeof(guint), pspec->minimum);
913 upper = describe_unsigned_constant (sizeof(guint), pspec->maximum);
914 if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT)
915 desc = g_strdup ("");
916 else if (pspec->minimum == 0)
917 desc = g_strdup_printf ("<= %s", upper);
918 else if (pspec->maximum == G_MAXUINT)
919 desc = g_strdup_printf (">= %s", lower);
921 desc = g_strdup_printf ("[%s,%s]", lower, upper);
925 else if (G_IS_PARAM_SPEC_LONG (spec))
927 GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec);
929 lower = describe_signed_constant (sizeof(glong), pspec->minimum);
930 upper = describe_signed_constant (sizeof(glong), pspec->maximum);
931 if (pspec->minimum == G_MINLONG && pspec->maximum == G_MAXLONG)
932 desc = g_strdup ("");
933 else if (pspec->minimum == G_MINLONG)
934 desc = g_strdup_printf ("<= %s", upper);
935 else if (pspec->maximum == G_MAXLONG)
936 desc = g_strdup_printf (">= %s", lower);
938 desc = g_strdup_printf ("[%s,%s]", lower, upper);
942 else if (G_IS_PARAM_SPEC_ULONG (spec))
944 GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec);
946 lower = describe_unsigned_constant (sizeof(gulong), pspec->minimum);
947 upper = describe_unsigned_constant (sizeof(gulong), pspec->maximum);
948 if (pspec->minimum == 0 && pspec->maximum == G_MAXULONG)
949 desc = g_strdup ("");
950 else if (pspec->minimum == 0)
951 desc = g_strdup_printf ("<= %s", upper);
952 else if (pspec->maximum == G_MAXULONG)
953 desc = g_strdup_printf (">= %s", lower);
955 desc = g_strdup_printf ("[%s,%s]", lower, upper);
959 else if (G_IS_PARAM_SPEC_INT64 (spec))
961 GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec);
963 lower = describe_signed_constant (sizeof(gint64), pspec->minimum);
964 upper = describe_signed_constant (sizeof(gint64), pspec->maximum);
965 if (pspec->minimum == G_MININT64 && pspec->maximum == G_MAXINT64)
966 desc = g_strdup ("");
967 else if (pspec->minimum == G_MININT64)
968 desc = g_strdup_printf ("<= %s", upper);
969 else if (pspec->maximum == G_MAXINT64)
970 desc = g_strdup_printf (">= %s", lower);
972 desc = g_strdup_printf ("[%s,%s]", lower, upper);
976 else if (G_IS_PARAM_SPEC_UINT64 (spec))
978 GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec);
980 lower = describe_unsigned_constant (sizeof(guint64), pspec->minimum);
981 upper = describe_unsigned_constant (sizeof(guint64), pspec->maximum);
982 if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT64)
983 desc = g_strdup ("");
984 else if (pspec->minimum == 0)
985 desc = g_strdup_printf ("<= %s", upper);
986 else if (pspec->maximum == G_MAXUINT64)
987 desc = g_strdup_printf (">= %s", lower);
989 desc = g_strdup_printf ("[%s,%s]", lower, upper);
993 else if (G_IS_PARAM_SPEC_FLOAT (spec))
995 GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec);
997 lower = describe_double_constant (pspec->minimum);
998 upper = describe_double_constant (pspec->maximum);
999 if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXFLOAT))
1001 if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT))
1002 desc = g_strdup ("");
1004 desc = g_strdup_printf ("<= %s", upper);
1006 else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT))
1007 desc = g_strdup_printf (">= %s", lower);
1009 desc = g_strdup_printf ("[%s,%s]", lower, upper);
1013 else if (G_IS_PARAM_SPEC_DOUBLE (spec))
1015 GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec);
1017 lower = describe_double_constant (pspec->minimum);
1018 upper = describe_double_constant (pspec->maximum);
1019 if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXDOUBLE))
1021 if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE))
1022 desc = g_strdup ("");
1024 desc = g_strdup_printf ("<= %s", upper);
1026 else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE))
1027 desc = g_strdup_printf (">= %s", lower);
1029 desc = g_strdup_printf ("[%s,%s]", lower, upper);
1033 #if GLIB_CHECK_VERSION (2, 12, 0)
1034 else if (G_IS_PARAM_SPEC_GTYPE (spec))
1036 GParamSpecGType *pspec = G_PARAM_SPEC_GTYPE (spec);
1037 gboolean is_pointer;
1039 desc = g_strdup (get_type_name (pspec->is_a_type, &is_pointer));
1042 #if GLIB_CHECK_VERSION (2, 25, 9)
1043 else if (G_IS_PARAM_SPEC_VARIANT (spec))
1045 GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec);
1046 gchar *variant_type;
1048 variant_type = g_variant_type_dup_string (pspec->type);
1049 desc = g_strdup_printf ("GVariant<%s>", variant_type);
1050 g_free (variant_type);
1055 desc = g_strdup ("");
1062 describe_default (GParamSpec *spec)
1066 if (G_IS_PARAM_SPEC_CHAR (spec))
1068 GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec);
1070 desc = g_strdup_printf ("%d", pspec->default_value);
1072 else if (G_IS_PARAM_SPEC_UCHAR (spec))
1074 GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec);
1076 desc = g_strdup_printf ("%u", pspec->default_value);
1078 else if (G_IS_PARAM_SPEC_BOOLEAN (spec))
1080 GParamSpecBoolean *pspec = G_PARAM_SPEC_BOOLEAN (spec);
1082 desc = g_strdup_printf ("%s", pspec->default_value ? "TRUE" : "FALSE");
1084 else if (G_IS_PARAM_SPEC_INT (spec))
1086 GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec);
1088 desc = g_strdup_printf ("%d", pspec->default_value);
1090 else if (G_IS_PARAM_SPEC_UINT (spec))
1092 GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec);
1094 desc = g_strdup_printf ("%u", pspec->default_value);
1096 else if (G_IS_PARAM_SPEC_LONG (spec))
1098 GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec);
1100 desc = g_strdup_printf ("%ld", pspec->default_value);
1102 else if (G_IS_PARAM_SPEC_LONG (spec))
1104 GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec);
1106 desc = g_strdup_printf ("%lu", pspec->default_value);
1108 else if (G_IS_PARAM_SPEC_INT64 (spec))
1110 GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec);
1112 desc = g_strdup_printf ("%" G_GINT64_FORMAT, pspec->default_value);
1114 else if (G_IS_PARAM_SPEC_UINT64 (spec))
1116 GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec);
1118 desc = g_strdup_printf ("%" G_GUINT64_FORMAT, pspec->default_value);
1120 else if (G_IS_PARAM_SPEC_UNICHAR (spec))
1122 GParamSpecUnichar *pspec = G_PARAM_SPEC_UNICHAR (spec);
1124 if (g_unichar_isprint (pspec->default_value))
1125 desc = g_strdup_printf ("'%c'", pspec->default_value);
1127 desc = g_strdup_printf ("%u", pspec->default_value);
1129 else if (G_IS_PARAM_SPEC_ENUM (spec))
1131 GParamSpecEnum *pspec = G_PARAM_SPEC_ENUM (spec);
1133 GEnumValue *value = g_enum_get_value (pspec->enum_class, pspec->default_value);
1135 desc = g_strdup_printf ("%s", value->value_name);
1137 desc = g_strdup_printf ("%d", pspec->default_value);
1139 else if (G_IS_PARAM_SPEC_FLAGS (spec))
1141 GParamSpecFlags *pspec = G_PARAM_SPEC_FLAGS (spec);
1142 guint default_value;
1145 default_value = pspec->default_value;
1146 acc = g_string_new ("");
1148 while (default_value)
1150 GFlagsValue *value = g_flags_get_first_value (pspec->flags_class, default_value);
1156 g_string_append (acc, " | ");
1157 g_string_append (acc, value->value_name);
1159 default_value &= ~value->value;
1162 if (default_value == 0)
1163 desc = g_string_free (acc, FALSE);
1166 desc = g_strdup_printf ("%d", pspec->default_value);
1167 g_string_free (acc, TRUE);
1170 else if (G_IS_PARAM_SPEC_FLOAT (spec))
1172 GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec);
1174 /* make sure floats are output with a decimal dot irrespective of
1175 * current locale. Use formatd since we want human-readable numbers
1176 * and do not need the exact same bit representation when deserialising */
1177 desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
1178 g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g",
1179 pspec->default_value);
1181 else if (G_IS_PARAM_SPEC_DOUBLE (spec))
1183 GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec);
1185 /* make sure floats are output with a decimal dot irrespective of
1186 * current locale. Use formatd since we want human-readable numbers
1187 * and do not need the exact same bit representation when deserialising */
1188 desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
1189 g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g",
1190 pspec->default_value);
1192 else if (G_IS_PARAM_SPEC_STRING (spec))
1194 GParamSpecString *pspec = G_PARAM_SPEC_STRING (spec);
1196 if (pspec->default_value)
1198 gchar *esc = g_strescape (pspec->default_value, NULL);
1200 desc = g_strdup_printf ("\\"%s\\"", esc);
1205 desc = g_strdup_printf ("NULL");
1207 #if GLIB_CHECK_VERSION (2, 25, 9)
1208 else if (G_IS_PARAM_SPEC_VARIANT (spec))
1210 GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec);
1212 if (pspec->default_value)
1213 desc = g_variant_print (pspec->default_value, TRUE);
1215 desc = g_strdup ("NULL");
1220 desc = g_strdup ("");
1228 output_object_args (FILE *fp, GType object_type)
1231 const gchar *object_class_name;
1233 gchar flags[16], *pos;
1234 GParamSpec **properties;
1236 gboolean child_prop;
1237 gboolean style_prop;
1238 gboolean is_pointer;
1239 const gchar *type_name;
1241 gchar *default_value;
1243 if (G_TYPE_IS_OBJECT (object_type))
1245 class = g_type_class_peek (object_type);
1249 properties = g_object_class_list_properties (class, &n_properties);
1251 #if GLIB_MAJOR_VERSION > 2 || (GLIB_MAJOR_VERSION == 2 && GLIB_MINOR_VERSION >= 3)
1252 else if (G_TYPE_IS_INTERFACE (object_type))
1254 class = g_type_default_interface_ref (object_type);
1259 properties = g_object_interface_list_properties (class, &n_properties);
1265 object_class_name = g_type_name (object_type);
1271 qsort (properties, n_properties, sizeof (GParamSpec *), compare_param_specs);
1272 for (arg = 0; arg < n_properties; arg++)
1274 GParamSpec *spec = properties[arg];
1275 const gchar *nick, *blurb, *dot;
1277 if (spec->owner_type != object_type)
1281 /* We use one-character flags for simplicity. */
1282 if (child_prop && !style_prop)
1286 if (spec->flags & G_PARAM_READABLE)
1288 if (spec->flags & G_PARAM_WRITABLE)
1290 if (spec->flags & G_PARAM_CONSTRUCT)
1292 if (spec->flags & G_PARAM_CONSTRUCT_ONLY)
1296 nick = g_param_spec_get_nick (spec);
1297 blurb = g_param_spec_get_blurb (spec);
1301 int str_len = strlen (blurb);
1302 if (str_len > 0 && blurb[str_len - 1] != '.')
1306 type_desc = describe_type (spec);
1307 default_value = describe_default (spec);
1308 type_name = get_type_name (spec->value_type, &is_pointer);
1309 fprintf (fp, "<ARG>\\n<NAME>%s::%s</NAME>\\n<TYPE>%s%s</TYPE>\\n<RANGE>%s</RANGE>\\n<FLAGS>%s</FLAGS>\\n<NICK>%s</NICK>\\n<BLURB>%s%s</BLURB>\\n<DEFAULT>%s</DEFAULT>\\n</ARG>\\n\\n",
1310 object_class_name, g_param_spec_get_name (spec), type_name, is_pointer ? "*" : "", type_desc, flags, nick ? nick : "(null)", blurb ? blurb : "(null)", dot, default_value);
1312 g_free (default_value);
1315 g_free (properties);
1317 #ifdef GTK_IS_CONTAINER_CLASS
1318 if (!child_prop && GTK_IS_CONTAINER_CLASS (class)) {
1319 properties = gtk_container_class_list_child_properties (class, &n_properties);
1325 #ifdef GTK_IS_CELL_AREA_CLASS
1326 if (!child_prop && GTK_IS_CELL_AREA_CLASS (class)) {
1327 properties = gtk_cell_area_class_list_cell_properties (class, &n_properties);
1333 #ifdef GTK_IS_WIDGET_CLASS
1334 #if GTK_CHECK_VERSION(2,1,0)
1335 if (!style_prop && GTK_IS_WIDGET_CLASS (class)) {
1336 properties = gtk_widget_class_list_style_properties (GTK_WIDGET_CLASS (class), &n_properties);
1345 if ($QUERY_CHILD_PROPERTIES) {
1348 properties = $QUERY_CHILD_PROPERTIES (class, &n_properties);
1366 # Compile and run our file
1369 $CC = $ENV{CC} ? $ENV{CC} : "gcc";
1372 $LD = $ENV{LD} ? $ENV{LD} : $CC;
1375 $CFLAGS = $ENV{CFLAGS} ? $ENV{CFLAGS} : "";
1378 $LDFLAGS = $ENV{LDFLAGS} ? $ENV{LDFLAGS} : "";
1381 $RUN = $ENV{RUN} ? $ENV{RUN} : "";
1385 if ($CC =~ /libtool/) {
1386 $o_file = "$MODULE-scan.lo"
1388 $o_file = "$MODULE-scan.o"
1392 if (!defined($VERBOSE) or $VERBOSE eq "0") {
1393 $stdout=">/dev/null";
1397 $command = "$CC $stdout $CFLAGS -c -o $o_file $MODULE-scan.c";
1398 system("($command)") == 0 or die "Compilation of scanner failed: $!\n";
1401 # FIXME: Can we turn off as-needed for the docs (or better fix it?)
1402 #$command = "$LD -Wl,--no-as-needed $o_file $LDFLAGS -o $MODULE-scan@EXEEXT@";
1403 $command = "$LD $stdout $o_file $LDFLAGS -o $MODULE-scan@EXEEXT@";
1404 system("($command)") == 0 or die "Linking of scanner failed: $!\n";
1406 # Running scanner $MODULE-scan ";
1407 system("($RUN ./$MODULE-scan@EXEEXT@)") == 0 or die "Scan failed: $!\n";
1410 if (!defined($ENV{"GTK_DOC_KEEP_INTERMEDIATE"})) {
1411 unlink "./$MODULE-scan.c", "./$MODULE-scan.o", "./$MODULE-scan.lo", "./$MODULE-scan@EXEEXT@";
1414 &UpdateFileIfChanged ($old_signals_filename, $new_signals_filename, 0);
1415 &UpdateFileIfChanged ($old_hierarchy_filename, $new_hierarchy_filename, 0);
1416 &UpdateFileIfChanged ($old_interfaces_filename, $new_interfaces_filename, 0);
1417 &UpdateFileIfChanged ($old_prerequisites_filename, $new_prerequisites_filename, 0);
1418 &UpdateFileIfChanged ($old_args_filename, $new_args_filename, 0);