Gapp::Manual - An introduction to GUI development with Gapp


Gapp is a framework for creating GUI applications in perl. Gapp is based on Moose and Gtk2-Perl. Gapp brings the post-modern feel of Moose to Gtk+ application development in perl.


Gapp is a Moose-enabled layer over Gtk2-Perl.

Each Gapp::Widget constructs an underlying Gtk2::Widget which is accessible through the gobject attribute. You can apply roles and traits to the widgets just like any other Moose based class.

Layouts are extensible classes that are used to define the positioning, spacing, and appearance of widgets in an application. By defining these properties in a sinlge location it is easy to maintain a consistent look and feel across an entire application. There is no need to hand configure every widget. Making a change to the layout propogates across the entire application.

Actions are reusable blocks of code that know how to display themselves on various widgets. Actions loosely separate business logic and interface design.

Forms keep your widgets and your data synchronised transparently. There is no need to manually move data between the object and the widgets or vice-versa when displaying or saving a form.


Gapp uses both Moose and Gtk2 extensively and assumes that the user has basic understanding of these modules as well. Any of the Gapp documentation that you find lacking is probably covered by these modules.


The documentation for Moose can be found on the CPAN at


The documentation for Gtk2-Perl can be found at

The documentation for Gtk+ can be found at


  use Gapp;

  $w = Gapp::Window->new(

    properties => {

      title => 'Gapp application',

    signal_connect => [

      [ 'delete-event' => sub { Gapp->quit } ],

    content => [

      Gapp::Label->new( text => 'Hello World!' ),





Worth noting is the abscence of the use Gtk2 '-init' line. Gapp calls this for you already.

One of the first things you will notice is that we can define widget properties, connect to signals, and pack widgets all within the constructor of the widget. This lends to code that is cleaner and easier to read and modify.


A Gapp::Widget is used to manage the construction of a Gtk2::Widget.

The Gtk2::Widget is created on the first call to Gapp::Widget::gobject. Make all configurations to your widget before this happens; any change you make to the Gapp::Widget will not be reflected in the GtkWidget once it has been constructed.



Any properties you set here will be applied to the Gtk+ widget upon construction. You may find valid properties by referencing the corresponding Gtk+ documentation at


You may connect to signals using the signal_connect parameter using the format in the example.


You can add widgets to containers using the content parameter. No formatting options are specified here, just the hierarchy of the widgets. Spacing and other rendering details are resolved by the layout. The layout will be discussed in more detail later in this manual.



In our example program, the call to gobject was made implicitly by calling show_all all on the window. This is because show_all is set up to delegate to the Gtk widget's show_all method. The documentation for the Gapp widget will provide more information on methods that have been setup for delegation.


The layout determines how widgets are displayed on the screen. It has control over things like spacing, alignment, borders, etc. By centralizing the code the determines the appearance of widgets, it is is possible to achieve a consistent look GUI. By making changes to the layout, you can affect the appearance of your whole application. You can subclass layouts too!

Using a Layout

Layouts are referenced using their class names. You can specify which layout to use when constructing your widget. All widgets accept the layout parameter.

  Gapp::Window->new( layout => 'My::Custom::Layout', content => ... );

Creating a Layout

You should see Gapp::Layout for information on creating layouts.


Actions can be performed and know how to display themselves in menu's and on on buttons. You can call them directly or connect them to signals.

  use Gapp::Actions::Basic qw( Quit );

  # call directly

  # connect to signal
  $w = Gapp::Window->new;
  $w->signal_connect( 'delete-event' => Quit );

  # display as menu item
  Gapp::MenuItem->new( action => Quit );

  # display as button
  Gapp::Button->new( action => Quit );

You should see Gapp::Actions for information on creating and using actions.


Apply traits and roles to your widgets to change their behavior!

  Gapp::Entry->new( traits => [qw( MyCustomTrait )] );


Advanced form handling allows you to easily get form data from widgets and vice versa. You don't manually need to update each field in the form. To create a form, add the Form trait to any widget.

  $form = Gapp::VBox->new(
    traits => [qw( Form )],
    content => [ Gapp::Entry->new( field => '' ) ],

The Stash

Now you can pull values from the form using the stash.


You can also set values in the form using the stash.

  $form->stash->store('', 'anonymous' );

You have to call update on the form before changes to the stash will be displayed.



Using a context you can sync data between objects and you form.

  $user = Foo::User;

  $cx = Gapp::Form::Context->new;

  $cx->add( 'user' => $user,

    writer_prefix => 'set_',

    reader_prefix => '',


  $form->set_context( $cx );

  # update the form from the context

  # update the stash and context


Gapp::Moose provides sugar for creating classes that have widgets as attributes.

  package Foo::Bar;

  use Gapp::Moose;

  widget 'window' => (

    is => 'ro',

    traits => [qw( GappWindow GappDefault )],

    construct => sub {

        title => 'Gapp Application',

        signal_connect => [

            [ 'delete-event' => sub { Gapp->main_quit } ]





Gapp extensions provide added functionality. The GappX:: namespace is the official place to find Gapp extensions. These extensions can be found on the CPAN.


Jeffrey Ray Hallock <jeffrey.hallock at gmail dot com>


    Copyright (c) 2011-2012 Jeffrey Ray Hallock.
    This program is free software; you can redistribute it and/or
    modify it under the same terms as Perl itself.