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 descendant 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 descendant 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 the section called “Return values from ancestor scripts” in Application Techniques.
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
-
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.
-
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.
-
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.
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
-
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.
-
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.
-
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.
To override an ancestor script
-
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.
-
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.
-
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.
At runtime, PowerBuilder executes the descendant 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 descendant window, select Override Ancestor Script and create a new script for the Open event in the descendant to display customer files.
When you write a script for a descendant object or control, you can call scripts written for any ancestor. You can refer by name to any ancestor of the descendant 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 section called “Calling functions and events in an object's ancestor” in PowerScript Reference.
When you write a script for a descendant 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:
function ( arguments )
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:
ancestorobject::function ( arguments )
This syntax works only in scripts for the descendant object itself, not in scripts for controls or user objects in the descendant 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 descendant object, do the following:
-
Define an object-level user-defined function in the descendant object that calls the ancestor function.
-
Call the function you just defined in the descendant script.
For more information about calling an ancestor function, see the the section called “Calling functions and events in an object's ancestor” in PowerScript Reference.
