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