/*************************************************************************
 *
 *  $RCSfile: DataSourceBrowser.idl,v $
 *
 *  $Revision: 1.10 $
 *
 *  last change: $Author: hr $ $Date: 2003-04-04 17:54:51 $
 *
 *  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 EXPRESS 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_sdb_DataSourceBrowser_idl__
#define __com_sun_star_sdb_DataSourceBrowser_idl__

#ifndef __com_sun_star_frame_XController_idl__
#include <com/sun/star/frame/XController.idl>
#endif
#ifndef __com_sun_star_lang_XInitialization_idl__
#include <com/sun/star/lang/XInitialization.idl>
#endif
#ifndef __com_sun_star_frame_XDispatchProvider_idl__
#include <com/sun/star/frame/XDispatchProvider.idl>
#endif
#ifndef __com_sun_star_form_FormController_idl__
#include <com/sun/star/form/FormController.idl>
#endif

module com {  module sun {  module star {  module sdb {

//=============================================================================
/** implements a component which allows browsing the data sources registered on the system.

    <p>
    This service implements a user interface for browsing data sources registered on the
    <service scope="com::sun::star::sdb">
    DatabaseContext
    </service>
    instance of the system.
    </p>

    <p>
    It is possible to navigate through all the data sources, it's queries and it's tables.
    The queries/tables can be displayed in a grid-like view, where functionality for searching,
    sorting, filtering, and such is provided.
    </p>

    <p>
    Usually, you won't instantiate this service directly, instead you use the dispatch mechanisms
    of the application framework to load the URL <b>.component:DB/DataSourceBrowser</b> into an arbitrary
    frame. This should involve a
    <service scope="com::sun::star::sdb">
    ContentLoader
    </service>
    service, which creates and initializes
    the browser.
    </p>

    <p>
    Some aspects of the browser can be controlled from outside, eg.,
    it is possible to dispatch a sort or filter
    request, if a table or query is being displayed.
    </p>

    <p
    >The communication between the browser and external instances works in two ways.
    <br/>
    The way <em>in</em> is provided by the
    <type scope="com::sun::star::frame">XDispatchProvider</type>
    interface the service exports (Please see below for more details on this).
    <br/>
    The way <em>out</em> works in another way. There are several URL's which an external
    instance can provide dispatches for (usually by implementing a
    <type scope="com::sun::star::frame">XDispatchProviderInterceptor</type>
    for the parent frame of the browser), thus indicating that the browser should provide special functionality.
    <br/>
    In this case, the browser displays and maintains some additional slots (to be more concrete: toolbox items), which,
    upon triggering, call the
    <member scope="com::sun::star::frame">XDispatch::dispatch()</member>methodoftheobject
    provided by the external instance.
    </p>

    <p>
        In particular, the supported URL's for communicating to an external instance are:
        <ul>
            <li><b>.uno:DataSourceBrowser/InsertColumns</b>
            <br/>
            Available whenever an external instance provides a dispatcher (
            <type scope="com::sun::star::frame">XDispatch</type>)
            for this URL.
            <br/>
            Enabled, if at least one row in the grid view of a table or query is selected.
            <br/>
            It is the task of the external instance to provide functionality for this URL, but usually it is used
            to implement some kind of "Data To Text" functionality.
            <br/>
            </li>
            <li><b>.uno:DataSourceBrowser/InsertContent</b>
            <br/>
            Available whenever an external instance provides a dispatcher(
            <type scope="com::sun::star::frame">XDispatch</type>
            ) for this URL.
            <br/>
            Enabled, if at least one row in the grid view of a table or query is selected.
            <br/>
            It is the task of the external instance to provide functionality for this URL, but usually it is used
            to implement some kind of "Data To Fields" functionality.
            <br/>
            </li>
            <li><b>.uno:DataSourceBrowser/FormLetter</b>
            <br/>
            Available whenever an external instance provides a dispatcher (
            <type scope="com::sun::star::frame">XDispatch</type>)forthisURL.
            <br/>
            It is the task of the external instance to provide functionality for this URL, but usually it is used
            to implement some kind of "Form Letter" functionality.
            <br/>
            </li>
        </ul>
    </p>
    <p>For all kinds of URL's, the parameters supplied during dispatching build up a <type>DataAccessDescriptor</type>,
    where the following properties are present:
    <ul>
        <li><member>DataAccessDescriptor::DataSourceName</member></li>
        <li><member>DataAccessDescriptor::Command</member></li>
        <li><member>DataAccessDescriptor::CommandType</member></li>
        <li><em>optional</em> <member>DataAccessDescriptor::Selection</member></li>
        <li><em>optional</em> <member>DataAccessDescriptor::BookmarkSelection</member></li>
        <li><em>optional</em> <member>DataAccessDescriptor::ResultSet</member></li>
    </ul>
    </p>
    <p>The default for <member>DataAccessDescriptor::Selection</member> is to contain bookmarks, if not specifies
    otherwise by <member>DataAccessDescriptor::BookmarkSelection</member>.</pr>
    </p>

    @see com::sun::star::sdb::ContentLoader
    @see com::sun::star::sdb::DatabaseContext
    @see com::sun::star::sdb::DataSource
    @see com::sun::star::frame::XDispatch
    @see com::sun::star::frame::XDispatchProvider
    @see com::sun::star::frame::XDispatchProviderInterceptor
*/
service DataSourceBrowser
{
    /** implements basic form controller functionality.
        <p>
        With a data source browser implementing this interface, external components have access to
        <ul><li>the grid control which is used to display the currently selected table/query
            (see
            <method scope="com.sun.star.form">XFormController::getControls()</method>
            )
            </li>
            <li>the data form used for displaying objects. As always for components implementing this service,
            the object returned by
            <method scope="com.sun.star.awt">XTabController::getModel()</method>isadataform.
            </li>
        </ul>
        </p>
    */
    [optional] service com::sun::star::form::FormController;

    /** allows the component to be plugged into frames.
    */
    interface com::sun::star::frame::XController;

    /** is used to initialize the browser.

        <p>
        Parameters (passed to the method
        <member scope="com::sun::star::lang">XInitialization::initialize()</member>
        )
        have to be instances of
        <type scope="com::sun::star::beans">PropertyValue</type>
        , where the
        <member scope="com::sun::star::beans">PropertyValue::Name</member>
        member specifies what the parameter controls,
        with the
        <member scope="com::sun::star::beans">PropertyValue::Value</member>
        member containing the value
        to be used.
        <br/>
        Recognized parameters are:
        <ul>
            <li><b>Frame</b>
            <br/>
            has to be an
            <type scope="com::sun::star::frame">XFrame</type>
            interface specifying the frame to plug the
            browser component into.
            </li>
            <li><b>DataSourceName</b>
            <br/>
            The name of the globally registered
            <service>
            DataSource
            </service>
            to be used for initial display. It is only
            meaningful together with the other parameters specifying the object to display.
            </li>
            <li><b>CommandType</b>
            <br/>
            This has to be a
            <type>
            CommandType
            </type>
            value, specifying the type of the object to display initially.
            It is only meaningful together with the <em>DataSourceName</em> and the <em>Command</em> parameters.
            </li>
            <li><b>Command</b>
            <br/>
            This is a string giving the name of the object to display initially. Whether it is table name, a query
            name or a SQL string is controller by the <em>CommandType</em> parameter.
            </li>
        </ul>
        </p>
    */
    interface com::sun::star::lang::XInitialization;

    /** is used to control the browser from outside.

    <p>
    You may use the
    <member scope="com::sun::star::frame">XDispatchProvider::queryDispatch</member>
    method
    to query for objects which implement the
    <type scope="com::sun::star::frame">XDispatch</type>
    interface,
    and which allow you to be notified on status changes and to dispatch special requests.
    </p>
    <p>
    The recognized URLs are:
        <ul>
            <li><b>.uno:Copy</b>
            <br/>
            implements the usual <em>Copy</em> command. Enabled if the grid view has the focus and text in any cell
            is selected.
            </li>
            <li><b>.uno:Cut</b>
            <br/>
            implements the usual <em>Cut</em> command. Enabled if the grid view has the focus and text in any cell
            is selected.
            </li>
            <li><b>.uno:Paste</b>
            <br/>
            implements the usual <em>Paste</em> command. Enabled if the grid view has the focus and a cell which
            allows text input is being edited.
            </li>
            <li><b>.uno:EditDoc</b>
            <br/>
            allows switching the edit mode of the grid view. Enabled if editing the data is allowed in general.
            </li>
            <li><b>.uno:Undo</b>
            <br/>
            revokes any changes done in the current row.
            </li>
            <li><b>.uno:Save</b><br/>
            saves the changes done in the current row.
            </li>
        </ul>
    </p>
    */
    interface com::sun::star::frame::XDispatchProvider;
};

//=============================================================================
}; }; }; };

#endif