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