Object Property Model
This section describes creating new items and setting up and modifying attributes to properties of Items.
- If you are not still on the Advanced Joist Tool Properties window, then click Templates tab, click Types tab, open Scripted Tools folder, open Items folder, double-click Joist Tool, then click on Advanced. This window is divided into ten different groups: Item, Estimating, Fill, Takeoff Data, Work Breakdown Structure, Other, Audit Trail, Joist Properties, Videos, and Events (Figure 1).
Figure 1 - Double-click on the Cost Total field under Estimating. This opens the Edit Property window (Figure 2) for the Joist Tool's Cost Total property, which is grouped under Estimating. Developers can use this window to modify the physical property settings (or attributes) of the property model. Everything that is in the Edit Property window is available through API. This is where a developer will spend a lot of time setting up attributes to properties of Items, so it's very important to understand what the functions of these properties do. Note that the descriptions that follow are modeled for COM rather than for scripting. Click on Cancel to close the Edit Property window, then click on any item in the first column of the Estimating group.
Figure 2 - Now click on the Add Property icon as shown in Figure 3.
Figure 3 - This opens a new Edit Property window (Figure 4). Notice that the Name: field is blank in this window, allowing you to give it a name of your choosing. The Type: field's down-arrow opens a drop-down menu that allows you to specify the type of value assigned to the field: Number, Color, Text, Memo, CheckBox, Path, Image, Large Image, Type, Script, File, Large File, File Name, Folder, Font Name, Connection String, Slider, and Dimension. The Type: field's default is Number. The attributes a developer would most commonly use are Text, Memo, or Number. A few others, including CheckBox and Slider could also be useful. Selecting CheckBox would display a checkbox, which represents a boolean value (true or false): if it is checked, it is true; if not checked, then it is false. Enter the name Test Property in the Name: field; click on the Type: field's down-arrow and select CheckBox from the menu, and then click on OK.
Figure 4 - You will now see "Test Property" at the bottom of the first column in the Estimating group (Figure 5). The next column to the right is the checkbox. Since the checkbox is not checked, its value is False, as seen in the 5th column (Result) to the right. Once checked, its value shows as True.
Figure 5 - Double-click on Test Property to open its Edit Property window again (Figure 6). This time select the Slider tool from the Type: drop-down menu. This opens the Slider Options (see red arrow). The Slider function is very useful and has its own properties, which is the minimum value and the maximum value. Enter "1" in as the minimum value and "100" in as the maximum value; set the Tick Frequency: field to 10 so that the ticks will show up every tenth time; and check the box Show Ticks. Now click on OK.
Figure 6 - The Test Property property will now show a slider bar with eleven tick marks. Click and hold on the slider on the bar, and drag it to anywhere on the bar; as you drag it, the value will be displayed in the 5th column (Result). The Slider function can be valuable in cases where you might have an image transparency function, or you need a finite number based off a value, or you need any type of minimal adjustment. Click on Type: again and select Number.
- The other Type: field values may be useful but will not be covered at this time.
- The Group: field shows that Test Property is assigned to the Estimating group. Clicking on the down-arrow allows you to assign it to one of the ten available groups in the Joist Tools Properties window: Item, Estimating, Fill, Takeoff Data, Work Breakdown Structure, Other, Audit Trail, Joist Properties, Videos, or Events.
- The Tool Hint: field allows you to enter a short description of the tool, which will be visible in the Form window when the cursor is hovered over the property. Such a hint can be helpful to explain the functionality of a property to a user. To see this in action, type "Joist Tool Hint" in the Hint: field; then click on OK to close the Edit Property window.
- At the Joist Tool Properties window, click on the box for the Test Property property you created (see arrow in Figure 7) so that it can be displayed in the Input and Form windows.
Figure 7 - Scroll to the bottom of the Joist Tool Properties window and click on Form, then hover over the Test Property text until the "Joist Tool Hint" appears with a yellow background as shown in Figure 8.
Figure 8 - Click on Advanced again to return to the Joist Tools Properties window, double-click on the Test Property property you created previously, and delete the Tool Hint: text. The Edit Property window for the Joist Tool should look similar to Figure 9.
Figure 9 - The Remember Value: checkbox has no functionality at this time.
- The Parse Formula: checkbox, when checked, causes anything within brackets to be read as a variable. If this box is not checked, then the text inside the brackets is read as a text string, not as a variable. By default in COM, this box is checked automatically.
- In the Input Options area of the Edit Properties window, there is an Input checkbox and a Condition: field. When the Input checkbox is checked and the condition in the Condition: field is satisfied, then the property will be displayed in the Form window. If the Condition: field is not satisfied, then the property will not be displayed in the Form window. If the Input box is checked but the Condition: field is blank, then the property will show up in the Form window. If the Input box is not checked, then the property will not be displayed in the Form window. As an example, enter [New Length] = 10 into the Condition: field. Also, make sure the Input box is checked. Click on OK to close the Edit Property window. Now click on Form at the bottom of the Joist Tools Properties window. You'll see in Figure 10 that there is no Test Property field. You will also notice that the New Length field is blank. Now put the value of 10 into the New Length field and press your keyboard's Tab key to invoke the changed value.
Figure 10 - The Test Property field now appears (Figure 11). If you change and invoke the value to anything but 10, then the Test Property field will disappear.
Figure 11 - Click on Advanced to return to the Joist Tool Properties window (Figure 11), and double-click on Test Property. The Compiled Options are shown in Figure 12.
Figure 12 - The Input Units and Units (Output Units) area allow you to specify the Input Units and Output Units columns in the Joist Tool Properties window (see Figure 13). You may specify whether they are to be hidden or locked by clicking the check boxes for Hidden or Locked. You may also specify the decimal places by entering a decimal value in the Decimal Places: field.
Figure 13 - The When creating new items of this type: area can be set to Normal, Inherit, or Ignore (Figure 14). The Normal setting allows for inherited properties to be editable. The Inherit setting allows properties to be modifiable but only by permission. The Ignore means that "anytime I inherit a property, I specifically do not want this property to be on that inheritance of that derived item.
Figure 14 - Checking the Formula checkbox allows the formula and the result to be inherited. Checking the Result checkbox allows only the result to be inherited. The Pull From: field is not commonly used. It allows you to inherit the actual result from a completely different item from either the same estimate or somewhere else by providing the relative path of that item and the property. The List Type: field allows the developer to provide a list that acts as a drop-down list to the property (see Figure 15) but will not be discussed at this time.
Figure 15 - This completes the coverage of what you need to know to get started using the API.