Registration

Dear SAP Community Member,
In order to fully benefit from what the SAP Community has to offer, please register at:
http://scn.sap.com
Thank you,
The SAP Community team.
Skip to end of metadata
Go to start of metadata

SAP Screen Personas


 

Current Available Events in Scripting


SAP SCREEN PERSONAS KNOWLEDGE BASE - by Clemens Gantert , Regina Sheynblat

Updated in Application Help for SP08 (9/17/2018)

Purpose

This article provides a reference list of UI controls and their events that can trigger a bound script to be executed. This reference includes the named parameters that are passed to the script when a particular event is fired.

Overview

This article describes event processing and available events included in SAP Screen Personas 3.0:
  1. The events that are now available for standard controls. Allowing event handlers to standard controls was introduced with SP02. The event processing flow is discussed including the capability of suppressing the standard behavior through the personas script that is attached.
  2. A comprehensive list of events and their passed parameters is given. 

Determine the Available Events and Passed Parameters in the Property Inspector 

You can access event information for every control in the script inspector.Select the control of interest in the script inspector by:
  1. Opening an existing or creating a new flavor
  2. Opening the scripting editor
  3. In the script inspector on the right, pressing the selection button.
  4. Hover with your mouse pointer over the control of interest and click it
Here is an example for GuiMainWindow: If you scroll to the bottom of the property list, then you will find the events, identified by a stylized ~. Please note the signature of the event handler methods. These are the names of the parameters that will be available in the bound script.If you select an event and then hover over the information icon ( circled "I") then a description will appear:

Event Processing Flow

There are two types of events:
  1. Page Lifecycle events or global events - onBeforeRefresh, onLoad, and onAfterRefresh
  2. Individual, control-specific events. Examples are GuiButton.onClick, GuiComboBox.onSelect, GuiMainWindow.onEnter, GuiMainWindow.onResize
Individual events are triggered mostly through user interaction. Some individual events are also triggered when a script executes certain methods. Example: A script executing the press() of a custom scripting button will also trigger onClick event of this button and the associated script will be executed.The global events (onLoad, onAfterRefresh, onBeforeRefresh) are triggered constantly - as a byproduct of individual events that are fired due to user interaction or - in case of the onLoad event - when the screen is first loaded.The below flow diagram depicts the event processing.Below is the flow of an onClick event on a standard button. Even though the below example is based on GuiButton.onClick, the flow can be applied to all events whose standard event processing can be suppressed. Note that there can be an event handler for onClick event of the button AND for the onBeforeRefresh of the window. In that case the following happens:
  1. First the script for the individual event executed (onClick). If this script suppresses the standard action by returning a Boolean true, then processing stops here and the UI is rolled back (only for GuiComboBox.onSelect). The standard action will not be processed.
  2. The onBeforeRefresh script is executed. If this script suppresses the standard action by returning a Boolean true, then the standard action will not be processed.

List of Available Events

GuiButton

Event NameHandler SignatureDescription
onClickonClick( GuiButton source)This event is fired when someone clicks on the button control.
Note: This event is also fired for custom controls, but not for standard controls when the press() method is called.
For standard button controls with an onClick script, the script is executed first, before the standard onClick action is performed. The script can suppress the stardard action by returning a Boolean true.
Note: The default behavior is to perform the standard action when the script does not return any value. For the standard action to run without error, the script must ensure that the transaction, program, and screen are the same at the end of script execution as they were before script execution. If a script navigates to a different screen without returning to the originating screen, then it must return a Boolean false to prevent the exection of the standard action from causing an error.

 

GuiComboBox

Event NameHandler SignatureDescription
onSelectonSelect( GuiComboBox source, String newKey)This event is fired when the dropdown listbox's selected value is changed by the user.
If the associated script returns a Boolean true value, then the event propagation is stopped and the backend is not informed that the selection event was raised on the client and the dropdown listbox's displayed, selected value reverts to its pre-selection value. If the script returns anything else ('undefined', 'null', an object, a string, etc.), then the event processing continues normally.
Note: Within the handler script, "source.key" is the old key, the one that was selected before the selection was changed triggering the current onSelect event. "newKey" represents the key that was just selected.

 

GuiTextField

Event NameHandler SignatureDescription
onF4onF4( GuiTextField source)JavaScript that is executed if someone presses the F4 help button

 

GuiCTextField

Event NameHandler SignatureDescription
onF4onF4( GuiTextField source)JavaScript that is executed if someone presses the F4 help button

 

GuiLabel

Event NameHandler SignatureDescription
onClickonClick( GuiLabel source)This event is fired when someone clicks on the label.
Note: This event is also fired for custom controls, but not for standard controls when the press() method is called.
For standard labels with an onClick script, the script is executed first, before the standard onClick action is performed. The script can suppress the stardard action by returning a Boolean true.
Note: The default behavior is to perform the standard action when the script does not return any value. For the standard action to run without error, the script must ensure that the transaction, program, and screen are the same at the end of script execution as they were before script execution. If a script navigates to a different screen without returning to the originating screen, then it must return a Boolean false to prevent the exection of the standard action from causing an error.

 

GuiPasswordField

Event NameHandler SignatureDescription
onF4onF4( GuiTextField source)JavaScript that is executed if someone presses the F4 help button

 

GuiMainWindow

Event NameHandler SignatureDescription
onAfterRefreshonAfterRefresh( GuiFrameWindow source)onAfterRefresh is called after every roundtrip, even on initial load of the page (after the onLoad script is executed).The roundtrip lifecycle is:
  1. onBeforeRefresh
  2. onLoad
  3. onAfterRefresh
onBeforeRefreshonBeforeRefresh( GuiFrameWindow source, TRIGGER_TYPE triggerType, GuiVComponent caller, String vkey, GuiVComponent focused)The assigned script is executed after a dynpro control has triggered a roundtrip. This event is fired on user action of standard controls only. It is not fired if flavor-created controls triggered the roundtrip or if a script triggered the roundtrip implicitly for example by invoking the GuiButton.press() method. Furthermore, technical events sending ok-codes starting with "%_GS" will not trigger onBeforeRefresh. Examples are Dataprovider load events, context menu load events and Personas ABAP layer events.
If the associated script returns a boolean true value, then the started roundtrip is stopped. If the script returns anything else or nothing (in javascript ''), then the started roundtrip continues normally.
  1. The parameter 'source' contains the window object to which the event handler script is attached.
  2. The parameter 'triggerType' contains a numeric differentiator between the various possible triggers. Possible trigger type values are defined as constants for all window objects. Currently supported types are: EVENT_VCOMP, EVENT_VKEY, EVENT_ENTER
  3. The parameter 'caller' is only provided if triggerType was EVENT_VCOMP. It contains the triggering object.
  4. The parameter 'vkey' is only provided if the triggerType was EVENT_VKEY. It contains the corresponding function key .
  5. The parameter 'focused' is only provided if triggerType was EVENT_ENTER. It contains the control that held the focus when the enter key was pressed.
onEnteronEnter( GuiFrameWindow source, GuiVComponent focused)This event is fired by either pressing the enter key or by pressing the enter button (i.e. the leftmost toolbar button with the green check mark).
If the associated script returns a Boolean true value, then the event propagation is stopped and the backend is not informed that the enter event was raised on the client. If the script returns anything else ('undefined', 'null', an object, a string, etc.), then the event processing continues normally. Note that some script actions will trigger the same behavior in the backend as if an enter event was sent, so that in effect the backend still processes an enter event even though the script was suppressing the enter event propagation by returning a Boolean true.
The parameter 'source' contains the window object to which the event handler script is attached.
The parameter 'focused' contains the control that held the focus when the enter key was pressed.
onLoadonLoad( GuiFrameWindow source)The assigned script is executed if any of the following has changed since the last roundtrip: transaction, program, screen number or flavor.
This event can be used to do one-time initialization.
The page load lifecycle is:
  1. onLoad
  2. onAfterRefresh
onResizeonResize( GuiFrameWindow source, int width, int height)This event is fired when the client window is resized.
If the associated script returns a Boolean true value, then the event propagation is stopped and the backend is not informed that the resize event was raised on the client. If the script returns anything else ('undefined', 'null', an object, a string, etc.), then the event processing continues normally.
The parameter 'source' contains the window object to which the event handler script is attached.
The parameters 'width' and 'height' contain the new client window dimensions in pixels.

 

GuiModalWindow

Event NameHandler SignatureDescription
onAfterRefreshonAfterRefresh( GuiFrameWindow source)onAfterRefresh is called after every roundtrip, even on initial load of the page (after the onLoad script is executed).The roundtrip lifecycle is:
  1. onBeforeRefresh
  2. onLoad
  3. onAfterRefresh
onBeforeRefreshonBeforeRefresh( GuiFrameWindow source, TRIGGER_TYPE triggerType, GuiVComponent caller, String vkey, GuiVComponent focused)The assigned script is executed after a dynpro control has triggered a roundtrip. This event is fired on user action of standard controls only. It is not fired if flavor-created controls triggered the roundtrip or if a script triggered the roundtrip implicitly for example by invoking the GuiButton.press() method. Furthermore, technical events sending ok-codes starting with "%_GS" will not trigger onBeforeRefresh. Examples are Dataprovider load events, context menu load events and Personas ABAP layer events.
If the associated script returns a boolean true value, then the started roundtrip is stopped. If the script returns anything else or nothing (in javascript ''), then the started roundtrip continues normally.
  1. The parameter 'source' contains the window object to which the event handler script is attached.
  2. The parameter 'triggerType' contains a numeric differentiator between the various possible triggers. Possible trigger type values are defined as constants for all window objects. Currently supported types are: EVENT_VCOMP, EVENT_VKEY, EVENT_ENTER
  3. The parameter 'caller' is only provided if triggerType was EVENT_VCOMP. It contains the triggering object.
  4. The parameter 'vkey' is only provided if the triggerType was EVENT_VKEY. It contains the corresponding function key .
  5. The parameter 'focused' is only provided if triggerType was EVENT_ENTER. It contains the control that held the focus when the enter key was pressed.
onEnteronEnter( GuiFrameWindow source, GuiVComponent focused)This event is fired by either pressing the enter key or by pressing the enter button (i.e. the leftmost toolbar button with the green check mark).
If the associated script returns a Boolean true value, then the event propagation is stopped and the backend is not informed that the enter event was raised on the client. If the script returns anything else ('undefined', 'null', an object, a string, etc.), then the event processing continues normally. Note that some script actions will trigger the same behavior in the backend as if an enter event was sent, so that in effect the backend still processes an enter event even though the script was suppressing the enter event propagation by returning a Boolean true.
The parameter 'source' contains the window object to which the event handler script is attached.
The parameter 'focused' contains the control that held the focus when the enter key was pressed.
onLoadonLoad( GuiFrameWindow source)The assigned script is executed if any of the following has changed since the last roundtrip: transaction, program, screen number or flavor.
This event can be used to do one-time initialization.
The page load lifecycle is:
  1. onLoad
  2. onAfterRefresh
onResizeonResize( GuiFrameWindow source, int width, int height)This event is fired when the client window is resized.
If the associated script returns a Boolean true value, then the event propagation is stopped and the backend is not informed that the resize event was raised on the client. If the script returns anything else ('undefined', 'null', an object, a string, etc.), then the event processing continues normally.
The parameter 'source' contains the window object to which the event handler script is attached.
The parameters 'width' and 'height' contain the new client window dimensions in pixels.

 

GuiTab

Event NameHandler SignatureDescription
onActivatedonActivated( GuiTab source, MODE mode)JavaScript that is executed after a tab was activated. The source parameter contains the GuiTab that was activated. The mode parameter indicates what caused the tab to be activated.

 

GuiPicture

Event NameHandler SignatureDescription
onClickonClick( GuiPicture source)This event is fired when someone clicks on the GuiPicture control.
Note: This event is also fired for custom controls, but not for standard controls when one of the following methods is called: click(), clickPictureArea(), clickContentArea().
For standard picture controls with an onClick script, the script is executed first, before the standard onClick action is performed. The script can suppress the stardard action by returning a Boolean true.
Note: The default behavior is to perform the standard action when the script does not return any value. For the standard action to run without error, the script must ensure that the transaction, program, and screen are the same at the end of script execution as they were before script execution. If a script navigates to a different screen without returning to the original screen, then it must return a Boolean false to prevent the exection of the standard action from causing an error.

 

GuiTableControl

Event NameHandler SignatureDescription
onCellDoubleClickonCellDoubleClick( GuiTableControl source, String columnName, int rowIndex, String cellValue)This event is fired when a cell is double-clicked. This event can be suppressed. In other words, if the script handler returns a JS boolean "true", then the occurance of this event is not sent to the ABAP backend.
onSelectonSelect( GuiTableControl source)This event is fired when a row selection is changed in any way. Table property 'selectedRows' will be updated before the event handler script is called and can be used within the script to determine the updated current list of selectedRows.

 

GuiGridView

Event NameHandler SignatureDescription
onCellDoubleClickonCellDoubleClick( GuiGridView source, String columnName, int rowIndex, String cellValue)This event is fired when a cell is double-clicked. This event can be suppressed. In other words, if the script handler returns a JS boolean "true", then the occurance of this event is not sent to the ABAP backend.
onSelectonSelect( GuiGridView source)This event is fired if when a row selection is changed in any way. Table property 'selectedRows' will be updated before the event handler script is called and can be used within the script to determine the updated current list of selectedRows.

 

Related Content

Related Search Terms:

SAP Screen Personas, Personas Scripting

Related SAP Notes/KBAs

Available Events for Scripting2050325 - SAP Screen Personas 3.0 : Released Notes Information