added new and improved wxFileCtrl implementation (patch 1763164)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@48733 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -168,8 +168,9 @@ All (GUI):
 - Added support for labels for toolbar controls (Vince Harron).
 - Added wxMessageDialog::SetMessage() and SetExtendedMessage().
 - Added XRCSIZERITEM() macro for obtaining sizers from XRC (Brian Vanderburg II)
-- Added wxEventBlocker class (Francesco Montorsi)..
-- Added wxFile/DirPickerCtrl::Get/SetFile/DirName() (Francesco Montorsi)..
+- New and improved wxFileCtrl (Diaa Sami and Marcin Wojdyr)
+- Added wxEventBlocker class (Francesco Montorsi).
+- Added wxFile/DirPickerCtrl::Get/SetFile/DirName() (Francesco Montorsi).
 - Added wxSizerFlags::Top() and Bottom().
 - Slovak translation added.
 - Fixed tab-related drawing and hit-testing bugs in wxRichTextCtrl.

docs/latex/wx/classes.tex

@@ -141,6 +141,8 @@
 \input ffilestr.tex
 \input file.tex
 \input fileconf.tex
+\input filectrl.tex
+\input fileevt.tex
 \input fildatob.tex
 \input filedlg.tex
 \input fildrptg.tex

docs/latex/wx/filectrl.tex

@@ -0,0 +1,222 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        filectrl.tex
+%% Purpose:     wxFilerCtrl documentation
+%% Author:      Diaa M. Sami
+%% Created:     2007-07-25
+%% RCS-ID:      $Id: $
+%% Copyright:   (c) 2007 Diaa M. Sami
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxFileCtrl}}\label{wxfilectrl}
+
+This control allows the user to select a file. two implemetations exist, one
+for Gtk and another generic one for anything other than Gtk.
+It is only available if \texttt{wxUSE\_FILECTRL} is set to $1$.
+
+\wxheading{Derived from}
+
+\helpref{wxWindow}{wxwindow}\\
+\helpref{wxEvtHandler}{wxevthandler}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/filectrl.h>
+
+\wxheading{Window styles}
+
+\twocolwidtha{5cm}%
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxFC\_DEFAULT\_STYLE}}{The default style: wxFC\_OPEN}
+\twocolitem{\windowstyle{wxFC\_OPEN}}{Creates an file control suitable for opening files.
+Cannot be combined with wxFC\_SAVE.}
+\twocolitem{\windowstyle{wxFC\_SAVE}}{Creates an file control suitable for saving files. Cannot be combined with wxFC\_OPEN.}
+\twocolitem{\windowstyle{wxFC\_MULTIPLE}}{For open control only, Allows selecting multiple files. Cannot be combined with wxFC\_SAVE}
+\twocolitem{\windowstyle{wxFC\_NOSHOWHIDDEN}}{Hides the ``Show Hidden Files" checkbox (Generic only)}
+\end{twocollist}
+
+\wxheading{Event handling}
+
+To process a file control event, use these event handler macros to direct
+input to member functions that take a \helpref{wxFileCtrlEvent}{wxfilectrlevent}
+argument.
+
+\twocolwidtha{7cm}%
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf EVT\_FILECTRL\_FILEACTIVATED(id, func)}}{The user activated a file(by double-clicking or pressing Enter)}
+\twocolitem{{\bf EVT\_FILECTRL\_SELECTIONCHANGED(id, func)}}{The user changed the current selection(by selecting or deselecting a file)}
+\twocolitem{{\bf EVT\_FILECTRL\_FOLDERCHANGED(id, func)}}{The current folder of the file ctrl has been changed}
+\end{twocollist}
+
+\wxheading{See also}
+
+\helpref{wxGenericDirCtrl}{wxgenericdirctrl}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxFileCtrl::wxFileCtrl}\label{wxfilectrlctor}
+
+\func{}{wxFileCtrl}{\void}
+
+Default constructor.
+
+\func{}{wxFileCtrl}{\param{wxWindow *}{parent},\rtfsp
+\param{wxWindowID}{ id},\rtfsp
+\param{const wxString\& }{defaultDirectory = wxEmptyString},\rtfsp
+\param{const wxString\& }{defaultFilename = wxEmptyString},\rtfsp
+\param{const wxPoint\& }{wildCard = wxFileSelectorDefaultWildcardStr},\rtfsp
+\param{long}{ style = wxFC\_DEFAULT\_STYLE},\rtfsp
+\param{const wxPoint\& }{pos = wxDefaultPosition},
+\param{const wxSize\& }{size = wxDefaultSize},
+\param{const wxString\& }{name = ``filectrl"}}
+
+\wxheading{Parameters}
+
+\docparam{parent}{Parent window, must not be non-\texttt{NULL}.}
+
+\docparam{id}{The identifier for the control.}
+
+\docparam{defaultDirectory}{The initial directory shown in the control. Must be
+a valid path to a directory or the empty string.
+In case it is the empty string, the current working directory is used.}
+
+\docparam{defaultFilename}{The default filename, or the empty string.}
+
+\docparam{wildcard}{A wildcard specifying which files can be selected,
+such as ``*.*" or ``BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".}
+
+\docparam{style}{The window style, see {\tt wxFC\_*} flags.}
+
+\docparam{pos}{Initial position.}
+
+\docparam{size}{Initial size.}
+
+\docparam{name}{Control name.}
+
+\wxheading{Return value}
+
+\true if the control was successfully created or \false if creation failed.
+
+\membersection{wxFileCtrl::Create}\label{wxfilectrlcreate}
+
+\func{bool}{Create}{\param{wxWindow *}{parent},\rtfsp
+\param{wxWindowID}{ id},\rtfsp
+\param{const wxString\& }{defaultDirectory = wxEmptyString},\rtfsp
+\param{const wxString\& }{defaultFilename = wxEmptyString},\rtfsp
+\param{const wxPoint\& }{wildCard = wxFileSelectorDefaultWildcardStr},\rtfsp
+\param{long}{ style = wxFC\_DEFAULT\_STYLE},\rtfsp
+\param{const wxPoint\& }{pos = wxDefaultPosition},
+\param{const wxSize\& }{size = wxDefaultSize},
+\param{const wxString\& }{name = ``filectrl"}}
+
+Create function for two-step construction. See \helpref{wxFileCtrl::wxFileCtrl}{wxfilectrlctor} for details.
+
+\membersection{wxFileDialog::GetFilename}\label{wxfilectrlgetfilename}
+
+\constfunc{wxString}{GetFilename}{\void}
+
+Returns the currently selected filename.
+For the controls having the {\tt wxFC\_MULTIPLE} style, use \helpref{GetFilenames}{wxfilectrlgetfilenames}
+instead
+
+\membersection{wxFileCtrl::GetDirectory}\label{wxfilectrlgetdirectory}
+
+\constfunc{wxString}{GetDirectory}{\void}
+
+Returns the current directory of the file ctrl(the directory shown in the file ctrl).
+
+\membersection{wxFileCtrl::GetWildcard}\label{wxfilectrlgetwildcard}
+
+\constfunc{wxString}{GetWildcard}{\void}
+
+Returns the current wildcard.
+
+\membersection{wxFileCtrl::GetPath}\label{wxfilectrlgetpath}
+
+\constfunc{wxString}{GetPath}{\void}
+
+Returns the full path (directory and filename) of the currently selected file.
+For the controls having the {\tt wxFC\_MULTIPLE} style, use \helpref{GetPaths}{wxfilectrlgetpaths}
+instead
+
+\membersection{wxFileCtrl::GetPaths}\label{wxfilectrlgetpaths}
+
+\constfunc{void}{GetPaths}{\param{wxArrayString\& }{paths}}
+
+Fills the array {\it paths} with the full paths of the files chosen. This
+function should be used with the controls having the {\tt wxFC\_MULTIPLE} style,
+use \helpref{GetPath}{wxfilectrlgetpath} otherwise.
+
+\wxheading{Remarks}
+
+{\it paths} is emptied first.
+
+\membersection{wxFileCtrl::GetFilenames}\label{wxfilectrlgetfilenames}
+
+\constfunc{void}{GetFilenames}{\param{wxArrayString\& }{filenames}}
+
+Fills the array {\it filenames} with the filenames only of selected items. This
+function should only be used with the controls having the {\tt wxFC\_MULTIPLE} style,
+use \helpref{GetFilename}{wxfilectrlgetfilename} for the others.
+
+\wxheading{Remarks}
+
+{\it filenames} is emptied first.
+
+\membersection{wxFileCtrl::GetFilterIndex}\label{wxfilectrlgetfilterindex}
+
+\constfunc{int}{GetFilterIndex}{\void}
+
+Returns the zero-based index of the currently selected filter.
+
+\membersection{wxFileCtrl::ShowHidden}\label{wxfilectrlshowhidden}
+
+\func{void}{ShowHidden}{\param{const bool }{show}}
+
+Sets whether hidden files and folders are shown or not.
+
+\membersection{wxFileCtrl::SetWildcard}\label{wxfilectrlsetwildcard}
+
+\func{void}{SetWildcard}{\param{const wxString\& }{wildCard}}
+
+Sets the wildcard, which can contain multiple file types, for example:
+
+``BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
+
+\membersection{wxFileCtrl::SetFilterIndex}\label{wxfilectrlsetfilterindex}
+
+\func{void}{SetFilterIndex}{\param{int }{filterIndex}}
+
+Sets the current filter index, starting from zero.
+
+\membersection{wxFileCtrl::SetDirectory}\label{wxfilectrlsetdirectory}
+
+\func{bool}{SetDirectory}{\param{const wxString\& }{directory}}
+
+Sets(changes) the current directory displayed in the control.
+
+\wxheading{Return value}
+
+Returns \true on success, \false otherwise.
+
+\membersection{wxFileCtrl::SetFilename}\label{wxfilectrlsetfilename}
+
+\func{bool}{SetFilename}{\param{const wxString\& }{filename}}
+
+Selects a certain file.
+
+\wxheading{Return value}
+
+Returns \true on success, \false otherwise
+
+\membersection{wxFileCtrl::SetPath}\label{wxfilectrlsetpath}
+
+\func{bool}{SetPath}{\param{const wxString\& }{path}}
+
+Selects a certain file using its path (the combined directory and filename).
+Equivalent to \helpref{SetPath}{wxfilectrlsetpath} then \helpref{SetFilename}{wxfilectrlsetfilename}.
+
+\wxheading{Return value}
+
+Returns \true on success, \false otherwise.

docs/latex/wx/fileevt.tex

@@ -0,0 +1,77 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        fileevt.tex
+%% Purpose:     wxFileCtrlEvent documentation
+%% Author:      Diaa M. Sami
+%% Created:     2007-07-25
+%% RCS-ID:      $Id: $
+%% Copyright:   (c) 2007 Diaa M. Sami
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxFileCtrlEvent}}\label{wxfilectrlevent}
+
+A file control event holds information about events associated with
+\helpref{wxFileCtrl}{wxfilectrl} objects.
+
+\wxheading{Derived from}
+
+\helpref{wxCommandEvent}{wxcommandevent}\\
+\helpref{wxEvent}{wxevent}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/filectrl.h>
+
+\wxheading{Event table macros}
+
+To process input from a file control, use these event handler macros to direct input to member
+functions that take a wxFileCtrlEvent argument.
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf EVT\_FILECTRL\_FILEACTIVATED(id, func)}}{The user activated a file(by double-clicking or pressing Enter)}
+\twocolitem{{\bf EVT\_FILECTRL\_SELECTIONCHANGED(id, func)}}{The user changed the current selection(by selecting or deselecting a file)}
+\twocolitem{{\bf EVT\_FILECTRL\_FOLDERCHANGED(id, func)}}{The current folder of the file ctrl has been changed}
+\end{twocollist}%
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxFileCtrlEvent::wxFileCtrlEvent}\label{wxfilectrleventctor}
+
+\func{}{wxFileCtrlEvent}{\param{wxEventType }{type}, \param{wxObject }{evtObject}, \param{int }{id}}
+
+Constructor.
+
+\membersection{wxFileCtrlEvent::GetFiles}\label{wxfilectrleventgetfiles}
+
+\constfunc{wxArrayString}{GetFiles}{\void}
+
+Returns the files selected.
+In case of a {\bf EVT\_FILECTRL\_SELECTIONCHANGED}, this method returns the
+files selected after the event.
+
+\membersection{wxFileCtrlEvent::GetDirectory}\label{wxfilectrleventgetdirectory}
+
+\constfunc{wxString}{GetDirectory}{\void}
+
+Returns the current directory.
+In case of a {\bf EVT\_FILECTRL\_FOLDERCHANGED}, this method returns the new directory.
+
+\membersection{wxFileCtrlEvent::GetFile}\label{wxfilectrleventgetfile}
+
+\constfunc{wxString}{GetFile}{\void}
+
+Returns the file selected(assuming it is only one file).
+
+\membersection{wxFileCtrlEvent::SetFiles}\label{wxfilectrleventsetfiles}
+
+\func{}{wxFileCtrlEvent::SetFiles}{\param{const wxArrayString &}{files}}
+
+Sets the files changed by this event.
+
+\membersection{wxFileCtrlEvent::SetDirectory}\label{wxfilectrleventsetdirectory}
+
+\func{}{wxFileCtrlEvent::SetDirectory}{\param{const wxString &}{directory}}
+
+Sets the current directory of this event.

docs/latex/wx/wxusedef.tex

@@ -75,6 +75,7 @@ using \texttt{#if} and not \texttt{#ifdef}.
 \twocolitem{wxUSE\_FFILE}{Use \helpref{wxFFile}{wxffile} class.}
 \twocolitem{wxUSE\_FILE}{Use \helpref{wxFile}{wxfile} class.}
 \twocolitem{wxUSE\_FILECONFIG}{Use \helpref{wxFileConfig}{wxfileconfig} class.}
+\twocolitem{wxUSE\_FILECTRL}{Use \helpref{wxFileCtrl}{wxfilectrl} class.}
 \twocolitem{wxUSE\_FILEDLG}{Use \helpref{wxFileDialog}{wxfiledialog} class.}
 \twocolitem{wxUSE\_FILEPICKERCTRL}{Use \helpref{wxFilePickerCtrl}{wxfilepickerctrl} class.}
 \twocolitem{wxUSE\_FILESYSTEM}{Use \helpref{wxFileSystem}{wxfilesystem} and related classes.}