Calling
functions and events in an object’s ancestor
Description
In PowerBuilder, when an object is instantiated with a descendant
object, even if its class is the ancestor and that descendant has a
function or event script that overrides the ancestor’s, the descendant’s
version is the one that is executed. If you specifically want to execute
the ancestor’s version of a function or event, you can use the ancestor
operator (::) to call the ancestor’s version explicitly.
Syntax
|
1 |
{ objectname. } ancestorclass ::{ type } { when } name ( { argumentlist } ) |
The following table describes the arguments used to call functions
and events in an object’s ancestor.
|
Argument |
Description |
|---|---|
|
objectname (optional) |
The name of the object whose ancestor contains the |
|
ancestorclass |
The name of the ancestor class whose function or |
|
type (optional) |
A keyword specifying whether you are calling a
|
|
when (optional) |
A keyword specifying whether the function or event
|
|
name |
The name of the object function or event you want to |
|
argumentlist (optional) |
The values you want to pass to name. Each value in |
Usage
The AncestorReturnValue variable
When you extend an event script in a descendant object, the compiler
automatically generates a local variable called AncestorReturnValue that
you can use if you need to know the return value of the ancestor event
script. The variable is also generated if you override the ancestor script
and use the CALL syntax to call the ancestor event script.
The datatype of the AncestorReturnValue variable is always the same
as the datatype defined for the return value of the event. The arguments
passed to the call come from the arguments that are passed to the event in
the descendant object.
Extending event scripts
The AncestorReturnValue variable is always available in extended
event scripts. When you extend an event script, PowerBuilder generates the
following syntax and inserts it at the beginning of the event
script:
|
1 |
CALL SUPER::event_name |
You only see the statement if you export the syntax of the object or
look at it in the Source editor.
The following example illustrates the code you can put in an
extended event script:
|
1 2 3 4 5 |
If AncestorReturnValue = 1 THEN // execute some code ELSE // execute some other code END IF |
Overriding event scripts
The AncestorReturnValue variable is only available when you override
an event script after you call the ancestor event using either of these
versions of the CALL syntax:
|
1 2 |
CALL SUPER::event_name CALL ancestor_name::event_name |
The compiler cannot differentiate between the keyword SUPER and the
name of the ancestor. The keyword is replaced with the name of the
ancestor before the script is compiled.
The AncestorReturnValue variable is only declared and a value
assigned when you use the CALL event syntax. It is not declared if you use
the new event syntax:
|
1 |
ancestor_name::EVENT event_name( ) |
You can use the same code in a script that overrides its ancestor
event script, but you must insert a CALL statement before you use the
AncestorReturnValue variable.
|
1 2 3 4 |
// execute code that does some preliminary processing CALL SUPER::uo_myevent IF AncestorReturnValue = 1 THEN ... |
For information about CALL, see CALL.
Examples
Example 1
Suppose a window w_ancestor has an event ue_process. A descendant
window has a script for the same event.
This statement in a script in the descendant searches the event
chain and calls all appropriate events. If the descendant extends the
ancestor script, it calls a script for each ancestor in turn followed by
the descendant script. If the descendant overrides the ancestor, it calls
the descendant script only:
|
1 |
EVENT ue_process( ) |
This statement calls the ancestor event only (this script works if
the calling script belongs to another object or the descendant
window):
|
1 |
w_ancestor::EVENT ue_process( ) |
Example 2
You can use the pronoun Super to refer to the ancestor. This
statement in a descendant window script or in a script for a control on
that window calls the Clicked script in the immediate ancestor of that
window.
|
1 |
Super::EVENT Clicked(0, x, y) |
Example 3
These statements call a function wf_myfunc in the ancestor window
(presumably, the descendant also has a function called wf_myfunc):
|
1 2 |
Super::wf_myfunc( ) Super::POST wf_myfunc( ) |