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 don’t use dot notation
for global variables and functions, because they exist independently
of any object. You don’t 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-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.

Many parent levels You can use parent qualifiers up to the level of the application.
You will 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 it requires to identify
the object, function, event, or property.

A parent object knows about the objects it contains. In a
window script, you don’t need to qualify the names of its
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:

• Unqualified:
  PowerBuilder

  li_index = SelectItem(5)

  1	li_index = SelectItem(5)

  
  
  An unqualified name is unclear and may result in ambiguities
  if there are local or global variables and functions with the same
  name.
• Qualified with the object’s name:
  PowerBuilder

  li_index = lb_choices.SelectItem(5)

  1	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:
  PowerBuilder

  li_index = This.SelectItem(5)

  1	li_index = This.SelectItem(5)

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

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

Without a qualifier, someone looking at the function or variable
in a script might not recognize it 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, 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 only works 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:

• 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
.

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 via 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:

No compiler checking For objects inside the container, the compiler can’t 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 validity of the names and properties after the Object
property are checked during execution only. Incorrect references
cause an execution error.

For more information For more information about execution time 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 the DataWindow
Reference
.

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

---