X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/954b8ae60391d18b87a604e7919c87c0c6ae208b..65baafba0e8cd74f2264b7e2f7625ff5bea84864:/docs/latex/wx/filedlg.tex?ds=inline diff --git a/docs/latex/wx/filedlg.tex b/docs/latex/wx/filedlg.tex index 1631a49d12..859b7a030c 100644 --- a/docs/latex/wx/filedlg.tex +++ b/docs/latex/wx/filedlg.tex @@ -16,39 +16,39 @@ This class represents the file chooser dialog. \wxheading{See also} \helpref{wxFileDialog overview}{wxfiledialogoverview}, \helpref{wxFileSelector}{wxfileselector} -%\rtfsp\helpref{wxFileSelectorEx}{wxfileselectorex} -%\helpref{wxLoadFileSelector}{wxloadfileselector},\rtfsp -%\helpref{wxSaveFileSelector}{wxsavefileselector} \wxheading{Remarks} -Pops up a file selector box. In Windows, this is the common file selector -dialog. In X, this is a file selector box with somewhat less functionality. -The path and filename are distinct elements of a full file pathname. +Pops up a file selector box. In Windows and GTK2.4+, this is the common +file selector dialog. In X, this is a file selector box with somewhat less +functionality. The path and filename are distinct elements of a full file pathname. If path is ``", the current directory will be used. If filename is ``", no default filename will be supplied. The wildcard determines what files are displayed in the file selector, and file extension supplies a type extension for the required filename. Flags may be a combination of wxOPEN, -wxSAVE, wxOVERWRITE\_PROMPT, wxHIDE\_READONLY, or 0. They are only significant -at present in Windows. +wxSAVE, wxOVERWRITE\_PROMPT, wxHIDE\_READONLY, wxFILE\_MUST\_EXIST, +wxMULTIPLE, wxCHANGE\_DIR or 0. Both the X and Windows versions implement a wildcard filter. Typing a filename containing wildcards (*, ?) in the filename text item, and clicking on Ok, will result in only those files matching the pattern being -displayed. In the X version, supplying no default name will result in the -wildcard filter being inserted in the filename text item; the filter is -ignored if a default name is supplied. - -Under Windows (only), the wildcard may be a specification for multiple +displayed. The wildcard may be a specification for multiple types of file with a description for each, such as: \begin{verbatim} - "BMP files (*.bmp) | *.bmp | GIF files (*.gif) | *.gif" + "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png" \end{verbatim} +It must be noted that wildcard support in the native Motif file +dialog is quite limited: only one alternative is supported, +and it is displayed without the descriptive test; ``BMP files (*.bmp)|*.bmp'' +is displayed as ``*.bmp'', and both +``BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif'' and +``Image files|*.bmp;*.gif'' are errors. + \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxFileDialog::wxFileDialog}\label{wxfiledialogconstr} +\membersection{wxFileDialog::wxFileDialog}\label{wxfiledialogctor} \func{}{wxFileDialog}{\param{wxWindow* }{parent}, \param{const wxString\& }{message = "Choose a file"},\rtfsp \param{const wxString\& }{defaultDir = ""}, \param{const wxString\& }{defaultFile = ``"},\rtfsp @@ -66,22 +66,35 @@ Constructor. Use \helpref{wxFileDialog::ShowModal}{wxfiledialogshowmodal} to sho \docparam{defaultFile}{The default filename, or the empty string.} -\docparam{wildcard}{A wildcard, such as ``*.*".} +\docparam{wildcard}{A wildcard, such as ``*.*" or ``BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". + +Note that the native Motif dialog has some limitations with respect to +wildcards; see the Remarks section above.} \docparam{style}{A dialog style. A bitlist of: \twocolwidtha{5cm} \begin{twocollist} -\twocolitem{{\bf wxOPEN}}{This is an open dialog (Windows only).} -\twocolitem{{\bf wxSAVE}}{This is a save dialog (Windows only).} -\twocolitem{{\bf wxHIDE\_READONLY}}{Hide read-only files (Windows only).} -\twocolitem{{\bf wxOVERWRITE\_PROMPT}}{Prompt for a conformation if a file will be overridden (Windows only).} +\twocolitem{{\bf wxOPEN}}{This is an open dialog.} +\twocolitem{{\bf wxSAVE}}{This is a save dialog.} +\twocolitem{{\bf wxOVERWRITE\_PROMPT}}{For save dialog only: prompt for a confirmation if a file will be overwritten.} +\twocolitem{{\bf wxHIDE\_READONLY}}{Do not display the checkbox to toggle display of read-only files. Deprecated in 2.6; the checkbox is never shown.} +\twocolitem{{\bf wxFILE\_MUST\_EXIST}}{The user may only select files that actually exist.} +\twocolitem{{\bf wxMULTIPLE}}{For open dialog only: allows selecting multiple files.} +\twocolitem{{\bf wxCHANGE\_DIR}}{Change the current working directory to the directory where the file(s) chosen by the user are.} \end{twocollist}% } \docparam{pos}{Dialog position. Not implemented.} -\membersection{wxFileDialog::\destruct{wxFileDialog}} +{\bf NB:} Previous versions of wxWidgets used {\tt wxCHANGE\_DIR} by default +under MS Windows which allowed the program to simply remember the last +directory where user selected the files to open/save. This (desired) +functionality must be implemented in the program itself now (manually remember +the last path used and pass it to the dialog the next time it is called) or +by using this flag. + +\membersection{wxFileDialog::\destruct{wxFileDialog}}\label{wxfiledialogdtor} \func{}{\destruct{wxFileDialog}}{\void} @@ -99,6 +112,19 @@ Returns the default directory. Returns the default filename. +\membersection{wxFileDialog::GetFilenames}\label{wxfiledialoggetfilenames} + +\constfunc{void}{GetFilenames}{\param{wxArrayString\& }{filenames}} + +Fills the array {\it filenames} with the names of the files chosen. This +function should only be used with the dialogs which have {\tt wxMULTIPLE} style, +use \helpref{GetFilename}{wxfiledialoggetfilename} for the others. + +Note that under Windows, if the user selects shortcuts, the filenames +include paths, since the application cannot determine the full path +of each referenced file by appending the directory containing the shortcuts +to the filename. + \membersection{wxFileDialog::GetFilterIndex}\label{wxfiledialoggetfilterindex} \constfunc{int}{GetFilterIndex}{\void} @@ -119,6 +145,14 @@ Returns the message that will be displayed on the dialog. Returns the full path (directory and filename) of the selected file. +\membersection{wxFileDialog::GetPaths}\label{wxfiledialoggetpaths} + +\constfunc{void}{GetPaths}{\param{wxArrayString\& }{paths}} + +Fills the array {\it paths} with the full paths of the files chosen. This +function should only be used with the dialogs which have {\tt wxMULTIPLE} style, +use \helpref{GetPath}{wxfiledialoggetpath} for the others. + \membersection{wxFileDialog::GetStyle}\label{wxfiledialoggetstyle} \constfunc{long}{GetStyle}{\void} @@ -147,7 +181,7 @@ Sets the default filename. \func{void}{SetFilterIndex}{\param{int }{filterIndex}} -Sets the default filter index, starting from zero. Windows only. +Sets the default filter index, starting from zero. \membersection{wxFileDialog::SetMessage}\label{wxfiledialogsetmessage} @@ -165,19 +199,24 @@ Sets the path (the combined directory and filename that will be returned when th \func{void}{SetStyle}{\param{long }{style}} -Sets the dialog style. See \helpref{wxFileDialog::wxFileDialog}{wxfiledialogconstr} for details. +Sets the dialog style. See \helpref{wxFileDialog::wxFileDialog}{wxfiledialogctor} for details. \membersection{wxFileDialog::SetWildcard}\label{wxfiledialogsetwildcard} \func{void}{SetWildcard}{\param{const wxString\& }{wildCard}} -Sets the wildcard, which in Windows can contain multiple file types. +Sets the wildcard, which can contain multiple file types, for example: + +``BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" + +Note that the native Motif dialog has some limitations with respect to +wildcards; see the Remarks section above. \membersection{wxFileDialog::ShowModal}\label{wxfiledialogshowmodal} \func{int}{ShowModal}{\void} -Shows the dialog, returning wxID\_OK if the user pressed OK, and wxOK\_CANCEL +Shows the dialog, returning wxID\_OK if the user pressed OK, and wxID\_CANCEL otherwise.