fileDialog.h

Engine/source/platform/nativeDialogs/fileDialog.h

More...

Classes:

class

FileDialog is a platform agnostic dialog interface for querying the user for file locations.

Detailed Description

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23#ifndef _FILEDIALOG_H_
 24#define _FILEDIALOG_H_
 25#include "console/simBase.h"
 26
 27// [03/14/07] The file dialogs need refactoring, and will be refactored in Jugg.
 28// Things that might need to change:
 29// - The interface is not in fact platform agnotsic, it is win32 oriented.
 30// - Filter format is highly windows specific, and is a little fragile, both for
 31//   win32 and for other platforms.
 32// - Platform specific path strings are exposed to the console, because the 
 33//   protected validators save them as such.
 34// - Several of the FDS_XXX values are not options we want to give the user, such
 35//   as NOT warning on file overwrite. The values FDS_OVERWRITEPROMPT,
 36//   FDS_MUSTEXIST, and FDS_CHANGEPATH are not good things to give the user.
 37// - The Execute method is virtual for good reason. It should be implemented for
 38//   each subclass. If common behavior is needed for Execute(), it can be 
 39//   factored out in hidden platform specific code.
 40
 41
 42/// @defgroup SystemDialogs Using System Dialogs
 43
 44/// @ingroup SystemDialogs
 45/// FileDialogOpaqueData is both defined and implemented on a platform specific
 46///   basis. 
 47class FileDialogOpaqueData;
 48
 49/// @ingroup SystemDialogs 
 50/// @internal
 51/// Platform Agnostic Structure for holding information about a file dialog.
 52struct FileDialogData
 53{
 54
 55public:
 56   FileDialogData();
 57   ~FileDialogData();
 58
 59   enum DialogStyle
 60   {
 61      FDS_OPEN             = BIT(0),///< This is an open dialog.
 62      FDS_SAVE             = BIT(1),///< This is a save dialog.
 63      FDS_OVERWRITEPROMPT  = BIT(2),///< Can only be used in conjunction with style SaveDialog: prompt for a confirmation if a file will be overwritten.
 64      FDS_MUSTEXIST        = BIT(3),///< The user may only select files that actually exist.
 65      FDS_MULTIPLEFILES    = BIT(4),///< Can only be used in conjunction with style OpenDialog: allows selecting multiple files.
 66      FDS_CHANGEPATH       = BIT(5),///< Change the current working path to the directory where the file(s) chosen by the user are.
 67      FDS_BROWSEFOLDER     = BIT(6) ///< Select folders instead of files
 68   };
 69   U8 mStyle;      ///< Specifies the Style of the File Dialog @see DialogStyle
 70
 71   StringTableEntry mFilters;             ///< List of Filters pipe separated e.g. "BMP Files (*.bmp)|*.bmp|JPG Files (*.jpg)|*.jpg"
 72   //StringTableEntry mFiles;             // this is never used   ///< Should only be referenced when using dialogStyle OpenDialog AND MultipleFiles: List of Files returned pipe separated
 73   StringTableEntry mFile;                ///< Should be referenced when dialogStyle MultipleFiles is NOT used: the file path of the user selected file.
 74   StringTableEntry mDefaultPath;         ///< Default path of dialog
 75   StringTableEntry mDefaultFile;         ///< Default selected file of dialog
 76   StringTableEntry mTitle;               ///< Title to display in file dialog
 77
 78   FileDialogOpaqueData *mOpaqueData;     ///< Stores platform specific info about the dialog
 79   
 80};
 81
 82/// @ingroup SystemDialogs
 83/// FileDialog is a platform agnostic dialog interface for querying the user for
 84///              file locations. It is designed to be used through the exposed
 85///              scripting interface.
 86///
 87/// FileDialog is the base class for Native File Dialog controls in Torque. It provides these
 88/// basic areas of functionality:
 89///
 90///      - Inherits from SimObject and is exposed to the scripting interface
 91///      - Provides blocking interface to allow instant return to script execution
 92///      - Simple object configuration makes practical use easy and effective
 93///
 94/// @attention
 95/// FileDialog is *NOT* intended to be used directly in script and is only exposed to script
 96/// to expose generic file dialog attributes. 
 97/// @see OpenFileDialog for a practical example on opening a file
 98/// @see SaveFileDialog for a practical example of saving a file
 99///
100///
101/// @{
102class FileDialog : public SimObject
103{
104   typedef SimObject Parent;
105
106protected:
107   FileDialogData mData; ///< Stores platform agnostic information about the dialogs properties
108   bool mChangePath; ///< Exposed ChangePath Property
109   bool mBoolTranslator; ///< Internally used to translate boolean values into their respective bits of dialog style
110   bool mForceRelativePath;
111public:
112
113   FileDialog();
114   virtual ~FileDialog();
115   DECLARE_CONOBJECT(FileDialog);
116
117   static void initPersistFields();
118
119   virtual bool Execute();
120
121   FileDialogData &getData() { return mData; };
122protected:
123   /// @name FileDialog Properties
124   /// @{
125   /// @@property DefaultPath (String) : <i>Path to use as the default when the dialog is shown.</i>
126   /// @code %fd.DefaultPath = "/source/myGameProject/data/images"; @endcode
127   ///
128   /// @li @b ChangePath (bool) : <c>Will change the working path of the tools to the selected path when not canceled</c>
129   /// @code %fd.ChangePath = true; // Change Working Path on Success @endcode
130   /// @internal
131   static bool setDefaultPath( void *object, const char *index, const char *data );
132   static bool setDefaultFile( void *object, const char *index, const char *data );
133   static bool setFilters( void *object, const char *index, const char *data );
134   static bool setChangePath( void *object, const char *index, const char *data );
135   static const char* getChangePath(void* obj, const char* data);
136   ///
137   /// @}
138
139   static bool setFile( void *object, const char *index, const char *data );
140};
141/// @}
142
143class OpenFileDialog : public FileDialog
144{
145   typedef FileDialog Parent;
146
147   /// Field Values
148   /// @{
149   /// @internal
150   bool mMustExist; ///< Corresponds to FDS_MUSTEXIST flag on the PlatformFileDlgData structure
151   bool mMultipleFiles; ///< Corresponds to the FDS_MULTIPLEFILES flag on the PlatformFileDlgData structure
152   /// @}
153
154public:
155   
156   OpenFileDialog();
157   virtual ~OpenFileDialog();
158
159   DECLARE_CONOBJECT(OpenFileDialog); /// @internal
160
161   static void initPersistFields();
162
163protected:
164   ///
165   /// @}
166
167   /// Must Exist Property
168   static bool setMustExist( void *object, const char *index, const char *data );
169   static const char*getMustExist(void* obj, const char* data);
170
171   /// Multiple Files Property
172   static bool setMultipleFiles( void *object, const char *index, const char *data );
173   static const char* getMultipleFiles(void* obj, const char* data);
174};
175
176class OpenFolderDialog : public OpenFileDialog
177{
178   typedef OpenFileDialog Parent;
179
180public:
181   StringTableEntry mMustExistInDir;
182
183   OpenFolderDialog();
184   DECLARE_CONOBJECT(OpenFolderDialog);
185
186   static void initPersistFields();
187};
188
189class SaveFileDialog : public FileDialog
190{
191   typedef FileDialog Parent;
192
193public:
194
195   SaveFileDialog();
196   virtual ~SaveFileDialog();
197   DECLARE_CONOBJECT(SaveFileDialog);
198   
199   bool mOverwritePrompt;
200
201   static void initPersistFields();
202
203protected:
204   // Overwrite Prompt Property
205   static bool setOverwritePrompt( void *object, const char *index, const char *data );
206   static const char* getOverwritePrompt(void* obj, const char* data);
207
208};
209
210#endif // _FILEDIALOG_H_
211