Referring to Form and Browse Objects
Description
Using Xbasic you can control form and browse windows in much the same way that the user does when he or she makes selections from menus and presses toolbar buttons. For example, you might have opened a form called Customers. If you want to enter a new record in this form, you could press the New Record icon on the speed bar. To accomplish the same thing using an Xbasic method, you could type this in the Interactive window:
:Customers.new_record()
In this case the object that you are addressing is the Customer form. Its address is ":customers". The method of the form that you are using is the <FORM>.NEW_RECORD() method. If you wanted to put a button on the customer form to enter a new record, you could attach the above code to the button, but it would be better to make the code more generic using aliases. For example:
parentform.new_record()
Since the parentform of the button is the form itself, this code inserts a new record into the form. Here is a slightly more complex example. Assume you have a set with a table called invoice_header linked one to many to invoice_items. This set has a form with an embedded browse (called Items ) showing line items. You could put a button on the form to enter a new line item. The code would be:
topparent:items.new_record()
The TopParent alias refers to the form itself. This object contains the Items browse object to which the .NEW_RECORD() method is applied. The command:
topparent.new_record()
would add a new record to invoice_header. In general, the syntax for calling an object's methods is: object_address.method, or object_pointer.method. The following two code segments do the same thing. One uses the object_address.method syntax, the other uses the object_pointer.method syntax. Using the Object Address syntax:
:form.view("customers")
:customers.new_record()
:customers:lastname.value = "smith"
:customers.commit()Using the Object Pointer syntax:
f = :form.view("customers")
f.new_record()
f:lastname.value = "smith"
f.commit()Object Value
You can refer to the current value in any of the objects on a form or browse by specify the object name. For example, assume that the embedded browse object is called Browse1 and that the Quantity column object is called quantity. You can reference the value in the current row of the embedded browse using the object name of the quantity column:
Browse1:quantity.value
As a further example, assume that the invoice total (which is a calculated field), is displayed in an object called inv_total. You can refer to the value in this object using name of this object:
Inv_total.value
Relative and Explicit Object Names
In a script, when you refer to an object on a form, you can use a "relative" or "explicit" object name. The concept of relative and explicit names is best explained by analogy. Assume you are telling someone how to find a particular person's home which is at 123 Main Street. If you are standing on Main Street when you are asked this question, your answer can be simply "go to number 123". This is a relative address because you are already on Main Street. Your answer is relative to Main Street. However if you are standing on Walnut Street when you are asked this question, your answer needs to be a little more explicit. You can say "go to 123 Main Street". Of course, if you are in the United Kingdom when you are asked this question, your answer needs to be even more explicit. You might say "go to 123 Main Street, in Boston, Massachusetts, in the United States". This answer will allow you to find the person's house no matter where you are when you ask the question. Similarly, if you have a script on a button on a form, and that script refers to another object on the same form, then a relative address for that object will be sufficient. For example, say you wanted to refer to the text property of an object called lastname. The relative object name is topparent:lastname, and the relative property name is topparent:lastname.text. The object name can be interpreted as follows - start at the highest level of the form ( topparent ). This level contains an object called lastname (the : symbol is used to indicate that the object on the right is contained within the object on the left of the : symbol).
If this form was called customers, then the explicit object name is :customers:lastname, and the explicit property name is :customers:lastname.text. The object name can be interpreted as follows - start at the highest level of Alpha Anywhere. This level contains the form customers. The customers form contains the object lastname. The advantage of using relative names where possible is that your script will not break if the form name is changed. Also if you open more than one instance of the form, your scripts will continue to work. They may not work as you would expect if you use explicit names. Consider the above example where the form is called customers. If you open two instances of this form, the first instance has the name customers, and the second instance has the name customers0 (or some other unique name). The script in the second instance of this form will continue to refer to the lastname control on the first instance of this form - probably now what you would want.
See Also