path: root/offapi/com/sun/star/ui/dialogs/FilePicker.idl

/*************************************************************************
 *
 *  $RCSfile: FilePicker.idl,v $
 *
 *  $Revision: 1.7 $
 *
 *  last change: $Author: mi $ $Date: 2002-10-03 13:10:41 $
 *
 *  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_FilePicker_idl__
#define __com_sun_star_ui_dialogs_FilePicker_idl__

#ifndef __com_sun_star_lang_XComponent_idl__
#include <com/sun/star/lang/XComponent.idl>
#endif

#ifndef __com_sun_star_lang_XServiceInfo_idl__
#include <com/sun/star/lang/XServiceInfo.idl>
#endif

#ifndef __com_sun_star_lang_XTypeProvider_idl__
#include <com/sun/star/lang/XTypeProvider.idl>
#endif

#ifndef __com_sun_star_lang_XInitialization_idl__
#include <com/sun/star/lang/XInitialization.idl>
#endif

#ifndef __com_sun_star_util_XCancellable_idl__ 
#include <com/sun/star/util/XCancellable.idl>
#endif

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

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

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

//=============================================================================
/** A FilePicker. 

    @see XFilePicker
*/

interface XFilePicker;
interface XFilePickerNotifier;
interface XFilePickerControlAccess;
interface XFilterManager;
interface XFilePreview;
interface XFilterGroupManager;
interface XControlInformation;
interface XControlAccess;
    
service FilePicker
{
    //-------------------------------------------------------------------------
    /** Allows to associate a help URL with the file picker instance.
    */
    [optional, property] string HelpURL;

    //-------------------------------------------------------------------------
    /** Provides access to the basic FilePicker functionality.		
    */
    interface XFilePicker;

    //-------------------------------------------------------------------------
    /** Provides the ability to request notifications about changes.
    */
    interface XFilePickerNotifier;

    //-------------------------------------------------------------------------
    /** Provides the ability to add different filter, query for the current 
        filters and set a current filter		
    */
    interface XFilterManager;

    //-------------------------------------------------------------------------
    /** Provides the ability to show a preview of a selected file		
    */
    [optional] interface XFilePreview;

    //-------------------------------------------------------------------------
    /** Provides the ability manage additional controls (checkboxes, listboxes etc.)
        offered by an extended FilePicker, these controls extend the subset of
        common controls that a FilePicker usually supports.

        <p>This interface is deprecated, newer implementations should support resp. use
        the <type>XControlAccess</type> interface instead, which provides a more general API.</p>

        
        @see com::sun::star::ui::dialogs::CommonFilePickerElementIds
        @see com::sun::star::ui::dialogs::ExtendedFilePickerElementIds		
        
        @deprecated
    */
    [optional] interface XFilePickerControlAccess;

    //-------------------------------------------------------------------------
    /** An interface which allows manipulation of groups of filters
    */
    [optional] interface XFilterGroupManager;

    //-------------------------------------------------------------------------
    /** Provides the ability to choose between different custom templates that
        do extend the subset of common controls a FilePicker usually supports. 
        Implementers may omit this interface if the FileOpen
        dialog doesn't support custom templates. In this case a createInstance
        will create an ordinary FileOpen dialog with only the common FilePicker
        elements.
        The client has to provide one of the specified constants in 
        TemplateDescription.
        <br/><br/>	
        <p><strong>Notes for the implementation of a FileSave dialog:</strong>
        The implementation of a FileSave dialog should automatically check 
        for existens of a file and issue a warning if a file with the same 
        name already exist.</p>
        
        @see com::sun::star::ui::dialogs::TemplateDescription
    */
    [optional] interface com::sun::star::lang::XInitialization;

    //-------------------------------------------------------------------------
    /** For canceling a running dialog instance.
        <p>This may be usefull for automatic test tools for instance.</p>
    */
    [optional] interface com::sun::star::util::XCancellable;

    //-------------------------------------------------------------------------
    /** Use this interface to query for the controls and control
            properties supported.
        @see XControlAccess
    */
    [optional] interface com::sun::star::ui::dialogs::XControlInformation;
    
    //-------------------------------------------------------------------------
    /** Use this interface to query for or modify the properties of the 
            supported controls.

            <p>The concrete controls and properties supported depend on the implementation of the
            service, but <em>if</em> an implementation supports these interfaces, the following
            control and property names are mandatory.<br/>
            This does not mean that all these controls and properties <em>have</em> to be supported,
            but if they can be accessed using <type>XControlAccess</type>, then they must be named
            as follows:</p>

            <table border="1" cellspacing="0">
            <tr valign="top"><td><b>Control name</b></td><td><b>Description</b></td></tr>

            <tr valign="top"><td>AutoExtensionBox</td>
                <td>a check box control which is used to allow for automatic file name extensions.
                    @see TemplateDescription::FILESAVE_AUTOEXTENSION_SELECTION
            </td></tr>

            <tr valign="top"><td>CancelButton</td>
                <td>a button which is used to close the dialog without any action.
            </td></tr>

            <tr valign="top"><td>CurrentFolderText</td>
                <td>a fixed text control which is used to display the current location.
            </td></tr>

            <tr valign="top"><td>DefaultLocationButton</td>
                <td>a button which is used to go to some default directory.
            </td></tr>

            <tr valign="top"><td>FileURLEdit</td>
                <td>the edit field which is used to enter a file name.
            </td></tr>

            <tr valign="top"><td>FileURLEditLabel</td>
                <td>the label of the <em>FileURLEdit</em> control.
            </td></tr>

            <tr valign="top"><td>FileView</td>
                <td>the file view control.
            </td></tr>

            <tr valign="top"><td>FilterList</td>
                <td>the list box which contains the possible filters.
                    @see XFilterManager
            </td></tr>

            <tr valign="top"><td>FilterListLabel</td>
                <td>the label of the <em>FilterList</em> control
            </td></tr>

            <tr valign="top"><td>FilterOptionsBox</td>
                <td>a check box control which is used to allow for additional filter settings
                    @see TemplateDescription::FILESAVE_AUTOEXTENSION_PASSWORD_FILTEROPTIONS 
            </td></tr>

            <tr valign="top"><td>HelpButton</td>
                <td>a button which is used to request help for the dialog.
            </td></tr>

            <tr valign="top"><td>ImageTemplateList</td>
                <td>a list box control which is used to select an image template.
                    @see TemplateDescription::FILESAVE_AUTOEXTENSION_TEMPLATE
            </td></tr>

            <tr valign="top"><td>ImageTemplateListLabel</td>
                <td>the label of the ImageTemplateList control
            </td></tr>

            <tr valign="top"><td>LevelUpButton</td>
                <td>a button which is used to travel to the parent directory
            </td></tr>

            <tr valign="top"><td>LinkBox</td>
                <td>a check box control which is used to determine if a graphics should be linked.
                    @see TemplateDescription::FILEOPEN_LINK_PREVIEW
            </td></tr>

            <tr valign="top"><td>NewFolderButton</td>
                <td>a button which is used to create a new folder in the current location
            </td></tr>

            <tr valign="top"><td>OkButton</td>
                <td>a button which is used to close the dialog, doing the action it was opened for. Depending
                    on the type of the dialog, this may be for instance a Save or a Open button.
                    @see TemplateDescription
            </td></tr>

            <tr valign="top"><td>PasswordBox</td>
                <td>a check box control which is used to allow for password encryption of saved files
                    @see TemplateDescription
            </td></tr>

            <tr valign="top"><td>PlayButton</td>
                <td>a button which is used to play a sound
                    @see TemplateDescription::FILEOPEN_PLAY
            </td></tr>

            <tr valign="top"><td>ReadOnlyBox</td>
                <td>a check box control which is used to determine if a file should be opened readonly
                    @see TemplateDescription::FILEOPEN_READONLY_VERSION
            </td></tr>

            <tr valign="top"><td>SelectionBox</td>
                <td>a check box control which is used to allow for saving a selection only
                    @see TemplateDescription::FILESAVE_AUTOEXTENSION_SELECTION
            </td></tr>

            <tr valign="top"><td>TemplateList</td>
                <td>a list box control which contains a list of templates or styles.
                    @see TemplateDescription::FILESAVE_AUTOEXTENSION_TEMPLATE
            </td></tr>

            <tr valign="top"><td>TemplateListLabel</td>
                <td>the label for the <em>TemplateList</em> control
            </td></tr>

            <tr valign="top"><td>VersionList</td>
                <td>a list box control which contains a list of versions supported by the selected filter.
                    @see TemplateDescription::FILEOPEN_READONLY_VERSION
            </td></tr>

            <tr valign="top"><td>VersionListLabel</td>
                <td>the label for the <em>VersionList</em> control
            </td></tr>

            </table>

            <br/>

            <table border="1" cellspacing="0">
            <tr valign="top"><td><b>Property name</b></td><td><b>Description</b></td><td><b>Type</b></td></tr>

            <tr valign="top"><td>Text</td>
                <td>the currently displayed text of a control</td>
                <td>String</td>
            </tr>

            <tr valign="top"><td>Enabled</td>
                <td>a flag indicating if the control is enabled</td>
                <td>Boolean</td>
            </tr>

            <tr valign="top"><td>ListItems</td>
                <td>a sequence of strings, making up the content of a list box control.</td>
                <td>String()</td>
            </tr>

            <tr valign="top"><td>Visible</td>
                <td>a flag indicating if the control is visible</td>
                <td>Boolean</td>
            </tr>

            <tr valign="top"><td>HelpURL</td>
                <td>a string indicating the help URL associated with the control</td>
                <td>String</td>
            </tr>

            <tr valign="top"><td>SelectedItem</td>
                <td>a string indicating the currently selected item</td>
                <td>String</td>
            </tr>

            <tr valign="top"><td>SelectedItemIndex</td>
                <td>the index of the currently selected item</td>
                <td>Long</td>
            </tr>

            <tr valign="top"><td>Checked</td>
                <td>a flag indicating if a check box control is currently checked</td>
                <td>Boolean</td>
            </tr>

            </table>

    */
    [optional] interface com::sun::star::ui::dialogs::XControlAccess;
    
    //-------------------------------------------------------------------------
    /** For shutdown and listener support.
    */
    interface com::sun::star::lang::XComponent;

    //-------------------------------------------------------------------------
    /** Service should always support this interface.
    */
    interface com::sun::star::lang::XServiceInfo;

    //-------------------------------------------------------------------------
    /** Service should always support this interface.
    */
    interface com::sun::star::lang::XTypeProvider;
};

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

}; }; }; }; };

#endif