=pod =head1 NAME Gapp::Manual - An introduction to Gapp programming =head1 POST-MODERN GUI APPLICATIONS Gapp is a framework for creating GUI applications in Perl 5. Gapp is based on Moose and Gtk2-Perl. Moose calls itself a I<post-modern> object system, and relative to Perl 5, it is. Gapp aims to bring that same I<post-modern> feel to developing Gtk+ applications in perl. Applications maintain a consistent look and feel without hand-configuring every widget. Gapp effectively separates GUI design from application logic and data structures, while keeping your widgets and data up-to-date. Gapp makes programming complex GUI applications fun and easy. =head2 PREREQUISITES Gapp uses both L<Moose> and L<Gtk2> extensively and assumes that the user understands these modules as well. Any of the Gapp documentation that you find lacking is probably covered by these modules. =head2 Moose The documentation for Moose can be found on the CPAN at L<http://search.cpan.org/search?query=Moose>. =head2 Gtk2 The documentation for Gtk2-Perl can be ound at <http://gtk2-perl.sourceforge.net/doc/pod/index.html>. The documentation for Gtk+ can be found at L<http://library.gnome.org/devel/gtk/stable/>. =head1 A BASIC APPLICATION use Gapp; $w = Gapp::Window->new( properties => { title => 'Gapp application', }, signal_connect => [ [ 'delete-event' => sub { Gapp->quit } ], ], content => [ Gapp::Label->new( text => 'Hello World!' ), ] ); $w->show_all; Gapp->main; =head1 WIDGET PARAMETERS =over 4 =item properties Any properties you set here will be applied to the Gtk+ widget upon construction. You may find valid parameters by referencing that Gtk+ documentation at L<http://library.gnome.org/devel/gtk/stable/>. In this example we could have said: Gapp::Window->new ( title => 'Gapp applicaiton' ... This is because the C<title> parameter delegates to the C<title> property of the Gtk widget. The documentation for the Gapp widget will provide more information on properties that have been setup for delegation. =item signal_connect You may connect to signals using the C<signal_connect> parameter using the format in the example. =item content You can add widgets to containers using the C<content> parameter. No formatting options are specified here, just the heirarchy of the widgets. Spacing and other rendering details are resolved by the layout. That will be discussed more later. =back =head1 WIDGET CONSTRUCTION As previously mentioned, Gapp is a layer over Gtk2. A L<Gapp::Widget> is used to manage the construction of a L<Gtk2::Widget>. The L<Gtk2::Widget> is created on the first call to C<Gapp::gtk_widget>. Make all configurations to your widget before this happens; any change you make to the L<Gapp::Widget> will not be reflected in the Gtk widget once it has been constructed. In our example program, the call to C<gtk_widget> was made implicitly by calling C<show_all> all on the window. This is because C<show_all> is set up to delegate to the Gtk widget's C<show_all> method. The documentation for the Gapp widget will provide more information on methods that have been setup for delegation. =head1 WIDGET LAYOUT 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 appearnce of your whole application. You can subclass layouts too! =head2 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 C<layout> parameter. Gapp::Window->new( layout => 'My::Custom::Layout', content => ... ); =head2 Creating a Layout You should see L<Gapp::Layout> for information on creating layouts. =head1 ACTIONS 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 do_Quit; # connect to signal $w = Gapp::Window->new; $w->signal_connect( 'delete-event' => Quit ); # display in menu Gapp::MenuItem->new( action => Quit ); You should see L<Gapp::Actions> for information on creatng and using actions. =head1 TRAITS Apply traits and roles to your widgets to change their behavior! Gapp::Entry->new( traits => [qw( MyCustomTrait )] ); =head1 FORMS 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. $form = Gapp::VBox->new( traits => [qw( Form )], content => [ Gapp::Entry->new( field => 'user_name' ) ], ); =head1 EXTENDING Gapp extensions provide added functionality. The GappX:: namespace is the official place to find Gapp extensions. These extensi.ons can be found on the CPAN. =head1 AUTHORS Jeffrey Ray Hallock E<lt>jeffrey.hallock at gmail dot comE<gt> =head1 COPYRIGHT Copyright (c) 2011 Jeffrey Ray Hallock. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut