Page tree

This document contains detailed rules description and examples in order to understand the order of execution for XML Definition actions.

General execution

Every time an event is handled by the phone (an event can be an"on press" event, an "on release" event etc), the following is executed:

  1. Prior to taking any action, all NotifyParsingRules are evaluated (first the rules of type "applies", then the rules of type "state")
  2. Next, all actions that apply to the current event based on the "when" type (on press, on release etc) are added to a list. For actions with a state or a states condition (for example, state="connected"), the condition is evaluated before any actions are executed (see Example 2)
  3. Next, all actions from the list are executed in the order in which they are added (first in first out)
    We will call this step an "act" = the execution of all the actions in a list. 

    Note that only 1 visible call at a time can be started in one act.

The Longpress feature

Especially when using the "on release" type for line keys, it is important to understand the event occurrence in relation to the "Longpress" feature. By default, this feature is on for all line keys. The feature can be turned off using setting fkey_longpressX (where X is the key index, for example fkey_longpress0 for the first key,  fkey_longpress1 for the second key etc).

If the Longpress feature is off

When pressing the key, the phone executes the expected press event. When releasing the key, the phone executes the expected release event.

If the Longpress feature is on

The initial key press event does not trigger any "on press" action, it only starts a 2-second timer (and if applicable shows the 'pressed' state background color for the key). The idea is to wait for the key release in order to see if this will be a short or a long press.
Then when the key is released:

  • if the key is released before the timer expires, the "on press" event and then the "on release" event are handled, followed by a second "on release" event (see Example 1)
  • if the button is not released before the timer expires, it is considered a long press and the "on press" and "on release" events are not executed. Instead, the longpress event is handled (either the default event which allows users to configure the key, or the action_longpress_url if configured)


Example 1

Configure the following XML definition for key P1:

<general type="Test"/>
  <url target="press" when="on press"/>
  <url target="release" when="on release"/>

Make sure that fkey_longpress0=on.

Press the key shortly (normal short keypress, with a quick release). You will see in the phone log:

Nov 4 13:37:53.776 [NOTICE] PHN: Fetching URL: http://press:80
Nov 4 13:37:53.780 [NOTICE] PHN: Fetching URL: http://release:80
Nov 4 13:37:53.783 [NOTICE] PHN: Fetching URL: http://release:80

This shows that, if the Longpress feature is on and the key is pressed shortly, there is one "on press" event followed by two "on release" events.

Press the key long (longer than 2 seconds). You will also notice that this does not fetch any URL. Instead, it opens a menu that allows you to edit the key functionality.

If you now disable the Longpress feature (you can do this by right-clicking the setting in the Web Interface → Settings, or from the phone menu under Settings → Preferences → Function Keys → Line Keys → Choose the 8th key → LP-Feature), and then press the key shortly again, you will see in the log:

Nov 4 13:45:04.847 [NOTICE] PHN: Fetching URL: http://press:80
Nov 4 13:45:04.988 [NOTICE] PHN: Fetching URL: http://release:80

This shows that, if the Longpress feature is off, the phone handles the expected press and release events (one "on press" followed by one "on release" event).

Example 2

Configure the following XML definition for key P1:

<general type="Test"/>
  <state value="two"/>
  <assign when="on press">    <!-- Assign 1 -->
    <source context="this entity" value="one"/>
    <destination context="this entity" id="state"/>
  <url target="URL1-$(state)" when="on press" states="one"/>  <!-- URL 1 -->
  <url target="URL2-$(state)" when="on press" states="two"/>  <!-- URL 2 -->
  <assign when="on press">   <!-- Assign 2 -->
    <source context="this entity" value="two"/>
    <destination context="this entity" id="state"/>

In this example it does not matter what fkey_longpress1 is set to on or off, because we will do only a short press and we are not using the "on release" event.

Press the key shortly. You will see in the phone log:

Nov 4 15:16:24.574 [NOTICE] PHN: Fetching URL: http://URL2-one:80

Here is an explanation of what happened. At key press, a list with actions got created. The list contained the two assign actions but only one of the url actions(!). Here is the list:

  • Assign 1
  • URL 2
  • Assign 2

Note that URL 1 did not make it to the list because at the time when the button was pressed the state was set to "two" at the time of the list creation, so URL 1 did not pass the condition (states="one").

After the list was created, it was executed:

  • Assign 1 was executed, so "state" got set to "one"
  • URL 2 was executed, so URL http://$(state) was fetched. Since the state was "one" at this point, the fetched URL was http://URL2-one:80
  • Assign 2 was executed, so "state" got set to "two"