example/ValidatorExample/main.cpp

Go to the documentation of this file.
00001 // @HEADER
00002 // ***********************************************************************
00003 // 
00004 //         Optika: A Tool For Developing Parameter Obtaining GUIs
00005 //                Copyright (2009) Sandia Corporation
00006 // 
00007 // Under terms of Contract DE-AC04-94AL85000, with Sandia Corporation, the 
00008 // U.S. Government retains certain rights in this software.
00009 // 
00010 // This library is free software; you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as
00012 // published by the Free Software Foundation; either version 2.1 of the
00013 // License, or (at your option) any later version.
00014 //  
00015 // This library is distributed in the hope that it will be useful, but
00016 // WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00018 // Lesser General Public License for more details.
00019 //  
00020 // You should have received a copy of the GNU Lesser General Public
00021 // License along with this library; if not, write to the Free Software
00022 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
00023 // USA
00024 // Questions? Contact Kurtis Nusbaum (klnusbaum@gmail.com) 
00025 // 
00026 // ***********************************************************************
00027 // @HEADER
00028 #include "Teuchos_XMLParameterListHelpers.hpp"
00029 #include "Teuchos_VerboseObject.hpp"
00030 #include "Optika_GUI.hpp"
00031 #include "Optika_SpecificParameterEntryValidators.hpp"
00032 #include "Teuchos_StandardParameterEntryValidators.hpp"
00033 #include "Optika_StandardDependencies.hpp"
00034 int main(){
00035  /*
00036   * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! 
00037   * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!              ATTENTION              !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
00038   * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
00039   * !!!!   PLEASE VIEW THE BASIC EXAMPLE FIRST BEFORE READING THIS EXAMPLE. IT PROVIDES FUNDAMENTAL    !!!! 
00040   * !!!!   KNOWLEDGE THAT WILL BE VERY HELPFUL IN UNDERSTANDING THIS EXAMPLE.                          !!!!
00041   * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
00042   * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
00043   */ 
00044   
00045 
00046  /*
00047   * Every supported data type (with the exception of bool and Teuchos::Array<bool>) has 
00048   * at least one validator. Lets take a look at them.
00049   */
00050  
00051  /*
00052   * The validator for number types has been templated. The validator has two constuctors.
00053   * The first takes three arguments:
00054   * 1. Minimum allowed value (inclusive).
00055   * 2. Maximum allowed value (inclusive).
00056   * 3. The step. This is the how much the value of the parameter should be changed
00057   * when it is told to increase or decrease in the GUI. Play around with this value a bit
00058   * to get a good idea of what it does. It really only has meaning when used with the GUI.
00059   *
00060   * The second constructor takes no arguments. It mearly enforces that a particular
00061   * parameter is of a certain number type. If you use this second constructor, no
00062   * minimum or maximum will be set. If you would like your validator to have a minimum 
00063   * and no maximum you may call the setMin function after using this constructor.
00064   * The same can be done with the setMax if you wish to have a maximum and no minimum.
00065   */
00066 
00067  /*
00068   * First we create an empty parameter list. We will use this to define
00069   * all of the parameters we wish to obtain from the user.
00070   */
00071   Teuchos::RCP<Teuchos::ParameterList> My_List = Teuchos::RCP<Teuchos::ParameterList>(new Teuchos::ParameterList);
00072   
00073 
00074  /*
00075   * Here we create a validator for an int parameter. It's minimum value is 0, and it's maximum value is 10.
00076   * The step is 1 (the default value for the argument).
00077   */
00078   Teuchos::RCP<Optika::EnhancedNumberValidator<int> > intVali = 
00079     Teuchos::rcp(new Optika::EnhancedNumberValidator<int>(0,10));
00080 
00081   /*
00082    * We then create an int parameter and use intVali as the
00083    * validator argument.
00084    */
00085   My_List->set("Int", 8, "Int tester", intVali);
00086 
00087   /*
00088    * Here we create an int validator with a minimum of 0, a maximum of 100
00089    * and a step value of 10. Try running the example program and press the up
00090    * and down buttons that appear in the edit box of this parameter. That's
00091    * the best way to explain what the step parameter specifies.
00092    */
00093   Teuchos::RCP<Optika::EnhancedNumberValidator<int> > intStepVali =
00094      Teuchos::rcp(new Optika::EnhancedNumberValidator<int>(0,100,10));
00095   My_List->set("Step int", 10, "Step int tester", intStepVali);
00096 
00097   /*
00098    * Now suppose we wanted to make a validator for a short parameter that only
00099    * had a minimum, and no maximum. First we creat it.
00100    */
00101   Teuchos::RCP<Optika::EnhancedNumberValidator<short> > shortVali = 
00102     Teuchos::rcp(new Optika::EnhancedNumberValidator<short>());
00103 
00104   /*
00105    * We then call the setMin function with a value of 0.
00106    */
00107   shortVali->setMin(0);
00108 
00109   /*
00110    * We then apply the validator to a short parameter.
00111    */
00112   My_List->set("Short", (short)4, "short tester", shortVali);
00113 
00114   /*
00115    * Floats and Doubles have an extra argument that can be tacked on to their constructor,
00116    * the precision argument. This controls how many decimals are displayed to the user in 
00117    * the GUI, NOT THE ACTUALL PRECISION USED TO STORE THE VALUE! Here we set the step of the
00118    * double validator to 1e-6 and the precision to 6 decimal places. Try running the program
00119    * to see it in action.
00120    */
00121   Teuchos::RCP<Optika::EnhancedNumberValidator<double> > doubleVali = 
00122     Teuchos::rcp(new Optika::EnhancedNumberValidator<double>(0,20,1e-6, 6));
00123   My_List->set("Double", (double)4.5, "double tester", doubleVali);
00124 
00125   /*
00126    * This validator is called a StringValidator. It takes a Teuchos tuple containg strings
00127    * and then makes sure what every parameter it is applied to is only ever set to one of those values.
00128    * Note: A Teuchos StringToIntegralParameterEntryValidator would also do the trick here, but they're
00129    * a little more complicated to use and kind of overkill for what we're doing here.
00130    */
00131   Teuchos::RCP<Optika::StringValidator> solverValidator = Teuchos::RCP<Optika::StringValidator>(
00132     new Optika::StringValidator(Teuchos::tuple<std::string>( "GMRES", "CG", "TFQMR" )));
00133   My_List->set("Solver", "GMRES", "The type of solver to use.", solverValidator);
00134   
00135   /*
00136    * The other validator that you may use is the FileNameValidator. This makes sure that the user supplies
00137    * a valid filename for this parameter.
00138    */
00139   Teuchos::RCP<Optika::FileNameValidator> filnameVali = 
00140     Teuchos::rcp(new Optika::FileNameValidator);
00141   My_List->set("filename", "", "filename tester", filnameVali);
00142 
00143   /*
00144    * Array validators may also be used as well. For arrays containing numbers, simply use the ArrayNumberValidator wrapper class.
00145    * The ArrayNumberValidator takes an ordinary EnhancedNumberValidator as an argument for its constructor, and then uses that
00146    * validator to validate each entry in the array.
00147    *
00148    * If you would like to emulate the functionality of the StringValidator for an array, use the
00149    * ArrayStringValidator wrapper class.
00150    *
00151    * If you would like to emulate the functionality of the FileNameValidator for an array, use the ArrayFileNameValidator
00152    * wrapper class.
00153    *
00154    * Examples of all these are shown below.
00155    */
00156   Teuchos::Array<int> intArray(10,0);
00157   Teuchos::Array<std::string> stringArray(10,"Option1");
00158   Teuchos::Array<std::string> filenameArray(3,"~/");
00159 
00160   My_List->set("IntArray", intArray, "intarray tester", 
00161   Teuchos::RCP<Optika::ArrayNumberValidator<int> >(new Optika::ArrayNumberValidator<int>(
00162     Teuchos::RCP<Optika::EnhancedNumberValidator<int> >(
00163       new Optika::EnhancedNumberValidator<int>(0,20,5)  
00164   ))));
00165 
00166 
00167   Teuchos::RCP<Optika::StringValidator> optionsValidator = Teuchos::RCP<Optika::StringValidator>(
00168     new Optika::StringValidator(Teuchos::tuple<std::string>("Option1", "Option2", "Option3", "Option4" )));
00169 
00170   My_List->set("StringArray", stringArray, "string tester", 
00171     Teuchos::RCP<Optika::ArrayStringValidator>(new Optika::ArrayStringValidator(optionsValidator))); 
00172 
00173   Teuchos::RCP<Optika::FileNameValidator> arrayFilnameVali = Teuchos::rcp(new Optika::FileNameValidator);
00174   
00175   My_List->set("Filename Array", filenameArray, "filename array tester",
00176     Teuchos::RCP<Optika::ArrayFileNameValidator>(new Optika::ArrayFileNameValidator(arrayFilnameVali)));
00177 
00178   /*
00179    * Here we print ouf the user entered values in XML format.
00180    */
00181   Optika::getInput(My_List);
00182   Teuchos::RCP<Teuchos::FancyOStream> out = Teuchos::VerboseObjectBase::getDefaultOStream();
00183   Teuchos::writeParameterListToXmlOStream(*My_List, *out);
00184 
00185   /*
00186    * Final Notes:
00187    *
00188    * Supported Validators:
00189    *  -EnhancedNumberValidator<S>
00190    *  -StringToIntegralValidator<S>
00191    *  -ArrayNumberValidator<S>
00192    *  -ArrayStringValidator
00193    *  -ArrayFileNameValidator
00194    *
00195    * If a validator is used that the GUI doesn't recognized, the GUI simply won't
00196    * use it. So if you're using validators not supported by the Optika package
00197    * make sure to check that your data is valid after running the getInput
00198    * function.
00199    *
00200    * Note: There's a validator factory class so that you can make validators
00201    * all quick and fast like. You should check it out if you use a lot of validators.
00202    * Chances are it could make your life rediculously easier.
00203    *
00204    * Remember: You default value for a parameter should be within the valid range
00205    * for the validator you are using on it. If this is not the case, an error will
00206    * be thrown before the GUI can even start up.
00207    *
00208    * Remember: Make sure you're using the right type of validator with the right
00209    * type of parameter, especially when it comes to arrays. If you don't use the
00210    * correct validator on the parameter, an error will be thrown before the GUI
00211    * can even startup.
00212    *
00213    * Careful! Reusing validators on multiple parameters is perfectly legal, but
00214    * be careful. Things like the NumberValidatorDependency can cause validators
00215    * min's and max's to change during the running of the GUI. Because we're
00216    * using pointers this means any parameter using the same validator will have
00217    * it's min's and max's changed too!
00218    */
00219   return 0;
00220 }
00221 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends
Generated on Wed Apr 13 10:05:58 2011 for Optika GUI Toolik by  doxygen 1.6.3