1 /* Gtk+ testing utilities
2 * Copyright (C) 2007 Imendio AB
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
23 #include "gtkspinbutton.h"
27 #include "gtkbutton.h"
28 #include "gtktextview.h"
38 * @Short_description: Utilities for testing GTK+ applications
44 * @argcp: Address of the <parameter>argc</parameter> parameter of the
45 * main() function. Changed if any arguments were handled.
46 * @argvp: (inout) (array length=argcp): Address of the
47 * <parameter>argv</parameter> parameter of main().
48 * Any parameters understood by g_test_init() or gtk_init() are
49 * stripped before return.
50 * @...: currently unused
52 * This function is used to initialize a GTK+ test program.
54 * It will in turn call g_test_init() and gtk_init() to properly
55 * initialize the testing framework and graphical toolkit. It'll
56 * also set the program's locale to "C" and prevent loading of rc
57 * files and Gtk+ modules. This is done to make tets program
58 * environments as deterministic as possible.
60 * Like gtk_init() and g_test_init(), any known arguments will be
61 * processed and stripped from @argc and @argv.
66 gtk_test_init (int *argcp,
70 g_test_init (argcp, argvp, NULL);
72 * - call g_test_init();
74 * - prevent RC files from loading;
75 * - prevent Gtk modules from loading;
76 * - supply mock object for GtkSettings
78 * - this function could install a mock object around GtkSettings
80 g_setenv ("GTK_MODULES", "", TRUE);
81 gtk_disable_setlocale();
82 setlocale (LC_ALL, "C");
83 g_test_bug_base ("http://bugzilla.gnome.org/show_bug.cgi?id=%s");
85 /* XSendEvent() doesn't work yet on XI2 events.
86 * So at the moment gdk_test_simulate_* can only
87 * send events that GTK+ understands if XI2 is
90 gdk_disable_multidevice ();
92 gtk_init (argcp, argvp);
96 test_find_widget_input_windows (GtkWidget *widget,
100 GList *node, *children;
101 GSList *matches = NULL;
104 window = gtk_widget_get_window (widget);
106 gdk_window_get_user_data (window, &udata);
107 if (udata == widget && (!input_only || (GDK_IS_WINDOW (window) && gdk_window_is_input_only (GDK_WINDOW (window)))))
108 matches = g_slist_prepend (matches, window);
109 children = gdk_window_get_children (gtk_widget_get_parent_window (widget));
110 for (node = children; node; node = node->next)
112 gdk_window_get_user_data (node->data, &udata);
113 if (udata == widget && (!input_only || (GDK_IS_WINDOW (node->data) && gdk_window_is_input_only (GDK_WINDOW (node->data)))))
114 matches = g_slist_prepend (matches, node->data);
116 return g_slist_reverse (matches);
120 * gtk_test_widget_send_key:
121 * @widget: Widget to generate a key press and release on.
122 * @keyval: A Gdk keyboard value.
123 * @modifiers: Keyboard modifiers the event is setup with.
125 * This function will generate keyboard press and release events in
126 * the middle of the first GdkWindow found that belongs to @widget.
127 * For %GTK_NO_WINDOW widgets like GtkButton, this will often be an
128 * input-only event window. For other widgets, this is usually widget->window.
129 * Certain caveats should be considered when using this function, in
130 * particular because the mouse pointer is warped to the key press
131 * location, see gdk_test_simulate_key() for details.
133 * Returns: wether all actions neccessary for the key event simulation were carried out successfully.
138 gtk_test_widget_send_key (GtkWidget *widget,
140 GdkModifierType modifiers)
142 gboolean k1res, k2res;
143 GSList *iwindows = test_find_widget_input_windows (widget, FALSE);
145 iwindows = test_find_widget_input_windows (widget, TRUE);
148 k1res = gdk_test_simulate_key (iwindows->data, -1, -1, keyval, modifiers, GDK_KEY_PRESS);
149 k2res = gdk_test_simulate_key (iwindows->data, -1, -1, keyval, modifiers, GDK_KEY_RELEASE);
150 g_slist_free (iwindows);
151 return k1res && k2res;
155 * gtk_test_widget_click:
156 * @widget: Widget to generate a button click on.
157 * @button: Number of the pointer button for the event, usually 1, 2 or 3.
158 * @modifiers: Keyboard modifiers the event is setup with.
160 * This function will generate a @button click (button press and button
161 * release event) in the middle of the first GdkWindow found that belongs
163 * For %GTK_NO_WINDOW widgets like GtkButton, this will often be an
164 * input-only event window. For other widgets, this is usually widget->window.
165 * Certain caveats should be considered when using this function, in
166 * particular because the mouse pointer is warped to the button click
167 * location, see gdk_test_simulate_button() for details.
169 * Returns: wether all actions neccessary for the button click simulation were carried out successfully.
174 gtk_test_widget_click (GtkWidget *widget,
176 GdkModifierType modifiers)
178 gboolean b1res, b2res;
179 GSList *iwindows = test_find_widget_input_windows (widget, FALSE);
181 iwindows = test_find_widget_input_windows (widget, TRUE);
184 b1res = gdk_test_simulate_button (iwindows->data, -1, -1, button, modifiers, GDK_BUTTON_PRESS);
185 b2res = gdk_test_simulate_button (iwindows->data, -1, -1, button, modifiers, GDK_BUTTON_RELEASE);
186 g_slist_free (iwindows);
187 return b1res && b2res;
191 * gtk_test_spin_button_click:
192 * @spinner: valid GtkSpinButton widget.
193 * @button: Number of the pointer button for the event, usually 1, 2 or 3.
194 * @upwards: %TRUE for upwards arrow click, %FALSE for downwards arrow click.
196 * This function will generate a @button click in the upwards or downwards
197 * spin button arrow areas, usually leading to an increase or decrease of
198 * spin button's value.
200 * Returns: wether all actions neccessary for the button click simulation were carried out successfully.
205 gtk_test_spin_button_click (GtkSpinButton *spinner,
209 GdkWindow *down_panel = NULL, *up_panel = NULL, *panel;
210 gboolean b1res = FALSE, b2res = FALSE;
212 _gtk_spin_button_get_panels (spinner, &down_panel, &up_panel);
214 panel = (upwards) ? up_panel : down_panel;
218 gint width = gdk_window_get_width (panel);
219 b1res = gdk_test_simulate_button (panel, width - 1, 1, button, 0, GDK_BUTTON_PRESS);
220 b2res = gdk_test_simulate_button (panel, width - 1, 1, button, 0, GDK_BUTTON_RELEASE);
222 return b1res && b2res;
226 * gtk_test_find_label:
227 * @widget: Valid label or container widget.
228 * @label_pattern: Shell-glob pattern to match a label string.
230 * This function will search @widget and all its descendants for a GtkLabel
231 * widget with a text string matching @label_pattern.
232 * The @label_pattern may contain asterisks '*' and question marks '?' as
233 * placeholders, g_pattern_match() is used for the matching.
234 * Note that locales other than "C" tend to alter (translate" label strings,
235 * so this function is genrally only useful in test programs with
236 * predetermined locales, see gtk_test_init() for more details.
238 * Returns: (transfer none): a GtkLabel widget if any is found.
243 gtk_test_find_label (GtkWidget *widget,
244 const gchar *label_pattern)
246 if (GTK_IS_LABEL (widget))
248 const gchar *text = gtk_label_get_text (GTK_LABEL (widget));
249 if (g_pattern_match_simple (label_pattern, text))
252 if (GTK_IS_CONTAINER (widget))
254 GList *node, *list = gtk_container_get_children (GTK_CONTAINER (widget));
255 for (node = list; node; node = node->next)
257 GtkWidget *label = gtk_test_find_label (node->data, label_pattern);
267 test_list_descendants (GtkWidget *widget,
270 GList *results = NULL;
271 if (GTK_IS_CONTAINER (widget))
273 GList *node, *list = gtk_container_get_children (GTK_CONTAINER (widget));
274 for (node = list; node; node = node->next)
276 if (!widget_type || g_type_is_a (G_OBJECT_TYPE (node->data), widget_type))
277 results = g_list_prepend (results, node->data);
279 results = g_list_concat (results, test_list_descendants (node->data, widget_type));
287 widget_geo_dist (GtkWidget *a,
291 GtkAllocation allocation;
292 int ax0, ay0, ax1, ay1, bx0, by0, bx1, by1, xdist = 0, ydist = 0;
294 gtk_widget_get_allocation (a, &allocation);
295 if (!gtk_widget_translate_coordinates (a, base, 0, 0, &ax0, &ay0) ||
296 !gtk_widget_translate_coordinates (a, base, allocation.width, allocation.height, &ax1, &ay1))
299 gtk_widget_get_allocation (b, &allocation);
300 if (!gtk_widget_translate_coordinates (b, base, 0, 0, &bx0, &by0) ||
301 !gtk_widget_translate_coordinates (b, base, allocation.width, allocation.height, &bx1, &by1))
313 return xdist + ydist;
317 widget_geo_cmp (gconstpointer a,
321 gpointer *data = user_data;
322 GtkWidget *wa = (void*) a, *wb = (void*) b, *toplevel = data[0], *base_widget = data[1];
323 int adist = widget_geo_dist (wa, base_widget, toplevel);
324 int bdist = widget_geo_dist (wb, base_widget, toplevel);
325 return adist > bdist ? +1 : adist == bdist ? 0 : -1;
329 * gtk_test_find_sibling:
330 * @base_widget: Valid widget, part of a widget hierarchy
331 * @widget_type: Type of a aearched for sibling widget
333 * This function will search siblings of @base_widget and siblings of its
334 * ancestors for all widgets matching @widget_type.
335 * Of the matching widgets, the one that is geometrically closest to
336 * @base_widget will be returned.
337 * The general purpose of this function is to find the most likely "action"
338 * widget, relative to another labeling widget. Such as finding a
339 * button or text entry widget, given its corresponding label widget.
341 * Returns: (transfer none): a widget of type @widget_type if any is found.
346 gtk_test_find_sibling (GtkWidget *base_widget,
349 GList *siblings = NULL;
350 GtkWidget *tmpwidget = base_widget;
352 /* find all sibling candidates */
355 tmpwidget = gtk_widget_get_parent (tmpwidget);
356 siblings = g_list_concat (siblings, test_list_descendants (tmpwidget, widget_type));
358 /* sort them by distance to base_widget */
359 data[0] = gtk_widget_get_toplevel (base_widget);
360 data[1] = base_widget;
361 siblings = g_list_sort_with_data (siblings, widget_geo_cmp, data);
362 /* pick nearest != base_widget */
363 siblings = g_list_remove (siblings, base_widget);
364 tmpwidget = siblings ? siblings->data : NULL;
365 g_list_free (siblings);
370 * gtk_test_find_widget:
371 * @widget: Container widget, usually a GtkWindow.
372 * @label_pattern: Shell-glob pattern to match a label string.
373 * @widget_type: Type of a aearched for label sibling widget.
375 * This function will search the descendants of @widget for a widget
376 * of type @widget_type that has a label matching @label_pattern next
377 * to it. This is most useful for automated GUI testing, e.g. to find
378 * the "OK" button in a dialog and synthesize clicks on it.
379 * However see gtk_test_find_label(), gtk_test_find_sibling() and
380 * gtk_test_widget_click() for possible caveats involving the search of
381 * such widgets and synthesizing widget events.
383 * Returns: (transfer none): a valid widget if any is found or %NULL.
388 gtk_test_find_widget (GtkWidget *widget,
389 const gchar *label_pattern,
392 GtkWidget *label = gtk_test_find_label (widget, label_pattern);
394 label = gtk_test_find_label (gtk_widget_get_toplevel (widget), label_pattern);
396 return gtk_test_find_sibling (label, widget_type);
401 * gtk_test_slider_set_perc:
402 * @widget: valid widget pointer.
403 * @percentage: value between 0 and 100.
405 * This function will adjust the slider position of all GtkRange
406 * based widgets, such as scrollbars or scales, it'll also adjust
407 * spin buttons. The adjustment value of these widgets is set to
408 * a value between the lower and upper limits, according to the
409 * @percentage argument.
414 gtk_test_slider_set_perc (GtkWidget *widget,
417 GtkAdjustment *adjustment = NULL;
418 if (GTK_IS_RANGE (widget))
419 adjustment = gtk_range_get_adjustment (GTK_RANGE (widget));
420 else if (GTK_IS_SPIN_BUTTON (widget))
421 adjustment = gtk_spin_button_get_adjustment (GTK_SPIN_BUTTON (widget));
423 gtk_adjustment_set_value (adjustment,
424 gtk_adjustment_get_lower (adjustment)
425 + (gtk_adjustment_get_upper (adjustment)
426 - gtk_adjustment_get_lower (adjustment)
427 - gtk_adjustment_get_page_size (adjustment))
428 * percentage * 0.01);
432 * gtk_test_slider_get_value:
433 * @widget: valid widget pointer.
435 * Retrive the literal adjustment value for GtkRange based
436 * widgets and spin buttons. Note that the value returned by
437 * this function is anything between the lower and upper bounds
438 * of the adjustment belonging to @widget, and is not a percentage
439 * as passed in to gtk_test_slider_set_perc().
441 * Returns: gtk_adjustment_get_value (adjustment) for an adjustment belonging to @widget.
446 gtk_test_slider_get_value (GtkWidget *widget)
448 GtkAdjustment *adjustment = NULL;
449 if (GTK_IS_RANGE (widget))
450 adjustment = gtk_range_get_adjustment (GTK_RANGE (widget));
451 else if (GTK_IS_SPIN_BUTTON (widget))
452 adjustment = gtk_spin_button_get_adjustment (GTK_SPIN_BUTTON (widget));
453 return adjustment ? gtk_adjustment_get_value (adjustment) : 0;
458 * @widget: valid widget pointer.
459 * @string: a 0-terminated C string
461 * Set the text string of @widget to @string if it is a GtkLabel,
462 * GtkEditable (entry and text widgets) or GtkTextView.
467 gtk_test_text_set (GtkWidget *widget,
470 if (GTK_IS_LABEL (widget))
471 gtk_label_set_text (GTK_LABEL (widget), string);
472 else if (GTK_IS_EDITABLE (widget))
475 gtk_editable_delete_text (GTK_EDITABLE (widget), 0, -1);
476 gtk_editable_insert_text (GTK_EDITABLE (widget), string, -1, &pos);
478 else if (GTK_IS_TEXT_VIEW (widget))
480 GtkTextBuffer *tbuffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (widget));
481 gtk_text_buffer_set_text (tbuffer, string, -1);
487 * @widget: valid widget pointer.
489 * Retrive the text string of @widget if it is a GtkLabel,
490 * GtkEditable (entry and text widgets) or GtkTextView.
492 * Returns: new 0-terminated C string, needs to be released with g_free().
497 gtk_test_text_get (GtkWidget *widget)
499 if (GTK_IS_LABEL (widget))
500 return g_strdup (gtk_label_get_text (GTK_LABEL (widget)));
501 else if (GTK_IS_EDITABLE (widget))
503 return g_strdup (gtk_editable_get_chars (GTK_EDITABLE (widget), 0, -1));
505 else if (GTK_IS_TEXT_VIEW (widget))
507 GtkTextBuffer *tbuffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (widget));
508 GtkTextIter start, end;
509 gtk_text_buffer_get_start_iter (tbuffer, &start);
510 gtk_text_buffer_get_end_iter (tbuffer, &end);
511 return gtk_text_buffer_get_text (tbuffer, &start, &end, FALSE);
517 * gtk_test_create_widget:
518 * @widget_type: a valid widget type.
519 * @first_property_name: (allow-none): Name of first property to set or %NULL
520 * @...: value to set the first property to, followed by more
521 * name-value pairs, terminated by %NULL
523 * This function wraps g_object_new() for widget types.
524 * It'll automatically show all created non window widgets, also
525 * g_object_ref_sink() them (to keep them alive across a running test)
526 * and set them up for destruction during the next test teardown phase.
528 * Returns: (transfer none): a newly created widget.
533 gtk_test_create_widget (GType widget_type,
534 const gchar *first_property_name,
539 g_return_val_if_fail (g_type_is_a (widget_type, GTK_TYPE_WIDGET), NULL);
540 va_start (var_args, first_property_name);
541 widget = (GtkWidget*) g_object_new_valist (widget_type, first_property_name, var_args);
545 if (!GTK_IS_WINDOW (widget))
546 gtk_widget_show (widget);
547 g_object_ref_sink (widget);
548 g_test_queue_unref (widget);
549 g_test_queue_destroy ((GDestroyNotify) gtk_widget_destroy, widget);
557 if (gtk_main_level())
562 test_increment_intp (int *intp)
566 return 1; /* TRUE in case we're connected to event signals */
570 * gtk_test_display_button_window:
571 * @window_title: Title of the window to be displayed.
572 * @dialog_text: Text inside the window to be displayed.
573 * @...: %NULL terminated list of (const char *label, int *nump) pairs.
575 * Create a window with window title @window_title, text contents @dialog_text,
576 * and a number of buttons, according to the paired argument list given
577 * as @... parameters.
578 * Each button is created with a @label and a ::clicked signal handler that
579 * incremrents the integer stored in @nump.
580 * The window will be automatically shown with gtk_widget_show_now() after
581 * creation, so when this function returns it has already been mapped,
582 * resized and positioned on screen.
583 * The window will quit any running gtk_main()-loop when destroyed, and it
584 * will automatically be destroyed upon test function teardown.
586 * Returns: (transfer full): a widget pointer to the newly created GtkWindow.
591 gtk_test_display_button_window (const gchar *window_title,
592 const gchar *dialog_text,
593 ...) /* NULL terminated list of (label, &int) pairs */
596 GtkWidget *window = gtk_test_create_widget (GTK_TYPE_WINDOW, "title", window_title, NULL);
597 GtkWidget *vbox = gtk_test_create_widget (GTK_TYPE_BOX, "parent", window, "orientation", GTK_ORIENTATION_VERTICAL, NULL);
599 gtk_test_create_widget (GTK_TYPE_LABEL, "label", dialog_text, "parent", vbox, NULL);
600 g_signal_connect (window, "destroy", G_CALLBACK (try_main_quit), NULL);
601 va_start (var_args, dialog_text);
602 arg1 = va_arg (var_args, const char*);
605 int *arg2 = va_arg (var_args, int*);
606 GtkWidget *button = gtk_test_create_widget (GTK_TYPE_BUTTON, "label", arg1, "parent", vbox, NULL);
607 g_signal_connect_swapped (button, "clicked", G_CALLBACK (test_increment_intp), arg2);
608 arg1 = va_arg (var_args, const char*);
611 gtk_widget_show_all (vbox);
612 gtk_widget_show_now (window);
613 while (gtk_events_pending ())
614 gtk_main_iteration ();
619 * gtk_test_create_simple_window:
620 * @window_title: Title of the window to be displayed.
621 * @dialog_text: Text inside the window to be displayed.
623 * Create a simple window with window title @window_title and
624 * text contents @dialog_text.
625 * The window will quit any running gtk_main()-loop when destroyed, and it
626 * will automatically be destroyed upon test function teardown.
628 * Returns: (transfer none): a widget pointer to the newly created GtkWindow.
633 gtk_test_create_simple_window (const gchar *window_title,
634 const gchar *dialog_text)
636 GtkWidget *window = gtk_test_create_widget (GTK_TYPE_WINDOW, "title", window_title, NULL);
637 GtkWidget *vbox = gtk_test_create_widget (GTK_TYPE_BOX, "parent", window, "orientation", GTK_ORIENTATION_VERTICAL, NULL);
638 gtk_test_create_widget (GTK_TYPE_LABEL, "label", dialog_text, "parent", vbox, NULL);
639 g_signal_connect (window, "destroy", G_CALLBACK (try_main_quit), NULL);
640 gtk_widget_show_all (vbox);
644 static GType *all_registered_types = NULL;
645 static guint n_all_registered_types = 0;
648 * gtk_test_list_all_types:
649 * @n_types: location to store number of types
651 * Return the type ids that have been registered after
652 * calling gtk_test_register_all_types().
654 * Returns: (array length=n_types zero-terminated=1) (transfer none):
655 * 0-terminated array of type ids
660 gtk_test_list_all_types (guint *n_types)
663 *n_types = n_all_registered_types;
664 return all_registered_types;
668 * gtk_test_register_all_types:
670 * Force registration of all core Gtk+ and Gdk object types.
671 * This allowes to refer to any of those object types via
672 * g_type_from_name() after calling this function.
677 gtk_test_register_all_types (void)
679 if (!all_registered_types)
681 const guint max_gtk_types = 999;
683 all_registered_types = g_new0 (GType, max_gtk_types);
684 tp = all_registered_types;
685 #include "gtktypefuncs.c"
686 n_all_registered_types = tp - all_registered_types;
687 g_assert (n_all_registered_types + 1 < max_gtk_types);