=head1 NAME Win32::GUI::Tutorial::Part3 - Dialog Boxes and Main Windows =head1 Win32::GUI Tutorial - Part 3 =head2 What is a Dialog Box? So far, in this tutorial, we have been creating our main window using the Win32::GUI::Window->new() constructor. While this works fine, Win32::GUI actually offers I<two> classes of main window. The first of these is the Win32::GUI::Window we have been using all along, and the second is Win32::GUI::DialogBox. "Why two classes?", you may ask. Basically, the reason is that a DialogBox adds extra functionality to the window which is not available with a simple Window. But the extra functionality has a cost, which means that we still make WIndow available for people who don't want the extra functionality of a DialogBox, or who don't want to pay the extra cost. (Actually, there's a further reason, which is that a Win32::GUI::DialogBox loses some of the flexibility which a Win32::GUI::Window has - this is a limitation of Win32::GUI, not of Windows itself, and may go away in a future version - there may even be workarounds available already.) See below for a more complete picture. =head2 Keyboard handling The main advantage that a DialogBox has over a basic Window, is that Win32::GUI automatically performs certain types of keyboard handling for you if you use a DialogBox. (The handling in question is the standard Windows actions - Tab moves between controls, Shift-Tab moves backwards, Escape cancels the dialog, and Return does the "default" action). To make the keyboard handling work properly, you need to add a number of options to your controls. =over 4 =item Tab and Shift-Tab To make the tab keys work as expected, you need to add the C<< -tabstop => 1 >> option to your controls. The tab keys move the focus between the controls with the C<-tabstop> option set. Other controls will be ignored when tabbing. =item Escape To make the escape key work as expected, you need to define a button with the C<< -cancel => 1 >> option. When the user presses the escape key, Windows will translate that action into a C<Click> event on the cancel button. It is normal to give this button a caption of C<"Cancel"> and to make its click event handler close the window without applying any changes - but this is up to you to implement. Windows just fires the relevant event. =item Return To make the return key work as expected, you need to give one of your dialog's buttons the C<< -ok => 1 >> option. When the return key is pressed, it is translated into a click event on the default button. The default button is also usually highlighted differently from the other buttons (it has a dark border), this is achieved by the C<< -default => 1 >> option, It is normal to give this button a caption C<"OK"> and make its click handler close the window, setting any changes made, but again, this is up to you. =back There are other default keyboard actions which occur, but you either don't need to, or can't, write code to handle them. =head2 Other Differences As well as the keyboard handling, the main difference between a DialogBox and a basic Window is that a DialogBox has a much more limited set of options available for controlling its appearance. Specifically =over 4 =item * A DialogBox has no Minimize or Maximize icons. =item * A DialogBox has a "?" (help) icon. =item * A DialogBox has a slightly different look. =item * A DialogBox cannot be resized. =back In most cases, the key issues will be whether you need the keyboard handling, and whether you need the user to be able to resize your windows. Otherwise, the choice is arbitrary. To switch types, the only change you need to make is the name of the constructor you use to create your application's main window. Recent versions of Win32::GUI have a C<-dialogui> option that controls the special keyboard handling. Setting this option to C<1> on a basic Window adds the special key handling to the window; setting it to C<0> on a DialogBox removes the special key handling. In the L<next part|Win32::GUI::Tutorial::Part4>, we will cover some further ways in which you can increase your application's functionality. =for comment $Id: pod_postamble.tpl,v 1.2 2005/08/03 21:45:59 robertemay Exp $ =head1 VERSION Documentation for Win32::GUI v1.14 created 01 Jun 2017 This document is autogenerated by the build process. Edits made here will be lost. Edit F<docs/GUI/Tutorial/Part3.pod> instead. =head1 SUPPORT Homepage: L<http://perl-win32-gui.sourceforge.net/>. For further support join the users mailing list from the website at L<http://lists.sourceforge.net/lists/listinfo/perl-win32-gui-users>. There is a searchable list archive at L<http://sourceforge.net/p/perl-win32-gui/mailman/perl-win32-gui-users/>. =head1 COPYRIGHT and LICENCE Copyright (c) 1997..2017 Aldo Calpini. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.