Client events allow you to add behavior and logic to the application mixing the execution between the client-side and server-side. As mentioned in Native Mobile Applications Events, Start, Refresh and Load are server-side(1) events. All other events are client-side events, you can mix the power of the server and the resources of our device.
Client-side events must use the Composite command when executing more than one action.
ClientStart event is the first event executed on the device, even before executing the Start event (server-side), without user interaction. Allows the developer to initialize the entry screen, e.g. UI, variables, etc.
Navigation.Start event(2) is executed immediately after the ClientStart event, and allows the developer to initialize aspects related to navigation style (e.g. call the main panel when the application has Slide navigation).
Back event allows the developer to capture when the end-user press back button on Android or do a back gesture on iOS.
These events are the programmatic response of the application to user interaction. These forms of interaction are called actions and can be seen in on-screen buttons, images, or other controls that when tapped, long tapped, etc., will execute the event associated to the action. There also exists other predefined events that are executed in special cases or without any user interaction.
Mainly you have two types of events: user and control events. Both are associated with controls. The slight difference is while the former has a name given by the developer and then associated to the controls themselves (with the tap gesture as the way to trigger them); the latter are automatically predefined, depending on control type, having, in the case of touch control events, the event itself as the way to trigger them (e.g. control.LongTap event). Other kind of control events are, for example, control.PageChanged event (when control is a grid of certain control type), or control.ControlValueChanged event (when control is a read-write attribute or variable).
What happens when the end-user triggers an action? The associated code is executed on the client-side (i.e. in the device) unless a roundtrip to the server is required; for example, when a procedure must be invoked. In any case, system events are not executed (unless they are explicitly required by the Refresh command).
In this event, the developer is allowed to:
- Call Rest Web Services:
- Call a WorkWith
Call a Work With object Detail node in order to Insert, Update or Delete information:
- WorkWithDevicesObject.levelname.Detail.Delete( primaryKey )
- WorkWithDevicesObject.levelname.Detail.Update( primaryKey )
- WorkWithDevicesObject.levelname.Detail.Insert( &bc )
Call a Work With object List or Detail:
- WorkWithDevicesObject.levelname.Detail( primaryKey )
- WorkWithDevicesObject.levelname.List( )
- Call a Panel object
- Call a Menu object
- Invoke the external objects of the Smart Devices API. For example,
- Confirm (&var)
- AddressBook.AddContact( ... )
- Call a Panel for Web by means of the Component domain.
This action displays a web page by the web navigator, loading the web panel without showing the navigator's frame. That can be recovered if the user wishes to do so.
- Call to Subroutines.
- Control properties assignments depending on the control.
When the developer enters the control name followed by a dot ("."), an IntelliTip is opened showing all possibilities for this control.
- Control.visible = ...
- Control.class = ...
- Simple variable assignment.
- &Var = "Test"
- &Var = 123
- &Var = proc.Udp()
- Use SDT or BC based variables element assignation.
- &Var = &SDT.Field
- &BC.item = ...
- Execute For Each Line and selected line commands in grids with multiple selections.
- Use If-Else-EndIf, Do-Case and Do-While code blocks.
Cannot use complex expressions on the conditions such as calling Procedures or External Objects methods; only simple conditions are allowed using variables, attributes or SDT members, and involving operators and standard functions.
Note: As you can see, the For Each command is not allowed. So, in case of defining it inside these events, the following error message will be displayed: error: Line can't be interpreted by devices.
(1) Note that in this context, "server-side" refers to the architecture and not to the actual location of the code being executed. In Offline applications, the Start, Refresh and Load events execute locally, but they still have the same limitation regarding the type of code they can execute.
(2) Navigation.Start event actually refers to a family of events. There is one evento for each type of navigation. For example, Tabs.Start or Slide.Start.
Grammar of Events on the Client Side and Composite Command
Events in Mobile Applications