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

SEE ALSO

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

AUTHORS

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