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 110public: 111 112 FileDialog(); 113 virtual ~FileDialog(); 114 DECLARE_CONOBJECT(FileDialog); 115 116 static void initPersistFields(); 117 118 virtual bool Execute(); 119 120 FileDialogData &getData() { return mData; }; 121protected: 122 /// @name FileDialog Properties 123 /// @{ 124 /// @@property DefaultPath (String) : <i>Path to use as the default when the dialog is shown.</i> 125 /// @code %fd.DefaultPath = "/source/myGameProject/data/images"; @endcode 126 /// 127 /// @li @b ChangePath (bool) : <c>Will change the working path of the tools to the selected path when not canceled</c> 128 /// @code %fd.ChangePath = true; // Change Working Path on Success @endcode 129 /// @internal 130 static bool setDefaultPath( void *object, const char *index, const char *data ); 131 static bool setDefaultFile( void *object, const char *index, const char *data ); 132 static bool setFilters( void *object, const char *index, const char *data ); 133 static bool setChangePath( void *object, const char *index, const char *data ); 134 static const char* getChangePath(void* obj, const char* data); 135 /// 136 /// @} 137 138 static bool setFile( void *object, const char *index, const char *data ); 139}; 140/// @} 141 142class OpenFileDialog : public FileDialog 143{ 144 typedef FileDialog Parent; 145 146 /// Field Values 147 /// @{ 148 /// @internal 149 bool mMustExist; ///< Corresponds to FDS_MUSTEXIST flag on the PlatformFileDlgData structure 150 bool mMultipleFiles; ///< Corresponds to the FDS_MULTIPLEFILES flag on the PlatformFileDlgData structure 151 /// @} 152 153public: 154 155 OpenFileDialog(); 156 virtual ~OpenFileDialog(); 157 158 DECLARE_CONOBJECT(OpenFileDialog); /// @internal 159 160 static void initPersistFields(); 161 162protected: 163 /// 164 /// @} 165 166 /// Must Exist Property 167 static bool setMustExist( void *object, const char *index, const char *data ); 168 static const char*getMustExist(void* obj, const char* data); 169 170 /// Multiple Files Property 171 static bool setMultipleFiles( void *object, const char *index, const char *data ); 172 static const char* getMultipleFiles(void* obj, const char* data); 173}; 174 175class OpenFolderDialog : public OpenFileDialog 176{ 177 typedef OpenFileDialog Parent; 178 179public: 180 StringTableEntry mMustExistInDir; 181 182 OpenFolderDialog(); 183 DECLARE_CONOBJECT(OpenFolderDialog); 184 185 static void initPersistFields(); 186}; 187 188class SaveFileDialog : public FileDialog 189{ 190 typedef FileDialog Parent; 191 192public: 193 194 SaveFileDialog(); 195 virtual ~SaveFileDialog(); 196 DECLARE_CONOBJECT(SaveFileDialog); 197 198 bool mOverwritePrompt; 199 200 static void initPersistFields(); 201 202protected: 203 // Overwrite Prompt Property 204 static bool setOverwritePrompt( void *object, const char *index, const char *data ); 205 static const char* getOverwritePrompt(void* obj, const char* data); 206 207}; 208 209#endif // _FILEDIALOG_H_ 210