1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_ui_dialogs_XFilePicker_idl__
24#define __com_sun_star_ui_dialogs_XFilePicker_idl__
25
26#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
27#include <com/sun/star/lang/IllegalArgumentException.idl>
28#endif
29
30#ifndef __com_sun_star_uno_XInterface_idl__
31#include <com/sun/star/uno/XInterface.idl>
32#endif
33
34#ifndef __com_sun_star_ui_dialogs_XExecutableDialog_idl__
35#include <com/sun/star/ui/dialogs/XExecutableDialog.idl>
36#endif
37
38//=============================================================================
39
40module com { module sun { module star { module ui { module dialogs {
41
42//=============================================================================
43/** Specifies an interface for a FilePicker
44*/
45
46published interface XFilePicker: com::sun::star::ui::dialogs::XExecutableDialog
47{
48
49	//-------------------------------------------------------------------------
50	/**	Enable/disable multiselection mode
51
52		<p>If the multiselection mode is enabled, multiple files
53		may be selected by the user else only one file selection at a time is possible</p>
54
55		@param bMode
56		<p>A value of <TRUE/> enables the multiselection mode.</p>
57		<p>A value of <FALSE/> disables the multiselection mode, this is the default.</p>
58	*/
59	void setMultiSelectionMode( [in] boolean bMode );
60
61	//-------------------------------------------------------------------------
62	/**	Sets the default string that appears in the file name box of a FilePicker.
63
64		@param aName
65		<p>	Specifies the default file name, displayed when the FilePicker
66			is shown. The implementation may accept any string, and does not
67			have to check for a valid file name or if the file really exists.
68		</p>
69	*/
70	void setDefaultName( [in] string aName );
71
72	//-------------------------------------------------------------------------
73	/**	Sets the directory that the file dialog initially displays.
74
75		@param aDirectory
76		Specifies the initial directory in URL format. The given URL must be
77		conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>).
78
79		@throws com::sun::star::lang::IllegalArgumentException
80		if the URL is invalid (doesn't conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>).
81	*/
82	void setDisplayDirectory( [in] string aDirectory )
83		raises( ::com::sun::star::lang::IllegalArgumentException );
84
85	//-------------------------------------------------------------------------
86	/**	Returns the directory that the file dialog is currently showing or
87		was last showing before closing the dialog with Ok. If the user
88		did cancel the dialog, the returned value is undefined.
89
90		@returns
91		The directory in URL format, must be conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>.
92	 */
93	string getDisplayDirectory();
94
95	//-------------------------------------------------------------------------
96	/**	Returns a sequence of the selected files including path information in
97		URL format, conform to <a href="http://www.w3.org/Addressing/rfc1738.txt">Rfc1738</a>.
98
99		<p>If the user closed the dialog with cancel an empty sequence will be
100		returned.</p>
101		<br/>
102		<p>If the dialog is in execution mode and a single file is selected
103		the complete URL of this file will be returned.</p>
104		<p>If the dialog is in execution mode and multiple files are selected
105		an empty sequence will be returned.</p>
106		<p>If the dialog is in execution mode and the selected file name is false
107		or any other error occurs an empty sequence will be returned.</p>
108
109		@returns
110		<p>	The complete path of the file or directory currently selected
111			in URL format. There are two different cases:
112			<ol>
113				<li>Multiselection is disabled:
114				The first and only entry of the sequence contains the complete
115				path/filename in URL format.</li>
116
117				<li>Multiselection is enabled:
118				If only one file is selected, the first entry
119				of the sequence contains the complete path/filename in URL format.
120				If multiple files are selected, the first entry of the sequence contains
121				the path in URL format, and the other entries contains the names of the selected
122				files without path information.</li>
123			</ol>
124
125			<br/>
126
127			<p><strong>Notes for the implementation of a FileSave dialog:</strong>If there exists
128			a checkbox "Automatic File Extension" which is checked and a valid filter is currently selected
129			the dialog may automatically add an extension to the selected file name.</p>
130		</p>
131	*/
132	sequence< string > getFiles();
133};
134
135//=============================================================================
136
137}; }; }; }; };
138
139
140#endif
141
142