Accessing and Modifying Query Items

To access individual query items (conditions or result fields, depending on the value of the ContentsType property), use the C1QueryFrame.Item object.

Before using the Item object, it is important to understand that it represents all query items at once, it does not represent any single particular item. There is always only one Item object associated with a C1QueryFrame control. The Item object works similar to a cursor or recordset, you navigate it through the tree of items. Once you have positioned on an item, you can get/set its properties.

You can either navigate through the item tree, or position to a single item.

To navigate through the item tree, use the following methods: MoveToRoot, MoveToChild and properties: ChildrenCount, IndexInParent. Alternatively, you can use methods MoveToNext, MoveToPrevious, MoveToFirstChild. Using the last three methods, test the existence of the destination item with Boolean properties HasNext, HasPrevious, HasChildren.

To position on a single item, you must know its id. Each query item has its own unique identifier – the item id, uniquely determining its position in the item tree. To position to an item with known id, use the FindByID method. For example, the following code positions the Item object on the item currently selected by the end user.

Example Title	Copy Code
C1QueryFrame1.Item.FindByID C1QueryFrame1.CurrentItemID

To retrieve the unique id of the item on which the Item object is currently positioned, use the ID property. The ParentID property returns the id of the item’s parent in the hierarchy. The root item id is always 0.

All properties of the Item object return/set properties of the item on which the Item object is currently positioned.

The Advanced and Complex read-only properties return Boolean values determining whether the item is an advanced elementary condition and whether it is a complex condition.

The following properties return/set the enumeration values for query item elements that can be selected by the user in corresponding menus: Comparison, Connective, Function, and Sort.

The LeftSideField and RightSideField properties return/set the strings, field names displayed on the left and right sides of a condition. The RightSideField property is applicable only to advanced conditions (those that can have fields on the left and right side). For result field items, only the LeftSideField property has a valid value determining the string shown as the field name.

The actual field used in a query item is not necessarily determined by the LeftSideField/RightSideField properties. By default, these properties contain the field name, but their values can be changed for UI customization purposes (using the AfterMenu event) without affecting the actual field.

The LeftFieldID property determines the field (its id, see below) selected on the left side. For an advanced elementary condition item with a field on the right side, the RightFieldID property determines the id of the field selected on the right side

Every field in a C1Query schema has its own unique identifier – field id. To obtain field id, use the FieldNameToFieldID method. If you want to retrieve field’s properties given a field id, use the FieldByID method that returns a Field object where you can get the field’s name and other properties.

Constant values in an elementary condition item are determined by the LeftSideValue and RightSideValue properties. The LeftSideValue property is applicable only to advanced conditions (those that can have constants on the left side). These properties determine the constant values used in SQL generation.

The LeftSide and RightSide properties return/set the strings displayed on the left and right sides of a condition. The LeftSideValue property is applicable only to advanced conditions.

By default, string presentation of a value is obtained from the value itself. However, the string presentation (LeftSide/RightSide properties) can be changed for UI customization purposes (using the EndEdit event) without affecting the actual value.

For an advanced elementary condition, the LeftSideKind and RightSideKind properties determine whether the left/right side is a field or a constant.

To modify the collection of query items programmatically, add/ delete items, use the following methods of the C1QueryFrame control: Clear, AddItem, DeleteItem, and PerformMainMenuAction. Adding an item, specify its parent’s id and condition type, whether it is simple, advanced or complex (for result field items, the condition type argument is ignored).

Modifying query items does not in itself update the control display. It is intentional, since item contents are usually modified in batches and display refresh on each assignment would be undesirable. After modifying query items, you must call the Render method to update display. If you forget to call Render, the control will remain in unstable state and unpredictable results can follow.