diff options
author | Frank Schönheit <frank.schoenheit@sun.com> | 2009-10-23 09:46:03 +0200 |
---|---|---|
committer | Frank Schönheit <frank.schoenheit@sun.com> | 2009-10-23 09:46:03 +0200 |
commit | c81e99461e33626ff0ae997379041757231342fa (patch) | |
tree | e998bc39b729b5d67a9e91a2054b3a863d8792c7 /offapi/com/sun/star | |
parent | 6107d76a57d3d5f5e0303d049558eb613ed33ae5 (diff) |
step 0 of an UNOization of the css.form.(X)FormController implementation: move the API to css.form.runtime, so we can later add new API chunks without breaking compatibility of the existing API in css.form
Diffstat (limited to 'offapi/com/sun/star')
-rw-r--r-- | offapi/com/sun/star/form/FormController.idl | 105 | ||||
-rw-r--r-- | offapi/com/sun/star/form/FormControllerDispatcher.idl | 170 | ||||
-rw-r--r-- | offapi/com/sun/star/form/XFormController.idl | 53 | ||||
-rw-r--r-- | offapi/com/sun/star/form/runtime/FormController.idl | 51 | ||||
-rw-r--r-- | offapi/com/sun/star/form/runtime/FormOperations.idl | 4 | ||||
-rw-r--r-- | offapi/com/sun/star/form/runtime/XFormController.idl | 342 | ||||
-rw-r--r-- | offapi/com/sun/star/form/runtime/XFormOperations.idl | 6 | ||||
-rw-r--r-- | offapi/com/sun/star/form/runtime/makefile.mk | 2 | ||||
-rw-r--r-- | offapi/com/sun/star/sdb/DataSourceBrowser.idl | 6 | ||||
-rw-r--r-- | offapi/com/sun/star/view/XFormLayerAccess.idl | 8 |
10 files changed, 416 insertions, 331 deletions
diff --git a/offapi/com/sun/star/form/FormController.idl b/offapi/com/sun/star/form/FormController.idl index 03e4bffc2074..4bd94946f1c1 100644 --- a/offapi/com/sun/star/form/FormController.idl +++ b/offapi/com/sun/star/form/FormController.idl @@ -84,127 +84,26 @@ module runtime { //============================================================================= -/** specifies a component controlling the interaction between the user and form functionality. - - <p>As soon as a form (containing controls) is to be presented to the user, - there is a need for an instance controlling the user interaction.<br/> - Such a <type>FormController</type> is responsible for dialog processing, - like controlling the tab order and the grouping of controls.</p> - - <p>As a form may contain one or many subforms, a <type>FormController</type> may - contain one or more other <type>FormController</type>s, so the form model structure or hierarchy - is reflected in the structure of <type>FormController</type>s.</p> - - <h3>Responsibilities</h3> - <p>A <type>FormController</type> is responsible for a <type scope="com::sun::star::awt">UnoControlContainer</type>, - and all controls therein.</p> - - <p>Furthermore, a form controller is responsible for preventing invalid user input. That is, if the form - contains controls bound to a database, or to an external validator, then the form controller will - check their current value when the current record is to be saved to the database.</p> - - <p>First, it will check whether any controls with an external validator exist. If so, those validators - will be asked to validate the current control content. If this fails, the message provided by the validator - is displayed to the user, the control is focused, and the update of the record is vetoed.</p> - - <p>Second, the controls are examined for NULL values. If a control is bound to a database field which - is declared to be <code>NOT NULL</code>, no auto-increment field, but still <NULL/>, then an error - message is shown to the user saying that input is required, the respective control is focused, and - the update of the record is vetoed.</p> - - <p>Note that you can precent the second check - for database fields containing <NULL/> values - on - a per-form and a per-database basis.<br/> - For the former, you need to add a boolean property <code>FormsCheckRequiredFields</code> to the form - (aka the <code>FormController</code>'s model), using its - <member scope="com::sun::star::beans">XPropertyContainer::addProperty</member> method, with a value - of <FALSE/>.<br/> - For the latter, you need to set the respective property of the data source's <code>Settings</code> - (also named <code>FormsCheckRequiredFields</code>) to <FALSE/>.</p> - - <p>Alternatively, you can prevent the check on a per-control basis, using the - <member>DataAwareControlModel::InputRequired</member> property of a single control model.</p> - - @see com::sun::star::form::component:Form - @see com::sun::star::awt::XTabController - @see com::sun::star::form::binding::BindableControlModel - @see com::sun::star::sdb::DataSource::Settings +/** is superseded by <type scope="com::sun::star::form::runtime">FormController</type>. + @deprecated */ published service FormController { - /** allows delegating form controller functionality to the component - - <p>If a control which the controller is responsible for supports the <type scope="com::sun::star::frame">XDispatchProviderInterception</type> - interface, the controller registers a dispatch interceptor. Then, the control can try to delegate part of its - functionality to the controller by querying the dispatch interceptor for it.</p> - */ [optional] service FormControllerDispatcher; - - /** denotes the instance which is used to implement operations on the form which the controller - works for. - - <p>This instance can be used, for instance, to determine the current state of certain form features.</p> - */ [optional, property] ::com::sun::star::form::runtime::XFormOperations FormOperations; /** is used for notifying the (de)activation of the controller. */ interface com::sun::star::form::XFormController; - - /** is used for tab controlling and grouping of the controls. - */ interface com::sun::star::awt::XTabController; - - - /** A FormController may have a parent controller, such as when the related form is a subform. - */ interface com::sun::star::container::XChild; - - - /** A FormController must be disposable. - */ interface com::sun::star::lang::XComponent; - - - /** A FormController must provide access to its sub controllers. - */ interface com::sun::star::container::XEnumerationAccess; - - - /** A FormController must communicate if any of its children (means sub controllers) or contained - controls have been modified. - */ interface com::sun::star::util::XModifyBroadcaster; - - /** used to notify deletions of data in the form before they happen. - - <p>A form controller listens for deletion events at the form it is responsible for.<br/> - If and only if no <type>XConfirmDeleteListener</type> is registered at - the controller, it uses an own dialog to ask the user for confirmation.</p> - - <p>You may use this interface to integrate your own confirmation dialogs.</p> - */ interface com::sun::star::form::XConfirmDeleteBroadcaster; - - /** used to notify errors which happen in the form the controller is responsible for. - - <p>A form controller listens for error events at the form it is responsible for.<br/> - If and only if no <type scope="com::sun::star::sdb">XSQLErrorListener</type> is registered at the controller, it - uses an own dialog to notify the user of the error.</p> - - */ interface com::sun::star::sdb::XSQLErrorBroadcaster; - - /** is used for multiplexing row set events happening on the form which the controller is responsible for. - */ interface com::sun::star::sdb::XRowSetApproveBroadcaster; - - /** is used broadcasting parameter events in the form. - - <p>A form controller listens for parameter events at the form it is responsible for.<br/> - If and only if no <type>XDatabaseParameterListener</type> is registered at the controller, it - uses an own dialog to ask the user for parameter values.</p> - */ interface com::sun::star::form::XDatabaseParameterBroadcaster; }; diff --git a/offapi/com/sun/star/form/FormControllerDispatcher.idl b/offapi/com/sun/star/form/FormControllerDispatcher.idl index 96cab9ee73f1..8e2513b62102 100644 --- a/offapi/com/sun/star/form/FormControllerDispatcher.idl +++ b/offapi/com/sun/star/form/FormControllerDispatcher.idl @@ -40,177 +40,13 @@ module com { module sun { module star { module form { //============================================================================= -/** specifies a component which can be used to dispatch form controller functionality. +/** is not used anymore, and superseded by <type scope="com::sun::star::form::runtime">FormController</type> and + <type scope="com::sun::star::form::runtime">FormOperations</type>. - <p>A form controller dispatcher is an instance which provides access to dispatchers - (<type scope="com::sun::star::frame">XDispatch</type>) for certain form controller - functionality.</p> - - <p>The way how access to these dispatchers is provided is not defined. It may either - be directly via an <type scope="com::sun::star::frame">XDispatchProvider</type> interface, - or indirectly, e.g. by registering dispatch interceptors (<type scope="com::sun::star::frame">XDispatchProviderInterceptor</type>) - at another instance which supports this (by exposing the <type scope="com::sun::star::frame">XDispatchProviderInterception</type> - interface).</p> - - <p>In any scenario, foreign components have a (implicit or explicit) possibility to request a dispatcher - for a given URL.</p> - - <p>Below, there's a list of URLs which have a defined meaning - if a <type>FormControllerDispatcher</type> - implementation supports one of them, there must be a guaranteed semantices. However, concrete implementations - may support an arbitrary sub or super set of these URLs.</p> - - <p>In general, all URLs start with the same prefix, namely <em>.uno:FormController/</em>. To this, a suffix is - appended which describes the requested functionality.<br/> - Example: The URL suffix for deleting the current record is <em>deleteRecord</em>, so the complete URL for - requesting a dispatcher for this functionality is <em>.uno:FormController/deleteRecord</em>.</p> - - <p>Some URLs may require parameters. For this, the sequence of <type scope="com::sun::star::beans">PropertyValue</type>s - passed to the <member scope="com::sun::star::frame">XDispatch::dispatch</member> call is used - every property value is - used as one named parameter.</p> - - <p>For all URLs, interested parties can register as status listeners (<type scope="com::sun::star::frame">XStatusListener</type>) - at the dispatchers, and be notified whenever the functionality associated with the URL becomes enabled or - disabled.<br/> - For instance, the URL with the suffix <em>moveToFirst</em> is associated with moving the form to the first - record, and it will be disabled in case the form is already positioned on the first record.</p> - - <p>Nearly all of the functionality offered by a <type>FormControllerDispatcher</type> can also be - reached by other means. E.g., moving a form to its first record can be achieved by calling the - method <member scope="com::sun::star::sdbc">XResultSet::first</member> of the form.<br/> - However, the advantage of using a <type>FormControllerDispatcher</type> is that it's usually implemented - by a component which has additional knowledge about the form. For instance, in a document which - displays a form, there might be a control which contains uncommitted changes, plus a control - whose changes were already committed to the current record, but <em>not</em> to the database. Simply - calling <member scope="com::sun::star::sdbc">XResultSet::first</member> on the form would lose - both the content in the uncommitted control, and the changes in the current record.<br/> - An <type>FormControllerDispatcher</type> is expected to care for both of these.</p> - - <table style="width:100%;" border="0" cellpadding="2" cellspacing="2"><tbody> - - <tr style="vertical-align: top;"> - <td><b>URL suffix</b></td> - <td><b>functionality</b></td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>positionForm</em></td> - <td>positions the form on a record given by absolute number.<br/> - There's one parameter for this functionality, named <em>Position</em>, which must be a long - value specifying the absolute position to which the form should be moved</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>RecordCount</em></td> - <td>This is a passive functionality: It cannot be dispatched, instead, interested parties may - use the dispatcher to add as <type scope="com::sun::star::frame">XStatusListener</type>, and be - notified when the record count changes.<br/> - The status value which is being notified (<member scope="com::sun::star::frame">FeatureStateEvent::State</member>) - is a string which can be used to display the record count. In particular, if the record count is not yet known - (<member scope="com::sun::star::sdb">RowSet::IsRowCountFinal</member> is <FALSE/>), this is indicated in the - string, too.</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>moveToFirst</em></td> - <td>moves the form to the first record</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>moveToPrev</em></td> - <td>moves the form to the record preceding the current one</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>moveToNext</em></td> - <td>moves the form to the record after the current one</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>moveToLast</em></td> - <td>moves the form to the last record</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>moveToNew</em></td> - <td>moves the form to the virtual "insert row", where new records can be inserted</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>saveRecord</em></td> - <td>Commits any potentially pending changes in the current control, and saves the current record to - the database, or inserts a new record if the form is currently positioned on the virtual insertion row.</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>undoRecord</em></td> - <td>reverts the changes done to the current record. Basically, this means refreshing the - current row from the database, and updating all controls with the new content.</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>deleteRecord</em></td> - <td>deletes the current record, after asking the user for confirmation.</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>refreshForm</em></td> - <td>reloads the complete form. After this, the form is positioned on the first record</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>sortUp</em></td> - <td>Adds an order clause to the form, to sort it ascending by the field which the current control is bound to, - and then reloads the form.</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>sortDown</em></td> - <td>Adds an order clause to the form, to sort it descending by the field which the current control is bound to, - and then reloads the form.</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>sort</em></td> - <td>opens an dialog, which allows the user to manipulate the current sorting order of the form. If the dialog - is closed with OK, the form is reloaded after setting the new sorting order.</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>autoFilter</em></td> - <td>creates, from the current control, a filter for the form. This is, if the current control is bound to - the field, say, "customer", and contains the value "Furs, Inc.", then a filter "customer = 'Furs, Inc.'" - is created and set at the form. After this, the form is reloaded.</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>filter</em></td> - <td>opens an dialog, which allows the user to manipulate the current filter of the form. If the dialog - is closed with OK, the form is reloaded after setting the new filter.</td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>applyFilter</em></td> - <td><p>Toggles the <member scope="com::sun::star::sdb">RowSet::ApplyFilter</member> property - of the form.</p> - <p>Additionally, status listeners will be provided with the current (boolean) state of this property - in the <member scope="com::sun::star::frame">FeatureStateEvent::State</member> member of the event - notified by the dispatcher.</p></td> - </tr> - - <tr style="vertical-align: top;"> - <td><em>removeFilterOrder</em></td> - <td>completely removes any filter and sorting order from the form, and reloads it.</td> - </tr> - - </tbody></table> - - @see FormController + @deprecated */ published service FormControllerDispatcher { - //------------------------------------------------------------------------- - /** allows direct access to the dispatchers provided by the component. - */ [optional] interface com::sun::star::frame::XDispatchProvider; }; diff --git a/offapi/com/sun/star/form/XFormController.idl b/offapi/com/sun/star/form/XFormController.idl index 832ec077b264..e1ca56c0b276 100644 --- a/offapi/com/sun/star/form/XFormController.idl +++ b/offapi/com/sun/star/form/XFormController.idl @@ -49,57 +49,14 @@ //============================================================================= -/** provides functionality to control the activation of forms controls. - - <p>There is a duality of forms (<type scope="com::sun::star::form::component">DataForm</type>) - and form controllers. In a document view, for every loaded form there is a form controller which is - responsible for exactly the controls which's models are direct children of the form.<br/> - - In some sense, a form controller is the view representation of a form, like a <em>form control</em> is the - view representation of a <em>form control model</em>.<br/> - - This is also reflected in this interface: If you call - <method scope="com::sun::star::awt">XTabController::getModel</method> on a form controller, the form which - the controller is responsible for will be returned.<br/> - - As always in the model-view-paradigm, there is no way from a model to its controller, mostly, because for - <em>one</em> given form, there is one controller for <em>every</em> view of the document.</p> - - <p>A controller is called <em>active</em> if one of the controls it is responsible for has the focus, - else inactive. To be notified whenever this activation state of a given controller changes, you can - add listeners.</p> - - @see com::sun::star::form::component::Form +/** is superseded by <type scope="com::sun::star::form::runtime">XFormController</type>. + @deprecated */ published interface XFormController: com::sun::star::awt::XTabController { - //------------------------------------------------------------------------- - - /** access to the currently active control - - @returns - the currently active control, or <NULL/> if there is no such control - */ - com::sun::star::awt::XControl getCurrentControl(); - - //------------------------------------------------------------------------- - - /** adds the specified listener to receive notifications whenever the activation state of - the controller changes. - - @param l - the listener to add. - */ - [oneway] void addActivateListener( [in] com::sun::star::form::XFormControllerListener l ); - - //------------------------------------------------------------------------- - - /** removes the specified listener - - @param l - the listener to remove. - */ - [oneway] void removeActivateListener( [in] com::sun::star::form::XFormControllerListener l ); + ::com::sun::star::awt::XControl getCurrentControl(); + [oneway] void addActivateListener( [in] ::com::sun::star::form::XFormControllerListener l ); + [oneway] void removeActivateListener( [in] ::com::sun::star::form::XFormControllerListener l ); }; diff --git a/offapi/com/sun/star/form/runtime/FormController.idl b/offapi/com/sun/star/form/runtime/FormController.idl new file mode 100644 index 000000000000..17501ffa162c --- /dev/null +++ b/offapi/com/sun/star/form/runtime/FormController.idl @@ -0,0 +1,51 @@ +/************************************************************************* +* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. +* +* Copyright 2009 by Sun Microsystems, Inc. +* +* 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 __offapi_com_sun_star_form_runtime_FormController_idl__ +#define __offapi_com_sun_star_form_runtime_FormController_idl__ + +#include <com/sun/star/form/runtime/XFormController.idl> + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +//============================================================================= + +/** specifies a component controlling the interaction between the user and multiple + form controls belonging to a single form. + */ +service FormController +{ + interface XFormController; +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/form/runtime/FormOperations.idl b/offapi/com/sun/star/form/runtime/FormOperations.idl index c9390ac25918..984a09e0d7c4 100644 --- a/offapi/com/sun/star/form/runtime/FormOperations.idl +++ b/offapi/com/sun/star/form/runtime/FormOperations.idl @@ -34,8 +34,8 @@ #ifndef __com_sun_star_form_runtime_XFormOperations_idl__ #include <com/sun/star/form/runtime/XFormOperations.idl> #endif -#ifndef __com_sun_star_form_XFormController_idl__ -#include <com/sun/star/form/XFormController.idl> +#ifndef __com_sun_star_form_runtime_XFormController_idl__ +#include <com/sun/star/form/runtime/XFormController.idl> #endif #ifndef __com_sun_star_form_XForm_idl__ #include <com/sun/star/form/XForm.idl> diff --git a/offapi/com/sun/star/form/runtime/XFormController.idl b/offapi/com/sun/star/form/runtime/XFormController.idl new file mode 100644 index 000000000000..76081bc82fe2 --- /dev/null +++ b/offapi/com/sun/star/form/runtime/XFormController.idl @@ -0,0 +1,342 @@ +/************************************************************************* +* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. +* +* Copyright 2009 by Sun Microsystems, Inc. +* +* 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 __offapi_com_sun_star_form_runtime_XFormController_idl__ +#define __offapi_com_sun_star_form_runtime_XFormController_idl__ + +#include <com/sun/star/awt/XTabController.idl> +#include <com/sun/star/container/XChild.idl> +#include <com/sun/star/lang/XComponent.idl> +#include <com/sun/star/container/XIndexAccess.idl> +#include <com/sun/star/container/XEnumerationAccess.idl> +#include <com/sun/star/util/XModifyBroadcaster.idl> +#include <com/sun/star/util/XModeSelector.idl> +#include <com/sun/star/form/XConfirmDeleteBroadcaster.idl> +#include <com/sun/star/sdb/XSQLErrorBroadcaster.idl> +#include <com/sun/star/sdb/XRowSetApproveBroadcaster.idl> +#include <com/sun/star/form/XDatabaseParameterBroadcaster2.idl> +#include <com/sun/star/form/XFormControllerListener.idl> + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +interface XFormOperations; + +//============================================================================= + +/** specifies a component controlling the interaction between the user and form functionality. + + <p>As soon as a form (containing controls) is to be presented to the user, + there is a need for an instance controlling the user interaction.<br/> + Such a <code>FormController</code> is responsible for dialog processing, + like controlling the tab order and the grouping of controls.</p> + + <p>As a form may contain one or many subforms, a <type>FormController</type> may + contain one or more other <type>FormController</type>s, so the form model structure or hierarchy + is reflected in the structure of <type>FormController</type>s. That is, retrieving the parent of + the model of a controller will give you the same object as retrieving the model of the parent of + the controller. Similarly, retrieving the model of the <code>n</code><sup>th</sup> child of + a controller gives you the same object as retrieving the <code>n</code><sup>th</sup> child of + the model of the controller.</p> + + <p>A controller is called <em>active</em> if one of the controls it is responsible for has the focus, + else inactive. To be notified whenever this activation state of a given controller changes, you can + add listeners.</p> + + <p>This interface supersedes the <type scope="com::sun::star::form">FormController</type>.</p> + + <h3>Responsibilities</h3> + <p>A <type>FormController</type> is responsible for a <type scope="com::sun::star::awt">UnoControlContainer</type>, + and all controls therein.</p> + + <p>Furthermore, a form controller is responsible for preventing invalid user input. That is, if the form + contains controls bound to a database, or to an external validator, then the form controller will + check their current value when the current record is to be saved to the database.</p> + + <p>First, it will check whether any controls with an external validator exist. If so, those validators + will be asked to validate the current control content. If this fails, the message provided by the validator + is displayed to the user, the control is focused, and the update of the record is vetoed.</p> + + <p>Second, the controls are examined for NULL values. If a control is bound to a database field which + is declared to be <code>NOT NULL</code>, no auto-increment field, but still <NULL/>, then an error + message is shown to the user saying that input is required, the respective control is focused, and + the update of the record is vetoed.</p> + + <p>Note that you can precent the second check - for database fields containing <NULL/> values - on + a per-form and a per-database basis.<br/> + For the former, you need to add a boolean property <code>FormsCheckRequiredFields</code> to the form + (aka the <code>FormController</code>'s model), using its + <member scope="com::sun::star::beans">XPropertyContainer::addProperty</member> method, with a value + of <FALSE/>.<br/> + For the latter, you need to set the respective property of the data source's <code>Settings</code> + (also named <code>FormsCheckRequiredFields</code>) to <FALSE/>.</p> + + <p>Alternatively, you can prevent the check on a per-control basis, using the + <member>DataAwareControlModel::InputRequired</member> property of a single control model.</p> + + <p>If a control which the controller is responsible for supports the <type scope="com::sun::star::frame">XDispatchProviderInterception</type> + interface, the controller registers a dispatch interceptor. Then, the control can try to delegate part of its + functionality to the controller by querying the dispatch interceptor for it.</p> + + <p>Below, there's a list of URLs which have a defined meaning - if an implementation supports one of them, + there must be a guaranteed semantices. However, concrete implementations may support an arbitrary sub or super + set of these URLs.</p> + + <p>In general, all URLs start with the same prefix, namely <em>.uno:FormController/</em>. To this, a suffix is + appended which describes the requested functionality.<br/> + Example: The URL suffix for deleting the current record is <em>deleteRecord</em>, so the complete URL for + requesting a dispatcher for this functionality is <em>.uno:FormController/deleteRecord</em>.</p> + + <p>Some URLs may require parameters. For this, the sequence of <type scope="com::sun::star::beans">PropertyValue</type>s + passed to the <member scope="com::sun::star::frame">XDispatch::dispatch</member> call is used - every property value is + used as one named parameter.</p> + + <p>For all URLs, interested parties can register as status listeners (<type scope="com::sun::star::frame">XStatusListener</type>) + at the dispatchers, and be notified whenever the functionality associated with the URL becomes enabled or + disabled.<br/> + For instance, the URL with the suffix <em>moveToFirst</em> is associated with moving the form to the first + record, and it will be disabled in case the form is already positioned on the first record.</p> + + <table style="width:100%;" border="0" cellpadding="2" cellspacing="2"><tbody> + + <tr style="vertical-align: top;"> + <td><b>URL suffix</b></td> + <td><b>functionality</b></td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>positionForm</em></td> + <td>positions the form on a record given by absolute number.<br/> + There's one parameter for this functionality, named <em>Position</em>, which must be a long + value specifying the absolute position to which the form should be moved</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>RecordCount</em></td> + <td>This is a passive functionality: It cannot be dispatched, instead, interested parties may + use the dispatcher to add as <type scope="com::sun::star::frame">XStatusListener</type>, and be + notified when the record count changes.<br/> + The status value which is being notified (<member scope="com::sun::star::frame">FeatureStateEvent::State</member>) + is a string which can be used to display the record count. In particular, if the record count is not yet known + (<member scope="com::sun::star::sdb">RowSet::IsRowCountFinal</member> is <FALSE/>), this is indicated in the + string, too.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>moveToFirst</em></td> + <td>moves the form to the first record</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>moveToPrev</em></td> + <td>moves the form to the record preceding the current one</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>moveToNext</em></td> + <td>moves the form to the record after the current one</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>moveToLast</em></td> + <td>moves the form to the last record</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>moveToNew</em></td> + <td>moves the form to the virtual "insert row", where new records can be inserted</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>saveRecord</em></td> + <td>Commits any potentially pending changes in the current control, and saves the current record to + the database, or inserts a new record if the form is currently positioned on the virtual insertion row.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>undoRecord</em></td> + <td>reverts the changes done to the current record. Basically, this means refreshing the + current row from the database, and updating all controls with the new content.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>deleteRecord</em></td> + <td>deletes the current record, after asking the user for confirmation.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>refreshForm</em></td> + <td>reloads the complete form. After this, the form is positioned on the first record</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>sortUp</em></td> + <td>Adds an order clause to the form, to sort it ascending by the field which the current control is bound to, + and then reloads the form.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>sortDown</em></td> + <td>Adds an order clause to the form, to sort it descending by the field which the current control is bound to, + and then reloads the form.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>sort</em></td> + <td>opens an dialog, which allows the user to manipulate the current sorting order of the form. If the dialog + is closed with OK, the form is reloaded after setting the new sorting order.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>autoFilter</em></td> + <td>creates, from the current control, a filter for the form. This is, if the current control is bound to + the field, say, "customer", and contains the value "Furs, Inc.", then a filter "customer = 'Furs, Inc.'" + is created and set at the form. After this, the form is reloaded.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>filter</em></td> + <td>opens an dialog, which allows the user to manipulate the current filter of the form. If the dialog + is closed with OK, the form is reloaded after setting the new filter.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>applyFilter</em></td> + <td><p>Toggles the <member scope="com::sun::star::sdb">RowSet::ApplyFilter</member> property + of the form.</p> + <p>Additionally, status listeners will be provided with the current (boolean) state of this property + in the <member scope="com::sun::star::frame">FeatureStateEvent::State</member> member of the event + notified by the dispatcher.</p></td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>removeFilterOrder</em></td> + <td>completely removes any filter and sorting order from the form, and reloads it.</td> + </tr> + + </tbody></table> + + @see ::com::sun::star::form::component:Form + @see ::com::sun::star::form::binding::BindableControlModel + @see ::com::sun::star::sdb::DataSource::Settings + */ +interface XFormController +{ + /** is used for tab controlling and grouping of the controls. + + <p>The model obtained via <member scope="com::sun::star::awt">XTabController::getModel</member> is the form for which the + controller is responsible.</p> + */ + interface ::com::sun::star::awt::XTabController; + + /** allows access to the parent controller. + */ + interface ::com::sun::star::container::XChild; + + /** allows access to the sub controllers. + */ + interface ::com::sun::star::container::XIndexAccess; + + /** allows enumerating sub controllers + */ + interface ::com::sun::star::container::XEnumerationAccess; + + /** allows life time control of the controller. + */ + interface ::com::sun::star::lang::XComponent; + + /** allows to register as listener for modifications in the controls which the controller is responsible + for. + */ + interface ::com::sun::star::util::XModifyBroadcaster; + + /** used to notify deletions of data in the form before they happen. + + <p>A form controller listens for deletion events at the form it is responsible for. If and only if no + <type scope="com::sun::star::form">XConfirmDeleteListener</type> is registered at + the controller, it uses an own dialog to ask the user for confirmation.</p> + */ + interface ::com::sun::star::form::XConfirmDeleteBroadcaster; + + /** is used to notify errors which happen in the form the controller is responsible for. + + <p>A form controller listens for error events at the form it is responsible for. If and only if no + <type scope="com::sun::star::sdb">XSQLErrorListener</type> is registered at the controller, it + uses an own dialog to notify the user of the error.</p> + + */ + interface ::com::sun::star::sdb::XSQLErrorBroadcaster; + + /** is used for multiplexing row set events happening on the form which the controller is responsible for. + */ + interface ::com::sun::star::sdb::XRowSetApproveBroadcaster; + + /** is used broadcasting parameter events in the form. + + <p>A form controller listens for parameter events at the form it is responsible for. If and only if no + <type scope="com::sun::star::form">XDatabaseParameterListener</type> is registered at the controller, it + uses an own dialog to ask the user for parameter values.</p> + */ + interface ::com::sun::star::form::XDatabaseParameterBroadcaster2; + + /** allows switching the form controller to different operation modes. + + <p>The two modes usually (but not necessarily) supported by a form controller are the <code>DataMode</code> + and the <code>FilterMode</code>, where the former is the usual modus operandi for displaying and modifying + data, and the latter is a special mode to enter a filter for the database form which the controller is + responsible for.</p> + */ + interface ::com::sun::star::util::XModeSelector; + + /** denotes the instance which is used to implement operations on the form which the controller + works for. + + <p>This instance can be used, for instance, to determine the current state of certain form features.</p> + */ + [attribute, readonly] XFormOperations FormOperations; + + /** provicdes access to the currently active control + */ + [attribute, readonly] ::com::sun::star::awt::XControl CurrentControl; + + /** adds the specified listener to receive notifications whenever the activation state of + the controller changes. + */ + void addActivateListener( [in] com::sun::star::form::XFormControllerListener _Listener ); + + /** removes the specified listener from the list of components to receive notifications whenever the activation + state of the controller changes. + */ + void removeActivateListener( [in] com::sun::star::form::XFormControllerListener _Listener ); +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/form/runtime/XFormOperations.idl b/offapi/com/sun/star/form/runtime/XFormOperations.idl index 24552584aa29..10b568923ec5 100644 --- a/offapi/com/sun/star/form/runtime/XFormOperations.idl +++ b/offapi/com/sun/star/form/runtime/XFormOperations.idl @@ -44,8 +44,8 @@ #ifndef __com_sun_star_sdbc_XResultSetUpdate_idl__ #include <com/sun/star/sdbc/XResultSetUpdate.idl> #endif -#ifndef __com_sun_star_form_XFormController_idl__ -#include <com/sun/star/form/XFormController.idl> +#ifndef __com_sun_star_form_runtime_XFormController_idl__ +#include <com/sun/star/form/runtime/XFormController.idl> #endif #ifndef __com_sun_star_lang_IllegalArgumentException_idl__ #include <com/sun/star/lang/IllegalArgumentException.idl> @@ -115,7 +115,7 @@ interface XFormOperations : ::com::sun::star::lang::XComponent case some functionality will not be available. In particular, every feature which relies on the active control of the controller might be of limited use.</p> */ - [attribute, readonly] ::com::sun::star::form::XFormController Controller; + [attribute, readonly] ::com::sun::star::form::runtime::XFormController Controller; /** retrieves the current state of the given feature diff --git a/offapi/com/sun/star/form/runtime/makefile.mk b/offapi/com/sun/star/form/runtime/makefile.mk index 81c66826793b..18d59244ddda 100644 --- a/offapi/com/sun/star/form/runtime/makefile.mk +++ b/offapi/com/sun/star/form/runtime/makefile.mk @@ -45,7 +45,9 @@ IDLFILES=\ FeatureState.idl\ FormFeature.idl \ FormOperations.idl \ + FormController.idl \ XFeatureInvalidation.idl \ + XFormController.idl \ XFormOperations.idl \ # ------------------------------------------------------------------ diff --git a/offapi/com/sun/star/sdb/DataSourceBrowser.idl b/offapi/com/sun/star/sdb/DataSourceBrowser.idl index 36c73ae9da2c..0690321608a4 100644 --- a/offapi/com/sun/star/sdb/DataSourceBrowser.idl +++ b/offapi/com/sun/star/sdb/DataSourceBrowser.idl @@ -168,13 +168,11 @@ published service DataSourceBrowser <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> - ) + (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>isadataform. + <method scope="com::sun::star::awt">XTabController::getModel</method>is a dataform. </li> </ul> </p> diff --git a/offapi/com/sun/star/view/XFormLayerAccess.idl b/offapi/com/sun/star/view/XFormLayerAccess.idl index a5a96dd31e5d..16d8fb5137c3 100644 --- a/offapi/com/sun/star/view/XFormLayerAccess.idl +++ b/offapi/com/sun/star/view/XFormLayerAccess.idl @@ -37,8 +37,8 @@ #ifndef __com_sun_star_form_XForm_idl__ #include <com/sun/star/form/XForm.idl> #endif -#ifndef __com_sun_star_form_XFormController_idl__ -#include <com/sun/star/form/XFormController.idl> +#ifndef __com_sun_star_form_runtime_XFormController_idl__ +#include <com/sun/star/form/runtime/XFormController.idl> #endif #ifndef __com_sun_star_lang_IllegalArgumentException_idl__ #include <com/sun/star/lang/IllegalArgumentException.idl> @@ -73,10 +73,10 @@ interface XFormLayerAccess @see isDesignMode @see setDesignMode - @see ::com::sun::star::form::FormController + @see ::com::sun::star::form::runtime::FormController @see ::com::sun::star::form::runtime::FormOperations */ - ::com::sun::star::form::XFormController + ::com::sun::star::form::runtime::XFormController getFormController( [in] ::com::sun::star::form::XForm Form ); |