Curses::UI::Tutorial

a b c d e f g h i j k l m n o p q r s t u v w x y z _
Curses::UI::Tutorial(User Contributed Perl DocumentatiCurses::UI::Tutorial(3)



NAME
       Curses::UI::Tutorial - Tutorial for the Curses::UI framework

Introduction
       The intention of this tutorial is a quick overview of Curses::UI and
       it’s widgets. The target of this example is to write a simple text
       editor using the Curses::UI framework.

First requirements
       In order to use Curses::UI start your program with "use Curses::UI;"
       and, as it is always a good idea,
	add "use strict" and the -w switch too.	 After that an instance of
       Curses::UI must be created. From now on, this instance will be called
       "the UI". You  also want to redirect STDERR to a file (e.g. perl
       myscript.pl 2> debug.out), so output that does not come from
       Curses::UI doesn’t clobber your display.	 You want fancy colors, so
       the option -color_support is set to a true value.

	   #!/usr/bin/perl -w

	   use strict;
	   use Curses::UI;
	   my $cui = new Curses::UI( -color_support => 1 );

Create a menu
	       my @menu = (
		 { -label => ’File’,
		   -submenu => [
		  { -label => ’Exit	 ^Q’, -value => \&exit_dialog  }
			       ]
		  },
	       );

       In order to describe the structure of a menu Curses::UI uses a rather
       ugly construct out of hash and arrayrefs. See Curses::UI::Menubar for
       details. What you do at this point is to create a Menubar with just
       one entry and one submenu. The entry is ’File’ and the submenu is
       ’Exit’.	The value of this menu item is a reference to a sub called
       exit_dialog.

Dialogs
	       sub exit_dialog()
	       {
		       my $return = $cui->dialog(
			       -message	  => "Do you really want to quit?",
			       -title	  => "Are you sure???",
			       -buttons	  => [’yes’, ’no’],

		       );

	       exit(0) if $return;
	       }

       The dialog method of Curses::UI gives us an easy and convenient way to
       create dialogs on the main screen. A dialog is a way to interact with
       the user in order to ask him a question or give him important informa-
       tion.  This dialog is a more complex one, which asks the question
       whether or not you really want to exit. As the button for "yes" would
       return us a true value, you can easily exit on this return value.

Add the Menubar
	       my $menu = $cui->add(
		       ’menu’,’Menubar’,
		       -menu => \@menu,
		       -fg  => "blue",
	       );

       To finally add the Menubar to our root object, you have to call the
       add method on the Curses UI object. You specify the internal name of
       the widget as the first argument, the widget type as the second argu-
       ment (like Label, TextViewer, etc.) and the menu structure you created
       at the beginning as an array reference as third object. Because you
       want the Menubar to have a blue theme, you give him the -fg option
       "blue". There are a couple of colors you can use, see
       Curses::UI::Color for details.

Add a window
	       my $win1 = $cui->add(
				    ’win1’, ’Window’,
				    -border => 1,
				    -y	  => 1,
				    -bfg  => ’red’,
			    );

       There are only two types of object you can add to the Curses::UI root
       object: Menubars and Windows. All other widgets have to be inserted
       into a window. Of course you can add a Menubar to a window, but not
       vice versa ;-).	The add method always has the same two first argu-
       ments: the internal name and the widget type. The internal name can be
       used to find an object. The method getobj takes this name and returns
       us the corresponding object out of the hierarchy. See Curses::UI for
       details.	 Again you want some fancy colors, so you tell the window to
       have a border, leave some space for the Menubar (-y => 1) and set the
       border foreground color to red.

Add a widget
	       my $texteditor = $win1->add("text", "TextEditor",
					-text => "Here is some text\n"
					       . "And some more");

       The next step is to add a useful widget to our new small Curses::UI
       app. Here you take a TextEditor widget which performs basic tasks as a
       text editor. You add some initial text to the widget to make it not
       seem that empty.

Making keybindings
	       $cui->set_binding(sub {$menu->focus()}, "\cX");
	       $cui->set_binding( \&exit_dialog , "\cQ");

       You want to be able to focus the Menubar if you finished editing in
       the TextEditor widget. Therefore you set a binding to the focus func-
       tion of the menu and the key sequence Control (specified by \c) com-
       bined with X. Now you can easily return to the menu after editing.
       Because it is easier to have a shortcut for closing the application
       you add a binding for the sequence Control-Q to our nice exit_dialog
       method.

The final steps
	       $texteditor->focus();
	       $cui->mainloop();

       You want to start editing directly. Therefore you set the initial
       focus on the TextEditor by calling it’s focus method directly.  The
       last thing you got to do is to tell Curses that it now contoles the
       program flow by starting it’s MainLoop.

You’re done!
       You have built a genuine Curses::UI application! Not that it is a very
       useful one, but who cares? Now try out if it works like you think it
       should. The complete source code of this application is located in the
       examples directory of the distribution (examples/tutorial.pl).

       Now you can enhance this application to become a full featured editor
       like Emacs :-)

Author
       2003-2004 (c) by Marcus Thiesen (marcus@cpan.org) All rights reserved
       This Tutorial is licensed under the same terms as perl itself.

       If you have some additions to this tutorial feel free to send me a
       mail.



perl v5.8.8			  2008-12-21	      Curses::UI::Tutorial(3)