FieldsByProperty Method
The FieldsByProperty method searches all the composite field’s descendants (not just its immediate children) and returns an array of fields that match the specified field property or tagged value. The name of the property or tag name must be specified exactly, but for its value you may specify wildcards, formatted values, and case insensitivity.
You can use this method to return all of the frame’s fields (by specifying no parameters), to find all fields with a particular attribute or tag value, or to manipulate a group of fields that are linked by tagged values. A group could be a multifield field template or a number of fields that are hidden or displayed together. An example of a field group is a business construct such as a shipping address, which comprises several fields such as street number, street name, city, state, and postal code that may not be formally linked together as an Address userclass object, but can be bound together by a particular tagged value.
There are no mandatory parameters for FieldsByProperty. If neither an attributename or tagname is specified, all other parameters are ignored. If you use a searchstring, you may optionally specify format and casesensitive. You may perform additional filtering with the optional searchset and singleton parameters.
The following statement returns all fields on the frame’s TopForm, whether directly or indirectly parented:
fields = Curframe.TopForm.FieldsByProperty();
This method has the following syntax:
array of FormField = CompositeField.FieldsByProperty
(
[
[attributename = varchar(32) | tagname = varchar(256),
value = expression] |
[attributename = varchar(32) | tagname = varchar(256),
searchstring = string [, format = string][, casesensitive = integer]]
[, searchset = array of FormField]
[, singleton = i4]
[, errorstatus = i4]
]
)
This method has the following parameters:
attributename
Specifies the field property to apply the search to.
tagname
Specifies the tag in the field’s taggedvalues to apply the search to. This parameter is ignored if attributename is specified. If you specify a value, it must have a string datatype.
value
Specifies an expression that evaluates to a type compatible with the specified attribute. The FieldsByProperty method searches for an exact match between the expression and the attribute's value.
For example, if you are searching for all invisible fields, the following call to the FieldsByProperty method returns an array containing all such fields:
fields = curframe.TopForm.FieldsByProperty(attributename = 'curbias',
value = FB_INVISIBLE);
searchstring
Specifies a string expression. It enables wildcard searches. The following wildcards are allowed:
• % (percent) represents any number of characters, including a possibly empty set.
• _ (underscore) represents exactly one character.
• \ (backslash) is used as the escape character.
For example, the following call to the FieldsByProperty method provides a search string that uses a wildcard to return all fields containing a taggedvalue with a tag of "category" and a value beginning with "date":
status = curframe.TopForm.FieldsByProperty(tagname = 'category',
searchstring = 'date%');
When including a searchstring parameter, you also may specify format and casesensitive.
When specifying a searchstring with an attributename, each of the field’s attribute values is converted to a string using either the default format for the datatype or the format you supply. A comparison is then performed to check whether the formatted string matches the provided searchstring.
format
Used only when searchstring is also specified. Specifies any of the template data formats described in the Workbench User Guide and allowed as an EntryField's FormatString attribute. However, the template must correspond to the attribute type specified in the attributename parameter. If searchstring is specified but format is omitted, OpenROAD chooses a default format template according to the attribute's type.
For example, the following call to the FieldsByProperty method returns all fields whose absxleft is between 1000 and 1999:
fields = curframe.TopForm.FieldsByProperty(attributename = 'absxleft',
searchstring = '1___', format = '-"zzzzz"');
Valid values for the format parameter depend on the data type of the attribute being searched. For a description of how to set format templates, see the Programming Guide.
casesensitive
Used only when searchstring is also specified. Specifies whether string comparisons against the searchstring parameter are case sensitive.
Default: TRUE
searchset
Specifies the set of fields to search. The default is the CompositeField's descendants (all its child fields, plus their child fields, if any, and so on).
You can use searchset to further refine a search (by feeding the results of the initial search into a second call), or you also can use it to search a set of fields completely unrelated to the CompositeField. For example:
fieldsSetOne = curframe.CreditInfoComposite.FieldsByProperty(
attributename='absxleft', searchstring='1%',
format='-"zzzzz"',
casesensitive=TRUE);
fieldsSetTwo = curframe.AddressComposite.FieldsByProperty(
attributename='classname', value='BUTTONFIELD',
searchset = fieldsSetOne);
singleton
Specifies whether to return only the first result found.
errorstatus
Specifies the outcome of the operation. To do so it must be supplied byref. The value it contains will be ER_OK if matching fields were found, ER_ROWNOTFOUND if no matches were found, and ER_FAIL if the operation was unsuccessful. Failure is caused by such problems as attempting to compare incompatible data types or specifying incorrect attributes.
The FieldsByProperty method returns an array of FormField.