package com.smartgwt.client.widgets;
import com.smartgwt.client.types.DragDataAction;
import com.smartgwt.client.types.*;
import com.smartgwt.client.data.*;
import com.google.gwt.core.client.JavaScriptObject;
import com.smartgwt.client.widgets.events.*;
import java.util.Map;
/**
* A DataBoundComponent is a widget that can configure itself for viewing or editing objects which
share a certain schema by "binding" to the schema
* for that object (called a "DataSource").<P>
* A schema (or DataSource) describes an object as consisting of a set of properties (or "fields").<P>
* DataBoundComponents have a {@link DataBoundComponent#getDataSource dataSource} for dealing with binding to DataSources, {@link DataBoundComponent#getFields fields}
* the schema information provided by a DataSource, and manipulating objects or sets of object from the DataSource.<P>
* The following visual components currently support databinding:<pre>
* {@link com.smartgwt.client.widgets.form.DynamicForm}
* {@link com.smartgwt.client.widgets.viewer.DetailViewer}
* {@link com.smartgwt.client.widgets.grid.ListGrid}
* {@link com.smartgwt.client.widgets.tree.TreeGrid}
* {@link com.smartgwt.client.widgets.tile.TileGrid}
* {@link com.smartgwt.client.widgets.grid.ColumnTree}
* {@link com.smartgwt.client.widgets.cube.CubeGrid}
* </pre>
* The following non-visual components also support databinding:<pre>
* {@link com.smartgwt.client.widgets.form.ValuesManager}
* {@link com.smartgwt.client.data.ResultSet}
* {@link com.smartgwt.client.widgets.tree.ResultTree}
* </pre>
*/
public interface DataBoundComponent extends HasFetchDataHandlers,
HasDropCompleteHandlers,
HasDragCompleteHandlers
{
JavaScriptObject getOrCreateJsObj();
/**
* How to fetch and manage records retrieved from the server. See {@link FetchMode}.
* <p>
* This setting only applies to the {@link ResultSet} automatically created by calling {@link DataBoundComponent#fetchData(com.smartgwt.client.data.Criteria) fetchData}.
* If a pre-existing ResultSet is passed to <code>setData()</code> instead, its existing setting for {@link com.smartgwt.client.data.ResultSet#getFetchMode() fetchMode}
* applies.
*
* @param fetchMode the fetch mode
*/
void setDataFetchMode(FetchMode fetchMode);
/**
* How to fetch and manage records retrieved from the server. See {@link FetchMode}.
* <p>
* This setting only applies to the {@link ResultSet} automatically created by calling {@link DataBoundComponent#fetchData(com.smartgwt.client.data.Criteria) fetchData}.
* If a pre-existing ResultSet is passed to <code>setData()</code> instead, its existing setting for {@link com.smartgwt.client.data.ResultSet#getFetchMode() fetchMode}
* applies.
*
* @return the fetch mode
*/
FetchMode getDataFetchMode();
/**
* When using data paging, how many records to fetch at a time. The value of this
attribute is passed on to the auto-constructed {@link com.smartgwt.client.data.ResultSet} object for this
component. In effect, this gives you control over the {@link com.smartgwt.client.data.ResultSet#getResultSize resultSize}
attribute for this component.
<P>
<b>Note</b> that regardless of the <code>dataPageSize</code> setting, a component will always fetch
all of data that it needs to draw. Settings such as
{@link com.smartgwt.client.widgets.grid.ListGrid#getShowAllRecords showAllRecords},
{@link com.smartgwt.client.widgets.grid.ListGrid#getDrawAllMaxCells drawAllMaxCells} and
{@link com.smartgwt.client.widgets.grid.ListGrid#getDrawAheadRatio drawAheadRatio} can cause more rows than the configured
<code>dataPageSize</code> to be fetched.
*
* @param dataPageSize dataPageSize Default value is 75
*/
void setDataPageSize(int dataPageSize);
/**
* When using data paging, how many records to fetch at a time. The value of this
attribute is passed on to the auto-constructed {@link com.smartgwt.client.data.ResultSet} object for this
component. In effect, this gives you control over the {@link com.smartgwt.client.data.ResultSet#getResultSize resultSize}
attribute for this component.
<P>
<b>Note</b> that regardless of the <code>dataPageSize</code> setting, a component will always fetch
all of data that it needs to draw. Settings such as
{@link com.smartgwt.client.widgets.grid.ListGrid#getShowAllRecords showAllRecords},
{@link com.smartgwt.client.widgets.grid.ListGrid#getDrawAllMaxCells drawAllMaxCells} and
{@link com.smartgwt.client.widgets.grid.ListGrid#getDrawAheadRatio drawAheadRatio} can cause more rows than the configured
<code>dataPageSize</code> to be fetched.
*
* @return int
*/
int getDataPageSize();
/**
* If true, the set of fields given by the "default binding" (see
{@link com.smartgwt.client.widgets.DataBoundComponent#getFields fields}) is used, with any fields specified in
<code>component.fields</code> acting as overrides that can suppress or modify the
display of individual fields, without having to list the entire set of fields that
should be shown.
<P>
If <code>component.fields</code> contains fields that are not found in the DataSource,
they will be shown after the most recently referred to DataSource field. If the new
fields appear first, they will be shown first.
*
* @param useAllDataSourceFields useAllDataSourceFields Default value is false
*/
void setUseAllDataSourceFields(Boolean useAllDataSourceFields);
/**
* If true, the set of fields given by the "default binding" (see
{@link com.smartgwt.client.widgets.DataBoundComponent#getFields fields}) is used, with any fields specified in
<code>component.fields</code> acting as overrides that can suppress or modify the
display of individual fields, without having to list the entire set of fields that
should be shown.
<P>
If <code>component.fields</code> contains fields that are not found in the DataSource,
they will be shown after the most recently referred to DataSource field. If the new
fields appear first, they will be shown first.
*
* @return Boolean
*/
Boolean getUseAllDataSourceFields();
/**
* Whether to show fields marked <code>hidden:true</code> when a DataBoundComponent is given a
DataSource but no <code>component.fields</code>.
<p>
The <code>hidden</code> property is used on DataSource fields to mark fields that are
never of meaning to an end user.
*
* @param showHiddenFields showHiddenFields Default value is false
*/
void setShowHiddenFields(Boolean showHiddenFields);
/**
* Whether to show fields marked <code>hidden:true</code> when a DataBoundComponent is given a
DataSource but no <code>component.fields</code>.
<p>
The <code>hidden</code> property is used on DataSource fields to mark fields that are
never of meaning to an end user.
*
* @return Boolean
*/
Boolean getShowHiddenFields();
/**
* Whether to show fields marked <code>detail:true</code> when a DataBoundComponent is
given a DataSource but no <code>component.fields</code>.
<p>
The <code>detail</code> property is used on DataSource fields to mark fields that
shouldn't appear by default in a view that tries to show many records in a small space.
*
* @param showDetailFields showDetailFields Default value is false
*/
void setShowDetailFields(Boolean showDetailFields);
/**
* Whether to show fields marked <code>detail:true</code> when a DataBoundComponent is
given a DataSource but no <code>component.fields</code>.
<p>
The <code>detail</code> property is used on DataSource fields to mark fields that
shouldn't appear by default in a view that tries to show many records in a small space.
*
* @return Boolean
*/
Boolean getShowDetailFields();
/**
* Whether to show fields of non-atomic types when a DataBoundComponent is given a
DataSource but no <code>component.fields</code>.
<p>
If true, the component will show fields that declare a complex type, for example, a
field 'shippingAddress' that declares type 'Address', where 'Address' is the ID of a
DataSource that declares the fields of a shipping address (city, street name, etc).
<P>
Such fields may need custom formatters or editors in order to create a usable interface,
for example, an Address field in a ListGrid might use a custom formatter to combine the
relevant fields of an address into one column, and might use a pop-up dialog for
editing.
* <p><b>Note : </b> This is an advanced setting</p>
*
* @param showComplexFields showComplexFields Default value is true
*/
void setShowComplexFields(Boolean showComplexFields);
/**
* Whether to show fields of non-atomic types when a DataBoundComponent is given a
DataSource but no <code>component.fields</code>.
<p>
If true, the component will show fields that declare a complex type, for example, a
field 'shippingAddress' that declares type 'Address', where 'Address' is the ID of a
DataSource that declares the fields of a shipping address (city, street name, etc).
<P>
Such fields may need custom formatters or editors in order to create a usable interface,
for example, an Address field in a ListGrid might use a custom formatter to combine the
relevant fields of an address into one column, and might use a pop-up dialog for
editing.
*
* @return Boolean
*/
Boolean getShowComplexFields();
/**
* Operation ID this component should use when performing fetch operations.
*
* @param fetchOperation fetchOperation Default value is null
*/
void setFetchOperation(String fetchOperation);
/**
* Operation ID this component should use when performing fetch operations.
*
* @return String
*/
String getFetchOperation();
/**
* {@link com.smartgwt.client.data.DSRequest#getOperationId operationId} this component
* should use when performing update operations.
*
* @param updateOperation Default value is null
* @see com.smartgwt.client.docs.Operations Operations overview and related methods
*/
void setUpdateOperation(String updateOperation);
/**
* {@link com.smartgwt.client.data.DSRequest#getOperationId operationId} this component
* should use when performing update operations.
*
* @return String
* @see com.smartgwt.client.docs.Operations Operations overview and related methods
*/
String getUpdateOperation();
/**
* {@link com.smartgwt.client.data.DSRequest#getOperationId operationId} this component
* should use when performing add operations.
*
* @param addOperation Default value is null
* @see com.smartgwt.client.docs.Operations Operations overview and related methods
*/
void setAddOperation(String addOperation);
/**
* {@link com.smartgwt.client.data.DSRequest#getOperationId operationId} this component
* should use when performing add operations.
*
* @return String
* @see com.smartgwt.client.docs.Operations Operations overview and related methods
*/
String getAddOperation();
/**
* {@link com.smartgwt.client.data.DSRequest#getOperationId operationId} this component
* should use when performing remove operations.
*
* @param removeOperation Default value is null
* @see com.smartgwt.client.docs.Operations Operations overview and related methods
*/
void setRemoveOperation(String removeOperation);
/**
* {@link com.smartgwt.client.data.DSRequest#getOperationId operationId} this component
* should use when performing remove operations.
*
* @return String
* @see com.smartgwt.client.docs.Operations Operations overview and related methods
*/
String getRemoveOperation();
/**
* The list of field-names to export. If provided, the field-list in the exported output is
limited and sorted as per the list.
<P>
If exportFields is not provided, the exported output includes all visible fields
from this component, sorted as they appear.
*
* @param exportFields exportFields Default value is null
*/
void setExportFields(String[] exportFields);
/**
* The list of field-names to export. If provided, the field-list in the exported output is
limited and sorted as per the list.
<P>
If exportFields is not provided, the exported output includes all visible fields
from this component, sorted as they appear.
*
*
* @return the list of field-names to export.
*
*/
String[] getExportFields();
/**
* Setting exportAll to true prevents the component from passing its list of fields to the
export call. The result is the export of all visible fields from {@link com.smartgwt.client.data.DataSource#getFields fields}.
<P>
If exportAll is false, an export operation will first consider
{@link com.smartgwt.client.widgets.DataBoundComponent#getExportFields exportFields}, if it's set, and fall back on all visible fields from
{@link com.smartgwt.client.data.DataSource#getFields fields} otherwise.
*
* @param exportAll exportAll Default value is false
*/
void setExportAll(Boolean exportAll);
/**
* Setting exportAll to true prevents the component from passing its list of fields to the
export call. The result is the export of all visible fields from {@link com.smartgwt.client.data.DataSource#getFields fields}.
<P>
If exportAll is false, an export operation will first consider
{@link com.smartgwt.client.widgets.DataBoundComponent#getExportFields exportFields}, if it's set, and fall back on all visible fields from
{@link com.smartgwt.client.data.DataSource#getFields fields} otherwise.
*
* @return Boolean
*/
Boolean getExportAll();
/**
* If set, detect and prevent duplicate records from being transferred to this component, either via
drag and drop or via {@link com.smartgwt.client.widgets.DataBoundComponent#transferSelectedData}.
* When a duplicate transfer is detected,
a dialog will appear showing the {@link com.smartgwt.client.widgets.DataBoundComponent#getDuplicateDragMessage duplicateDragMessage}.
<P>
*
If the component either does not have a {@link com.smartgwt.client.data.DataSource} or has a DataSource with no
{@link com.smartgwt.client.data.DataSourceField#getPrimaryKey primaryKey}
* declared, duplicate checking is off by
default. If duplicate checking is enabled, it looks for an existing record in the dataset
that has <b>all</b> of the
* properties of the dragged record, and considers that a duplicate.
<P>
*
For {@link com.smartgwt.client.types.DragDataAction}:"copy" where the target DataSource is related to the source
DataSource by foreignKey, a duplicate means that
* the target list, as filtered by the current
criteria, already has a record whose value for the foreignKey field matches the
primaryKey of the record being
* transferred.
<P>
For example, consider dragging "employees" to "teams", where "teams" has a field
"teams.employeeId" which is a foreignKey pointing to
* "employees.id", and the target
grid has search criteria causing it to show all the members of one team. A duplicate -
adding an employee to the same team
* twice - is when the target grid's dataset contains an
record with "employeeId" matching the "id" field of the dropped employee.
*
* @param preventDuplicates preventDuplicates Default value is null
* @throws IllegalStateException this property cannot be changed after the component has been created
*/
void setPreventDuplicates(Boolean preventDuplicates) throws IllegalStateException;
/**
* If set, detect and prevent duplicate records from being transferred to this component, either via
drag and drop or via {@link com.smartgwt.client.widgets.DataBoundComponent#transferSelectedData}.
* When a duplicate transfer is detected,
a dialog will appear showing the {@link com.smartgwt.client.widgets.DataBoundComponent#getDuplicateDragMessage duplicateDragMessage}.
<P>
*
If the component either does not have a {@link com.smartgwt.client.data.DataSource} or has a DataSource with no
{@link com.smartgwt.client.data.DataSourceField#getPrimaryKey primaryKey}
* declared, duplicate checking is off by
default. If duplicate checking is enabled, it looks for an existing record in the dataset
that has <b>all</b> of the
* properties of the dragged record, and considers that a duplicate.
<P>
*
For {@link com.smartgwt.client.types.DragDataAction}:"copy" where the target DataSource is related to the source
DataSource by foreignKey, a duplicate means that
* the target list, as filtered by the current
criteria, already has a record whose value for the foreignKey field matches the
primaryKey of the record being
* transferred.
<P>
For example, consider dragging "employees" to "teams", where "teams" has a field
"teams.employeeId" which is a foreignKey pointing to
* "employees.id", and the target
grid has search criteria causing it to show all the members of one team. A duplicate -
adding an employee to the same team
* twice - is when the target grid's dataset contains an
record with "employeeId" matching the "id" field of the dropped employee.
*
* @return Boolean
*/
Boolean getPreventDuplicates();
/**
* Message to show when a user attempts to transfer duplicate records into this component, and
{@link com.smartgwt.client.widgets.DataBoundComponent#getPreventDuplicates preventDuplicates}
* is enabled. If set to null, duplicates will not be reported and the dragged duplicates will not be saved.
*
* @param duplicateDragMessage duplicateDragMessage Default value is "Duplicates not allowed"
* @throws IllegalStateException this property cannot be changed after the component has been created
*/
void setDuplicateDragMessage(String duplicateDragMessage) throws IllegalStateException;
/**
* Message to show when a user attempts to transfer duplicate records into this component, and
{@link com.smartgwt.client.widgets.DataBoundComponent#getPreventDuplicates preventDuplicates}
* is enabled. If set to null, duplicates will not be reported and the dragged duplicates will not be saved.
*
* @return String
*/
String getDuplicateDragMessage();
/**
* Indicates whether to add "drop values" to items dropped on this component, if both the source and target widgets are databound, either to the same DataSource or to
* different DataSources that are related via a foreign key. "Drop values" are properties of the dropped item that you wish to change (and persist) as a result of the
* item being dropped on this grid.<P>
* If this value is true and this component is databound, {@link com.smartgwt.client.widgets.DataBoundComponent#getDropValues} will be called for every databound item
* dropped on this grid, and an update performed on the item
*
* @param addDropValues addDropValues Default value is true
*/
void setAddDropValues(Boolean addDropValues);
/**
* Indicates whether to add "drop values" to items dropped on this component, if both the source and target widgets are databound, either to the same DataSource or to
* different DataSources that are related via a foreign key. "Drop values" are properties of the dropped item that you wish to change (and persist) as a result of the
* item being dropped on this grid.<P>
* If this value is true and this component is databound, {@link com.smartgwt.client.widgets.DataBoundComponent#getDropValues} will be called for every databound item
* dropped on this grid, and an update performed on the item
*
* @return Boolean
*/
Boolean getAddDropValues();
/**
* When an item is dropped on this component, and {@link com.smartgwt.client.widgets.DataBoundComponent#getAddDropValues addDropValues} is true and both the source and
* target widgets are databound, either to the same DataSource or to different DataSources that are related via a foreign key, this object provides the "drop values" that
* Smart GWT will apply to the dropped object before updating it.<P>
* If this property is not defined, Smart GWT defaults to returning the selection criteria currently in place for this component. Thus, any databound items (for example,
* rows from other grids bound to the same DataSource) dropped on the grid will, by default, be subjected to an update that makes them conform to the grid's current filter criteria.
* <p><b>Note : </b> This is an advanced setting</p>
*
* @param dropValues dropValues Default value is null
*/
void setDropValues(Map dropValues);
/**
* When an item is dropped on this component, and {@link com.smartgwt.client.widgets.DataBoundComponent#getAddDropValues addDropValues} is true and both the source and
* target widgets are databound, either to the same DataSource or to different DataSources that are related via a foreign key, this object provides the "drop values" that
* Smart GWT will apply to the dropped object before updating it.<P>
* If this property is not defined, Smart GWT defaults to returning the selection criteria currently in place for this component. Thus, any databound items (for example,
* rows from other grids bound to the same DataSource) dropped on the grid will, by default, be subjected to an update that makes them conform to the grid's current filter criteria.
* <p><b>Note : </b> This is an advanced setting</p>
*
*
* @return Returns the "drop values" to apply to a record dropped on this component prior to update. Only
applicable to databound components - see {@link com.smartgwt.client.widgets.DataBoundComponent#getDropValues dropValues} for more details. If multiple records
are being dropped, this method is called for each of them in turn.
<P>
This method returns the following:
<UL>
<LI>Nothing, if {@link com.smartgwt.client.widgets.DataBoundComponent#getAddDropValues addDropValues} is false</LI>
<LI>dropValues, if that property is set. If the component's criteria object is applicable (as explained
in the next item), it is merged into dropValues, with properties in dropValues taking precedence.</LI>
<LI>The component's criteria object, if the most recent textMatchStyle for the component was "exact"
and it is simple criteria (ie, not an AdvancedCriteria object)</LI>
<LI>Otherwise nothing</LI>
</UL>
<P>
You can override this method if you need more complex setting of drop values than can be
provided by simply supplying a dropValues object.
*
*/
Map getDropValues();
/**
* The <code>useFlatFields</code> flag causes all simple type fields anywhere in a nested
set of DataSources to be exposed as a flat list for form binding.
<P>
<code>useFlatFields</code> is typically used with imported metadata, such as
{@link com.smartgwt.client.data.XMLTools#loadXMLSchema} from a
{@link com.smartgwt.client.data.XMLTools#loadWSDL}, as a means of eliminating levels of XML
nesting that aren't meaningful in a user interface, without the cumbersome and fragile
process of mapping form fields to XML structures.
<P>
For example, having called {@link com.smartgwt.client.data.WebService#getInputDS} to retrieve the input message
schema for a web service operation whose input message looks like this:
<pre>
<FindServices>
<searchFor>search text</searchFor>
<Options>
<caseSensitive>false</caseSensitive>
</Options>
<IncludeInSearch>
<serviceName>true</serviceName>
<documentation>true</documentation>
<keywords>true</keywords>
</IncludeInSearch>
</FindServices>
</pre>
Setting <code>useFlatFields</code> on a {@link com.smartgwt.client.widgets.form.DynamicForm} that is bound to this input
message schema would result in 5 {@link com.smartgwt.client.widgets.form.fields.FormItem} reflecting the 5 simple type
fields in the message.
<P>
For this form, the result of {@link com.smartgwt.client.widgets.form.DynamicForm#getValues} might look
like:
<P>
<pre>{
searchFor: "search text",
caseSensitive: false,
serviceName: true,
documentation : true,
keywords : true
}</pre>
When contacting a {@link com.smartgwt.client.data.WebService}, these values can be automatically
mapped to the structure of the input message for a web service operation by setting
{@link com.smartgwt.client..WSRequest#getUseFlatFields useFlatFields} (for use with {@link com.smartgwt.client.data.WebService#callOperation}) or by setting
{@link com.smartgwt.client.data.DSRequest#getUseFlatFields useFlatFields} (for use with a {@link com.smartgwt.client.data.DataSource} that is
{@link com.smartgwt.client.docs.WsdlBinding 'bound to a WSDL web service'} via
{@link com.smartgwt.client.data.OperationBinding#getWsOperation wsOperation}).
<P>
Using these two facilities in conjunction (component.useFlatFields and
request.useFlatFields) allows gratuitous nesting to be consistently bypassed in both the user
presentation and when providing the data for XML messages.
<P>
You can also set {@link com.smartgwt.client.data.OperationBinding#getUseFlatFields useFlatFields} to automatically enable
"flattened" XML serialization (request.useFlatFields) for all DataSource requests of a
particular operationType.
<P>
Note that <code>useFlatFields</code> is not generally recommended for use with structures
where multiple simple type fields exist with the same name, however if used with such a
structure, the first field to use a given name wins. "first" means the first field
encountered in a depth first search. "wins" means only the first field will be present as a
field when data binding.
*
* @param useFlatFields useFlatFields Default value is null
* @throws IllegalStateException this property cannot be changed after the component has been created
*/
void setUseFlatFields(Boolean useFlatFields) throws IllegalStateException;
/**
* The <code>useFlatFields</code> flag causes all simple type fields anywhere in a nested
set of DataSources to be exposed as a flat list for form binding.
<P>
<code>useFlatFields</code> is typically used with imported metadata, such as
{@link com.smartgwt.client.data.XMLTools#loadXMLSchema} from a
{@link com.smartgwt.client.data.XMLTools#loadWSDL}, as a means of eliminating levels of XML
nesting that aren't meaningful in a user interface, without the cumbersome and fragile
process of mapping form fields to XML structures.
<P>
For example, having called {@link com.smartgwt.client.data.WebService#getInputDS} to retrieve the input message
schema for a web service operation whose input message looks like this:
<pre>
<FindServices>
<searchFor>search text</searchFor>
<Options>
<caseSensitive>false</caseSensitive>
</Options>
<IncludeInSearch>
<serviceName>true</serviceName>
<documentation>true</documentation>
<keywords>true</keywords>
</IncludeInSearch>
</FindServices>
</pre>
Setting <code>useFlatFields</code> on a {@link com.smartgwt.client.widgets.form.DynamicForm} that is bound to this input
message schema would result in 5 {@link com.smartgwt.client.widgets.form.fields.FormItem} reflecting the 5 simple type
fields in the message.
<P>
For this form, the result of {@link com.smartgwt.client.widgets.form.DynamicForm#getValues} might look
like:
<P>
<pre>{
searchFor: "search text",
caseSensitive: false,
serviceName: true,
documentation : true,
keywords : true
}</pre>
When contacting a {@link com.smartgwt.client.data.WebService}, these values can be automatically
mapped to the structure of the input message for a web service operation by setting
{@link com.smartgwt.client..WSRequest#getUseFlatFields useFlatFields} (for use with {@link com.smartgwt.client.data.WebService#callOperation}) or by setting
{@link com.smartgwt.client.data.DSRequest#getUseFlatFields useFlatFields} (for use with a {@link com.smartgwt.client.data.DataSource} that is
{@link com.smartgwt.client.docs.WsdlBinding 'bound to a WSDL web service'} via
{@link com.smartgwt.client.data.OperationBinding#getWsOperation wsOperation}).
<P>
Using these two facilities in conjunction (component.useFlatFields and
request.useFlatFields) allows gratuitous nesting to be consistently bypassed in both the user
presentation and when providing the data for XML messages.
<P>
You can also set {@link com.smartgwt.client.data.OperationBinding#getUseFlatFields useFlatFields} to automatically enable
"flattened" XML serialization (request.useFlatFields) for all DataSource requests of a
particular operationType.
<P>
Note that <code>useFlatFields</code> is not generally recommended for use with structures
where multiple simple type fields exist with the same name, however if used with such a
structure, the first field to use a given name wins. "first" means the first field
encountered in a depth first search. "wins" means only the first field will be present as a
field when data binding.
*
* @return Boolean
*/
Boolean getUseFlatFields();
/**
* Marker that can be set on a record to flag that record as hilited. Should be set to a value
that matches {@link com.smartgwt.client..Hilite#getId id} for a hilite defined on this component.
*
* @param hiliteProperty hiliteProperty Default value is "_hilite"
*/
void setHiliteProperty(String hiliteProperty);
/**
* Marker that can be set on a record to flag that record as hilited. Should be set to a value
that matches {@link com.smartgwt.client..Hilite#getId id} for a hilite defined on this component.
*
* @return String
*/
String getHiliteProperty();
/**
* Indicates what to do with data dragged into another DataBoundComponent. See
DragDataAction type for details.
*
* @param dragDataAction dragDataAction Default value is Canvas.MOVE
*/
void setDragDataAction(DragDataAction dragDataAction);
/**
* Indicates what to do with data dragged into another DataBoundComponent. See
DragDataAction type for details.
*
* @return DragDataAction
*/
DragDataAction getDragDataAction();
/**
* CSS Style to apply to the drag tracker when dragging occurs on this component.
*
* @param dragTrackerStyle dragTrackerStyle Default value is "gridDragTracker"
*/
void setDragTrackerStyle(String dragTrackerStyle);
/**
* CSS Style to apply to the drag tracker when dragging occurs on this component.
*
* @return String
*/
String getDragTrackerStyle();
/**
* Adds an item to the header context menu allowing users to launch a dialog to define a new
field based on values present in other fields, using the {@link com.smartgwt.client..FormulaBuilder}.
<P>
User-added formula fields can be persisted via {@link com.smartgwt.client.widgets.grid.ListGrid#getFieldState} and
{@link com.smartgwt.client.widgets.grid.ListGrid#setFieldState}.
*
* @param canAddFormulaFields canAddFormulaFields Default value is false
*/
void setCanAddFormulaFields(Boolean canAddFormulaFields);
/**
* Convenience method to display a {@link com.smartgwt.client..SummaryBuilder} to create a new Summary Field. This
is equivalent to calling {@link DataBoundComponentGen#editSummaryField} with
no parameter.
*/
void addSummaryField();
/**
* Convenience method to display a {@link com.smartgwt.client..FormulaBuilder} to create a new Formula Field. This
is equivalent to calling {@link DataBoundComponentGen#editFormulaField} with
no parameter.
*/
void addFormulaField();
/**
* Adds an item to the header context menu allowing users to launch a dialog to define a new
field based on values present in other fields, using the {@link com.smartgwt.client..FormulaBuilder}.
<P>
User-added formula fields can be persisted via {@link com.smartgwt.client.widgets.grid.ListGrid#getFieldState} and
{@link com.smartgwt.client.widgets.grid.ListGrid#setFieldState}.
*
* @return Boolean
*/
Boolean getCanAddFormulaFields();
/**
* Text for a menu item allowing users to add a formula field
*
* @param addFormulaFieldText addFormulaFieldText Default value is "Add formula column..."
*/
void setAddFormulaFieldText(String addFormulaFieldText);
/**
* Text for a menu item allowing users to add a formula field
*
* @return String
*/
String getAddFormulaFieldText();
/**
* Text for a menu item allowing users to edit a formula field
*
* @param editFormulaFieldText editFormulaFieldText Default value is "Edit formula..."
*/
void setEditFormulaFieldText(String editFormulaFieldText);
/**
* Text for a menu item allowing users to edit a formula field
*
* @return String
*/
String getEditFormulaFieldText();
/**
* Adds an item to the header context menu allowing users to launch a dialog to define a new
text field that can contain both user-defined text and the formatted values present in other
fields, using the {@link com.smartgwt.client..SummaryBuilder}.
<P>
User-added summary fields can be persisted via {@link com.smartgwt.client.widgets.grid.ListGrid#getFieldState} and
{@link com.smartgwt.client.widgets.grid.ListGrid#setFieldState}.
*
* @param canAddSummaryFields canAddSummaryFields Default value is false
*/
void setCanAddSummaryFields(Boolean canAddSummaryFields);
/**
* Adds an item to the header context menu allowing users to launch a dialog to define a new
text field that can contain both user-defined text and the formatted values present in other
fields, using the {@link com.smartgwt.client..SummaryBuilder}.
<P>
User-added summary fields can be persisted via {@link com.smartgwt.client.widgets.grid.ListGrid#getFieldState} and
{@link com.smartgwt.client.widgets.grid.ListGrid#setFieldState}.
*
* @return Boolean
*/
Boolean getCanAddSummaryFields();
/**
* Text for a menu item allowing users to add a formula field
*
* @param addSummaryFieldText addSummaryFieldText Default value is "Add summary column..."
*/
void setAddSummaryFieldText(String addSummaryFieldText);
/**
* Text for a menu item allowing users to add a formula field
*
* @return String
*/
String getAddSummaryFieldText();
/**
* Text for a menu item allowing users to edit the formatter for a field
*
* @param editSummaryFieldText editSummaryFieldText Default value is "Edit summary format..."
*/
void setEditSummaryFieldText(String editSummaryFieldText);
/**
* Text for a menu item allowing users to edit the formatter for a field
*
* @return String
*/
String getEditSummaryFieldText();
/**
* Select/deselect a {@link com.smartgwt.client.data.Record} passed in explicitly, or by index.
*
* @param record record (or row number) to select
*/
void selectRecord(Record record);
/**
* Select/deselect a {@link com.smartgwt.client.data.Record} passed in explicitly, or by index.
*
* @param record record (or row number) to select
*/
void selectRecord(int record);
/**
* Select/deselect a {@link com.smartgwt.client.data.Record} passed in explicitly, or by index.
*
* @param record record (or row number) to select
* @param newState new selection state (if null, defaults to true)
*/
void selectRecord(int record, boolean newState);
/**
* Select/deselect a {@link com.smartgwt.client.data.Record} passed in explicitly, or by index.
*
* @param record record (or row number) to select
* @param newState new selection state (if null, defaults to true)
*/
void selectRecord(Record record, boolean newState);
/**
* Select/deselect a list of {@link com.smartgwt.client.data.Record}s passed in explicitly, or by index.
*
* @param records records (or row numbers) to select
*/
void selectRecords(int[] records);
/**
* Select/deselect a list of {@link com.smartgwt.client.data.Record}s passed in explicitly, or by index.
*
* @param records records (or row numbers) to select
* @param newState new selection state
*/
void selectRecords(int[] records, boolean newState);
/**
* Select/deselect a list of {@link com.smartgwt.client.data.Record}s passed in explicitly, or by index.
*
* @param records records (or row numbers) to select
*/
void selectRecords(Record[] records);
/**
* Select/deselect a list of {@link com.smartgwt.client.data.Record}s passed in explicitly, or by index.
*
* @param records records (or row numbers) to select
* @param newState new selection state (if null, defaults to true)
*/
void selectRecords(Record[] records, boolean newState);
/**
* Deselect a {@link com.smartgwt.client.data.Record} passed in explicitly, or by index. <P> Synonym for
* <code>selectRecord(record, false)</code>
*
* @param record record (or row number) to deselect
*/
void deselectRecord(Record record);
/**
* Deselect a {@link com.smartgwt.client.data.Record} passed in explicitly, or by index. <P> Synonym for
* <code>selectRecord(record, false)</code>
*
* @param record record (or row number) to deselect
*/
void deselectRecord(int record);
/**
* Deselect a list of {@link com.smartgwt.client.data.Record}s passed in explicitly, or by index. <P> Synonym
* for <code>selectRecords(records, false)</code>
*
* @param records records (or row numbers) to deselect
*/
void deselectRecords(int[] records);
/**
* Deselect a list of {@link com.smartgwt.client.data.Record}s passed in explicitly, or by index. <P> Synonym
* for <code>selectRecords(records, false)</code>
*
* @param records records (or row numbers) to deselect
*/
void deselectRecords(Record[] records);
/**
* Select all records
*/
void selectAllRecords();
/**
*
Deselect all records
*/
void deselectAllRecords();
/**
* Whether at least one item is selected
*
* @return true == at least one item is selected false == nothing at all is selected
*/
Boolean anySelected();
/**
* Enable / disable a {@link com.smartgwt.client.widgets.DataBoundComponent#getHilites hilites}
*
* @param hiliteID ID of hilite to enable
*/
void enableHilite(String hiliteID);
/**
* Enable / disable a {@link com.smartgwt.client.widgets.DataBoundComponent#getHilites hilites}
*
* @param hiliteID ID of hilite to enable
* @param enable new enabled state to apply - if null, defaults to true
*/
void enableHilite(String hiliteID, boolean enable);
/**
* Disable a hilite
*
* @param hiliteID ID of hilite to disable
*/
void disableHilite(String hiliteID);
/**
* Enable all hilites.
*/
void enableHiliting();
/**
* Enable all hilites.
*
* @param enable new enabled state to apply - if null, defaults to true
*/
void enableHiliting(boolean enable);
/**
* Disable all hilites.
*/
void disableHiliting();
/**
* During a drag-and-drop interaction, this method returns the set of records being dragged out of the component. In the default implementation, this is the list of currently selected records.<p>
* This method is consulted by
{@link com.smartgwt.client.widgets.grid.ListGrid#willAcceptDrop}.
*
* @return Array of {@link com.smartgwt.client.data.Record}s that are currently selected.
*/
Record[] getDragData();
/**
* Simulates a drag / drop type transfer of the selected records in some other component to this component, without requiring any user interaction. This method acts on the
* dropped records exactly as if they had been dropped in an actual drag / drop interaction, including any special databound behavior invoked by calling
* {@link com.smartgwt.client.widgets.DataBoundComponent#getDropValues} for each dropped record.<P>
* To transfer <b>all</b> data in, for example, a {@link com.smartgwt.client.widgets.grid.ListGrid}, call grid.selection.selectAll() first.<P>
* Note that drag/drop type transfers of records between components are asynchronous operations: Smart GWT may need to perform server turnarounds to establish whether
* dropped records already exist in the target component. Therefore, it is possible to issue a call to <code>transferSelectedData()</code> and/or the <code>drop()</code>
* method of a databound component whilst a transfer is still active. When this happens, Smart GWT adds the second and subsequent transfer requests to a queue and runs
* them one after the other. If you want to be notified when a transfer process has actually completed, use {@link addDropCompleteHandler}.
* See the {@link com.smartgwt.client.docs.Dragging} documentation for an overview of list grid drag/drop data transfer.
*
* @param source source component from which the records will be tranferred
*/
void transferSelectedData(DataBoundComponent source);
/**
* Simulates a drag / drop type transfer of the selected records in some other component to this component, without requiring any user interaction. This method acts on the
* dropped records exactly as if they had been dropped in an actual drag / drop interaction, including any special databound behavior invoked by calling
* {@link com.smartgwt.client.widgets.DataBoundComponent#getDropValues} for each dropped record.<P>
* To transfer <b>all</b> data in, for example, a {@link com.smartgwt.client.widgets.grid.ListGrid}, call grid.selection.selectAll() first.<P>
* Note that drag/drop type transfers of records between components are asynchronous operations: Smart GWT may need to perform server turnarounds to establish whether
* dropped records already exist in the target component. Therefore, it is possible to issue a call to <code>transferSelectedData()</code> and/or the <code>drop()</code>
* method of a databound component whilst a transfer is still active. When this happens, Smart GWT adds the second and subsequent transfer requests to a queue and runs
* them one after the other. If you want to be notified when a transfer process has actually completed, use {@link addDropCompleteHandler}.
* See the {@link com.smartgwt.client.docs.Dragging} documentation for an overview of list grid drag/drop data transfer.
*
* @param source source component from which the records will be tranferred
* @param index target index (drop position) of the rows within this grid.
*/
void transferSelectedData(DataBoundComponent source, int index);
/**
* Get the index of the provided record.
<P>
Override in subclasses to provide more specific behaviour, for instance, when data holds a
large number of records
*
* @param record the record whose index is to be retrieved
* @return indexindex of the record, or -1 if not found
*/
int getRecordIndex(Record record);
/**
* Get the value of the titleField for the passed record
<P>
Override in subclasses
*
* @param record the record whose index is to be retrieved
* @return valuethe value of the titleField for the passed record
*/
String getTitleFieldValue(Record record);
/**
* Method to return the fieldName which represents the "title" for records in this
Component.<br>
If this.titleField is explicitly specified it will always be used.
Otherwise, default implementation will check {@link com.smartgwt.client.data.DataSource#getTitleField titleField} for databound
components.<br>
For non databound components returns the first defined field name of <code>"title"</code>,
<code>"name"</code>, or <code>"id"</code>. If we dont find any field-names that match these
titles, the first field in the component will be used instead.
*
* @return fieldName the title field for this component.
*/
String getTitleField();
/**
* Sets the best field to use for a user-visible title for an individual record from this component.
*
* @param fieldName the title field for this component.
*/
void setTitleField(String titleField);
/**
* Bind to a DataSource. Binding to a DataSource means that the component will use the DataSource to provide default data for its fields.<P>
* When binding a previously-bound componenet to a new DataSource, if the component has any existing "fields" or has a dataset, these will be
* discarded by default, since it is assumed the new DataSource may represent a completely unrelated set of objects. If the old "fields" are
* still relevant, you may be able to refer to setDataSource(dataSource, fields) as an alternative method if the widget has an implementation of it.
*
* @param dataSource DataSource to bind to. Default value is null
*/
void setDataSource(DataSource dataSource);
/**
* Bind to a DataSource. Binding to a DataSource means that the component will use the DataSource to provide default data for its fields.<P>
* When binding a previously-bound componenet to a new DataSource, if the component has any existing "fields" or has a dataset, these will be
* discarded by default, since it is assumed the new DataSource may represent a completely unrelated set of objects. If the old "fields" are
* still relevant, you may be able to refer to setDataSource(dataSource, fields) as an alternative method if the widget has an implementation of it.
*
* @param dataSource name of DataSource to bind to
*/
void setDataSource(String dataSource);
/**
* The DataSource that this component should bind to for default fields and for performing {@link com.smartgwt.client.data.DSRequest DataSource requests}.
*
* @return DataSource
*/
DataSource getDataSource();
/**
* Retrieves data from the DataSource that matches the specified criteria.
* <p>
* When <code>fetchData()</code> is first called, if data has not already been provided via
* <code>setData()</code>, this method will create a {@link com.smartgwt.client.data.ResultSet}, which will be
* configured based on component settings such as {@link #setFetchOperation fetchOperation} and {@link #setDataPageSize dataPageSize}, as well
* as the general purpose <code>dataProperties</code>. The created ResultSet will automatically send a DSRequest
* to retrieve data from {@linkplain #setDataSource the dataSource}, and from then on will
* automatically manage paging through large datasets, as well as performing filtering and
* sorting operations inside the browser when possible - see the ResultSet docs for
* details.
* <p>
* <b>NOTE:</b> do not use <b>both</b> {@link #setAutoFetchData autoFetchData} <b>and</b> a
* call to <code>fetchData()</code> - this may result in two DSRequests to fetch data. Use
* either {@link #setAutoFetchData autoFetchData} and <code>setAutoFetchCriteria()</code> <b>or</b> a manual call to fetchData()
* passing criteria.
* <p>
* Whether a ResultSet was automatically created or provided via <code>setData()</code>, subsequent
* calls to fetchData() will simply call {@link com.smartgwt.client.data.ResultSet#setCriteria resultSet.setCriteria()}.
* <p>
* Changes to criteria may or may not result in a DSRequest to the server due to
* {@linkplain com.smartgwt.client.data.ResultSet#setUseClientFiltering client-side filtering}. You can call
* {@link com.smartgwt.client.data.ResultSet#willFetchData willFetchData(criteria)} to determine if new criteria will
* result in a server fetch.
* <P>
* If you need to force data to be re-fetched, you can call
* {@link com.smartgwt.client.widgets.grid.ListGrid#invalidateCache invalidateCache()} and new data will
* automatically be fetched from the server using the current criteria and sort direction. <b>NOTE:</b>
* when using <code>invalidateCache()</code> there is no need to <b>also</b> call <code>fetchData()</code>
* and in fact this could produce unexpected results.
* <p>
* This method takes an optional callback parameter (set to a {@link com.smartgwt.client.data.DSCallback})
* to fire when the fetch completes. Note that this callback will not fire if no server fetch is performed.
* In this case the data is updated synchronously, so as soon as this method completes you
* can interact with the new data. If necessary, you can use
* {@link com.smartgwt.client.data.ResultSet#willFetchData resultSet.willFetchData()} to determine whether or not a server
* fetch will occur when <code>fetchData()</code> is called with new criteria.
* <p>
* In addition to the callback parameter for this method, developers can use
* {@link com.smartgwt.client.data.ResultSet#addDataArrivedHandler resultSet.addDataArrivedHandler} to be notified every time data is loaded.
*/
void fetchData();
/**
* Retrieves data from the DataSource that matches the specified criteria.
* <p>
* When <code>fetchData()</code> is first called, if data has not already been provided via
* <code>setData()</code>, this method will create a {@link com.smartgwt.client.data.ResultSet}, which will be
* configured based on component settings such as {@link #setFetchOperation fetchOperation} and {@link #setDataPageSize dataPageSize}, as well
* as the general purpose <code>dataProperties</code>. The created ResultSet will automatically send a DSRequest
* to retrieve data from {@linkplain #setDataSource the dataSource}, and from then on will
* automatically manage paging through large datasets, as well as performing filtering and
* sorting operations inside the browser when possible - see the ResultSet docs for
* details.
* <p>
* <b>NOTE:</b> do not use <b>both</b> {@link #setAutoFetchData autoFetchData} <b>and</b> a
* call to <code>fetchData()</code> - this may result in two DSRequests to fetch data. Use
* either {@link #setAutoFetchData autoFetchData} and <code>setAutoFetchCriteria()</code> <b>or</b> a manual call to fetchData()
* passing criteria.
* <p>
* Whether a ResultSet was automatically created or provided via <code>setData()</code>, subsequent
* calls to fetchData() will simply call {@link com.smartgwt.client.data.ResultSet#setCriteria resultSet.setCriteria()}.
* <p>
* Changes to criteria may or may not result in a DSRequest to the server due to
* {@linkplain com.smartgwt.client.data.ResultSet#setUseClientFiltering client-side filtering}. You can call
* {@link com.smartgwt.client.data.ResultSet#willFetchData willFetchData(criteria)} to determine if new criteria will
* result in a server fetch.
* <P>
* If you need to force data to be re-fetched, you can call
* {@link com.smartgwt.client.widgets.grid.ListGrid#invalidateCache invalidateCache()} and new data will
* automatically be fetched from the server using the current criteria and sort direction. <b>NOTE:</b>
* when using <code>invalidateCache()</code> there is no need to <b>also</b> call <code>fetchData()</code>
* and in fact this could produce unexpected results.
* <p>
* This method takes an optional callback parameter (set to a {@link com.smartgwt.client.data.DSCallback})
* to fire when the fetch completes. Note that this callback will not fire if no server fetch is performed.
* In this case the data is updated synchronously, so as soon as this method completes you
* can interact with the new data. If necessary, you can use
* {@link com.smartgwt.client.data.ResultSet#willFetchData resultSet.willFetchData()} to determine whether or not a server
* fetch will occur when <code>fetchData()</code> is called with new criteria.
* <p>
* In addition to the callback parameter for this method, developers can use
* {@link com.smartgwt.client.data.ResultSet#addDataArrivedHandler resultSet.addDataArrivedHandler} to be notified every time data is loaded.
*
* @param criteria Search criteria. If a {@link com.smartgwt.client.widgets.form.DynamicForm}
* is passed in as this argument instead of a raw criteria object, will be
* derived by calling {@link com.smartgwt.client.widgets.form.DynamicForm#getValuesAsCriteria}
*/
void fetchData(Criteria criteria);
/**
* Retrieves data from the DataSource that matches the specified criteria.
* <p>
* When <code>fetchData()</code> is first called, if data has not already been provided via
* <code>setData()</code>, this method will create a {@link com.smartgwt.client.data.ResultSet}, which will be
* configured based on component settings such as {@link #setFetchOperation fetchOperation} and {@link #setDataPageSize dataPageSize}, as well
* as the general purpose <code>dataProperties</code>. The created ResultSet will automatically send a DSRequest
* to retrieve data from {@linkplain #setDataSource the dataSource}, and from then on will
* automatically manage paging through large datasets, as well as performing filtering and
* sorting operations inside the browser when possible - see the ResultSet docs for
* details.
* <p>
* <b>NOTE:</b> do not use <b>both</b> {@link #setAutoFetchData autoFetchData} <b>and</b> a
* call to <code>fetchData()</code> - this may result in two DSRequests to fetch data. Use
* either {@link #setAutoFetchData autoFetchData} and <code>setAutoFetchCriteria()</code> <b>or</b> a manual call to fetchData()
* passing criteria.
* <p>
* Whether a ResultSet was automatically created or provided via <code>setData()</code>, subsequent
* calls to fetchData() will simply call {@link com.smartgwt.client.data.ResultSet#setCriteria resultSet.setCriteria()}.
* <p>
* Changes to criteria may or may not result in a DSRequest to the server due to
* {@linkplain com.smartgwt.client.data.ResultSet#setUseClientFiltering client-side filtering}. You can call
* {@link com.smartgwt.client.data.ResultSet#willFetchData willFetchData(criteria)} to determine if new criteria will
* result in a server fetch.
* <P>
* If you need to force data to be re-fetched, you can call
* {@link com.smartgwt.client.widgets.grid.ListGrid#invalidateCache invalidateCache()} and new data will
* automatically be fetched from the server using the current criteria and sort direction. <b>NOTE:</b>
* when using <code>invalidateCache()</code> there is no need to <b>also</b> call <code>fetchData()</code>
* and in fact this could produce unexpected results.
* <p>
* This method takes an optional callback parameter (set to a {@link com.smartgwt.client.data.DSCallback})
* to fire when the fetch completes. Note that this callback will not fire if no server fetch is performed.
* In this case the data is updated synchronously, so as soon as this method completes you
* can interact with the new data. If necessary, you can use
* {@link com.smartgwt.client.data.ResultSet#willFetchData resultSet.willFetchData()} to determine whether or not a server
* fetch will occur when <code>fetchData()</code> is called with new criteria.
* <p>
* In addition to the callback parameter for this method, developers can use
* {@link com.smartgwt.client.data.ResultSet#addDataArrivedHandler resultSet.addDataArrivedHandler} to be notified every time data is loaded.
*
* @param criteria Search criteria. If a {@link com.smartgwt.client.widgets.form.DynamicForm}
* is passed in as this argument instead of a raw criteria object, will be
* derived by calling {@link com.smartgwt.client.widgets.form.DynamicForm#getValuesAsCriteria}
* @param callback callback to invoke when a fetch is complete. Fires only
* if server contact was required
*/
void fetchData(Criteria criteria, DSCallback callback);
/**
* Retrieves data from the DataSource that matches the specified criteria.
* <p>
* When <code>fetchData()</code> is first called, if data has not already been provided via
* <code>setData()</code>, this method will create a {@link com.smartgwt.client.data.ResultSet}, which will be
* configured based on component settings such as {@link #setFetchOperation fetchOperation} and {@link #setDataPageSize dataPageSize}, as well
* as the general purpose <code>dataProperties</code>. The created ResultSet will automatically send a DSRequest
* to retrieve data from {@linkplain #setDataSource the dataSource}, and from then on will
* automatically manage paging through large datasets, as well as performing filtering and
* sorting operations inside the browser when possible - see the ResultSet docs for
* details.
* <p>
* <b>NOTE:</b> do not use <b>both</b> {@link #setAutoFetchData autoFetchData} <b>and</b> a
* call to <code>fetchData()</code> - this may result in two DSRequests to fetch data. Use
* either {@link #setAutoFetchData autoFetchData} and <code>setAutoFetchCriteria()</code> <b>or</b> a manual call to fetchData()
* passing criteria.
* <p>
* Whether a ResultSet was automatically created or provided via <code>setData()</code>, subsequent
* calls to fetchData() will simply call {@link com.smartgwt.client.data.ResultSet#setCriteria resultSet.setCriteria()}.
* <p>
* Changes to criteria may or may not result in a DSRequest to the server due to
* {@linkplain com.smartgwt.client.data.ResultSet#setUseClientFiltering client-side filtering}. You can call
* {@link com.smartgwt.client.data.ResultSet#willFetchData willFetchData(criteria)} to determine if new criteria will
* result in a server fetch.
* <P>
* If you need to force data to be re-fetched, you can call
* {@link com.smartgwt.client.widgets.grid.ListGrid#invalidateCache invalidateCache()} and new data will
* automatically be fetched from the server using the current criteria and sort direction. <b>NOTE:</b>
* when using <code>invalidateCache()</code> there is no need to <b>also</b> call <code>fetchData()</code>
* and in fact this could produce unexpected results.
* <p>
* This method takes an optional callback parameter (set to a {@link com.smartgwt.client.data.DSCallback})
* to fire when the fetch completes. Note that this callback will not fire if no server fetch is performed.
* In this case the data is updated synchronously, so as soon as this method completes you
* can interact with the new data. If necessary, you can use
* {@link com.smartgwt.client.data.ResultSet#willFetchData resultSet.willFetchData()} to determine whether or not a server
* fetch will occur when <code>fetchData()</code> is called with new criteria.
* <p>
* In addition to the callback parameter for this method, developers can use
* {@link com.smartgwt.client.data.ResultSet#addDataArrivedHandler resultSet.addDataArrivedHandler} to be notified every time data is loaded.
*
* @param criteria Search criteria. If a {@link com.smartgwt.client.widgets.form.DynamicForm}
* is passed in as this argument instead of a raw criteria object,
* will be derived by calling {@link com.smartgwt.client.widgets.form.DynamicForm#getValuesAsCriteria}
* @param callback callback to invoke when a fetch is complete. Fires
* only if server contact was required
* @param requestProperties additional properties to set on the DSRequest
* that will be issued
*/
void fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties);
/**
* Retrieves data that matches the provided criteria and displays the matching data in this component. <P> This
* method behaves exactly like {@link com.smartgwt.client.widgets.grid.ListGrid#fetchData} except that {@link
* com.smartgwt.client.data.DSRequest#getTextMatchStyle textMatchStyle} is automatically set to "substring" so that
* String-valued fields are matched by case-insensitive substring comparison.
*
* @param criteria Search criteria. If a {@link com.smartgwt.client.widgets.form.DynamicForm}
* is passed in as this argument instead of a raw criteria object, will be
* derived by calling {@link com.smartgwt.client.widgets.form.DynamicForm#getValuesAsCriteria}
*/
void filterData();
/**
* Retrieves data that matches the provided criteria and displays the matching data in this component. <P> This
* method behaves exactly like {@link com.smartgwt.client.widgets.grid.ListGrid#fetchData} except that {@link
* com.smartgwt.client.data.DSRequest#getTextMatchStyle textMatchStyle} is automatically set to "substring" so that
* String-valued fields are matched by case-insensitive substring comparison.
*
* @param criteria Search criteria. If a {@link com.smartgwt.client.widgets.form.DynamicForm}
* is passed in as this argument instead of a raw criteria object, will be
* derived by calling {@link com.smartgwt.client.widgets.form.DynamicForm#getValuesAsCriteria}
* @param callback callback to invoke when a fetch is complete. Fires only
* if server contact was required; see {@link
* #fetchData} for details
*/
void filterData(Criteria criteria);
/**
* Retrieves data that matches the provided criteria and displays the matching data in this component. <P> This
* method behaves exactly like {@link com.smartgwt.client.widgets.grid.ListGrid#fetchData} except that {@link
* com.smartgwt.client.data.DSRequest#getTextMatchStyle textMatchStyle} is automatically set to "substring" so that
* String-valued fields are matched by case-insensitive substring comparison.
*
* @param criteria Search criteria. If a {@link com.smartgwt.client.widgets.form.DynamicForm}
* is passed in as this argument instead of a raw criteria object,
* will be derived by calling {@link com.smartgwt.client.widgets.form.DynamicForm#getValuesAsCriteria}
* @param callback callback to invoke when a fetch is complete. Fires
* only if server contact was required; see
* {@link #fetchData} for details
*/
void filterData(Criteria criteria, DSCallback callback);
/**
* Retrieves data that matches the provided criteria and displays the matching data in this component. <P> This
* method behaves exactly like {@link com.smartgwt.client.widgets.grid.ListGrid#fetchData} except that {@link
* com.smartgwt.client.data.DSRequest#getTextMatchStyle textMatchStyle} is automatically set to "substring" so that
* String-valued fields are matched by case-insensitive substring comparison.
*
* @param criteria Search criteria. If a {@link com.smartgwt.client.widgets.form.DynamicForm}
* is passed in as this argument instead of a raw criteria object,
* will be derived by calling {@link com.smartgwt.client.widgets.form.DynamicForm#getValuesAsCriteria}
* @param callback callback to invoke when a fetch is complete. Fires
* only if server contact was required; see
* {@link #fetchData} for details
* @param requestProperties for databound components only - optional additional
* properties to set on the DSRequest that will be issued
*/
void filterData(Criteria criteria, DSCallback callback, DSRequest requestProperties);
/**
* If true, when this component is first drawn, automatically call {@link #fetchData()} or {@link #filterData()} depending on
* {@link #getAutoFetchAsFilter()} . Criteria for this fetch may be picked up from {@link #getInitialCriteria() initialCriteria}
* and textMatchStyle may be specified via {@link #getAutoFetchTextMatchStyle}. <P>
* <font color='red'>NOTE:</font> If autoFetchData is set, calling ListGrid.fetchData() before draw will cause two requests to be
* issued, one from the manual call to fetchData() and one from the autoFetchData setting. The second request will use only
* {@link #getInitialCriteria() initialCriteria} and not any other criteria or settings from the first request. Generally, turn off
* autoFetchData if you are going to manually call fetchData() at any time.
*
* @param autoFetchData autoFetchData
*/
void setAutoFetchData(Boolean autoFetchData);
/**
* If true, when this component is first drawn, automatically call {@link #fetchData()} or {@link #filterData()} depending on
* {@link #getAutoFetchAsFilter()} . Criteria for this fetch may be picked up from {@link #getInitialCriteria() initialCriteria}
* and textMatchStyle may be specified via {@link #getAutoFetchTextMatchStyle}. <P>
* <font color='red'>NOTE:</font> If autoFetchData is set, calling ListGrid.fetchData() before draw will cause two requests to be
* issued, one from the manual call to fetchData() and one from the autoFetchData setting. The second request will use only
* {@link #getInitialCriteria() initialCriteria} and not any other criteria or settings from the first request. Generally, turn off
* autoFetchData if you are going to manually call fetchData() at any time.
*
* @return autoFetchData autoFetchData
*/
Boolean getAutoFetchData();
/**
* If {@link #setAutoFetchData(Boolean)} is true, this attribute determines whether the initial fetch operation should be
* performed via {@link #fetchData()} or {@link #filterData()}
*
* @param autoFetchAsFilter autoFetchAsFilter
*/
void setAutoFetchAsFilter(Boolean autoFetchAsFilter);
/**
* If {@link #setAutoFetchData(Boolean)} is true, this attribute determines whether the initial fetch operation should be
* performed via {@link #fetchData()} or {@link #filterData()}
*
* @return auto fetch as filter
*/
Boolean getAutoFetchAsFilter();
/**
* If {@link #getAutoFetchData autoFetchData} is <code>true</code>, this attribute allows the developer to specify a textMatchStyle
* for the initial {@link #fetchData} call.
*
* @param autoFetchTextMatchStyle autoFetchTextMatchStyle
*/
void setAutoFetchTextMatchStyle(TextMatchStyle autoFetchAsFilter);
/**
* If {@link #getAutoFetchData autoFetchData} is <code>true</code>, this attribute allows the developer to specify a textMatchStyle
* for the initial {@link #fetchData} call.
*
* @return autoFetchTextMatchStyle autoFetchTextMatchStyle
*/
TextMatchStyle getAutoFetchTextMatchStyle();
/**
* Criteria to use when {@link #setAutoFetchData(Boolean)} is used.
*
* @param initialCriteria the initial criteria
* @throws IllegalStateException this property cannot be changed after the component has been created
*/
void setInitialCriteria(Criteria initialCriteria) throws IllegalStateException;
/**
* Criteria to use when {@link #setAutoFetchData(Boolean)} is used.
*
* @return the criteria
*/
Criteria getInitialCriteria();
/**
* Invalidate the current data cache for this databound component via a call to
<code>this.data.invalidateCache()</code>. If necessary, this will cause a new fetch to
be performed with the current set of criteria for this component.
<P>
Has no effect if this component is not showing a set of filtered data.
*/
void invalidateCache();
/**
* Return the underlying data of this DataBoundComponent as a {@link com.smartgwt.client.data.ResultSet}.
* <p>
* Note that this method should only be called after initial data has been fetched by this DataBoundComponent.
*
* @return ResultSet, or null if the underlying data is not a ResultSet
* @see #fetchData()
*/
ResultSet getResultSet();
/**
* Return the underlying data of this DataBoundComponent as a {@link com.smartgwt.client.data.RecordList}.
* <p>
* Depending on the component configuration, the actual JavaScript instance of the returned
* RecordList may be one of several types: <ul>
* <li>If the component is not bound to a {@link com.smartgwt.client.data.DataSource},
* the instance is generally an Array of {@link com.smartgwt.client.data.Record}.</li>
* <li>If the component is bound to a DataSource, the instance is a
* {@link com.smartgwt.client.data.ResultSet}.</li>
* <li>If the component is a grouped ListGrid, the instance is a
* {@link com.smartgwt.client.widgets.tree.Tree}.
* To access the ungrouped record list regardless of grouping status, use
* <pre>isGrouped() ? getOriginalRecordList() : getRecordList()</pre></li>
* <li>If the component is a {@link com.smartgwt.client.widgets.tree.TreeGrid},
* the instance is a ResultTree.</li>
* </ul>The underlying type determines the structure of the returned data.
* An Array or ResultSet represents a list of records, but a Tree or ResultTree represents
* a list of open rows in the tree, including groups or other nodes which contain no records.
*
* @return the RecordList
*/
RecordList getRecordList();
JavaScriptObject getDataAsJSList();
/**
* Uses a "fetch" operation on the current {@link com.smartgwt.client.widgets.DataBoundComponent#getDataSource DataSource}
* to retrieve data that matches the current filter and sort criteria for this component, then exports the resulting data
* to a file or window in the requested format. <P> A variety of DSRequest settings, such as {@link
* com.smartgwt.client.data.DSRequest#getExportAs exportAs} and {@link com.smartgwt.client.data.DSRequest#getExportFilename
* exportFilename}, affect the exporting process: see {@link com.smartgwt.client.data.DSRequest#getExportResults
* exportResults} for further detail. <P> Note that data exported via this method does not include any client-side
* formatting and relies on both the Smart GWT server and server-side DataSources. To export client-data with formatters
* applied, see {@link com.smartgwt.client.widgets.DataBoundComponent#exportClientData exportClientData}, which still
* requires the Smart GWT server but does not rely on server-side DataSources. <P> For more information on exporting data,
* see {@link com.smartgwt.client.data.DataSource#exportData DataSource.exportData}.
* @see com.smartgwt.client.docs.DataBoundComponentMethods DataBoundComponentMethods overview and related methods
*/
void exportData();
/**
* Uses a "fetch" operation on the current {@link com.smartgwt.client.widgets.DataBoundComponent#getDataSource DataSource}
* to retrieve data that matches the current filter and sort criteria for this component, then exports the resulting data
* to a file or window in the requested format. <P> A variety of DSRequest settings, such as {@link
* com.smartgwt.client.data.DSRequest#getExportAs exportAs} and {@link com.smartgwt.client.data.DSRequest#getExportFilename
* exportFilename}, affect the exporting process: see {@link com.smartgwt.client.data.DSRequest#getExportResults
* exportResults} for further detail. <P> Note that data exported via this method does not include any client-side
* formatting and relies on both the Smart GWT server and server-side DataSources. To export client-data with formatters
* applied, see {@link com.smartgwt.client.widgets.DataBoundComponent#exportClientData exportClientData}, which still
* requires the Smart GWT server but does not rely on server-side DataSources. <P> For more information on exporting data,
* see {@link com.smartgwt.client.data.DataSource#exportData DataSource.exportData}.
* @param requestProperties additional properties to set on the DSRequest that will be issued
* @see com.smartgwt.client.docs.DataBoundComponentMethods DataBoundComponentMethods overview and related methods
*/
void exportData(DSRequest requestProperties);
/**
* Shows a HiliteEditor interface allowing end-users to edit the data-hilites currently in use by this DataBoundComponent.
*/
void editHilites();
/**
* Get the current hilites encoded as a String, for saving.
*
* @return the hilite state
*/
String getHiliteState();
/**
* Set the current hilites based on a hiliteState String previously returned from getHilitesState.
*
* @param hiliteState hilites state encoded as a String
*/
void setHiliteState(String hiliteState);
/**
* Accepts an array of hilite objects and applies them to this DataBoundComponent. See also {@link #getHilites() getHilites} for a method of
* retrieving the hilite array for storage, including hilites manually added by the user.
*
* @param hilites array of hilite objects
*/
void setHilites(Hilite[] hilites);
/**
* Return the set of hilite-objects currently applied to this DataBoundComponent. These can be saved for
* storage and then restored to a component later via setHilites().
*
* @return array of hilite objects
*/
Hilite[] getHilites();
}