/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0 .
 */


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
    com::sun::star::sdb::DatabaseContext
    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
    com::sun::star::sdb::ContentLoader
    service, which creates and initializes
    the browser.
    </p>

    <p>
    Some aspects of the browser can be controlled from outside, e.g.,
    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
    com::sun::star::frame::XDispatchProvider
    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 URLs which an external
    instance can provide dispatches for (usually by implementing a
    com::sun::star::frame::XDispatchProviderInterceptor
    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
    com::sun::star::frame::XDispatch::dispatch() method of the object
    provided by the external instance.
    </p>

    <p>
        In particular, the supported URLs for communicating to an external instance are:
        <ul>
            <li><b>.uno:DataSourceBrowser/InsertColumns</b>
            <br/>
            Available whenever an external instance provides a dispatcher (
            com::sun::star::frame::XDispatch)
            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(
            com::sun::star::frame::XDispatch
            ) 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 (
            com::sun::star::frame::XDispatch) for this URL.
            <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 URLs, the parameters supplied during dispatching build up a DataAccessDescriptor,
    where the following properties are present:
    <ul>
        <li>DataAccessDescriptor::DataSourceName</li>
        <li>DataAccessDescriptor::Command</li>
        <li>DataAccessDescriptor::CommandType</li>
        <li><em>optional</em> DataAccessDescriptor::Selection</li>
        <li><em>optional</em> DataAccessDescriptor::BookmarkSelection</li>
        <li><em>optional</em> DataAccessDescriptor::ResultSet</li>
    </ul>
    </p>
    <p>The default for DataAccessDescriptor::Selection is to contain bookmarks, if not specified
    otherwise by DataAccessDescriptor::BookmarkSelection.
    </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
*/
published 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 com::sun::star::awt::XTabController::getControls())
            </li>
            <li>the data form used for displaying objects. As always for components implementing this service,
            the object returned by
            com::sun::star::awt::XTabController::getModel() is a dataform.
            </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 com::sun::star::lang::XInitialization::initialize())
        have to be instances of com::sun::star::beans::PropertyValue, or
        instances of com::sun::star::beans::NamedValue, where the <code>Name</code> member
        specifies what the parameter controls, with the <code>Value</code> member containing the value to be used.
        <br/>
        Recognized parameters are:
        <ul>
            <li><b>Frame</b><br/>
            has to be an  com::sun::star::frame::XFrame interface specifying the frame to
            plug the browser component into.</li>

            <li><b>DataSourceName</b><br/>
            The name of the globally registered DataSource 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 CommandType 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>

            <li><b>EnableBrowser</b><br/>
            is a boolean value (defaulting to `TRUE`), which specifies whether to enable the data source browser
            control. This is a tree control on the left hand side of the view, which allows to browse all registered
            data sources, including their tables and queries.</li>

            <li><b>ShowBrowser</b><br/>
            is a boolean value (defaulting to `TRUE`), which specifies whether to initially show the data source
            browser control. If <code>EnableBrowser</code> is `FALSE`, then this parameter is ignored. If
            <code>EnableBrowser</code> is `TRUE`, and <code>ShowBrowser</code> is `FALSE`, then the control
            is initially hidden, but can be toggled by a toolbar button.</p>

            <li><b>ShowMenu</b><br/>
            is a boolean value (defaulting to `TRUE`), specifying whether or not to show a menu in the frame
            where the component is plugged.</li>
        </ul>
        </p>
    */
    interface com::sun::star::lang::XInitialization;

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

    <p>
    You may use the
    com::sun::star::frame::XDispatchProvider::queryDispatch()
    method
    to query for objects which implement the
    com::sun::star::frame::XDispatch
    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;

    /** allows to intercept user-triggered context menus in the data source browser

        <p>Context menu interception is currently supported only for the browser control where the registered
        data sources and all their tables and queries are displayed in a tree view.</p>

        <p>The selection supplied by com::sun::star::ui::ContextMenuExecuteEvent::Selection,
        in the event structure passed to the context menu interceptors, actually is a value from the
        com::sun::star::sdb::application::NamedDatabaseObject group.</p>

        @since OOo 3.0
    */
    [optional] interface ::com::sun::star::ui::XContextMenuInterception;
};

}; }; }; };

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */