1Gtk3(3)               User Contributed Perl Documentation              Gtk3(3)
2
3
4

NAME

6       Gtk3 - Perl interface to the 3.x series of the gtk+ toolkit
7

SYNOPSIS

9         use Gtk3 -init;
10         my $window = Gtk3::Window->new ('toplevel');
11         my $button = Gtk3::Button->new ('Quit');
12         $button->signal_connect (clicked => sub { Gtk3::main_quit });
13         $window->add ($button);
14         $window->show_all;
15         Gtk3::main;
16

ABSTRACT

18       Perl bindings to the 3.x series of the gtk+ toolkit.  This module
19       allows you to write graphical user interfaces in a Perlish and object-
20       oriented way, freeing you from the casting and memory management in C,
21       yet remaining very close in spirit to original API.
22

DESCRIPTION

24       The "Gtk3" module allows a Perl developer to use the gtk+ graphical
25       user interface library.  Find out more about gtk+ at
26       <http://www.gtk.org>.
27
28       The gtk+ reference manual is also a handy companion when writing "Gtk3"
29       programs in Perl: <http://developer.gnome.org/gtk3/stable/>.  The Perl
30       bindings follow the C API very closely, and the C reference
31       documentation should be considered the canonical source.  The
32       principles underlying the mapping from C to Perl are explained in the
33       documentation of Glib::Object::Introspection, on which "Gtk3" is based.
34
35       Glib::Object::Introspection also comes with the "perli11ndoc" program
36       which displays the API reference documentation of all installed
37       libraries organized in accordance with these principles.
38
39   Wrapped libraries
40       "Gtk3" automatically sets up the following correspondence between C
41       libraries and Perl packages:
42
43         Library       | Package
44         --------------+----------
45         Gtk-3.0       | Gtk3
46         Gdk-3.0       | Gtk3::Gdk
47         GdkPixbuf-2.0 | Gtk3::Gdk
48         GdkPixdata-2.0| Gtk3::Gdk
49         Pango-1.0     | Pango
50
51   Import arguments
52       When importing "Gtk3", you can pass "-init" as in "use Gtk3 -init;" to
53       have "Gtk3::init" automatically called.  You can also pass a version
54       number to require a certain version of "Gtk3".
55
56   Customizations and overrides
57       In order to make things more Perlish or to make porting from "Gtk2" to
58       "Gtk3" easier, "Gtk3" customizes the API generated by
59       Glib::Object::Introspection in a few spots:
60
61       •   The array ref normally returned by the following functions is
62           flattened into a list:
63
64           Gtk3::ActionGroup::list_actions
65           Gtk3::Builder::get_objects
66           Gtk3::CellLayout::get_cells
67           Gtk3::Container::get_children
68           Gtk3::SizeGroup::get_widgets
69           Gtk3::TreePath::get_indices
70           Gtk3::TreeView::get_columns
71           Gtk3::UIManager::get_action_groups
72           Gtk3::UIManager::get_toplevels
73           Gtk3::Window::list_toplevels
74           Gtk3::stock_list_ids
75           Gtk3::Gdk::Pixbuf::get_formats
76       •   The following functions normally return a boolean and additional
77           out arguments, where the boolean indicates whether the out
78           arguments are valid.  They are altered such that when the boolean
79           is true, only the additional out arguments are returned, and when
80           the boolean is false, an empty list is returned.
81
82           Gtk3::TextBuffer::get_selection_bounds
83           Gtk3::TreeModel::get_iter
84           Gtk3::TreeModel::get_iter_first
85           Gtk3::TreeModel::get_iter_from_string
86           Gtk3::TreeModel::iter_children
87           Gtk3::TreeModel::iter_nth_child
88           Gtk3::TreeModel::iter_parent
89           Gtk3::TreeModelFilter::convert_child_iter_to_iter
90           Gtk3::TreeModelSort::convert_child_iter_to_iter
91           Gtk3::TreeSelection::get_selected
92           Gtk3::TreeView::get_dest_row_at_pos
93           Gtk3::TreeView::get_path_at_pos
94           Gtk3::TreeView::get_tooltip_context
95           Gtk3::TreeView::get_visible_range
96           Gtk3::TreeViewColumn::cell_get_position
97           Gtk3::stock_lookup
98           Gtk3::Gdk::Event::get_axis
99           Gtk3::Gdk::Event::get_button
100           Gtk3::Gdk::Event::get_click_count
101           Gtk3::Gdk::Event::get_coords
102           Gtk3::Gdk::Event::get_keycode
103           Gtk3::Gdk::Event::get_keyval
104           Gtk3::Gdk::Event::get_scroll_direction
105           Gtk3::Gdk::Event::get_scroll_deltas
106           Gtk3::Gdk::Event::get_state
107           Gtk3::Gdk::Event::get_root_coords
108           Gtk3::Gdk::Window::get_origin
109       •   Values of type Gtk3::ResponseType are converted to and from nick
110           names if possible, while still allowing raw IDs, in the following
111           places:
112
113           - For Gtk3::Dialog and Gtk3::InfoBar: the signal "response" as well
114           as the methods "add_action_widget", "add_button", "add_buttons",
115           "response", "set_default_response" and "set_response_sensitive".
116           - For Gtk3::Dialog: the methods "get_response_for_widget",
117           "get_widget_for_response", "run" and
118           "set_alternative_button_order".
119       •   Values of type Gtk3::IconSize are converted to and from nick names
120           if possible, while still allowing raw IDs, in the following places:
121
122           - Gtk3::Image: the constructors new_from_stock, new_from_icon_set,
123           new_from_icon_name and new_from_gicon, the getters get_stock,
124           get_icon_set, get_icon_name and get_gicon and the setters
125           set_from_stock, set_from_icon_set, set_from_icon_name,
126           set_from_gicon.
127           - Gtk3::Widget: the method render_icon.
128       •   The constants "Gtk3::EVENT_PROPAGATE" and "Gtk3::EVENT_STOP" can be
129           used in handlers for event signals like "key-press-event" to
130           indicate whether or not the event should continue propagating
131           through the widget hierarchy.
132
133       •   The records corresponding to the various Gtk3::Gdk::Event types,
134           like "expose" or "key-release", are represented as objects blessed
135           into specific Perl packages, like "Gtk3::Gdk::EventExpose" or
136           "Gtk3::Gdk::EventKey", that all inherit from "Gtk3::Gdk::Event".
137           This allows you to seemlessly access type-specific fields as well
138           as common fields, as in "$event->window" or "$event->keyval".
139
140       •   Gtk3::Gdk::Atom has overloads for the "==" and "!=" operators that
141           check for equality of the underlying atoms.
142
143       •   For backwards compatibility, the functions "Gtk3::get_version_info"
144           and "Gtk3::GET_VERSION_INFO" are provided, and the functions
145           "Gtk3::CHECK_VERSION", "Gtk3::check_version", "Gtk3::init",
146           "Gtk3::init_check", "Gtk3::main", "Gtk3::main_level" and
147           "Gtk3::main_quit" can be called as class-static or as normal
148           functions: for example, "Gtk3->main_quit" and "Gtk3::main_quit" are
149           both supported.  Additionally, "Gtk3::init" and "Gtk3::init_check"
150           automatically handle passing and updating @ARGV as appropriate.
151
152       •   A Perl reimplementation of "Gtk3::show_about_dialog" is provided.
153
154       •   Perl reimplementations of "Gtk3::ActionGroup::add_actions",
155           "add_radio_actions" and "add_toggle_actions" are provided.
156
157       •   "Gtk3::Builder::add_objects_from_file" and
158           "add_objects_from_string" also accept a list of objects instead of
159           an array ref.
160
161       •   "Gtk3::Builder::add_objects_from_string" and "add_from_string"
162           don't take length arguments, as they are computed automatically.
163
164       •   A Perl reimplementation of "Gtk3::Builder::connect_signals" is
165           provided.
166
167       •   The default "new" constructors of Gtk3::Button, Gtk3::CheckButton,
168           Gtk3::ColorButton, Gtk3::FontButton and Gtk3::ToggleButton reroute
169           to "new_with_mnemonic" if given an extra argument.
170
171       •   The default "new" constructor of Gtk3::CheckMenuItem reroutes to
172           "new_with_mnemonic" if given an extra argument.
173
174       •   The "length" argument of "Gtk3::Clipboard::set_text" is optional.
175
176       •   Perl reimplementations of "Gtk3::Container::add_with_properties",
177           "Gtk3::Container::child_get" and "Gtk3::Container::child_set" are
178           provided.
179
180       •   "Gtk3::Container::find_child_property" and
181           "Gtk3::Container::list_child_properties" are forwarded to the
182           corresponding functions in "Gtk3::ContainerClass".
183
184       •   "Gtk3::Container::get_focus_chain" returns a list of widgets, or an
185           empty list.
186
187       •   "Gtk3::Container::set_focus_chain" also accepts a list of widgets.
188
189       •   "Gtk3::CssProvider::load_from_data" also accepts a string.
190
191       •   For Gtk3::Dialog and Gtk3::InfoBar, a Perl implementation of
192           "add_buttons" is provided.
193
194       •   "Gtk3::Dialog::new" can optionally be called as "Gtk3::Dialog->new
195           (TITLE, PARENT, FLAGS, ...)" where "..." is a series of button text
196           and response id pairs.
197
198       •   A Perl implementation of "Gtk3::Dialog::new_with_buttons" is
199           provided.
200
201       •   The "length" argument of "Gtk3::Editable::insert_text" is optional.
202
203       •   A Perl implementation of "Gtk3::FileChooserDialog::new" is
204           provided.
205
206       •   "Gtk3::HBox::new" uses the defaults homogeneous = FALSE and spacing
207           = 5.
208
209       •   The default "new" constructor of Gtk3::ImageMenuItem reroutes to
210           "new_with_mnemonic" if given an extra argument.
211
212       •   "Gtk3::InfoBar::new" can optionally be called as
213           "Gtk3::InfoBar->new (...)" where "..." is a series of button text
214           and response id pairs.
215
216       •   A Perl reimplementation of "Gtk3::InfoBar::new_with_buttons" is
217           provided.
218
219       •   The default "new" constructor of Gtk3::LinkButton reroutes to
220           "new_with_label" if given an extra argument.
221
222       •   "Gtk3::ListStore::new" also accepts a list of type names.
223
224       •   Gtk3::ListStore has a "get" method that calls
225           "Gtk3::TreeModel::get" instead of "Glib::Object::get".
226
227       •   "Gtk3::ListStore::insert_with_values" also accepts a list of
228           "column => value" pairs and reroutes to "insert_with_valuesv".
229
230       •   "Gtk3::ListStore::set" also accepts a list of "column => value"
231           pairs.
232
233       •   "Gtk3::Menu::popup" reroutes to "popup_for_device" for better
234           callback handling.
235
236       •   "Gtk3::Menu::popup_for_device" allows the given menu position func
237           to return only x and y coordinates, defaulting "push_in" to FALSE.
238
239       •   The default "new" constructor of Gtk3::MenuItem reroutes to
240           "new_with_mnemonic" if given an extra argument.
241
242       •   A Perl reimplementation of "Gtk3::MessageDialog::new" is provided.
243
244       •   A Perl reimplementation of "Gtk3::MessageDialog::new_with_markup"
245           is provided.
246
247       •   A Perl reimplementation of
248           "Gtk3::MessageDialog::format_secondary_text" and
249           "Gtk3::MessageDialog::format_secondary_markup" is provided
250
251       •   The group handling in the constructors and accessors of
252           Gtk3::RadioAction, Gtk3::RadioButton, Gtk3::RadioMenuItem and
253           Gtk3::RadioToolButton is amended to work correctly when given array
254           refs of group members or single group members.
255
256       •   Perl reimplementations of "Gtk3::RecentChooserDialog::new" and
257           "new_for_manager" are provided.
258
259       •   Redirects are provided from "Gtk3::Stock::[function]" to
260           "Gtk3::stock_[function]" for "add", "add_static", "list_ids",
261           "lookup" and "set_translate_func".
262
263       •   A Perl reimplementation of "Gtk3::StyleContext::get" is provided.
264
265       •   An override for "Gtk3::TargetEntry::new" is provided that
266           automatically handles the conversion of the "flags" argument.
267
268       •   A Perl reimplementation of "Gtk3::TextBuffer::create_tag" is
269           provided.
270
271       •   The "length" arguments of "Gtk3::TextBuffer::insert",
272           "insert_at_cursor", "insert_interactive",
273           "insert_interactive_at_cursor", "insert_markup" and "set_text" are
274           optional.
275
276       •   Perl reimplementations of "Gtk3::TextBuffer::insert_with_tags" and
277           "insert_with_tags_by_name" are provided which do not require a
278           "length" argument.
279
280       •   A Perl reimplementation of "Gtk3::TreeModel::get" is provided.
281
282       •   A redirect is added from "Gtk3::TreeModelFilter::new" to
283           <Gtk3::TreeModel::filter_new> so that Gtk3::TreeModelFilter objects
284           can be constructed normally.
285
286       •   Gtk3::TreeModelFilter has a "get" method that calls
287           "Gtk3::TreeModel::get" instead of "Glib::Object::get".
288
289       •   Prior to gtk+ 3.24.14, a redirect is added from
290           "Gtk3::TreeModelSort::new_with_model" to
291           <Gtk3::TreeModel::sort_new_with_model> so that Gtk3::TreeModelSort
292           objects can be constructed normally.
293
294       •   Gtk3::TreeModelSort has a "get" method that calls
295           "Gtk3::TreeModel::get" instead of "Glib::Object::get".
296
297       •   "Gtk3::TreePath::new" redirects to "new_from_string" if an
298           additional argument is given.
299
300       •   A Perl reimplementation of "Gtk3::TreePath::new_from_indices" is
301           provided.
302
303       •   "Gtk3::TreeStore::new" also accepts a list of type names.
304
305       •   Gtk3::TreeStore has a "get" method that calls
306           "Gtk3::TreeModel::get" instead of "Glib::Object::get".
307
308       •   "Gtk3::TreeStore::insert_with_values" also accepts a list of
309           "column => value" pairs.
310
311       •   "Gtk3::TreeStore::set" also accepts a list of "column => value"
312           pairs.
313
314       •   "Gtk3::TreeView::new" redirects to "new_with_model" if an
315           additional argument is given.
316
317       •   A Perl reimplementation of
318           "Gtk3::TreeView::insert_column_with_attributes" is provided.
319
320       •   A Perl reimplementation of
321           "Gtk3::TreeViewColumn::new_with_attributes" is provided.
322
323       •   Perl reimplementations of "Gtk3::TreeViewColumn::set_attributes"
324           and "Gtk3::CellLayout::set_attributes" are provided.
325
326       •   "Gtk3::UIManager::add_ui_from_string" takes no "length" argument.
327
328       •   "Gtk3::VBox::new" uses the defaults homogeneous = FALSE and spacing
329           = 5.
330
331       •   "Gtk3::Widget::add_events" and "Gtk3::Widget::set_events" also
332           accept strings, array references and "Gtk3::Gdk::EventMask" objects
333           for the "events" parameter.
334
335       •   "Gtk3::Widget::get_events" returns a "Gtk3::Gdk::EventMask" object
336           that can also be compared to numeric values with "==" and ">=".
337
338       •   "Gtk3::Widget::find_style_property" and
339           "Gtk3::Widget::list_style_properties" are forwarded to the
340           corresponding functions in "Gtk3::WidgetClass".
341
342       •   A Perl reimplementation of "Gtk3::Widget::style_get" is provided.
343
344       •   "Gtk3::Window::new" uses the default type = 'toplevel'.
345
346       •   A constructor "Gtk3::Gdk::RGBA::new" is provided that can be called
347           as "Gtk3::Gdk::RGBA->new (r, g, b, a)".
348
349       •   "Gtk3::Gdk::RGBA::parse" can be called as a function returning a
350           new instance ("$rgba = Gtk3::Gdk::RGBA::parse ($spec)") or as a
351           method ("$rgba->parse ($spec)").
352
353       •   "Gtk3::Gdk::Window::new" optionally computes the "attr_mask"
354           automatically from the given "attr".
355
356       •   "Gtk3::Gdk::Pixbuf::get_pixels" returns a byte string.
357
358       •   "Gtk3::Gdk::Pixbuf::new_from_data" is reimplemented in terms of
359           "new_from_bytes" (with gdk-pixbuf >= 2.32) or "new_from_inline"
360           (with gtk-pixbuf < 2.32) for correct memory management.  No
361           "destroy_fn" and "destroy_fn_data" arguments are needed.
362
363       •   "Gtk3::Gdk::Pixbuf::new_from_inline" does not take a "copy_pixels"
364           argument.  It is always set to TRUE for correct memory management.
365
366       •   "Gtk3::Gdk::Pixbuf::new_from_xpm_data" also accepts a list of XPM
367           lines.
368
369       •   "Gtk3::Gdk::Pixbuf::save", "save_to_buffer" and "save_to_callback"
370           also accept "key => value" pairs and invoke the correct C function
371           as appropriate for the current gdk-pixbuf version.
372
373       •   The "length" arguments of "Pango::Layout::set_text" and
374           "set_markup" are optional.
375
376   Perl compatibility
377       As of 5.20.0, perl does not automatically re-check the locale
378       environment for changes.  If a function thus changes the locale behind
379       perl's back, problems might arise whenever numbers are formatted, for
380       example when checking versions.  To ensure perl's assumption about the
381       locale are up-to-date, the functions "Gtk3::init", "init_check",
382       "init_with_args" and "parse_args" are amended to let perl know of any
383       changes.
384
385   Porting from Gtk2 to Gtk3
386       The majority of the API has not changed, so as a first approximation
387       you can run "s/Gtk2/Gtk3/" on your application.  A big exception to
388       this rule is APIs that were deprecated in gtk+ 2.x -- these were all
389       removed from gtk+ 3.0 and thus from Gtk3.  The migration guide at
390       <http://developer.gnome.org/gtk3/stable/migrating.html> describes what
391       to use instead.  Apart from this, here is a list of some other
392       incompatible differences between Gtk2 and Gtk3:
393
394       •   The call syntax for class-static methods is now always
395           "Gtk3::Stock::lookup" instead of "Gtk3::Stock->lookup".
396
397       •   The %Gtk2::Gdk::Keysyms hash is gone; instead of
398           "Gtk2::Gdk::Keysyms{XYZ}", use "Gtk3::Gdk::KEY_XYZ".
399
400       •   The Gtk2::Pango compatibility wrapper was not carried over; simply
401           use the namespace "Pango" everywhere.  It gets set up automatically
402           when loading Gtk3.
403
404       •   The types Gtk3::Allocation and Gtk3::Gdk::Rectangle are now aliases
405           for Cairo::RectangleInt, and as such they are represented as plain
406           hashes with keys 'width', 'height', 'x' and 'y'.
407
408       •   Gtk3::Editable: Callbacks connected to the "insert-text" signal do
409           not have as many options anymore as they had in Gtk2.  Changes to
410           arguments will not be propagated to the next signal handler, and
411           only the updated position can and must be returned.
412
413       •   Gtk3::Menu: In gtk+ < 3.16, the position callback passed to popup()
414           does not receive x and y parameters.
415
416       •   Gtk3::RadioAction: The constructor now follows the C API.
417
418       •   Gtk3::TreeModel: iter_next() is now a method that is modifying the
419           iter directly, instead of returning a new one.  rows_reordered()
420           and the "rows-reordered" signal are currently unusable.
421
422       •   Gtk3::TreeSelection: get_selected_rows() now returns two values: an
423           array ref containing the selected paths, and the model.
424           get_user_data() is not available currently.
425
426       •   Gtk3::TreeSortable: get_sort_column_id() has an additional boolean
427           return value.
428
429       •   Gtk3::TreeStore, Gtk3::ListStore: reorder() is currently unusable.
430
431       •   Gtk3::Widget: grab_add() and grab_remove() are methods now:
432           "$widget->grab_add", "$widget->grab_remove".
433
434       •   Gtk3::Gdk::Atom: The constructor new() is not provided anymore, and
435           the class function intern() must now be called as
436           "Gtk3::Gdk::Atom::intern (name, only_if_exists)".
437
438       •   Implementations of Gtk3::TreeModel: Gtk3::TreeIter now has a
439           constructor called new() expecting "key => value" pairs;
440           new_from_arrayref() does not exist anymore.  To access the contents
441           of Gtk3::TreeIter, use stamp(), user_data(), user_data2() and
442           user_data3(); to_arrayref() does not exist anymore.  GET_ITER(),
443           ITER_CHILDREN(), ITER_NTH_CHILD() and ITER_PARENT() must return an
444           additional boolean value.  ITER_NEXT() must modify the iter and
445           return a boolean rather than return a new iter.  GET_VALUE() must
446           return the value wrapped with
447           "Glib::Object::Introspection::GValueWrapper->new".
448
449       •   Implementations of Gtk3::CellLayout: GET_CELLS() now needs to
450           return an array ref instead of a list.
451
452       Note also that Gtk3::CHECK_VERSION will always fail when passed 2.y.z,
453       so if you have any existing version checks in your code, you will most
454       likely need to remove them.
455

SEE ALSO

457       •   To discuss Gtk3 and ask questions join gtk-perl-list@gnome.org at
458           <http://mail.gnome.org/mailman/listinfo/gtk-perl-list>.
459
460       •   Also have a look at the gtk2-perl website and sourceforge project
461           page, <http://gtk2-perl.sourceforge.net>.
462
463       •   Glib
464
465       •   Glib::Object::Introspection
466

AUTHORS

468       Torsten Schönfeld <kaffeetisch@gmx.de>
469
471       Copyright (C) 2011-2015 by Torsten Schoenfeld <kaffeetisch@gmx.de>
472
473       This library is free software; you can redistribute it and/or modify it
474       under the terms of the GNU Library General Public License as published
475       by the Free Software Foundation; either version 2.1 of the License, or
476       (at your option) any later version.
477
478
479
480perl v5.36.0                      2022-07-22                           Gtk3(3)
Impressum