offapi/com/sun/star/ui/dialogs/XFilePicker.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XFilePicker.idl,v $
  10  * $Revision: 1.10 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_ui_dialogs_XFilePicker_idl__
  31 #define __com_sun_star_ui_dialogs_XFilePicker_idl__
  32
  33 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  34 #include <com/sun/star/lang/IllegalArgumentException.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_uno_XInterface_idl__
  38 #include <com/sun/star/uno/XInterface.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_ui_dialogs_XExecutableDialog_idl__
  42 #include <com/sun/star/ui/dialogs/XExecutableDialog.idl>
  43 #endif
  44
  45 //=============================================================================
  46
  47 module com { module sun { module star { module ui { module dialogs {
  48
  49 //=============================================================================
  50 /** Specifies an interface for a FilePicker
  51 */
  52
  53 published interface XFilePicker: com::sun::star::ui::dialogs::XExecutableDialog
  54 {
  55
  56     //-------------------------------------------------------------------------
  57     /** Enable/disable multiselection mode
  58
  59         <p>If the multiselection mode is enabled, multiple files
  60         may be selected by the user else only one file selection at a time is possible</p>
  61
  62         @param bMode
  63         <p>A value of <TRUE/> enables the multiselection mode.</p>
  64         <p>A value of <FALSE/> disables the multiselection mode, this is the default.</p>
  65     */
  66     void setMultiSelectionMode( [in] boolean bMode );
  67
  68     //-------------------------------------------------------------------------
  69     /** Sets the default string that appears in the file name box of a FilePicker.
  70
  71         @param aName
  72         <p>     Specifies the default file name, displayed when the FilePicker
  73             is shown. The implementation may accept any string, and does not
  74             have to check for a valid file name or if the file really exists.
  75         </p>
  76     */
  77     void setDefaultName( [in] string aName );
  78
  79     //-------------------------------------------------------------------------
  80     /** Sets the directory that the file dialog initially displays.
  81
  82         @param aDirectory
  83         Specifies the initial directory in URL format. The given URL must be
  84         conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>).
  85
  86         @throws com::sun::star::lang::IllegalArgumentException
  87         if the URL is invalid (doesn't conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>).
  88     */
  89     void setDisplayDirectory( [in] string aDirectory )
  90         raises( ::com::sun::star::lang::IllegalArgumentException );
  91
  92     //-------------------------------------------------------------------------
  93     /** Returns the directory that the file dialog is currently showing or
  94         was last showing before closing the dialog with Ok. If the user
  95         did cancel the dialog, the returned value is undefined.
  96
  97         @returns
  98         The directory in URL format, must be conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>.
  99      */
 100     string getDisplayDirectory();
 101
 102     //-------------------------------------------------------------------------
 103     /** Returns a sequence of the selected files including path information in
 104         URL format, conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>.
 105
 106         <p>If the user closed the dialog with cancel an empty sequence will be
 107         returned.</p>
 108         <br/>
 109         <p>If the dialog is in execution mode and a single file is selected
 110         the complete URL of this file will be returned.</p>
 111         <p>If the dialog is in execution mode and multiple files are selected
 112         an empty sequence will be returned.</p>
 113         <p>If the dialog is in execution mode and the selected file name is false
 114         or any other error occurs an empty sequence will be returned.</p>
 115
 116         @returns
 117         <p>     The complete path of the file or directory currently selected
 118             in URL format. There are two different cases:
 119             <ol>
 120                 <li>Multiselection is disabled:
 121                 The first and only entry of the sequence contains the complete
 122                 path/filename in URL format.</li>
 123
 124                 <li>Multiselection is enabled:
 125                 If only one file is selected, the first entry
 126                 of the sequence contains the complete path/filename in URL format.
 127                 If multiple files are selected, the first entry of the sequence contains
 128                 the path in URL format, and the other entries contains the names of the selected
 129                 files without path information.</li>
 130             </ol>
 131
 132             <br/>
 133
 134             <p><strong>Notes for the implementation of a FileSave dialog:</strong>If there exists
 135             a checkbox "Automatic File Extension" which is checked and a valid filter is currently selected
 136             the dialog may automatically add an extension to the selected file name.</p>
 137         </p>
 138     */
 139     sequence< string > getFiles();
 140 };
 141
 142 //=============================================================================
 143
 144 }; }; }; }; };
 145
 146
 147 #endif
 148