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       ·   The group handling in the constructors and accessors of
245           Gtk3::RadioAction, Gtk3::RadioButton, Gtk3::RadioMenuItem and
246           Gtk3::RadioToolButton is amended to work correctly when given array
247           refs of group members or single group members.
248
249       ·   Perl reimplementations of "Gtk3::RecentChooserDialog::new" and
250           "new_for_manager" are provided.
251
252       ·   Redirects are provided from "Gtk3::Stock::[function]" to
253           "Gtk3::stock_[function]" for "add", "add_static", "list_ids",
254           "lookup" and "set_translate_func".
255
256       ·   A Perl reimplementation of "Gtk3::StyleContext::get" is provided.
257
258       ·   An override for "Gtk3::TargetEntry::new" is provided that
259           automatically handles the conversion of the "flags" argument.
260
261       ·   A Perl reimplementation of "Gtk3::TextBuffer::create_tag" is
262           provided.
263
264       ·   The "length" arguments of "Gtk3::TextBuffer::insert",
265           "insert_at_cursor", "insert_interactive",
266           "insert_interactive_at_cursor", "insert_markup" and "set_text" are
267           optional.
268
269       ·   Perl reimplementations of "Gtk3::TextBuffer::insert_with_tags" and
270           "insert_with_tags_by_name" are provided which do not require a
271           "length" argument.
272
273       ·   A Perl reimplementation of "Gtk3::TreeModel::get" is provided.
274
275       ·   A redirect is added from "Gtk3::TreeModelFilter::new" to
276           <Gtk3::TreeModel::filter_new> so that Gtk3::TreeModelFilter objects
277           can be constructed normally.
278
279       ·   Gtk3::TreeModelFilter has a "get" method that calls
280           "Gtk3::TreeModel::get" instead of "Glib::Object::get".
281
282       ·   Prior to gtk+ 3.24.14, a redirect is added from
283           "Gtk3::TreeModelSort::new_with_model" to
284           <Gtk3::TreeModel::sort_new_with_model> so that Gtk3::TreeModelSort
285           objects can be constructed normally.
286
287       ·   Gtk3::TreeModelSort has a "get" method that calls
288           "Gtk3::TreeModel::get" instead of "Glib::Object::get".
289
290       ·   "Gtk3::TreePath::new" redirects to "new_from_string" if an
291           additional argument is given.
292
293       ·   A Perl reimplementation of "Gtk3::TreePath::new_from_indices" is
294           provided.
295
296       ·   "Gtk3::TreeStore::new" also accepts a list of type names.
297
298       ·   Gtk3::TreeStore has a "get" method that calls
299           "Gtk3::TreeModel::get" instead of "Glib::Object::get".
300
301       ·   "Gtk3::TreeStore::insert_with_values" also accepts a list of
302           "column => value" pairs.
303
304       ·   "Gtk3::TreeStore::set" also accepts a list of "column => value"
305           pairs.
306
307       ·   "Gtk3::TreeView::new" redirects to "new_with_model" if an
308           additional argument is given.
309
310       ·   A Perl reimplementation of
311           "Gtk3::TreeView::insert_column_with_attributes" is provided.
312
313       ·   A Perl reimplementation of
314           "Gtk3::TreeViewColumn::new_with_attributes" is provided.
315
316       ·   Perl reimplementations of "Gtk3::TreeViewColumn::set_attributes"
317           and "Gtk3::CellLayout::set_attributes" are provided.
318
319       ·   "Gtk3::UIManager::add_ui_from_string" takes no "length" argument.
320
321       ·   "Gtk3::VBox::new" uses the defaults homogeneous = FALSE and spacing
322           = 5.
323
324       ·   "Gtk3::Widget::add_events" and "Gtk3::Widget::set_events" also
325           accept strings, array references and "Gtk3::Gdk::EventMask" objects
326           for the "events" parameter.
327
328       ·   "Gtk3::Widget::get_events" returns a "Gtk3::Gdk::EventMask" object
329           that can also be compared to numeric values with "==" and ">=".
330
331       ·   "Gtk3::Widget::find_style_property" and
332           "Gtk3::Widget::list_style_properties" are forwarded to the
333           corresponding functions in "Gtk3::WidgetClass".
334
335       ·   A Perl reimplementation of "Gtk3::Widget::style_get" is provided.
336
337       ·   "Gtk3::Window::new" uses the default type = 'toplevel'.
338
339       ·   A constructor "Gtk3::Gdk::RGBA::new" is provided that can be called
340           as "Gtk3::Gdk::RGBA->new (r, g, b, a)".
341
342       ·   "Gtk3::Gdk::RGBA::parse" can be called as a function returning a
343           new instance ("$rgba = Gtk3::Gdk::RGBA::parse ($spec)") or as a
344           method ("$rgba->parse ($spec)").
345
346       ·   "Gtk3::Gdk::Window::new" optionally computes the "attr_mask"
347           automatically from the given "attr".
348
349       ·   "Gtk3::Gdk::Pixbuf::get_pixels" returns a byte string.
350
351       ·   "Gtk3::Gdk::Pixbuf::new_from_data" is reimplemented in terms of
352           "new_from_bytes" (with gdk-pixbuf >= 2.32) or "new_from_inline"
353           (with gtk-pixbuf < 2.32) for correct memory management.  No
354           "destroy_fn" and "destroy_fn_data" arguments are needed.
355
356       ·   "Gtk3::Gdk::Pixbuf::new_from_inline" does not take a "copy_pixels"
357           argument.  It is always set to TRUE for correct memory management.
358
359       ·   "Gtk3::Gdk::Pixbuf::new_from_xpm_data" also accepts a list of XPM
360           lines.
361
362       ·   "Gtk3::Gdk::Pixbuf::save", "save_to_buffer" and "save_to_callback"
363           also accept "key => value" pairs and invoke the correct C function
364           as appropriate for the current gdk-pixbuf version.
365
366       ·   The "length" arguments of "Pango::Layout::set_text" and
367           "set_markup" are optional.
368
369   Perl compatibility
370       As of 5.20.0, perl does not automatically re-check the locale
371       environment for changes.  If a function thus changes the locale behind
372       perl's back, problems might arise whenever numbers are formatted, for
373       example when checking versions.  To ensure perl's assumption about the
374       locale are up-to-date, the functions "Gtk3::init", "init_check",
375       "init_with_args" and "parse_args" are amended to let perl know of any
376       changes.
377
378   Porting from Gtk2 to Gtk3
379       The majority of the API has not changed, so as a first approximation
380       you can run "s/Gtk2/Gtk3/" on your application.  A big exception to
381       this rule is APIs that were deprecated in gtk+ 2.x -- these were all
382       removed from gtk+ 3.0 and thus from Gtk3.  The migration guide at
383       <http://developer.gnome.org/gtk3/stable/migrating.html> describes what
384       to use instead.  Apart from this, here is a list of some other
385       incompatible differences between Gtk2 and Gtk3:
386
387       ·   The call syntax for class-static methods is now always
388           "Gtk3::Stock::lookup" instead of "Gtk3::Stock->lookup".
389
390       ·   The %Gtk2::Gdk::Keysyms hash is gone; instead of
391           "Gtk2::Gdk::Keysyms{XYZ}", use "Gtk3::Gdk::KEY_XYZ".
392
393       ·   The Gtk2::Pango compatibility wrapper was not carried over; simply
394           use the namespace "Pango" everywhere.  It gets set up automatically
395           when loading Gtk3.
396
397       ·   The types Gtk3::Allocation and Gtk3::Gdk::Rectangle are now aliases
398           for Cairo::RectangleInt, and as such they are represented as plain
399           hashes with keys 'width', 'height', 'x' and 'y'.
400
401       ·   Gtk3::Editable: Callbacks connected to the "insert-text" signal do
402           not have as many options anymore as they had in Gtk2.  Changes to
403           arguments will not be propagated to the next signal handler, and
404           only the updated position can and must be returned.
405
406       ·   Gtk3::Menu: In gtk+ < 3.16, the position callback passed to popup()
407           does not receive x and y parameters.
408
409       ·   Gtk3::RadioAction: The constructor now follows the C API.
410
411       ·   Gtk3::TreeModel: iter_next() is now a method that is modifying the
412           iter directly, instead of returning a new one.  rows_reordered()
413           and the "rows-reordered" signal are currently unusable.
414
415       ·   Gtk3::TreeSelection: get_selected_rows() now returns two values: an
416           array ref containing the selected paths, and the model.
417           get_user_data() is not available currently.
418
419       ·   Gtk3::TreeSortable: get_sort_column_id() has an additional boolean
420           return value.
421
422       ·   Gtk3::TreeStore, Gtk3::ListStore: reorder() is currently unusable.
423
424       ·   Gtk3::Widget: grab_add() and grab_remove() are methods now:
425           "$widget->grab_add", "$widget->grab_remove".
426
427       ·   Gtk3::Gdk::Atom: The constructor new() is not provided anymore, and
428           the class function intern() must now be called as
429           "Gtk3::Gdk::Atom::intern (name, only_if_exists)".
430
431       ·   Implementations of Gtk3::TreeModel: Gtk3::TreeIter now has a
432           constructor called new() expecting "key => value" pairs;
433           new_from_arrayref() does not exist anymore.  To access the contents
434           of Gtk3::TreeIter, use stamp(), user_data(), user_data2() and
435           user_data3(); to_arrayref() does not exist anymore.  GET_ITER(),
436           ITER_CHILDREN(), ITER_NTH_CHILD() and ITER_PARENT() must return an
437           additional boolean value.  ITER_NEXT() must modify the iter and
438           return a boolean rather than return a new iter.  GET_VALUE() must
439           return the value wrapped with
440           "Glib::Object::Introspection::GValueWrapper->new".
441
442       ·   Implementations of Gtk3::CellLayout: GET_CELLS() now needs to
443           return an array ref instead of a list.
444
445       Note also that Gtk3::CHECK_VERSION will always fail when passed 2.y.z,
446       so if you have any existing version checks in your code, you will most
447       likely need to remove them.
448

SEE ALSO

450       ·   To discuss Gtk3 and ask questions join gtk-perl-list@gnome.org at
451           <http://mail.gnome.org/mailman/listinfo/gtk-perl-list>.
452
453       ·   Also have a look at the gtk2-perl website and sourceforge project
454           page, <http://gtk2-perl.sourceforge.net>.
455
456       ·   Glib
457
458       ·   Glib::Object::Introspection
459

AUTHORS

461       Torsten Schönfeld <kaffeetisch@gmx.de>
462
464       Copyright (C) 2011-2015 by Torsten Schoenfeld <kaffeetisch@gmx.de>
465
466       This library is free software; you can redistribute it and/or modify it
467       under the terms of the GNU Library General Public License as published
468       by the Free Software Foundation; either version 2.1 of the License, or
469       (at your option) any later version.
470
471
472
473perl v5.30.2                      2020-04-06                           Gtk3(3)
Impressum