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 GdkPixdata-2.0| Gtk3::Gdk
49 Pango-1.0 | Pango
50 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 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 · The array ref normally returned by the following functions is
62 flattened into a list:
63 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 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 - 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 - 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 · 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 · Gtk3::Gdk::Atom has overloads for the "==" and "!=" operators that
141 check for equality of the underlying atoms.
142 · 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 · A Perl reimplementation of "Gtk3::show_about_dialog" is provided.
153 · Perl reimplementations of "Gtk3::ActionGroup::add_actions",
155 "add_radio_actions" and "add_toggle_actions" are provided.
156 · "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 · "Gtk3::Builder::add_objects_from_string" and "add_from_string"
162 don't take length arguments, as they are computed automatically.
163 · A Perl reimplementation of "Gtk3::Builder::connect_signals" is
165 provided.
166 · 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 · The default "new" constructor of Gtk3::CheckMenuItem reroutes to
172 "new_with_mnemonic" if given an extra argument.
173 · The "length" argument of "Gtk3::Clipboard::set_text" is optional.
175 · Perl reimplementations of "Gtk3::Container::add_with_properties",
177 "Gtk3::Container::child_get" and "Gtk3::Container::child_set" are
178 provided.
179 · "Gtk3::Container::find_child_property" and
181 "Gtk3::Container::list_child_properties" are forwarded to the
182 corresponding functions in "Gtk3::ContainerClass".
183 · "Gtk3::Container::get_focus_chain" returns a list of widgets, or an
185 empty list.
186 · "Gtk3::Container::set_focus_chain" also accepts a list of widgets.
188 · "Gtk3::CssProvider::load_from_data" also accepts a string.
190 · For Gtk3::Dialog and Gtk3::InfoBar, a Perl implementation of
192 "add_buttons" is provided.
193 · "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 · A Perl implementation of "Gtk3::Dialog::new_with_buttons" is
199 provided.
200 · The "length" argument of "Gtk3::Editable::insert_text" is optional.
202 · A Perl implementation of "Gtk3::FileChooserDialog::new" is
204 provided.
205 · "Gtk3::HBox::new" uses the defaults homogeneous = FALSE and spacing
207 = 5.
208 · The default "new" constructor of Gtk3::ImageMenuItem reroutes to
210 "new_with_mnemonic" if given an extra argument.
211 · "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 · A Perl reimplementation of "Gtk3::InfoBar::new_with_buttons" is
217 provided.
218 · The default "new" constructor of Gtk3::LinkButton reroutes to
220 "new_with_label" if given an extra argument.
221 · "Gtk3::ListStore::new" also accepts a list of type names.
223 · Gtk3::ListStore has a "get" method that calls
225 "Gtk3::TreeModel::get" instead of "Glib::Object::get".
226 · "Gtk3::ListStore::insert_with_values" also accepts a list of
228 "column => value" pairs and reroutes to "insert_with_valuesv".
229 · "Gtk3::ListStore::set" also accepts a list of "column => value"
231 pairs.
232 · "Gtk3::Menu::popup" reroutes to "popup_for_device" for better
234 callback handling.
235 · "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 · The default "new" constructor of Gtk3::MenuItem reroutes to
240 "new_with_mnemonic" if given an extra argument.
241 · A Perl reimplementation of "Gtk3::MessageDialog::new" is provided.
243 · 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 · Perl reimplementations of "Gtk3::RecentChooserDialog::new" and
250 "new_for_manager" are provided.
251 · 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 · A Perl reimplementation of "Gtk3::StyleContext::get" is provided.
257 · An override for "Gtk3::TargetEntry::new" is provided that
259 automatically handles the conversion of the "flags" argument.
260 · A Perl reimplementation of "Gtk3::TextBuffer::create_tag" is
262 provided.
263 · 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 · 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 · A Perl reimplementation of "Gtk3::TreeModel::get" is provided.
274 · 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 · Gtk3::TreeModelFilter has a "get" method that calls
280 "Gtk3::TreeModel::get" instead of "Glib::Object::get".
281 · 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 · Gtk3::TreeModelSort has a "get" method that calls
288 "Gtk3::TreeModel::get" instead of "Glib::Object::get".
289 · "Gtk3::TreePath::new" redirects to "new_from_string" if an
291 additional argument is given.
292 · A Perl reimplementation of "Gtk3::TreePath::new_from_indices" is
294 provided.
295 · "Gtk3::TreeStore::new" also accepts a list of type names.
297 · Gtk3::TreeStore has a "get" method that calls
299 "Gtk3::TreeModel::get" instead of "Glib::Object::get".
300 · "Gtk3::TreeStore::insert_with_values" also accepts a list of
302 "column => value" pairs.
303 · "Gtk3::TreeStore::set" also accepts a list of "column => value"
305 pairs.
306 · "Gtk3::TreeView::new" redirects to "new_with_model" if an
308 additional argument is given.
309 · A Perl reimplementation of
311 "Gtk3::TreeView::insert_column_with_attributes" is provided.
312 · A Perl reimplementation of
314 "Gtk3::TreeViewColumn::new_with_attributes" is provided.
315 · Perl reimplementations of "Gtk3::TreeViewColumn::set_attributes"
317 and "Gtk3::CellLayout::set_attributes" are provided.
318 · "Gtk3::UIManager::add_ui_from_string" takes no "length" argument.
320 · "Gtk3::VBox::new" uses the defaults homogeneous = FALSE and spacing
322 = 5.
323 · "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 · "Gtk3::Widget::get_events" returns a "Gtk3::Gdk::EventMask" object
329 that can also be compared to numeric values with "==" and ">=".
330 · "Gtk3::Widget::find_style_property" and
332 "Gtk3::Widget::list_style_properties" are forwarded to the
333 corresponding functions in "Gtk3::WidgetClass".
334 · A Perl reimplementation of "Gtk3::Widget::style_get" is provided.
336 · "Gtk3::Window::new" uses the default type = 'toplevel'.
338 · A constructor "Gtk3::Gdk::RGBA::new" is provided that can be called
340 as "Gtk3::Gdk::RGBA->new (r, g, b, a)".
341 · "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 · "Gtk3::Gdk::Window::new" optionally computes the "attr_mask"
347 automatically from the given "attr".
348 · "Gtk3::Gdk::Pixbuf::get_pixels" returns a byte string.
350 · "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 · "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 · "Gtk3::Gdk::Pixbuf::new_from_xpm_data" also accepts a list of XPM
360 lines.
361 · "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 · The "length" arguments of "Pango::Layout::set_text" and
367 "set_markup" are optional.
368 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 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 · The call syntax for class-static methods is now always
388 "Gtk3::Stock::lookup" instead of "Gtk3::Stock->lookup".
389 · The %Gtk2::Gdk::Keysyms hash is gone; instead of
391 "Gtk2::Gdk::Keysyms{XYZ}", use "Gtk3::Gdk::KEY_XYZ".
392 · 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 · 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 · 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 · Gtk3::Menu: In gtk+ < 3.16, the position callback passed to popup()
407 does not receive x and y parameters.
408 · Gtk3::RadioAction: The constructor now follows the C API.
410 · 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 · 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 · Gtk3::TreeSortable: get_sort_column_id() has an additional boolean
420 return value.
421 · Gtk3::TreeStore, Gtk3::ListStore: reorder() is currently unusable.
423 · Gtk3::Widget: grab_add() and grab_remove() are methods now:
425 "$widget->grab_add", "$widget->grab_remove".
426 · 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 · 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 · Implementations of Gtk3::CellLayout: GET_CELLS() now needs to
443 return an array ref instead of a list.
444 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
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 · Also have a look at the gtk2-perl website and sourceforge project
454 page, <http://gtk2-perl.sourceforge.net>.
455 · Glib
457 · Glib::Object::Introspection
459
461 Torsten Schönfeld <kaffeetisch@gmx.de>
462
464 Copyright (C) 2011-2015 by Torsten Schoenfeld <kaffeetisch@gmx.de>
465 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.
470perl v5.30.2 2020-04-06 Gtk3(3)