fileDialog.h
Engine/source/platform/nativeDialogs/fileDialog.h
Classes:
class
FileDialog is a platform agnostic dialog interface for querying the user for file locations.
class
class
class
class
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