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 · 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 · Gtk3::TreeModelSort has a "get" method that calls
287 "Gtk3::TreeModel::get" instead of "Glib::Object::get".
288 · "Gtk3::TreePath::new" redirects to "new_from_string" if an
290 additional argument is given.
291 · A Perl reimplementation of "Gtk3::TreePath::new_from_indices" is
293 provided.
294 · "Gtk3::TreeStore::new" also accepts a list of type names.
296 · Gtk3::TreeStore has a "get" method that calls
298 "Gtk3::TreeModel::get" instead of "Glib::Object::get".
299 · "Gtk3::TreeStore::insert_with_values" also accepts a list of
301 "column => value" pairs.
302 · "Gtk3::TreeStore::set" also accepts a list of "column => value"
304 pairs.
305 · "Gtk3::TreeView::new" redirects to "new_with_model" if an
307 additional argument is given.
308 · A Perl reimplementation of
310 "Gtk3::TreeView::insert_column_with_attributes" is provided.
311 · A Perl reimplementation of
313 "Gtk3::TreeViewColumn::new_with_attributes" is provided.
314 · Perl reimplementations of "Gtk3::TreeViewColumn::set_attributes"
316 and "Gtk3::CellLayout::set_attributes" are provided.
317 · "Gtk3::UIManager::add_ui_from_string" takes no "length" argument.
319 · "Gtk3::VBox::new" uses the defaults homogeneous = FALSE and spacing
321 = 5.
322 · "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 · "Gtk3::Widget::get_events" returns a "Gtk3::Gdk::EventMask" object
328 that can also be compared to numeric values with "==" and ">=".
329 · "Gtk3::Widget::find_style_property" and
331 "Gtk3::Widget::list_style_properties" are forwarded to the
332 corresponding functions in "Gtk3::WidgetClass".
333 · A Perl reimplementation of "Gtk3::Widget::style_get" is provided.
335 · "Gtk3::Window::new" uses the default type = 'toplevel'.
337 · A constructor "Gtk3::Gdk::RGBA::new" is provided that can be called
339 as "Gtk3::Gdk::RGBA->new (r, g, b, a)".
340 · "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 · "Gtk3::Gdk::Window::new" optionally computes the "attr_mask"
346 automatically from the given "attr".
347 · "Gtk3::Gdk::Pixbuf::get_pixels" returns a byte string.
349 · "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 · "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 · "Gtk3::Gdk::Pixbuf::new_from_xpm_data" also accepts a list of XPM
358 lines.
359 · "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 · The "length" arguments of "Pango::Layout::set_text" and
365 "set_markup" are optional.
366 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 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 · The call syntax for class-static methods is now always
386 "Gtk3::Stock::lookup" instead of "Gtk3::Stock->lookup".
387 · The %Gtk2::Gdk::Keysyms hash is gone; instead of
389 "Gtk2::Gdk::Keysyms{XYZ}", use "Gtk3::Gdk::KEY_XYZ".
390 · 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 · 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 · 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 · Gtk3::Menu: In gtk+ < 3.16, the position callback passed to popup()
405 does not receive x and y parameters.
406 · Gtk3::RadioAction: The constructor now follows the C API.
408 · 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 · 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 · Gtk3::TreeSortable: get_sort_column_id() has an additional boolean
418 return value.
419 · Gtk3::TreeStore, Gtk3::ListStore: reorder() is currently unusable.
421 · Gtk3::Widget: grab_add() and grab_remove() are methods now:
423 "$widget->grab_add", "$widget->grab_remove".
424 · 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 · 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 · Implementations of Gtk3::CellLayout: GET_CELLS() now needs to
441 return an array ref instead of a list.
442 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
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 · Also have a look at the gtk2-perl website and sourceforge project
452 page, <http://gtk2-perl.sourceforge.net>.
453 · Glib
455 · Glib::Object::Introspection
457
459 Torsten Schönfeld <kaffeetisch@gmx.de>
460
462 Copyright (C) 2011-2015 by Torsten Schoenfeld <kaffeetisch@gmx.de>
463 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.
468perl v5.28.1 2019-02-15 Gtk3(3)