Using inherited scripts

In the hierarchy formed by ancestors and descendants, each
descendant inherits its event scripts from its immediate ancestor.
If an inherited event does not have a script, you can write a script
for the event in the descendant. If the inherited event does have
a script, the ancestor script will execute in the descendant unless
you extend the script or override it. You can:

• Extend the ancestor
  script–build a script that executes after the
  ancestor script
• Override the ancestor script–build a script
  that executes instead of the ancestor script

You cannot delete or modify an ancestor script from within
a descendant.

Extending or overriding a script

The Extend Ancestor Script item on the Edit menu or the pop-up
menu in the Script view determines whether the script is extended
or overridden. If the menu item is selected (a check mark displays
next to it) the ancestor script is extended. If there is no check
mark, the ancestor script is overridden.

When there is no script for the descendant, the Extend Ancestor
Script menu item is selected and disabled. You cannot clear the
menu item unless you add a script to the descendant. When you have
added a script, the menu item is enabled and you can choose to override
the ancestor script by clearing the menu item, or to extend it by
leaving the menu item selected.

If you delete the script in the descendant If after adding a script to the descendant and clearing the
Extend Ancestor Script menu item, you delete the script, the menu
item returns to its default state: selected and disabled. A message
displays in the status bar warning you that this has occurred. If
you then add a new script, the menu item is reenabled. You must
remember to clear the Extend Ancestor Script menu item if you want to
override the ancestor script.

Executing code before the ancestor script

To write a script that executes before the
ancestor script, first override the ancestor script and then in
the descendent script explicitly call the ancestor script at the
appropriate place. For more information, see “Calling an ancestor script”.

Getting the return value of the ancestor script

To get the return value of an ancestor script, you can use
the AncestorReturnValue variable. This variable is always available
in descendent scripts that extend an ancestor script. It is also
available if you override the ancestor script and use the CALL syntax
to call the ancestor event script. For more information, see Application
Techniques
.

Viewing inherited scripts

If an inherited object or control has a script defined only
in an ancestor, no script displays in the Script view.

Script icons in the second drop-down list

The second drop-down list in the Script view indicates which
events have scripts written for an ancestor as follows:

• If the event has a script in an ancestor only, the
  script icon next to the event name in the second drop-down list
  is displayed in color
• If the event has a script in an ancestor as well
  as in the object you are working with, the script icon is displayed
  half in color

Script icons in the third drop-down list

The third drop-down list in the Script view shows the current
object followed by each of its ancestors in ascending order. The
icons next to object names indicate whether the object has a script
for the event selected in the second drop-down list as follows:

• If an object is the highest
  class in the hierarchy to have a script, a transparent script icon
  displays next to its name. No icon displays next to the names of
  any of its ancestors.
• If an object does not have a script for the event
  but it has an ancestor that has a script for the event, the script
  icon next to its name is displayed in color.
• If an object has a script for the event, and it
  has an ancestor that also has a script for the event, the script
  icon next to its name is displayed half in color.

To view an ancestor script:

1. In the Script view for an inherited object,
   select the object itself or a control in the first drop-down list,
   and the event whose script you want to see in the second drop-down
   list.

   The Script view does not display the script for the ancestor.
   No script displays.

2. In the third drop-down list in the Script view,
   select an ancestor object that has a script for the selected event.

   The Script view displays any script defined in the ancestor
   object.

3. To climb the inheritance hierarchy, in the third
   drop-down list select the script for the grandparent of the current
   object, great-grandparent, and so on until you display the scripts
   you want.

   The Script view displays the scripts for each of the ancestor
   objects. You can traverse the entire inheritance hierarchy using
   the third drop-down list.

Extending a script

When you extend an ancestor script for an event, PowerBuilder executes
the ancestor script, then executes the script
for the descendant when the event is triggered.

To extend an ancestor script:

1. In the first drop-down list in the Script
   view, select the object or a control, and in the second drop-down
   list, select the event for which you want to extend the script.

2. Make sure that Extend Ancestor Script on the Edit
   menu or the pop-up menu in the Script view is selected.

   Extending
   the ancestor script is the default.

3. In the Script view, enter the appropriate statements.

   You can call the script for any event in any ancestor as well
   as call any user-defined functions that have been defined for the
   ancestor. For information about calling an ancestor script or function,
   see “Calling an ancestor script” and “Calling
   an ancestor function”.

Example of extending a script

If the ancestor script for the Clicked event in a button beeps
when the user clicks the button without selecting an item in a list,
you might extend the script in the descendant to display a message
box in addition to beeping.

Overriding
a script

To override an ancestor script:

1. In the first drop-down list in the Script
   view, select the object or a control, and in the second drop-down
   list, select the event for which you want to override the script.

2. Code a script for the event in the descendant.

   You can call the script for any event in any ancestor as well
   as call any user-defined functions that have been defined for the
   ancestor.

   For information about calling an ancestor
   script or function, see “Calling an ancestor script” and “Calling
   an ancestor function”.

   Override but not execute To override a script for the ancestor but not execute a script
   in the descendant, enter only a comment in the Script view.

3. Select Extend Ancestor Script on the Edit menu
   or the pop-up menu to clear the check mark.

   Clearing the Extend Ancestor Script item means that you are
   overriding the script.

During execution, PowerBuilder executes the descendent script
when the event is triggered. The ancestor script is not executed.

Example of overriding a script

If the script for the Open event in the ancestor window displays
employee files and you want to display customer files in the descendent
window, select Override Ancestor Script and create a new script
for the Open event in the descendant to display customer files.

Calling an ancestor script

When you write a script for a descendent object or control,
you can call scripts written for any ancestor. You can refer by
name to any ancestor of the descendent object in a script, not just
the immediate ancestor (parent). To reference
the immediate ancestor (parent), you can use the Super reserved word.

For more information about calling scripts
for an event in an ancestor window, user object, or menu, and about
the Super reserved word, see the PowerScript Reference
.

Calling an ancestor function

When you write a script for a descendent window, user object,
or menu, you can call user-defined functions that have been defined
for any of its ancestors. To call the first function up the inheritance
hierarchy, just call the function as usual:

If there are several versions of the function up the inheritance
hierarchy and you do not want to call the first one up, you need
to specify the name of the object defining the function you want:

This syntax works only in scripts for the descendent object
itself, not in scripts for controls or user objects in the descendent
object or in menu item scripts.To call a specific version of an
ancestor user-defined function in a script for a control, user object,
or menu item in a descendent object, do the following:

1. Define an object-level user-defined
   function in the descendent object that calls the ancestor function.
2. Call the function you just defined in the descendent
   script.

For more information about calling an ancestor
function, see the PowerScript Reference
.

---