X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c61f4f6dbd971245f694eb01034c86040a44db00..f644bc116bbe46d6ab609a44c05835dc4d87ba02:/docs/latex/wx/filedlg.tex

diff --git a/docs/latex/wx/filedlg.tex b/docs/latex/wx/filedlg.tex
index 63d4a9bd1a..859b7a030c 100644
--- a/docs/latex/wx/filedlg.tex
+++ b/docs/latex/wx/filedlg.tex
@@ -19,14 +19,15 @@ This class represents the file chooser dialog.
 
 \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, wxMULTIPLE or 0.
+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
@@ -35,12 +36,19 @@ 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
@@ -58,7 +66,10 @@ 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:
 
@@ -66,15 +77,24 @@ Constructor. Use \helpref{wxFileDialog::ShowModal}{wxfiledialogshowmodal} to sho
 \begin{twocollist}
 \twocolitem{{\bf wxOPEN}}{This is an open dialog.}
 \twocolitem{{\bf wxSAVE}}{This is a save dialog.}
-\twocolitem{{\bf wxHIDE\_READONLY}}{Hide read-only files.}
-\twocolitem{{\bf wxOVERWRITE\_PROMPT}}{Prompt for a conformation if a file will be overridden.}
-\twocolitem{{\bf wxMULTIPLE}}{For open dialog only: allows selecting multiple files}
+\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}
 
@@ -100,6 +120,11 @@ 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}
@@ -156,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}
 
@@ -174,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.