DataRepeater Control

The DataRepeater control functions as a scrollable container of data-bound user controls. Each control appears in its own row as a "repeated" control, allowing the user to view several data-bound user controls at once.

Syntax

DataRepeater

Remarks

To use the DataRepeater control, you must first create a data-bound user control, and compile it into an .ocx. After creating the user control, the following basic steps must be taken:

  1. Add the user control to the project using the Components dialog box. This ensures that appropriate files are included by the Visual Basic Package and Deployment Wizard. It also allows access to the control's public properties, events, and methods.

  2. On the Properties window, click RepeatedControlName and select the user control from the drop down list.

  3. Add a data source, such as the ADO Data Control, to the form, and connect it to a data provider.

  4. Set the DataRepeater control's DataSource property to the data source.

  5. Right-click the DataRepeater control and click DataRepeater Properties.

  6. Click the RepeaterBindings tab.

  7. Set the PropertyName to an appropriate DataField, and click the Add button.

The DataRepeater control saves computer resources by only displaying a single user control — the active control — at a time. The other controls displayed are simple images that do not maintain individual connections to the data source, as would happen if several user controls were contained on a form.

Distribution Note When you create and distribute applications that use the DataRepeater control, you should install MSDatRep.ocx in the customer's Microsoft Windows System or System32 subdirectory. The Setup Kit included with Visual Basic provides tools to help you write setup programs that install your applications correctly.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.


RepeaterBindings Collection

A collection of RepeaterBinding objects.

Syntax

RepeaterBindings

Remarks

Use the RepeaterBindings property to return a reference to the collection.


DataRepeater Control Constants

Appearance Constants

Constant | Value | Description
drpflat | 0 | Control appears flat.
drp3D | 1 | Control has 3D features.

BorderStyle Constants

Constant | Value | Description
drpNoBorder | 0 | Control has no border.
drpFixedSingle | 1 | Control has a single line border

CaptionStyle Constants

Constant | Value | Description
drpNoCaption | 0 | Caption is hidden.
drpLeftAligned | 1 | Caption is left-aligned.
drpRightAligned | 2 | Caption is right-aligned.
drpCentered | 3 | Caption is centered.

Error Constants

Constant | Value | Description
drpOutOfMemory | 7 | Out of memory.
drpTypeMismatch | 13 | Type mismatch.
drpObjVarNotSet | 91 (&H5B) | Object variable or With block variable not set.
drpInvalidPropertyValue | 380 (&H17C) | Invalid property value.
drpInvalidPropertyArrayIndex | 381 (&H17D) | Invalid property array index.
drpSetNotSupportedAtRuntime | 382 (&H17E) | The property can't be set at run time.
drpSetNotSupported | 383 (&H17F) | Property is read-only.
drpSetNotPermitted | 387 (&H183) | Property can't be set on this control.
drpGetNotSupported | 394 (&H18A) | Property is write-only.
drpObjectDoesntSupportProp | 438 (&H1B6) | Object doesn't support this property or method.
drpCreateRepeaterControl | 32000 (&H7D00) | Unable to create RepeatedControl
drpInvalidProgID | 32001 (&H7D01) | Invalid ProgID or class object not supported.
drpInvalidBookmark | 32002 (&H7D02) | Invalid bookmark
drpNoDataSource | 32003 (&H7D03) | No datasource or datasource is empty.
drpNoVisibleRows | 32004 (&H7D04) | There are no visible rows.
drpCantSetActiveRow | 32005 (&H7D05) | The active row cannot be set without affecting the current record position.
drpBadVisibleRecordIndex | 32006 (&H7D06) | VisibleRecord index must be between zero and VisibleRows-1.
drpInvalidRecordBookmark | 32007 (&H7D07) | The bookmark is invalid or the corresponding record is no longer present.
drpIndexOutOfBounds | 35600 (&H8B10) | Index out of bounds.
drpElemNotFound | 35601 (&H8B11) | Element not found.
drpNonUniqueKey | 35602 (&H8B12) | Key is not unique in collection.
drpInvalidKey | 35603 (&H8B13) | Invalid key.
drpElemNotPartOfCollection | 35605 (&H8B15) | Object is no longer a collection member.
drpCollectionChangedDuringEnum | 35606 (&H8B16) | Control's collection has been modified.
drpBadObjectReference | 35610 (&H8B1A) | Invalid object.
drpWouldIntroduceCycle | 35614 (&H8B1E) | Action would introduce a cycle.
drpCircularReference | 35700 (&H8B74) | Circular object referencing is not allowed.
drpPropertyNotBindable | 35701 (&H8B75) | Property is not bindable.
drpInvalidIndexOrKey | 35702 (&H8B76) | Invalid index or key.
drpAlreadyBound | 35703 (&H8B77) | PropertyName already bound.
drpInvalidPropertyName | 35704 (&H8B78) | Invalid PropertyName.
drpInvalidDataField | 35705 (&H8B79) | Invalid DataField.

MousePointer Constants

Constant | Value | Description
drpDefault | 0 | Default.
drpArrow | 1 | Arrow mouse pointer.
drpCross | 2 | Cross mouse pointer.
drpIBeam | 3 | I-Beam mouse pointer.
drpIcon | 4 | Icon mouse pointer.
drpSize | 5 | Size mouse pointer.
drpSizeNESW | 6 | Size NE SW mouse pointer.
drpSizeNS | 7 | Size N S mouse pointer.
drpSizeNWSE | 8 | Size NW SE mouse pointer.
drpSizeEW | 9 | Size W E mouse pointer.
drpUpArrow | 10 | Up arrow mouse pointer.
drpHourglass | 11 | Hourglass mouse pointer.
drpNoDrop | 12 | No drop mouse pointer.
drpArrowHourglass | 13 | Arrow and Hourglass mouse pointer
drpArrowQuestion | 14 | Arrow and Question mark mouse pointer.
drpSizeAll | 15 | Size all mouse pointer.
drpCustom | 99 (&H63) | Custom mouse pointer icon specified by the MouseIcon property.

RowDividerStyle Constants

Constant | Value | Description
drpNoDivider | 0 | No line drawn between rows.
drpFlatLine | 1 | Flat line drawn between rows.
drpInset | 2 | 3D inset line drawn between rows.
drpRaised | 3 | 3D raised line drawn between rows.

Scrollbars Constants

Constant | Value | Description
drpNoScrollBars | 0 | No scrollbars.
drpHorizontal | 1 | Horizontal scrollbars only.
drpVertical | 2 | Vertical scrollbars only.
drpBoth | 3 | Horizontal and Vertical scrollbars appear.
drpAuto | 4 | Scrollbars are drawn as required.


ActiveRowChanged Event

Occurs when the ActiveRow property is set.

Syntax

object_ActiveRowChanged( )

The object placeholder represents an object expression that evaluates to an object in the Applies To list.


CurrentRecordChanged Event

Occurs when the current record changes to a different record.

Syntax

Private Sub object_CurrentRecordChanged()

The object placeholder represents an object expression that resolves to an object in the Applies To list.

Remarks

The user can change the current record by clicking any record on the control, or by using the forward, backward, move first, and move last buttons on a data control.


CurrentRecordChanged Event Example

The example stores the bookmark of the current record using the CurrentRecord property.

Option Explicit
Option Base 1
Private mRecords(10) As Variant ' Array for bookmarks.
                                ' We only store last 10.

Private Sub DataRepeater1_CurrentRecordChanged()
    If intC = 10 Then intC = 1
    mRecords(intC) = DataRepeater1.CurrentRecord
    intC = intC + 1
End Sub


DataUpdate Event

Occurs when a field is edited either programmatically or by a user.

Syntax

Private Sub object_DataUpdate(cancel As boolean, ByVal Record As Variant, ByVal field As String)

The DataUpdate event syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
cancel | A Boolean value that specifies if the operation is canceled.
record | A Variant array that contains the bookmark of the current record.
field | A string that indicates the name of the field which is about to change.

Remarks

The field argument does not have to be a bound field. If any field in the recordset is changed, the event will occur.


RepeatedControlLoaded, RepeatedControlUnloaded Events

RepeatedControlLoaded — Occurs after the RepeatedControl has been created and initialized.

RepeatedControlUnLoaded — Occurs when the RepeatedControl is about to be unloaded.

Syntax

Private Sub object_RepeatedControlLoaded()

Private Sub object_RepeatedControlUnloaded()

The object placeholder represents an object expression that resolves to an object in the Applies To list.

Remarks

At run time you can change the RepeatedControl by setting the RepeatedControlName property to a new programmatic ID. When doing so, use the RepeatedControlLoaded event to initialize values on the user control.


VisibleRecordChanged Event

Occurs when the VisibleRecords property changes.

Syntax

object_VisibleRecordChanged()

The object placeholder represents an object expression that resolves to an object in the Applies To list.


Add Method (RepeaterBindings Collection)

Adds a RepeaterBinding object to the RepeaterBindings collection and returns a reference to the new object.

Syntax

object.Add(PropertyName, DataField, DataFormat, key)

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
PropertyName | Required. A string that sets the data-bound property of the user control.
DataField | Required. A string that sets the data source field to bind to the property specified in PropertyName.
DataFormat | Optional. Sets the DataFormat object to be used.
key | Optional. A unique string that identifies the object. Use this value to retrieve a specific member of the collection.


RepeaterBinding Object

The RepeaterBinding object represents a bindable property of a component.

Syntax

RepeaterBinding

Remarks

Use the RepeaterBinding object at run time to change the contents of a DataRepeater control by changing how fields are bound.


RepeaterBinding Object Example

The example below first prints the existing property names of the RepeaterBindings collection, then adds a DataBinding object to the collection, and finally changes the format of a DataBinding object.

Private Sub DataRepeater1_RepeatedControlLoaded()
   Dim rb As RepeaterBinding

   For Each rb In DataRepeater1.RepeaterBindings
      Debug.Print rb.PropertyName ' Print all property names.
   Next

   With DataRepeater1
      ' Add a new RepeaterBinding object.
      .RepeaterBindings.Add "cleared", "cleared"
      ' Change the Format to all caps.
      .RepeaterBindings(2).DataFormat.Format = ">"
   End With
End Sub


ActiveRow Property

Returns or sets the row index where the current record will be positioned. The ActiveRowChanged event occurs when setting this property.

Syntax

object.ActiveRow [=integer]

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
integer | A numeric expression that specifies the row where the current record is placed.

Remarks

The property value must be between 1 and the value of the VisibleRows property.

The row index is 1-based, and setting the property to 0 is not allowed. However, when 0 is returned, it indicates that the current record is scrolled out of view.

When the DataRepeater control displays the beginning or end of a recordset, it's possible that the ActiveRow won't have a logical setting. For example, if the current record is the last in the recordset, setting the ActiveRow to 2 or 1 when the VisibleRows is 3, is an invalid setting.


CaptionStyle Property

Returns or sets a value that determines the style of the caption, including alignment and visibility.

Syntax

object.CaptionStyle [=integer]

The CaptionStyle property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
integer | A numeric expression that determines the alignment of the caption, as shown in Settings.

Settings

Constant | Value | Description
drpNoCaption | 0 | The caption is hidden.
drpLeftAligned | 1 | (Default) The caption is left aligned.
drpRightAligned | 2 | The caption is right aligned.
drpCentered | 3 | The caption is centered.


CurrentRecord Property

Returns the bookmark of the current record.

Syntax

object.CurrentRecord

The object placeholder represents an object expression that resolves to an object in the Applies To list.

Return Type

Variant


CurrentRecord, VisibleRecords Properties Example

The example causes the current record to become the first record visible. If the user scrolls the DataRepeater control so that the current record is hidden, invoking the procedure causes the current record to reappear.

Private Sub MakeFirstVisibleRecord()
   DataRepeater1.VisibleRecords(1)=DataRepeater1.CurrentRecord
End Sub


DataField Property (RepeaterBinding Object)

Returns or sets a DataField to be bound to a property.

Syntax

object.DataField [=string]

The DataField property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
string | The name of the property to bind to.


DataFields Property

Returns an array of DataField names of the DataSource.

Syntax

object.DataFields(index)

The DataFields property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
index | The index of an element in the array. The array is 0-based.

Return Type

String

Remarks

The DataFields array contains the names of all bindable properties of the repeated control (see RepeatedControlName).

Use the Ubound method to determine how many elements are in the array. Since the array is 0-based, use the following code:

Debug.Print Ubound(DataRepeater1.DataFields) + 1


DataFormat Property (RepeaterBinding Object)

Returns or sets a reference to a DataFormat object.

Syntax

object.DataFormat [=dataformat]

The DataFormat property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
dataformat | Optional. A reference to a DataFormat object.


IntegralHeight Property (DataRepeater Control)

Returns or sets a value that determines if the control displays partial rows.

Syntax

object.IntegralHeight [=boolean]

The IntegralHeight property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
boolean | A Boolean expression specifying if the control shows partial rows, as shown in Settings.

Settings

The settings for boolean are:

Constant | Description
False | Partial rows are shown.
True | (Default) The control shows only complete rows.


PropertyName Property (RepeaterBinding Object)

Returns or sets the name of a bindable property of the user control.

Syntax

object.PropertyName [=string]

The PropertyName property syntas has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
string | A bindable property of the RepeatedControl.


PropertyNames Property

Returns an array of property names of the repeated control.

Syntax

object.PropertyNames(index)

The PropertyNames property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
index | The index of an element in the array. The array is 0-based.

Remarks

Use the Ubound method to determine how many elements are in the array. Since the array is 0-based, use the following code:

Debug.Print Ubound(DataRepeater1.DataFields) + 1


RecordCount Property

Returns the number of records in the recordset.

Syntax

object.RecordCount

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Type

Long


RepeatedControlName Property

Returns or sets the programmatic ID of the repeated control.

object.RepeatedControl [=string]

The RepeatedControl property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
string | The programmatic ID of a user control.

Remarks

The repeated control cannot be a Visual Basic intrinsic control.

The programmatic ID of a control consists of its project name and class name in the format projectname.classname. The Visual Basic Object Browser displays the project name in the Project/Library box, and the class name in the Classes list.


RepeatedControl Property

Returns a reference to the repeated control.

Syntax

object.RepeatedControl

The object placeholder represents an object expression that resolves to an object in the Applies To list.

Remarks

Use the reference to set public properties, or invoke public functions of the user control. For example, the code below retrieves the repeated control's public property named "Value":

MsgBox DataRepeater1.RepeatedControl.Value


RepeaterBindings Property

Returns a reference to the RepeaterBindings collection of RepeaterBinding objects.

Syntax

object.RepeaterBindings

object.RepeaterBindings(index)

The RepeaterBindings property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
index | The Index or Key that specifies a member of the collection.


RowDividerStyle Property (DataRepeater Control)

Returns or sets a value that determines the appearance of the row divider.

Syntax

object.RowDividerStyle [=integer]

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
integer | A numeric expression that determines the row divider appearance, as shown in Settings.

Settings

Constant | Value | Description
drpNoDivider | 0 | No lines between rows.
drpFlatLine | 1 | (Default) Lines between rows.
drpInset | 2 | Inset lines are drawn between rows.
drpRaised | 3 | Raised lines are drawn between rows.


RowIndicator Property

Returns or sets a value that determines if the row indicator (a solid black triangle) is drawn on the control. The indicator identifies the active record.

Syntax

object.RowIndicator [=boolean]

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
boolean | A Boolean expression specifying if the row divider is drawn, as shown in Settings.

Settings

The settings for boolean are:

Constant | Description
False | The row indicator is not drawn.
True | (Default) The row indicator is drawn.


Scrollbars Property (DataRepeater Control)

Returns or sets a value that determines the scrollbar style.

Syntax

object.Scrollbars [= integer]

The Scrollbars property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
integer | A numeric expression that determines the scrollbar appearance, as shown in Settings.

Settings

Constant | Value | Description
vbSBNone | 0 | None.
vbHoriz | 1 | Horizontal scrollbars only.
vbVert | 2 | (Default) Vertical scrollbars only.
vbBoth | 3 | Vertical and Horizontal scrollbars.
vbAuto | 4 | Scrollbars appear when needed.


VisibleRecords Property

Returns or sets the bookmark of the record to be displayed at the specified row index.

Syntax

object.VisibleRecords(rowindex) [=bookmark]

The VisibleRecords property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
rowindex | Required. A Long value that specifies which row to display a record in.
bookmark | Optional. Sets the bookmark of the record to display in the rowindex row.

Return Type

Variant

Remarks

The rowindex value cannot evaluate to a position beyond the EOF or BOF of the recordset.

The rowindex value must be between 1 (the top row) and the value of the VisibleRows property.


VisibleRows Property (DataRepeater Control)

Returns the number of fully visible rows in the control.

Syntax

object.VisibleRows

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Type

Long

Remarks

Use the VisibleRows property together with the VisibleRecords property to specify where the current record displays. For example, to display the current record in the bottommost row, use the code below:

DataRepeater1.VisibleRecords(DataRepeater1.VisibleRows) = _
DataRepeater1.CurrentRecord