ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / WLanguage functions / Web-specific functions / Miscellaneous WEBDEV functions
  • Mechanism for propagating the events in a browser
  • Special cases
  • Differences between the Event and JSEvent functions
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
Associates a browser procedure with an event on an object in browser code.
This function asks the browser to intercept an event on the current page or on an element of the current page. A specific WLanguage procedure is automatically run when the event is triggered on the specified object. To end the management of the event, you must use JSEndEvent.
Example
// Intercepts all clicks on the page
nPageClick is int
nPageClick = JSEvent(Proc_PageClick, jsEventBody, jsEventClick)
Syntax
<Result> = JSEvent(<WLanguage procedure> , <Target Object> , <Event> [, <Options>])
<Result>: Integer
  • Identifier of event,
  • 0 if an error occurs.
<WLanguage procedure>: Procedure name
Name of WLanguage procedure that will be run when intercepting the event.
This procedure can be a browser procedure global to the project or a browser procedure local to the page that contains the code currently run.
This procedure must have the following format:
PROCEDURE EventManagementProcedure(pclEventJS is object dynamic)
When making the call, the pclEventJS parameter will be initialized with the JavaScript object of the browser event. This is the same object as the one handled or returned by JSInfoEvent.
<Target Object>: Character string or Integer constant
Element on which the event will be managed.
The possible values are:
  • One of the following constants:
    jsEventBodyThe event is directed to the BODY tag of HTML page.
    jsEventDocumentThe event is directed to the document ("document" object of DOM).
    jsEventFormThe event is directed to the current form.
    jsEventWindowThe event is directed to the window ("window" object of DOM).
  • A character string specifying one of the DOM objects (Document Object Model).
  • A character string specifying the ID of one of the page HTML tags.
  • The alias of a page control (Alias)
<Event>: Variant
Name of event to intercept.
This value can be:
  • a character string that indicates the event name.
  • a preset constant:
    jsEventBeforeUnloadThe event is triggered before unloading the page.

    Remark: You can allow the Web user to exit from the page by using the code:
    JSInfoEvent("returnValue") = "Message"
    RETURN "Message"

    The browser will display the message with the "Exit from the page" and "Stay on the page" buttons (or a variation according to the browser used).
    jsEventBlurThe event is triggered when the target object loses focus.
    jsEventChangeThe event is triggered whenever the target object is modified.
    jsEventClickThe event is triggered by a click on the target object.
    jsEventDoubleClickThe event is triggered by a double click on the target object.
    jsEventFocusThe event is triggered when the target object takes focus.
    jsEventGestureChangeThe event is triggered when the user changes the zoom of screen with his fingers (event managed during a display on a phone for example).
    jsEventGestureEndThe event is triggered when the user stops the zoom of screen with his fingers (event managed during the display on a phone for example).
    jsEventGestureStartThe event is triggered when the user starts the zoom of screen with 2 fingers (event managed during a display on a phone for example).
    jsEventKeyDownThe event is triggered when a key is pressed.
    jsEventKeyPressThe event is triggered when a key is pressed and released.
    jsEventKeyUpThe event is triggered when a key is released.
    jsEventLoadThe event is triggered at the end of load of HTML form.
    jsEventMouseDownThe event is triggered when a mouse button is pressed.
    jsEventMouseEnterThe event is triggered when the mouse cursor enters the surface of target object. This event affects the target object only.
    jsEventMouseLeaveThe event is triggered when the mouse cursor leaves the surface of target object. This event affects the target object only.
    jsEventMouseMoveThe event is triggered whenever the mouse is moved.
    jsEventMouseOutThe event is triggered when the mouse cursor leaves the surface of target object. This event affects the target object or one of its children.
    jsEventMouseOverThe event is triggered when the mouse cursor enters the surface of target object. This event affects the target object or one of its children.
    jsEventMouseUpThe event is triggered when a mouse button is released.
    jsEventOrientationChangeThe event is triggered when the device orientation changes (event managed during a display on a phone for example).
    jsEventTouchCancelThe event is triggered when the user cancels the action performed with his finger: displaying the popup menu for example (event managed during a display on a phone for example).
    jsEventTouchEndThe event is triggered when the user removes his finger from the screen to end an action on the screen (event managed during a display on a phone for example).
    jsEventTouchMoveThe event is triggered when the user moves his finger on the screen (event managed during a display on a phone for example).
    jsEventTouchStartThe event is triggered when the user touches the screen with one or 2 fingers (event managed during a display on a phone for example).
    jsEventResetThe event is triggered during a click on a "Reset" button.
    jsEventResizeThe event is triggered when the window is resized.
    jsEventScrollThe event is triggered whenever the browser window is scrolled.
    jsEventSelectThe event is triggered when selecting the target object.
    jsEventSubmitThe event is triggered during a click on a "Submit" button.
    jsEventUnloadThe event is triggered when unloading the HTML form (closing the browser or navigating toward another page).
<Options>: Optional combination of Integer constants
Direction for intercepting the event.
In browser code, an event can be intercepted during the capture or during the return. This parameter is used to specify when the function that processes the event will be called.
The possible values are:
jsEventBubbleThe processing function is called when the event is returned in the target object.
jsEventCapture
(Default value)
The processing function is called when the event is captured by the target object.
Remarks

Mechanism for propagating the events in a browser

The events that can occur in a Web page and that can be intercepted by JSEvent circulate in both directions via the different elements included in the Web page:
  • The capture phase
    In this phase, the event (a mouse click for example) is transmitted to all the page elements in the following order:
    • the window,
    • the document,
    • the HTML form,
    • the different containers (cells) from the most external one to the most internal one,
    • the control.
    To intercept the event during this phase, you must use the jsEventCapture constant.
  • The return phase (also called bubble)
    The event is propagated to the same elements as during the capture phase but in reverse order.
If the process of the event is interrupted during the capture phase (with JSInterruptEvent), the return phase will be run from the element currently processed during the call to JSInterruptEvent.
If the process of event is interrupted during the return phase, the parent elements of the element currently processed will not receive the event.

Special cases

  • Some event names differ according to the browsers. If the event is specified by name, make sure that the name is valid for the browser of Web user. This is the reason why we advise you to use the WLanguage constants that will be automatically interpreted according to the browser.
  • If the target object is a control, the alias (Alias property) of the control must be passed as a parameter to JSEvent instead of its name.

Differences between the Event and JSEvent functions

  • Unlike Event, which is used to capture events in Windows, browser events are propagated to all elements of the relevant webpage in two directions (see above).
  • The procedure called and Event do not have the same prototype.
  • The generic target objects (with the "*" notation) of the Event function are not supported.
Component: WDJS.DLL
Minimum version required
  • Version 15
Comments
Click [Add] to post a comment

Last update: 06/22/2023

Send a report | Local help