Language:

The Free and Open Productivity Suite
Apache OpenOffice 4.1.4 released

Developer's Guide

API

SDK

Tips 'n' Tricks

Miscellaneous


:: com :: sun :: star :: sdb ::

service DataSourceBrowser
Description
implements a component which allows browsing the data sources registered on the system.

This service implements a user interface for browsing data sources registered on the DatabaseContext instance of the system.

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.

Usually, you won't instantiate this service directly, instead you use the dispatch mechanisms of the application framework to load the URL .component:DB/DataSourceBrowser into an arbitrary frame. This should involve a ContentLoader service, which creates and initializes the browser.

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.

The communication between the browser and external instances works in two ways.
The way in is provided by the ::com::sun::star::frame::XDispatchProvider interface the service exports (Please see below for more details on this).
The way out works in another way. There are several URL's 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.
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()methodoftheobject provided by the external instance.

In particular, the supported URL's for communicating to an external instance are:

  • .uno:DataSourceBrowser/InsertColumns
    Available whenever an external instance provides a dispatcher ( ::com::sun::star::frame::XDispatch) for this URL.
    Enabled, if at least one row in the grid view of a table or query is selected.
    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.
  • .uno:DataSourceBrowser/InsertContent
    Available whenever an external instance provides a dispatcher( ::com::sun::star::frame::XDispatch ) for this URL.
    Enabled, if at least one row in the grid view of a table or query is selected.
    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.
  • .uno:DataSourceBrowser/FormLetter
    Available whenever an external instance provides a dispatcher ( ::com::sun::star::frame::XDispatch)forthisURL.
    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.

For all kinds of URL's, the parameters supplied during dispatching build up a DataAccessDescriptor, where the following properties are present:

The default for DataAccessDescriptor::Selection is to contain bookmarks, if not specified otherwise by DataAccessDescriptor::BookmarkSelection.

See also
ContentLoader, DatabaseContext, DataSource, ::com::sun::star::frame::XDispatch, ::com::sun::star::frame::XDispatchProvider, ::com::sun::star::frame::XDispatchProviderInterceptor
Developers Guide
OfficeDev - Component - Controllers - Document Specific Controller Services

Included Services - Summary
::com::sun::star::form::FormController

implements basic form controller functionality. (details)

Exported Interfaces - Summary
::com::sun::star::frame::XController

allows the component to be plugged into frames.

::com::sun::star::lang::XInitialization

is used to initialize the browser. (details)

::com::sun::star::frame::XDispatchProvider

is used to control the browser from outside. (details)

::com::sun::star::ui::XContextMenuInterception

allows to intercept user-triggered context menus in the data source browser (details)

Included Services - Details
::com::sun::star::form::FormController
Usage Restrictions
optional
Description
implements basic form controller functionality.

With a data source browser implementing this interface, external components have access to

  • the grid control which is used to display the currently selected table/query (see XTabController::getControls)
  • the data form used for displaying objects. As always for components implementing this service, the object returned by XTabController::getModelis a dataform.

Exported Interfaces - Details
::com::sun::star::frame::XController
Description
allows the component to be plugged into frames.
::com::sun::star::lang::XInitialization
Description
is used to initialize the browser.

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 Name member specifies what the parameter controls, with the Value member containing the value to be used.
Recognized parameters are:

  • Frame
    has to be an ::com::sun::star::frame::XFrame interface specifying the frame to plug the browser component into.
  • DataSourceName
    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.
  • CommandType
    This has to be a CommandType value, specifying the type of the object to display initially. It is only meaningful together with the DataSourceName and the Command parameters.
  • Command
    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 CommandType parameter.
  • EnableBrowser
    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.
  • ShowBrowser
    is a boolean value (defaulting to true), which specifies whether to initially show the data source browser control. If EnableBrowser is false, then this parameter is ignored. If EnableBrowser is true, and ShowBrowser is false, then the control is initially hidden, but can be toggled by a toolbar button.

  • ShowMenu
    is a boolean value (defaulting to true), specifying whether or not to show a menu in the frame where the component is plugged.

::com::sun::star::frame::XDispatchProvider
Description
is used to control the browser from outside.

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.

The recognized URLs are:

  • .uno:Copy
    implements the usual Copy command. Enabled if the grid view has the focus and text in any cell is selected.
  • .uno:Cut
    implements the usual Cut command. Enabled if the grid view has the focus and text in any cell is selected.
  • .uno:Paste
    implements the usual Paste command. Enabled if the grid view has the focus and a cell which allows text input is being edited.
  • .uno:EditDoc
    allows switching the edit mode of the grid view. Enabled if editing the data is allowed in general.
  • .uno:Undo
    revokes any changes done in the current row.
  • .uno:Save
    saves the changes done in the current row.

::com::sun::star::ui::XContextMenuInterception
Usage Restrictions
optional
Description
allows to intercept user-triggered context menus in the data source browser

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.

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.

Since
OOo 3.0

 
Top of Page

Apache Software Foundation

Copyright & License | Privacy | Contact Us | Donate | Thanks

Apache and the Apache feather logo are trademarks of The Apache Software Foundation. OpenOffice, OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.