Dot notation – PB Docs 2018

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.

Qualifying a reference

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

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

Adding a parent qualifier

To fully identify an object, you can use additional dot qualifiers
to name the parent of an object, and its parent, and so on:

A parent object contains the child object. It is not an
ancestor-descendant 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.

Many parent levels

You can use parent qualifiers up to the level of the application.
You typically need qualifiers only up to the window level.

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:

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:

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

How many qualifiers?

You need to specify as many qualifiers as are required to identify
the object, function, event, or property.

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:

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:

Referencing objects

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

This pronoun

In a script for the object, you can use the pronoun This as a
generic reference to the owning object:

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:

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:

Parent pronoun

The pronoun Parent refers to the parent of an object. When you use
Parent and you rename the parent object or reuse the script in other
contexts, it is still valid.

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:

GetParent function

The Parent pronoun works only within dot notation. If you want to
get a reference to the parent of an object, use the GetParent function.
You might want to get a reference to the parent of an object other than
the one that owns the script, or you might want to save the reference in a
variable:

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:

ParentWindow property and function

Other tools for getting the parent of an object include:

For more about these pronouns and functions, see the section called “Pronouns” in PowerScript Reference and the section called “ParentWindow” in PowerScript Reference.

Objects in a container object

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:

Objects that you can access using the Object property are:

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

No compiler checking

For objects inside the container, the compiler cannot be sure that
the dot notation is valid. For example, the DataWindow object is not bound
to the control and can be changed at any time. Therefore, the names and
properties after the Object property are checked for validity during
execution only. Incorrect references cause an execution error.

For more information

For more information about runtime checking, see Optimizing expressions for DataWindow and
external objects.

For more information about dot notation for properties and data of
DataWindow objects and handling errors, see DataWindow Reference.

For more information about OLE objects and dot notation for OLE
automation, see Using OLE in
an Application.