About the IWSIDOCollection interface
The IWSIDOCollection interface is a result set retrieved by WinStudio from an IDO into a local cache. To access the IWSIDOCollection interface, use the following IWSForm methods and properties:
- PrimaryIDOCollection property
- CurrentIDOCollection property
- GetSecondaryIDOCollection method
Data is retrieved and placed in an IDO collection whenever WinStudio performs a refresh (query) operation. Data is moved from the IDO collection to the middle tier IDO whenever WinStudio performs a save operation. Otherwise, WinStudio data operations involve interactions with the IWSIDOCollection interface itself. A new operation, for instance, adds a new member to the IDO collection. A delete operation marks a collection member for deletion. Any changes of values to fields are represented as changes to the IWSIDOCollection properties. All of these kinds of changes are committed to the middle tier and ultimately to the database when a WinStudio save operation is performed.
A separate IWSIDOCollection interface cache exists for each primary collection, secondary collection, and subcollection bound to a form or form component. Access the primary IDO collection using the form's PrimaryIDOCollection property.
Example:
' Assign the form's primary IDOCollection to oPrimaryIDOCollection
Dim oPrimaryIDOCOllection As IWSIDOCOllection
oPrimaryIDOCollection = ThisForm.PrimayrIDOCollection
Retrieve secondary IDO collection caches using the form's GetSecondaryIDOCollection method. Note that the GetSecondaryIDOCollection parameter is 2-based. That is, the first secondary IDO collection is retrieved with GetSecondaryIDOCollection(2); the second is retrieved with GetSecondaryIDOCollection(3); and so on. This numbering makes the method consistent with the notation used to reference the secondary IDO collection caches.
' Assign the form's first secondary IDO collection (that is, objects2) to oSecondaryIDOCollection
Dim oSecondaryIDOCollection As IWSIDOCollection
oSecondaryIDOCollection = ThisForm.GetSecondaryIDOCollection(2)
To retrieve a subcollection, use the GetSubCollection method on the grid component to which the subcollection is bound.
Dim oSubCollection As IWSIDOCollection
Dim i As Integer
oSubCollection = ThisForm.PrimaryIDOCollection.GetSubCollection("ItemOrderLines", i)
The current object
Every IDO collection has a current object (IDO item). This is the member of the IDO collection that is currently active in the user interface. You can retrieve and manipulate property values of the current object using the GetCurrentObjectProperty and SetCurrentObjectProperty methods.
' Assign the value of the Name property of the primary IDOCollection's
' current object to strName.
Dim strName as String
StrName = ThisForm.PrimaryIDOCollection.GetCurrentObjectProperty("Name")
The current object can be set by using the First, Last, Next, Previous, and SetCurrentObject methods.
Accessing an IDO collection member object by index
Any IDO collection member can be accessed by its index in the IDO collection, whether or not it is the current item. Many of the same operations are available for items accessed by index as for current items:
| Current Object Operation | Indexed Object Operation |
|---|---|
| GetCurrentObjectProperty | GetObjectProperty |
| IsCurrentObjectAutoInsertedAndUnmodified | IsObjectAutoInsertedAndUnmodified |
| IsCurrentObjectDeleted | IsObjectDeleted |
| IsCurrentObjectInvalid | IsObjectInvalid |
| IsCurrentObjectModified | IsObjectModified |
| IsCurrentObjectNew | IsObjectNew |
| IsCurrentObjectNewAndUnmodified | IsObjectNewAndUnmodified |
| IsCurrentObjectTheAutoInsertRow | IsObjectTheAutoInsertRow |
| SetCurrentObjectModified | SetObjectModified |
| SetCurrentObjectProperty | SetObjectProperty |
| SetCurrentObjectPropertyModified | SetObjectPropertyModified |
Updating a property of an IDO collection member
A property of an IDO collection member object can be updated using the SetObjectProperty or SetCurrentObjectProperty method. These methods update the property in the IDO collection, but they do not mark the property as modified. Unless the property is marked as modified, it will not participate in the normal automatic save processing. To mark the property as modified, use the SetObjectPropertyModified or SetCurrentObjectPropertyModified method.
In addition to the property, you must mark the IDO collection member object as modified to ensure that it is included in the automatic save processing. To do this, use the SetObjectModified or SetCurrentObjectModified method.
Finally, setting an object's property does not automatically cause form components that are bound to, or dependent on, the property to refresh themselves. Accomplish this by calling the NotifyDependentsToRefresh method. The following code sample illustrates each of these methods.
' Assign the form's primary IDOCollection to oIDOCollection
Dim oIDOCollection As IWSIDOCollection
oIDOCollection = ThisForm.PrimaryIDOCollection
' Update the current object's Name property
oIDOCollection.SetCurrentObjectProperty("Name", "Jane Doe")
' Set the property as modified so that our change will be
' be automatically saved when the object is updated.
oIDOCollection.SetCurrentObjectPropertyModified("Name", True)
' Mark the object itself as modified so that it will be updated
' when the IDOCollection is saved.
oIDOCollection.SetCurrentObjectModified(True)
' Force any components that are dependent on Name to
' refresh themselves
oIDOCollection.NotifyDependentsToRefresh("Name")
The sequence of method calls in this example is so common that WinStudio provides a single method that updates, marks as modified, and notifies the dependents of a property. The following code performs exactly the same operations as the previous example.
' Assign the form's primary IDOCollection to oIDOCollection
Dim oIDOCollection As IWSIDOCollection
oIDOCollection = ThisForm.PrimaryIDOCollection
' Update the current object's Name property, set the
' property as modified and notify components to refresh
oIDOCollection.SetCurrentObjectPropertyPlusModifyRefresh("Name", "New Name")
' Mark the object itself as modified so that it will be
' updated when the IDOCollection is saved.
oIDOCollection.SetCurrentObjectModified(True)
Iterating an IDO collection
The indexed IDO collection member object methods are useful when you need to iterate through all of the objects in an IDO collection. The following code iterates through a form's primary IDO collection and sums all of the Qty properties.
Dim i as Integer
Dim iTotal as Integer
Dim oPrimaryIDOCollection As IWSIDOCollection
' Assign PrimaryIDOCollection to oPrimaryIDOCollection
oPrimaryIDOCollection = ThisForm.PrimaryIDOCollection
' Initialize accumulator
iTotal = 0
For i = 0 To oPrimaryIDOCollection.GetNumEntries - 1
iTotal = iTotal + oPrimaryIDOCollection.GetObjectProperty("Qty", i)
Next i