/*************************************************************************
 *
 *  $RCSfile: XFilePicker.idl,v $
 *
 *  $Revision: 1.6 $
 *
 *  last change: $Author: hr $ $Date: 2003/03/26 13:58:05 $
 *
 *  The Contents of this file are made available subject to the terms of
 *  either of the following licenses
 *
 *         - GNU Lesser General Public License Version 2.1
 *         - Sun Industry Standards Source License Version 1.1
 *
 *  Sun Microsystems Inc., October, 2000
 *
 *  GNU Lesser General Public License Version 2.1
 *  =============================================
 *  Copyright 2000 by Sun Microsystems, Inc.
 *  901 San Antonio Road, Palo Alto, CA 94303, USA
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License version 2.1, as published by the Free Software Foundation.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 *  MA  02111-1307  USA
 *
 *
 *  Sun Industry Standards Source License Version 1.1
 *  =================================================
 *  The contents of this file are subject to the Sun Industry Standards
 *  Source License Version 1.1 (the "License"); You may not use this file
 *  except in compliance with the License. You may obtain a copy of the
 *  License at http://www.openoffice.org/license.html.
 *
 *  Software provided under this License is provided on an "AS IS" basis,
 *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
 *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
 *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
 *  See the License for the specific provisions governing your rights and
 *  obligations concerning the Software.
 *
 *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
 *
 *  Copyright: 2000 by Sun Microsystems, Inc.
 *
 *  All Rights Reserved.
 *
 *  Contributor(s): _______________________________________
 *
 *
 ************************************************************************/
#ifndef __com_sun_star_ui_dialogs_XFilePicker_idl__
#define __com_sun_star_ui_dialogs_XFilePicker_idl__

#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
#include <com/sun/star/lang/IllegalArgumentException.idl>
#endif

#ifndef __com_sun_star_uno_XInterface_idl__
#include <com/sun/star/uno/XInterface.idl>
#endif

#ifndef __com_sun_star_ui_dialogs_XExecutableDialog_idl__
#include <com/sun/star/ui/dialogs/XExecutableDialog.idl>
#endif

//=============================================================================

module com { module sun { module star { module ui { module dialogs {

//=============================================================================
/** Specifies an interface for a FilePicker
*/
 
interface XFilePicker: com::sun::star::ui::dialogs::XExecutableDialog
{

	//-------------------------------------------------------------------------
	/**	Enable/disable multiselection mode 

		<p>If the multiselection mode is enabled, multiple files 
		may be selected bz the user else only one file selection at a time is possible</p>
	
		@param bMode 
		<p>A value of <TRUE/> enables the multiselection mode.</p>
		<p>A value of <FALSE/> disables the multiselection mode, this is the default.</p>
	*/
	void setMultiSelectionMode( [in] boolean bMode );

	//-------------------------------------------------------------------------
	/**	Sets the default string that appears in the file name box of a FilePicker.

		@param aName
		<p>	Specifies the default file name, displayed when the FilePicker 
			is shown. The implementation may accept any string, and does not
			have to check for a valid file name or if the file really exists.
		</p>
	*/
	void setDefaultName( [in] string aName );

	//-------------------------------------------------------------------------
	/**	Sets the directory that the file dialog initially displays.

		@param aDirectory
		Specifies the initial directory in URL format. The given URL must be
		conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>). 
			
		@throws com::sun::star::lang::IllegalArgumentException
		if the URL is invalid (doesn't conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>).		
	*/
	void setDisplayDirectory( [in] string aDirectory )
		raises( ::com::sun::star::lang::IllegalArgumentException );

	//-------------------------------------------------------------------------
	/**	Returns the directory that the file dialog is currently showing or 
		was last showing before closing the dialog with Ok. If the user 
		did cancel the dialog, the returned value is undefined. 

		@returns 
		The directory in URL format, must be conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>.		
	 */
	string getDisplayDirectory();

	//-------------------------------------------------------------------------
	/**	Returns a sequence of the selected files including path information in
		URL format, conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>.

		<p>If the user closed the dialog with cancel an empty sequence will be 
		returned.</p>
		<br/>
		<p>If the dialog is in execution mode and a single file is selected 
		the complete URL of this file will be returned.</p>
		<p>If the dialog is in execution mode and multiple files are selected 
		an empty sequence will be returned.</p>
		<p>If the dialog is in execution mode and the selected file name is false
		or any other error occurs an empty sequence will be returned.</p>

		@returns 
		<p>	The complete path of the file or directory currently selected
			in URL format. There are two different cases:
			<ol>
				<li>Multiselection is disabled: 
				The first and only entry of the sequence contains the complete 
				path/filename in URL format.</li>

				<li>Multiselection is enabled:  
				If only one file is selected, the first entry
				of the sequence contains the complete path/filename in URL format. 
				If multiple files are selected, the first entry of the sequence contains 
				the path in URL format, and the other entries contains the names of the selected 
				files without path information.</li>
			</ol>
			
			<br/>

			<p><strong>Notes for the implementation of a FileSave dialog:</strong>If there exists 
			a checkbox "Automatic File Extension" which is checked and a valid filter is currently selected
			the dialog may automatically add an extension to the selected file name.</p>
		</p>
	*/
	sequence< string > getFiles();
};

//=============================================================================

}; }; }; }; };


#endif

