NAME

Gtk2Fu - GTK2 Forked Ultimate, a powerful layer on top of Gtk2. (forked from ugtk2.)

INTRODUCTION

gtk2-fu is a layer on top of perl gtk2, that brings power, simplicity and speed of development. It brings additional methods to ease the widget creation among other things. But the most important feature is that it brings you a lot of derivated methods from existing methods, that does exactly the same thing, except that ir returns the widget. Example :

  $window->set_title('foo');  #the normal method
  $window->set_title_('foo');  #the gtk2-fu derivated method

set_title_ does the same things as set_title, but it returns $window.

What's the advantage? you can chain actions ! Look at the 2 code examples below :

  # normal perl-gtk2
  my $window = Gtk2::Window->new();
  my $entry = Gtk2::Entry->new();
  $entry->set_text('foo');
  $entry->set_editable(0);
  $window->add($entry);

  # using gtk2-fu
  my $window = Gtk2::Window->new();
  $window->add(
    Gtk2::Entry->new()
      ->set_text_('foo')
      ->set_editable_(0)
  );

You could even get rid of the $window declaration. The gain can seem to you very minor, but in more complex cases, it allows you to create a complex GUI really easilly. You'll find a bigger example at the end of this documentation

In addition to this feature, gtk2-fu provides a toolbox of useful help methods to create widgets, ask things to the user, and misc other things.

HISTORY

gtk2-fu is a fork of ugtk2 (Ultimate gtk2) which is a port to gtk2 of ugtk (Ultimate gtk), which is an improvment of mygtk, which was the created by pixel at mandrakesoft, to basically address the same issues.

ugtk2 is great, but mandrakesoft specific, and not clean enough for me. The derivated methods that return the widget are written one by one by hand; ugtk2 goal is not to be exhaustive, but reduced to the need of mandrakesoft coders, so it is useless for external coders. In addition, the derivated methods are not object oriented, you need to call the explicitely. And a lot of helpers functions use specific things related to the MandrakeLinux installer, config tools, or Interactive.

OK now to the documentation :

DESCRIPTION

DERIVATED METHODS

Not all methods are wrapped so that they can be called with a trailing _ to return the widget. If you need one that is not yet done, mail me at <dams@gentoo.org>

implemented derivated methods

the derivated methods are implemented only for original methods that return nothing (void). Here is the list of derivated methodes, ordered by classes:

Gnome2::App add_dock_item add_toolbar set_contents create_menus create_toolbar enable_layout_config insert_menus install_menu_hints set_menus remove_menu_range remove_menus set_statusbar_custom set_statusbar set_toolbar

Gnome2::AppBar clear_prompt clear_stack set_default install_menu_hints pop set_progress_percentage set_prompt push refresh set_status

Gnome2::AppHelper install_menu_hints_

Gnome2::Bonobo::Dock add_floating_item_ add_item_ allow_floating_items_ set_client_area_

Gnome2::Bonobo::Dock set_shadow_type_

Gnome2::Canvas set_center_scroll_region_ set_dither_ set_pixels_per_unit_ request_redraw_ set_scroll_region_ scroll_to_ set_stipple_origin_ update_now_

Gnome2::Canvas::Bpath set_path_def_

Gnome2::Canvas::Item affine_absolute_ affine_relative_ grab_focus_ hide_ lower_ lower_to_bottom_ move_ raise_ raise_to_top_ reparent_ request_update_ reset_bounds_ show_ ungrab_ update_bbox_

Gnome2::Canvas::PathDef closepath_ closepath_current_ curveto_ ensure_space_ finish_ lineto_ lineto_moving_ moveto_ reset_

Gnome2::Canvas::RichText set_buffer_ copy_clipboard_ cut_clipboard_ paste_clipboard_

Gnome2::Canvas::Shape set_path_def_

Gnome2::Client add_static_arg_ set_clone_command_ connect_ set_current_directory_ set_discard_command_ disconnect_ set_environment_ flush_ set_global_config_prefix_ set_priority_ request_interaction_ request_phase_2_ request_save_ set_resign_command_ set_restart_command_ set_restart_style_ save_any_dialog_ save_error_dialog_ set_shutdown_command_

Gnome2::ColorPicker set_d_ set_dither_ set_i16_ set_i8_ set_title_ set_use_alpha_

Gnome2::DateEdit set_flags_ set_popup_range_ set_time_

Gnome2::Druid append_page_ set_buttons_sensitive_ insert_page_ set_page_ prepend_page_ set_show_finish_ set_show_help_

Gnome2::DruidPage finish_ prepare_

Gnome2::DruidPageEdge set_bg_color_ set_logo_bg_color_ set_logo_ set_text_color_ set_text_ set_textbox_color_ set_title_color_ set_title_ set_top_watermark_ set_watermark_

Gnome2::DruidPageStandard append_item_ set_background_ set_contents_background_ set_logo_background_ set_logo_ set_title_foreground_ set_title_ set_top_watermark_

Gnome2::DruidPageStandard append_history_ clear_history_ set_history_id_ set_max_saved_ prepend_history_

Gnome2::FileEntry set_default_path_ set_directory_entry_ set_filename_ set_modal_ set_title_

Gnome2::FontPicker fi_set_show_size_ fi_set_use_font_in_label_ set_mode_ set_preview_text_ set_title_ uw_set_widget_

Gnome2::GConf::Client add_dir_ clear_cache_ set_error_handling_ set_ get_list_ notify_remove_ get_pair_ preload_ remove_dir_ suggest_sync_

Gnome2::GConf::Engine notify_remove_ remove_dir_ suggest_sync_

Gnome2::HRef set_label_ set_text_ set_url_

Gnome2::IconEntry set_browse_dialog_title_ set_history_id_ set_max_saved_ set_pixmap_subdir_

Gnome2::IconList clear_ set_col_spacing_ focus_icon_ freeze_ set_hadjustment_ set_icon_border_ set_icon_width_ insert_ insert_pixbuf_ moveto_ remove_ set_row_spacing_ select_icon_ set_selection_mode_ set_separators_ set_text_spacing_ thaw_ unselect_icon_ set_vadjustment_

Gnome2::IconSelection add_defaults_ add_directory_ clear_ select_icon_ show_icons_ stop_loading_

Gnome2::IconTextItem configure_ focus_ select_ setxy_ start_editing_ stop_editing_

Gnome2::IconTheme set_allow_svg_ append_search_path_ set_custom_theme_ prepend_search_path_ set_search_path_

Gnome2::PasswordDialog set_password_ set_readonly_username_ set_username_

Gnome2::PixmapEntry set_pixmap_subdir_ set_preview_ set_preview_size_

Gnome2::PopupMenu add_popup_items_ append_from_ attach_to_ do_popup_

Gnome2::Print::Config dump_

Gnome2::Print::Dialog set_copies_

Gnome2::Print::FontPreview set_color_ set_font_ set_phrase_

Gnome2::Print::FontSelection set_font_

Gnome2::Print::GlyphList advance_ font_ glyph_ kerning_ letterspace_ moveto_ rmoveto_ text_dumb_

Gnome2::Print::UnitSelector add_adjustment_ set_bases_ remove_adjustment_ set_unit_

Gnome2::Rsvg::Handle set_dpi_ set_size_callback_

Gnome2::Scores set_color_ set_colors_ set_current_player_ set_def_color_ set_logo_label_ set_logo_label_title_ set_logo_pixmap_ set_logo_widget_

Gnome2::ThumbnailFactory create_failed_thumbnail_ save_thumbnail_

Gnome2::VFS::Application add_mime_type_ set_bool_value_ clear_mime_types_ remove_application_ remove_mime_type_ unset_key_ set_value_

Gnome2::VFS::Async::Handle cancel_ close_ read_ write_

Gnome2::VFS::Mime::Application save_

Gnome2::VFS::URI set_host_name_ set_host_port_ set_password_ set_user_name_

Gnome2::Vte::Terminal set_allow_bold_ set_audible_bellâ_ set_background_image_file_ set_background_image_ set_background_saturation_ set_background_tint_color_ set_background_transparent_ set_backspace_binding_ set_color_background_ set_color_bold_ set_color_dim_ set_color_foreground_ set_colors_ copy_clipboard_ copy_primary_ set_cursor_blinks_ set_default_colors_ set_delete_binding_ set_emulation_ set_encoding_ feed_ feed_child_ set_font_from_string_ set_font_ im_append_menuitems_ match_clear_all_ match_remove_ match_set_cursor_ match_set_cursor_type_ set_mouse_autohide_ paste_clipboard_ paste_primary_ reset_ set_scroll_background_ set_scroll_on_keystroke_ set_scroll_on_output_ set_scrollback_lines_ set_size_ set_visible_bell_ set_word_chars_

Gnome2::Window toplevel_set_title_

Gnome2::Wnck::Pager set_n_rows_ set_orientation_ set_screen_ set_shadow_type_ set_show_all_

Gnome2::Wnck::Screen change_workspace_count_ force_update_ move_viewport_ release_workspace_layout_ toggle_showing_desktop_

Gnome2::Wnck::Tasklist set_grouping_limit_ set_icon_loader_ set_include_all_workspaces_ set_minimum_height_ set_minimum_width_ set_screen_ set_switch_workspace_on_unminimize_

Gnome2::Wnck::Window activate_ activate_ activate_transient_ activate_transient_ close_ close_ set_icon_geometry_ keyboard_move_ keyboard_size_ maximize_ maximize_horizontally_ maximize_vertically_ minimize_ move_to_workspace_ pin_ shade_ set_skip_pager_ set_skip_tasklist_ stick_ unmaximize_ unmaximize_horizontally_ unmaximize_vertically_ unminimize_ unminimize_ unpin_ unshade_ unstick_

Gnome2::Wnck::Workspace activate_ activate_ change_name_

METHODS for creation

These methods return a widget, ready to use. to use them you need to do :

  use Gtk2Fu qw(:create);
or 

  use Gtk2Fu qw(:all);

create_window()

 $widget = create_window($title, $type='toplevel', $resizable=1, $modal=0, $border_width=0, $delete_event=sub{})

Creates a window with specified properties.

create_entry()

  $entry = create_entry($text)

Creates an entry with a default text if provided.

create_full_menubar()

  $menubar = $window->create_full_menubar($menu_items=
                                          [
                                            [ "/_File" ,undef,0 ,0 ,"<Branch>" ],
                                            [ "/File/_New" ,"<control>N" ,\&callback,0 ,"<StockItem>" ,"gtk-new" ,"create a new file" ],
                                          ],
                                          $start_path='<main>');
  ($menubar, $factory) = $window->create_full_menubar($menu_items=
                                          [
                                            [ "/_File" ,undef,0 ,0 ,"<Branch>" ],
                                            [ "/File/_New" ,"<control>N" ,\&callback,0 ,"<StockItem>" ,"gtk-new" ,"create a new file" ],
                                          ],
                                          $start_path='<main>');

Creates a full menubar with menuitems of any type, and shortcuts. In scalar context, returns the menubar ready to be added in a box for instance. In list context, returns the menubar widget, and the factory, for advanced use. $start_path is optional.

create_scrolled_window()

  $viewport = $widget->create_scrolled_window($policy=['automatic','automatic'], $viewport_shadow)

Creates a scrolled viewport from a given $widget. Returns the viewport

METHODS for interaction with user

These methods create some widgets, launch a main loop, then return a value.

The ask_from_dialog methods display a dialog box and returns a value corresponding to the button clicked. The dialogs can take $options. $options is a HASHREF with keys/values tha can be :

stock => STRING

an icon for the dialog box

cancel => BOOLEAN

if set to 1, a cancel button will be added

width => INTEGER

set a specific width to the dialog box

width => INTEGER

set a specific height to the dialog box

transient => BOOLEAN

set the transient state of the dialog box

use_markup => BOOLEAN

use markup or not

ask_from_info_dialog()

  $widget = ask_from_info_dialog($title, $label, $options={});

Information dialog

ask_from_warn_dialog()

 $widget = ask_from_warn_dialog($title, $label, {});

Warning dialog

ask_from_err_dialog()

 $widget = ask_from_err_dialog($title, $label, {});

Error dialog

ask_from_dialog()

  $widget = ask_from_dialog($title, $label, {});

Normal dialog

toolbox METHODS

Packing helpers methods. The methods aim to replace the pack_start and pack_end methods.

gtkpack()

  $widget = gtkpack($box, $widget1, $widget2, ...)

Packs $widgets in $box, with expand set to 1 and fill set to 1

gtkpack_()

  $widget = gtkpack_($box, 0 => $widget1, 1 => $widget2 ...)

Packs $widgets in $box, with fill set to 1. For each widget, the boolean set the expand property in the packing.

gtkpack__()

  $widget = gtkpack__($box, $widget1, $widget2, ...)

Packs $widgets in $box, with expand set to 0 and fill set to 1

gtkpack2()

  $widget = gtkpack2($box, $widget1, $widget2, ...)

Packs $widgets in $box, with expand set to 1 and fill set to 0

gtkpack2_()

  $widget = gtkpack2_($box, 0 => $widget1, 1 => $widget2 ...)

Packs $widgets in $box, with fill set to 0. For each widget, the boolean set the expand property in the packing.

gtkpack2__()

  $widget = gtkpack2__($box, $widget1, $widget2, ...)

Packs $widgets in $box, with expand set to 0 and fill set to 0

miscellaneous METHODS

miscellaneous helpers methods.

gtkflush()

flushes the pending iterations

EXAMPLE

  my $w = create_window()
    ->signal_connect_(destroy => sub { Gtk2->main_quit })
    ->set_size_request_(600, 450)
    ->set_border_width_(5)
    ->add_(Gtk2::VBox->new(0,5)
           ->gtkpack_(0, new Gtk2::HBox(0, 0)
                      ->gtkpack_(1, my $darea = Gtk2::DrawingArea->new()
                                    ->signal_connect_(expose_event => \&draw_banner),
                                 0, new Gtk2::VBox(0, 0)
                                    ->gtkpack_(1, '', 0, $arrow_button)
                                ),
                      1, Gtk2::HPaned->new()
                      ->pack1_(new Gtk2::VBox(0, 5)
                               ->gtkpack_(0, new Gtk2::HBox(0, 5)
                                             ->gtkpack_(0, my $search_entry = Gtk2::Entry->new(),
                                                        0, my $search_ok = Gtk2::Button->new('search'),
                                                        0, my $search_label = Gtk2::Label->new(),
                                                       ),
                                          1, $slist->create_scrolled_window()
                                         ), 1, 0
                              )
                      ->pack2_($hpan2 = new Gtk2::VBox(0, 5)
                               ->gtkpack_(0, Gtk2::HBox->new(0, 5)
                                             ->gtkpack_(0, 'flag name :',
                                                        1, my $flag_name = Gtk2::Entry->new()
                                                       ),
                                          0, Gtk2::HBox->new(0, 5)
                                             ->gtkpack__(my $flag_M = Gtk2::CheckButton->new('')
                                                           ->set_sensitive_(0),
                                                         'set in make.defaults'),
                                          0, Gtk2::HBox->new(0, 5)
                                             ->gtkpack__(my $flag_U = Gtk2::CheckButton->new('')
                                                           ->set_sensitive_(0),
                                                         'set in use.defaults'),
                                          0, Gtk2::HBox->new(0, 5)
                                             ->gtkpack__(my $flag_C = Gtk2::CheckButton->new('')
                                                           ->set_sensitive_(0),
                                                         'set in make.conf'),
                                          0, Gtk2::Label->new('description :')
                                             ->set_alignment_(0, 0.5),
                                          1, Gtk2::Frame->new()
                                             ->set_shadow_type_('in')
                                             ->add_($flag_description)
                                         ),
                               1, 0)->set_position_(400),
                      0, Gtk2::HButtonBox->new()
                         ->set_layout_('end')
                         ->gtkpack(Gtk2::Button->new('Cancel')
                                     ->signal_connect_(clicked => sub { Gtk2->main_quit }),
                                   Gtk2::Button->new('OK')
                                     ->signal_connect_(clicked => sub { main_ok() })
                                  )
                     )
          )
    ->show_all_();
  $darea->size(-1, 38);

COPYRIGHT

Copyright (c) 2004-2005 Damien Krotkine. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Gtk2Fu

perl -MCPAN -e shell
install Gtk2Fu