Progress.Data.BindingSource class

(Windows only; GUI for .NET only)

A BindingSource object (the ProBindingSource) that allows you to bind a .NET control on a form to one of the following ABL data source objects:

A query involving a temp-table or database table (which can be a join query)

A ProDataSet object

A Buffer object

Note: Progress Software Corporation recommends that you open (or reopen) any query associated with a ProBindingSource instance using the PRESELECT option, which optimizes query performance.

The Progress.Data.BindingSource class is an OpenEdge .NET class that extends the .NET System.Windows.Forms.BindingSource class. The ProBindingSource acts as a conduit between a .NET control and an ABL data source object. A bound .NET control considers the ProBindingSource to be its data source. In turn, the ProBindingSource sets the underlaying ABL data source object as its data source. For a complete overview of data binding between .NET controls and ABL data source objects, see OpenEdge Development: GUI for .NET Programming.

Constructors

PUBLIC BindingSource ( INPUT `query-hdl` AS HANDLE [ , INPUT `include-fields` AS CHARACTER, INPUT `except-fields` AS CHARACTER ] ) PUBLIC BindingSource ( INPUT `dataset-hdl` AS HANDLE [ , { INPUT `parent-buffer-name` AS CHARACTER \| INPUT `parent-buffer-hdl` AS HANDLE } ] [ , INPUT `include-fields` AS CHARACTER, INPUT `except-fields` AS CHARACTER ] ) PUBLIC BindingSource ( INPUT `buffer-hdl` AS HANDLE [ , INPUT `include-fields` AS CHARACTER, INPUT `except-fields` AS CHARACTER ] ) PUBLIC BindingSource ( )

PUBLIC BindingSource ( INPUT query-hdl AS HANDLE 
                  [ , INPUT include-fields AS CHARACTER, 
                       INPUT except-fields AS CHARACTER ] ) 
PUBLIC BindingSource ( INPUT dataset-hdl AS HANDLE 
                  [ , { INPUT parent-buffer-name AS CHARACTER  
                         | INPUT parent-buffer-hdl AS HANDLE } ] 
                  [ , INPUT include-fields AS CHARACTER,  
                      INPUT except-fields AS CHARACTER ] ) 
PUBLIC BindingSource ( INPUT buffer-hdl AS HANDLE  
                  [ , INPUT include-fields AS CHARACTER,  
                      INPUT except-fields AS CHARACTER ] ) 
PUBLIC BindingSource ( )

query-hdl

A HANDLE variable that represents the handle to a query object.

dataset-hdl

A HANDLE variable that represents the handle to a ProDataSet object.

buffer-hdl

A HANDLE variable that represents the handle to a buffer object.

parent-buffer-name

A CHARACTER variable that represents the name of a parent buffer in a ProDataSet object. This corresponds to the top-level table displayed in a hierarchical control (such as a grid or a treeview).

parent-buffer-hdl

A HANDLE variable that represents the handle to a parent buffer in a ProDataSet object. This corresponds to the top-level table displayed in a hierarchical control (such as a grid or a treeview).

include-fields

An optional CHARACTER expression that evaluates to a comma-separated list of fields in the ABL data source object to bind to the ProBindingSource. To include all fields, specify an asterisk (“*”) in include-fields. To include all but a few fields, specify an asterisk (“*”) in include-fields and a comma-separated list of fields to exclude in except-fields. If include-fields contains specific fields, except-fields is ignored.

When including fields for a ProDataSet object, you must specify a comma-separated list of fields to display in display order and qualify the field names with their buffer name. For example:


"table1.field1, table1.field2, table2.field1, table1.field3"

You must specify at least one field from each table in the hierarchy to be displayed.

When including fields for a query or a join query, you must specify a comma-separated list of fields to display in display order and you should qualify ambiguous field names with their buffer name.

Do not specify a RAW temp-table or a database field in include-fields. If you explicitly specify a RAW field, the AVM generates a run-time error. If you specify an asterisk (“*”) to include all fields and there is a RAW field in the table, the AVM excludes it automatically even if it is not specified in except-fields.

except-fields

A CHARACTER expression that evaluates to a comma-separated list of fields in the ABL data source object to exclude from binding to the ProBindingSource. You can specify fields to exclude only when include-fields contains an asterisk (“*”). If you do not have any fields to exclude, you must specify the empty string (“”). If include-fields contains specific fields, except-fields is ignored.

Binding to a query associated with a temp-table or database table

When binding to a temp-table or database table through a query, consider the following:

The query may, or may not, be part of a ProDataSet object.

The query can be either static or dynamic.

You use a handle to access either a static or a dynamic query.

The query must be scrolling. That is, a static query must be defined with the SCROLLING keyword and a dynamic query, which defaults to scrolling, must remain that way (its FORWARD-ONLY attribute must be FALSE).

The query can be a join involving one or more tables. In this case, one row is displayed in the control for each result list entry.

The ProBindingSource takes information from the table schema definition and makes it available to the bound .NET control for headings and labels. The ProBindingSource determines headings and labels by using either the column label (if defined), the field label (if defined), or the field name from the schema.

If the query is a join with duplicate field names in the tables, you should qualify the field names with the buffer names using the buffer-name.field-name syntax. Also, the ProBindingSource treats elements in an array field as separate fields and makes them unique by appending their array subscript using the array-name[subscript] syntax.

If the .NET control does not handle sorting on its own, you can do either of the following:

Let the ProBindingSource automatically sort records in the ABL data source object by setting the AutoSort property to TRUE.

Define a trigger to handle a SortRequest event.

Note: If you need to reopen the query, you must do so using the QUERY-PREPARE and QUERY-OPEN methods (not the OPEN QUERY statement). Progress Software Corporation recommends that you reopen the query using the PRESELECT option, which optimizes query performance.

The ProBindingSource automatically changes currency in the query (as reflected by the Position property) as the selected row in the bound .NET control changes.

Binding to a ProDataSet object

Binding to a ProDataSet object enables you to create a hierarchical display of a parent buffer and its child buffers in the same .NET control (such as a grid or a treeview). When binding to a ProDataSet object, consider the following:

The ProDataSet object can contain one or more parent and child buffers (and a set of data relations describing the relationship between the parent and child buffers).

The ProDataSet object can be either static or dynamic.

You use a handle to access either a static or dynamic ProDataSet object.

You can identify a temp-table in a ProDataSet object by either its name or its handle.

To bind a hierarchy of parent and child buffers to a single .NET control, specify a parent buffer from the ProDataSet object as the top-level table to display in the .NET control. A parent buffer is typically a top-level buffer in the ProDataSet object, but it need not be. Any child buffers of the specified parent buffer are automatically included in the hierarchy. The ProBindingSource makes a buffer’s data available to a bound .NET control as follows:

If you specify a parent buffer that is a top-level buffer, the ProBindingSource uses the buffer’s top-level navigation query (specified by the TOP-NAV-QUERY attribute) to populate the primary set of records, and uses the data-relation queries associated with each of the child buffers for subsequent levels.

If you specify a parent buffer that is not a top-level buffer, the ProBindingSource uses the buffer’s data-relation query to populate the primary set of records, and uses the data-relation queries associated with each of the child buffers for subsequent levels.

If you specify a buffer that is not a parent buffer (that is, a buffer that has no child buffers), the ProBindingSource binds to a single table. You can achieve this same result by binding to the buffer’s top-level navigation query (specified by the TOP-NAV-QUERY attribute) or its data-relation query.

If you do not specify any buffer, the ProBindingSource binds to the first top-level buffer in the ProDataSet object. The first top-level buffer is based on the order in which the buffers were defined or added in the ProDataSet object, and it matches the result from GET-TOP-BUFFER(1).

To display both parent and child buffers within the same .NET control, use a single ProBindingSource instance bound to the ProDataSet object. To display the parent and child buffers in separate .NET controls, use separate ProBindingSource instances bound to their respective queries.

The ProBindingSource automatically changes currency in the parent buffer (as reflected by the Position property) as the selected parent or child row in the bound .NET control changes.

For more information on how the ProBindingSource manages currency between parent and child buffers, including a code example, see the data-binding chapter in OpenEdge Development: GUI for .NET Programming.

When the user first expands (not selects) a parent row in the bound .NET control, all of the child rows for that parent row are displayed. The ProBindingSource uses the ProDataSet object’s data-relation query to create and maintain a unique query for all child rows related to the expanded parent row. For example, if the user expands multiple parent rows, there will be an open child query for each expanded parent row based on the corresponding parent record.

The ProBindingSource takes information from the ProDataSet object schema definition and makes it available to the bound .NET control for headings and labels. The ProBindingSource determines headings and labels by using either the column label (if defined), the field label (if defined), or the field name from the schema.

Binding to a buffer object

When binding to a temp-table or database buffer, consider the following:

The buffer might (but not necessarily) be part of a ProDataSet object.

The buffer can be either static or dynamic.

You use a handle to access either a static or dynamic buffer.

Use a buffer as a data source for one or more single-value controls (such as a check box or a text box).

The Position property value will always be set to zero. Therefore, you must manage currency for the buffer by changing the record in the ABL data source object programatically.

Binding to an unbound ProBindingSource instance

An unbound ProBindingSource instance is created by invoking the ProBindingSource constructor with no parameters. When binding to an unbound ProBindingSource instance, consider the following:

To limit which fields are exposed in the data source object, use the SetFields( ) method before binding to the data source object.

You must bind an unbound ProBindingSource object instance to an ABL data source object at run time by setting the ProBindingSource’s Handle property to the handle of the associated ABL data source object.

When you set the ProBindingSource’s Handle property, the AVM includes, by default, all fields from the ABL data source object’s schema in the .NET control. (This is equivalent to specifying an asterisk (“*”) in the include-fields parameter when invoking a ProBindingSource constructor with parameters.) If you want to limit the available fields, you must use the ProBindingSource’s SetFields( ) method before you specify the Handle property. Attempting to use the SetFields( ) method after specifying the Handle property causes the ProBindingSource to throw a .NET exception.

Super Class

System.Windows.Forms.BindingSource class (from the .NET Framework)

Interfaces

This class does not implement interfaces (beyond those it inherits from its base class).

Public
Properties


AllowEdit property	AllowNew property	AllowRemove property
AutoSort property	AutoSync property	AutoUpdate property
Batching property	ChildAllowEdit property	ChildAllowNew property
ChildAllowRemove property	ChildInputValue property	Count property
Handle property	InputValue property	MaxDataGuess property
NewRow property	NoLOBs property	Position property
RowModified property	TableSchema property	Tag property (Progress.Data.BindingSource)

Public
Methods


Assign( ) method	Dispose( ) method
Refresh( ) method	RefreshAll( ) method
SetFields( ) method	–

Public
Events


CreateRow event	CancelCreateRow event
OffEnd event (.NET)	PositionChanged event
SortRequest event	–

Notes

Since you are working with a combination of .NET controls and ABL objects, it is important to remember that .NET control parameter and property indexes are always zero-based values and ABL indexes are always one-based values.

For information on the public class members inherited from the System.Windows.Forms.BindingSource class, refer to the .NET Framework class library.