include/pwlib/opendlg.h

   1 /*
   2  * opendlg.h
   3  *
   4  * Open existing file dialog.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.19  2001/05/22 12:49:33  robertj
  31  * Did some seriously wierd rewrite of platform headers to eliminate the
  32  *   stupid GNU compiler warning about braces not matching.
  33  *
  34  * Revision 1.18  1999/03/10 03:49:52  robertj
  35  * More documentation adjustments.
  36  *
  37  * Revision 1.17  1999/03/09 08:01:49  robertj
  38  * Changed comments for doc++ support (more to come).
  39  *
  40  * Revision 1.16  1999/02/16 08:08:46  robertj
  41  * MSVC 6.0 compatibility changes.
  42  *
  43  * Revision 1.15  1998/09/23 06:24:31  robertj
  44  * Added open source copyright license.
  45  *
  46  * Revision 1.14  1998/03/09 07:15:29  robertj
  47  * More implementation of file type lists.
  48  *
  49  * Revision 1.13  1998/03/09 01:41:14  robertj
  50  * Enhanced file types for standard file dialog.
  51  *
  52  * Revision 1.12  1995/06/17 11:12:49  robertj
  53  * Documentation update.
  54  *
  55  * Revision 1.11  1995/03/14 12:41:55  robertj
  56  * Updated documentation to use HTML codes.
  57  *
  58  * Revision 1.10  1994/12/21  11:53:17  robertj
  59  * Documentation and variable normalisation.
  60  *
  61  * Revision 1.9  1994/08/23  11:32:52  robertj
  62  * Oops
  63  *
  64  * Revision 1.8  1994/08/22  00:46:48  robertj
  65  * Added pragma fro GNU C++ compiler.
  66  *
  67  * Revision 1.7  1994/04/20  12:17:44  robertj
  68  * Split name into PFilePath
  69  *
  70  * Revision 1.6  1994/04/11  14:13:05  robertj
  71  * Added extra standard resource IDs and normalised dialog ids.
  72  *
  73  * Revision 1.5  1994/03/07  07:38:19  robertj
  74  * Major enhancementsacross the board.
  75  *
  76  * Revision 1.4  1994/01/03  04:42:23  robertj
  77  * Mass changes to common container classes and interactors etc etc etc.
  78  *
  79  * Revision 1.3  1993/12/01  16:09:05  robertj
  80  * Windows NT port.
  81  *
  82  * Revision 1.2  1993/07/14  12:49:16  robertj
  83  * Fixed RCS keywords.
  84  *
  85  */
  86
  87
  88 #define _POPENFILEDIALOG
  89
  90 #ifdef __GNUC__
  91 #pragma interface
  92 #endif
  93
  94
  95 /**A standard dialog for obtaining an existing file name for loading by the
  96    application. The exact appearance of the dialog is platform specific,
  97    however they all consists of the same basic functions.
  98
  99    The semantics of the set of file types is slightly different on different
 100    platforms. For the Macintosh all files in the set are displayed. For
 101    MS-Window a choice box is available which allows the user to select one
 102    of the types in the set and only files for that single type are available.
 103
 104    Note that unlike most dialogs, most operations such as
 105    \Ref{PInteractor::Show()}, \Ref{PInteractorLayout::GetControl()} etc may
 106    {\bf not} be executed before the \Ref{PModalDialog::RunModal()} function
 107    has been executed. Furthermore, they are not available {\bf after}
 108    \Ref{PModalDialog::RunModal()} has returned. Similarly some functions such
 109    as \Ref{PFileDialog::SetDirectory()} are not available {\bf within} the
 110    centext of \Ref{PModalDialog::RunModal()}. This is due to the
 111    implementation on some platforms which goes to great lengths to use the
 112    actual standard file dialog for the platform.
 113  */
 114 class POpenFileDialog : public PFileDialog
 115 {
 116   PCLASSINFO(POpenFileDialog, PFileDialog);
 117
 118   public:
 119    /**Create a new standard open file dialog. The actual appearence is
 120        platform dependent and is displayed using the standard resource. This
 121        resource may be overridden by the #resID# parameter but must
 122        still contain all of the controls of the standard resource.
 123      */
 124     POpenFileDialog(
 125       PInteractor * parent,   /// Owner interactor for the dialog.
 126       PRESOURCE_ID resID = PSTD_ID_DIALOG_OPEN_FILE
 127         /// Resource identifier for the dialog description resource.
 128     );
 129
 130     /** Destroy the standard open file dialog. */
 131     virtual ~POpenFileDialog();
 132
 133
 134   /**@name New functions for class */
 135    /**Add a file type to the array of file types that may be specified for the
 136        file dialog.
 137
 138        The file type array is used to filter out file names unless they have
 139        a file type within the set. If the array is empty then all files are
 140        available. They may be subsequently filtered by the
 141        \Ref{OnFilterFile()} callback function.
 142
 143        @return
 144        Index of new entry in array
 145      */
 146     PINDEX AddFileType(
 147       const PString & type    /// File type to add to set of file types.
 148     );
 149
 150    /**Get the array of file types that may be specified for the file dialog.
 151
 152        The file type array is used to filter out file names unless they have
 153        a file type within the set. If the set is empty then all files are
 154        available. They may be subsequently filtered by the
 155        \Ref{OnFilterFile()} callback function.
 156
 157        @return
 158        array of file type strings.
 159      */
 160     PStringArray GetFileTypes() const;
 161
 162    /**Set the array of file types that may be specified for the file dialog.
 163      */
 164     void SetFileTypes(
 165       const PStringArray & array
 166     );
 167
 168    /**Set the file type displayed when dialog is opened
 169      */
 170     void SetInitialFileType(
 171       PINDEX idx
 172     );
 173     void SetInitialFileType(
 174         const PString & str
 175     );
 176
 177    /**Get file type that was finally displayed
 178      */
 179     PINDEX GetFinalFileType() const;
 180     BOOL GetFinalFileType(
 181       PString & str
 182     ) const;
 183
 184   /**@name Callback functions */
 185    /**This is called as the dialog fills the list of files available to be
 186        selected. An application specific file select dialog may filter out
 187        files from the list. The default is to display the current file type(s)
 188        only.
 189
 190        Note that the files are pre-filtered with those files that are specified
 191        in the file types set created with the \Ref{AddFileType()} function.
 192
 193        @return
 194        TRUE if the file is to be included in the list.
 195      */
 196     virtual BOOL OnFilterFile(
 197       const PFilePath & file  /// File to determine if is displayed.
 198     );
 199
 200
 201   protected:
 202     // Member variables
 203     PStringArray fileTypes;
 204
 205
 206 // Include platform dependent part of class
 207 #include <pwlib/opendlg.h>
 208 };
 209
 210
 211 // End Of File ///////////////////////////////////////////////////////////////