| stdDataFormat Object (VB6) |
Description
The stdDataFormat object sits silently between the Binding object and the data consumer control. Data coming into the Binding object is reformatted by the stdDataFormat object and made ready for display in the consumer control. Data changed by the user that the Binding object is returning to the database is automatically unformatted as it leaves the data consumer control.
The formatting applied to the data is based on the properties you have set for the particular format object. In the case of complex formatting, you may also be required to unformat the data manually before processing by the database. In all cases, you should set the Type property, which tells the format object which format you require; optionally, you can provide a property value for one or more of the special format properties.
Only one format object can be applied to a Binding object, but there is no limit on how many different format objects your application can contain. If you use multiple format objects, you should contain them within the stdDataFormats collection object and simply pass a reference to the object in the collection to the Binding object. This prevents you from having many stdDataFormat objects all live at the same time. The drawback to this approach, though, is that the collection object stifles the format object's Format and Unformat events, which are vital for custom formatting.
If the purpose of the format object is incompatible with the control being bound, an error is generated by the BindingsCollection.Add method. For example, if you have created a format object that deals with a checkbox format and try to bind this to a Textbox control, an error occurs.
For an overview of data format objects, including the library reference needed to access the object model, see the Data Format Objects entry.
Createable
Yes
Properties
FalseValue
Data Type: Variant
When used in conjunction with a Type value of fmtBoolean, the FalseValue is assigned to the consumer control's bound property if the incoming data is False (0). For example, in the following snippet, if the value of the bound data field is 0, the string "No Contract" is placed in the bound control:
Set fmtF2 = New StdDataFormat fmtF2.Type = fmtBoolean fmtF2.FalseValue = "No Contract"
When changed data is read back into the database, if the value of the bound control property matches FalseValue, a False (0) is written to the database. For example, using our snippet above, if the data in the bound control is changed to "No Contract," or False is written to the database.
It's advisable to provide both a FalseValue and a TrueValue for a format object whose Type is fmtBoolean.
FirstDayOfWeek
Data Type: constant from FirstDayOfWeek enumeration
Specifies which day should be treated as the first day of the week. This property can be used for date formatting. The FirstDayOfWeek constants used by stdFormatObject differ from the intrinsic ones by their "fmt" (instead of "vb") prefix.
FirstWeekOfYear
Data Type: constant of FirstWeekOfYear enumeration
Specifies which week of the year should be treated as the first. This property can be used for date formatting. The FirstWeekOfYear constants used by stdFormatObject differ from the intrinsic ones by their "fmt" (instead of "vb") prefix.
Format
Data Type: String
When the value of the Type property is fmtCustom, the Type property can provide a formatting string identical to those recognized by the Format function; for details, see the entry for the Format function.
NullValue
Data Type: Variant
Defines the value to replace a Null for all format types. If the data from the data source is Null, it's automatically replaced by this value. Beware, though: if the data in the bound control is changed to this value, the Binding object attempts to write a Null to the database. For example, in the following snippet, a value of appears in the bound control if the original value in the database is Null. However, if the original database value is 1 and the user changes it to 0, then Null is written to the database.
Set fmtF2 = New StdDataFormat fmtF2.Type = fmtGeneral fmtF2.NullValue = 0
Note that an order of precedence applies when translating the values of bound data controls back to their original values. Typically, the NullValue property has the lowest precedence. For example, if the value of the Type property is fmtCheckbox, a data value of sets the checkbox's value to vbUnchecked, and a value of 1 sets it to vbChecked. If the value of the NullValue property is also 0, a Null isn't written to the database when the checkbox control becomes unchecked (i.e., its value changes to 0), since this is interpreted as vbUnchecked rather than Null. Similarly, for a type of fmtBoolean, a is interpreted as False rather than Null.
TrueValue
Data Type: Variant
Defines the value assigned to the consumer control's bound property for format objects whose Type is fmtBoolean and whose incoming data is True (1 or –1). For example, in the following code fragment, if the value of the bound data field is 1 or –1, the string "Contract Signed" appears in the bound control:
Set fmtF2 = New StdDataFormat fmtF2.Type = fmtBoolean fmtF2.TrueValue = "Contract Signed"
Type
Data Type: Constant of FormatType enumeration
Defines the type of data to be formatted, which in turn determines which properties are used in formatting a data item. Ensure that the type you set is compatible with both the data you are binding and with the control you are binding to. The FormatType constants are as follows:
Constant Value Description fmtGeneral
0 For any type of data. Forces the Format and Unformat events to fire. fmtCustom
1 For any type of data. The Format property can define a custom format value. Forces the Format and Unformat events to fire. fmtPicture
2 Format and Unformat events aren't fired. fmtObject
3 Format and Unformat events aren't fired. fmtCheckbox
4 For binding to a checkbox control. A data value of equates to vbUnChecked, whereas 1 or –1 equates to vbChecked. Format and Unformat events aren't fired for this type. fmtBoolean
5 For Boolean data; specifies that the TrueValue and FalseValue properties be used. Format and Unformat events aren't fired.
stdDataFormats Events
Your stdDataFormat object variable must be declared WithEvents to receive events. The following events are supported by the stdDataformat object:
Changed
Fired when the formatting properties of the object are changed.
Format
Fired when the bound data is about to be formatted for the fmtGeneral and fmtCustom format types. The event handler can override the formatting manually. An stdDataValue object is passed to the event, as the following example shows:
Private Sub fmtF1_Format(ByVal DataValue As _ StdFormat.StdDataValue) If DataValue.TargetObject.Name = "txtFirstName" Then 'force lowercase fmtF1.Format = ">" Else 'force uppercase fmtF1.Format = "<" End If End Sub
Note that the stdDataValue object isn't createable and only manifests itself as a parameter passed to the Format and Unformat event handlers.
Unformat
Fired for the fmtGeneral and fmtCustom format types when the bound data is to be unformatted and written back to the database. The event handler can override the unformatting manually. A stdDataValue object is passed into the event, as the following example shows:
Private Sub fmtF1_UnFormat(ByVal DataValue As _ StdFormat.StdDataValue) DataValue.Value = StrConv(DataValue.Value, _ vbProperCase) End Sub
Note that the stdDataValue object isn't createable and only manifests itself as a parameter passed to the Format and Unformat event handlers.
Example
See the Data Binding Objects entry for a complete example of how data binding and data formatting is performed.