/*************************************************************************
 *
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 * 
 * Copyright 2000, 2010 Oracle and/or its affiliates.
 *
 * OpenOffice.org - a multi-platform office productivity suite
 *
 * This file is part of OpenOffice.org.
 *
 * OpenOffice.org is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License version 3
 * only, as published by the Free Software Foundation.
 *
 * OpenOffice.org 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 version 3 for more details
 * (a copy is included in the LICENSE file that accompanied this code).
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 3 along with OpenOffice.org.  If not, see
 * <http://www.openoffice.org/license.html>
 * for a copy of the LGPLv3 License.
 *
 ************************************************************************/


#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
#ifndef __com_sun_star_ui_XContextMenuInterception_idl__
#include <com/sun/star/ui/XContextMenuInterception.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
	<type scope="com::sun::star::sdb">
	DatabaseContext
	</type> 
	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 
	<type scope="com::sun::star::sdb">
	ContentLoader
	</type> 
	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 specified
	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
*/
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 <method scope="com::sun::star::awt">XTabController::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>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 <member scope="com::sun::star::lang">XInitialization::initialize()</member>)
		have to be instances of <type scope="com::sun::star::beans">PropertyValue</type>, or
        instances of <type scope="com::sun::star::beans">NamedValue</type>, 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  <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 <type>DataSource</type> 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>

            <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 
	<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;

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

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

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

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