##########################################################################
# TEPAM - Tcl's Enhanced Procedure and Argument Manager
##########################################################################
#
# 2_argument_dialogbox_introduction.demo: This file is part of the TEPAM demo
#
# Copyright (C) 2009, 2010 Andreas Drollinger
# 
# Id: 2_argument_dialogbox_introduction.demo
##########################################################################
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
##########################################################################

#### Initialization ####

DemoControl(Initialization) 1
DemoControl(IsExecutable) {0}

# TEPAM provides the flexible entry form generator argument_dialogbox. A first 
# example of this demo shows the simplicity of building composed entry forms with
# argument_dialogbox. A second example provides an overview of the entry types, 
# features and options that are available with argument_dialogbox.

   package require Tk
   package require tepam
   namespace import -force tepam::*; # Import tepam::procedure and tepam::argument_dialogbox

#### Argument dialogbox - Simple example ####

DemoControl(IsExecutable) {1}

# This first example illustrates the simplicity to create complex data entry 
# forms. It creates an input mask that allows specifying a file to copy, a 
# destination folder as well as a checkbox that allows specifying if an 
# eventual existing file can be overwritten. Comfortable browsers can be used 
# to select files and directories. And finally, the form offers also the 
# possibility to accept and decline the selection.

# The argument_dialogbox returns 0 when the entered data are validated and 1 
# when the data entry is canceled. After the validation of the entered data, the 
# argument_dialogbox defines all the specified variables with the entered data 
# inside the calling context.

# A pair of arguments has to be provided to argument_dialogbox for each variable 
# that has to be specified by this last one. The first argument defines the entry 
# widget type to use to select the variable's data and the second one is a lists 
# of attributes related to the variable and the entry widget.

   set Result [tepam::argument_dialogbox \
      -existingfile {-label "Source file" -variable SourceFile} \
      -existingdirectory {-label "Destination folder" -variable DestDir} \
      -checkbutton {-label "Overwrite existing file" -variable Overwrite}]

   if {$Result=="ok"} {
      puts "Copy $SourceFile to $DestDir"
      if {$Overwrite} {
         puts "Overwrite an eventual existing file"
      }
   } else {
      puts "Canceled"
   }

#### Argument dialogbox - Comprehensive example ####

DemoControl(IsExecutable) {1}

# Many entry widget types are available: Beside the simple generic entries, 
# there are different kinds of list and combo boxes available, browsers for 
# existing and new files and directories, check and radio boxes and buttons, as 
# well as color and font pickers. If necessary, additional entry widget types 
# can be defined.

# The attribute list contains pairs of attribute names and attribute data. The 
# primary attribute is -variable used to specify the variable in the calling 
# context into which the entered data has to be stored. Another often used 
# attribute is -label that allows adding a label to the data entry widget. Other 
# attributes are available that allows specifying default values, the expected 
# data types, valid data ranges, etc.

# The next example of a more complex argument dialog box provides a good overview 
# about the different available entry widget types and parameter attributes. The 
# example contains also some formatting instructions like -frame and -sep which 
# allows organizing the different entry widgets in frames and sections:

   set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"}
 
   set Result [tepam::argument_dialogbox \
      -title "System configuration" \
      -context test_1 \
      -frame {-label "Text entries"} \
         -entry {-label Entry1 -variable Entry1} \
         -entry {-label Entry2 -variable Entry2 -default "my default"} \
         -text {-label Text1 -variable Text1 -height 3 -wrap none -default "Start here: "} \
      -frame {-label "Listbox & combobox"} \
         -listbox {-label "Listbox, single selection" -variable Listbox1 \
                   -choices {1 2 3 4 5 6 7 8} -default 1 -height 3} \
         -listbox {-label "Listbox, multiple selection" -variable Listbox2 \
                   -choicevariable ChoiceList -default {"Choice 2" "Choice 3"} \
                   -multiple_selection 1 -height 3} \
         -disjointlistbox {-label "Disjoined listbox" -variable DisJntListbox \
                           -choicevariable ChoiceList \
                           -default {"Choice 3" "Choice 5"} -height 3} \
         -combobox {-label "Combobox" -variable Combobox \
                    -choices {1 2 3 4 5 6 7 8} -default 3} \
      -frame {-label "Checkbox, radiobox and checkbutton"} \
         -checkbox {-label Checkbox -variable Checkbox \
                    -choices {bold italic underline} -choicelabels {Bold Italic Underline} \
                    -default italic} \
         -radiobox {-label Radiobox -variable Radiobox \
                    -choices {bold italic underline} -choicelabels {Bold Italic Underline} \
                    -default underline} \
         -checkbutton {-label CheckButton -variable Checkbutton -default 1} \
      -frame {-label "Files & directories"} \
         -existingfile {-label "Input file" -variable InputFile} \
         -file {-label "Output file" -variable OutputFile} \
         -sep {} \
         -existingdirectory {-label "Input directory" -variable InputDirectory} \
         -directory {-label "Output irectory" -variable OutputDirectory} \
      -frame {-label "Colors and fonts"} \
         -color {-label "Background color" -variable Color -default red} \
         -sep {} \
         -font {-label "Font" -variable Font -default {Courier 12 italic}}]
 
   if {$Result=="ok"} {
      puts "Arguments: "
      foreach Var {
         Entry1 Entry2
         Listbox1 Listbox2 Listbox3 
         Combobox1 Checkbox Radiobox Checkbutton
         InputFile OutputFile InputDirectory OutputDirectory
         Color Font
      } {
         puts "  $Var: '[set $Var]'"
      }
   } else {
      puts "Canceled"
   }

##########################################################################
# Id: 2_argument_dialogbox_introduction.demo
# Modifications:
#
# Revision 1.3  2012/05/07 20:27:26  droll
# * TEPAM version 0.4.0
# * Add the new text procedure argument type and the text multi line data
#   entry widget.
#
# Revision 1.2  2012/03/26 20:58:15  droll
#
# Revision 1.1  2010/02/11 21:54:38  droll
# * TEPAM module checkin
##########################################################################