Dot notation

Dot notation lets you qualify the item you are referring to—instance variable, property, event, or function—with the object that owns it.

Dot notation is for objects. You do not use dot notation for global variables and functions, because they are independent of any object. You do not use dot notation for shared variables either, because they belong to an object class, not an object instance.

Dot notation names an object variable as a qualifier to the item you want to access:

objectvariable.item

The object variable name is a qualifier that identifies the owner of the property or other item.

parent.objectvariable.item

A parent object contains the child object. It is not an ancestor-descendent relationship. For example, a window is a control’s parent. A Tab control is the parent of the tab pages it contains. A Menu object is the parent of the Menu objects that are the items on that menu.

For example, if you want to call the Retrieve function for a DataWindow control on a tab page, you might qualify the name like this:

w_choice.tab_alpha.tabpage_a.dw_names.Retrieve()

Menu objects often need several qualifiers. Suppose a window w_main has a menu object m_mymenu, and m_mymenu has a File menu with an Open item. You can trigger the Open item’s Selected event like this:

w_main.m_mymenu.m_file.m_open.EVENT Selected()

As you can see, qualifying a name gets complex, particularly for menus and tab pages in a Tab control.

A parent object knows about the objects it contains. In a window script, you do not need to qualify the names of the window’s controls. In scripts for the controls, you can also refer to other controls in the window without a qualifier.

For example, if the window w_main contains a DataWindow control dw_data and a CommandButton cb_close, a script for the CommandButton can refer to the DataWindow control without a qualifier:

dw_data.AcceptText()
dw_data.Update()

If a script in another window or a user object refers to the DataWindow control, the DataWindow control needs to be qualified with the window name:

w_main.dw_data.AcceptText()

There are three ways to qualify an element of an object in the object’s own scripts:

• Unqualified:

  li_index = SelectItem(5)
  

  An unqualified name is unclear and might result in ambiguities if there are local or global variables and functions with the same name.

• Qualified with the object’s name:

  li_index = lb_choices.SelectItem(5)
  

  Using the object name in the object’s own script is unnecessarily specific.

• Qualified with a generic reference to the object:

  li_index = This.SelectItem(5)
  

  The pronoun This shows that the item belongs to the owning object.

This.property

This.function

Although the property or function could stand alone in a script without a qualifier, someone looking at the script might not recognize the property or function as belonging to an object. A script that uses This is still valid if you rename the object. The script can be reused with less editing.

You can also use This by itself as a reference to the current object. For example, suppose you want to pass a DataWindow control to a function in another user object:

uo_data.uf_retrieve(This)

This example in a script for a DataWindow control sets an instance variable of type DataWindow so that other functions know the most recently used DataWindow control:

idw_currentdw = This

For example, in a DataWindow control script, suppose you want to call the Resize function for the window. The DataWindow control also has a Resize function, so you must qualify it:

// Two ways to call the window function
w_main.Resize(400, 400)
Parent.Resize(400, 400)

// Three ways to call the control's function
Resize(400, 400)
dw_data.Resize(400, 400)
This.Resize(400, 400)

window w_save
w_save = dw_data.GetParent()

For example, in another CommandButton’s Clicked event script, suppose you wanted to pass a reference to the control’s parent window to a function defined in a user object. Use GetParent in the function call:

uo_winmgmt.uf_resize(This.GetParent(), 400, 600)

• ParentWindow property – used in a menu script to refer to the window that is the parent of the menu

• ParentWindow function – used in any script to get a reference to the window that is the parent of a particular window

For more about these pronouns and functions, see the PowerScript Reference.

Dot notation also allows you to reach inside an object to the objects it contains. To refer to an object inside a container, use the Object property in the dot notation. The structure of the object in the container determines how many levels are accessible:

control.Object.objectname.property

control.Object.objectname.Object.qualifier.qualifier.property

Objects that you can access using the Object property are:

• DataWindow objects in DataWindow controls

• External OLE objects in OLE controls

These expressions refer to properties of the DataWindow object inside a DataWindow control:

dw_data.Object.emp_lname.Border
dw_data.Object.nestedrpt[1].Object.salary.Border