Back event

This documentation is valid for:
GeneXus 18 Help
GeneXus 17 Help

Defines an action to be performed when the back button is pressed.

Scope

Objects: Panel, WorkWith
Generators: Android, Apple

Description

In some cases, you may need to control navigation in your application. For example, in a wizard, users should not return to previous steps once they move forward.

The Back event allows you to control this behavior by changing the back button's action or displaying a confirmation dialog before navigating to the previous Panel object.

Apple Limitations

The body of the Back event is restricted to:
1. Leaving it empty for disabling the back button.
2. Programming a Return command only. No other code is allowed.
The reason for this limitation is that Apple does not allow the developer to change the default behavior of a back action (e.g. display a message before back).
As of GeneXus 17, the limitation above does not apply when the Panel is called with CallType.Popup and CallTargetSize different than Large (that is, when it has value Small, Medium, or Default).
In that case, Apple does allow the developer to control how the call is ended, and it is allowed to have a fully supportive Back event.
When a UI object is called with CallOption.Target = 'Blank', ensure that the object does not contain an action on the top-left side of the Application Bar (i.e. Position property = Custom (Apple) and top-left alignment) because the back button will be positioned in that place. If the developer situates a custom button in that place, the back button (and its swipe right gesture) will be disabled and it is the responsibility of the developer to implement the "back action" when it is desired.

Samples

Warning: All examples work as described in Android and on Apple when the above limitations do not apply, but only examples 1) and 2) always work in Apple.

1) Disable the back button.

Event Back
EndEvent

2) Change the default behavior of the back action by using the return command.

Event Back
    Return
EndEvent

3) Display a confirm dialog before canceling the action.

Event Back
    Composite
      Confirm("Are you sure you want to return?") 
      Actions.Cancel()
    EndComposite
EndEvent

4) Call a Panel when the Back button is pressed.

Event Back
      HelloWorldPanel()
EndEvent

Notes

If you are trying to skip Panels that have already been done on a wizard, it is recommended to use CallOptions.Type = Replace on the caller, instead of calling a Panel on the Back event. With that, you optimize the usage of the application stack, replacing old Panels with new ones when navigating through the application.
When the Back event is not implemented, on each platform it behaves by default as an execution of the Actions.Cancel() method. In such a case, the subsequent code of the caller object won't be executed if it is inside a Composite command.
In contrast to the above point, if the Back event is implemented by using the Return command, the subsequent code of the caller object will be executed. For example, suppose you have two Panels, A and B, and the Panel A calls Panel B as follows:

Event 'Call_B'
  Composite
     // ... do something before calling B
     B()  //B is called without parameters
     msg("After calling B")
     // ... do something else after calling B
  EndComposite
EndEvent

If no Back event is implemented on B, or it is implemented using the Actions.Cancel() method, the message after the calling will not be executed if the code is inside a Composite command. If the Back event is implemented by using the Return command, the message ("After calling B") will be displayed on Panel A.