~anjan/sxmo-docs-stable

0005a5fd322dfa811e128f63f47330f97f140ef4 — Peter John Hartman 2 years ago 9983324
split hooks from other scripts
1 files changed, 50 insertions(+), 36 deletions(-)

M USERGUIDE.md
M USERGUIDE.md => USERGUIDE.md +50 -36
@@ 535,7 535,7 @@ refer to [the changelog](./CHANGELOG.md).

## **User Customizable Functionality**

### **Files and Folders**
### **General Settings**

<table>
  <tbody>


@@ 559,11 559,6 @@ refer to [the changelog](./CHANGELOG.md).
      You can also trigger commands in it with "exec".</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_start.sh [^1]</td>
      <td>This is a good place to set the wallpaper for instance, or to start
      some daemons</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/contacts.tsv</td>
      <td>
        <p>TSV file wherein each row is: contactnumber TAB contactname</p>


@@ 589,28 584,52 @@ refer to [the changelog](./CHANGELOG.md).
      <td>$XDG_CONFIG_HOME/sxmo/userscripts</td>
      <td>Directory or file to place user scripts which will automatically appear in the menu system</td>
    </tr>
  </tbody>
</table>

### **Hooks**

If a user-defined hook file does not exist on activity, sxmo will run the
corresponding project defined default hook from `/usr/share/sxmo/default_hooks/`.
For example, if you pickup a call and `$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_pickup.sh` does
not exist, `/usr/share/sxmo/default_hooks/sxmo_hook_pickup.sh` will be run.

Note also that some hooks will be in a subdirectory with a devicename.  For
instance, in `/usr/share/sxmo/default_hooks/` there are `one_button_ereader`
and `three_button_touchscreen` and various names linked to them.  (We determine
the name of your device by looking at
`/sys/firmware/devicetree/base/compatible`.) This allows you to have unique
hooks depending on the kind of device that you are running.

<table>
  <tbody>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_start.sh</td>
      <td>This is a good place to set the wallpaper for instance, or to start
      some daemons</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_ring.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_ring.sh</td>
      <td>
      <p>Executable script to run when the phone is receiving a call / rings</p>
      <p>This script is called with "$1" set to the contact name or incoming number if not in contacts.</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_pickup.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_pickup.sh</td>
      <td>
      <p>Executable script to run when the phone is accepting an incoming call</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_missed_call.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_missed_call.sh</td>
      <td>
      <p>Executable script to run when the phone missed an incoming call</p>
      <p>This script is called with "$1" set to the contact name or incoming number if not in contacts.</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_sms.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_sms.sh</td>
      <td>
      <p>Executable script to run when the phone is receiving a text, mms, or vvm (visual voice mail)</p>
      <p>This script is called with "$1" set to the contact name or incoming number if not in contacts and "$2" the actual text.</p>


@@ 619,20 638,20 @@ refer to [the changelog](./CHANGELOG.md).
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_sendsms.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_sendsms.sh</td>
      <td>
      <p>Executable script to run when the phone has just sent a text</p>
      <p>This script is called with "$1" set to the number (or contact name) and "$2" the actual text.</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_check_state_mutexes.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_check_state_mutexes.sh</td>
      <td>
      <p>This script contains various rules for programs that should block suspend and/or locking.</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_statusbar.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_statusbar.sh</td>
      <td>
        <p>This script contain methods to update some status bar components. See SYSTEMGUIDE</p>
      </td>


@@ 648,33 667,33 @@ refer to [the changelog](./CHANGELOG.md).
      menu (see sxmo_appmenu.sh)</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_presuspend.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_presuspend.sh</td>
      <td>Executable script that is executed prior to suspending the device. If the exit code of this script is
      non-zero, suspend will be cancelled</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_postwake.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_postwake.sh</td>
      <td>Executable script that is executed after waking from suspension. </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/$DEVICE_NAME/sxmo_hook_lock.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/*devicename*/sxmo_hook_lock.sh</td>
      <td>Executable script that is executed prior to locking the device</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/$DEVICE_NAME/sxmo_hook_unlock.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/*devicename*/sxmo_hook_unlock.sh</td>
      <td>Executable script that is executed immediately after unlocking the device</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_lisgdstart.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_lisgdstart.sh</td>
      <td>Script that is executed to start the gesture deamon, overrides the defaults (see ``sxmo_lisgdstart.sh``). This
      allows defining custom gestures.</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_stop.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_stop.sh</td>
      <td>Executable script that is executed immediately after closing the window manager (dwm/sway)</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/$DEVICE_NAME/sxmo_hook_inputhandler.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/*devicename*/sxmo_hook_inputhandler.sh</td>
      <td>Script that is executed when a gesture is to be interpreted. It is passed the WM_CLASS of the active window as
      first parameter and the identifier/name of the gesture (or command to run) in the second argument, as configured with lisgd. See
      ``sxmo_inputhandler.sh`` for details. This script allows you to define your own context-sensitive (i.e. application


@@ 682,54 701,54 @@ refer to [the changelog](./CHANGELOG.md).
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_discard.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_discard.sh</td>
      <td>This script is executed (asynchronously) when you discard an incoming
      call
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_mute_ring.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_mute_ring.sh</td>
      <td>This script is executed (asynchronously) when you mute an incoming call
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_notification.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_notification.sh</td>
      <td>This script will run whenever any kind of notification is received. It can be used for example to blink the
      led if you want to override the default behaviour</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_modem.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_modem.sh</td>
      <td>This hook will run when the modem changes state.  This is where you can use custom code if the SIM is locked.
	    You can consider putting
            something like ``mmcli -i 0 --pin 1234`` in it to unlock automatically, if you don't mind the negative security implications
            that carries in case your device gets compromised.</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_desktopwidget.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_desktopwidget.sh</td>
      <td>This script is run after the window manager starts to provide a desktop widget (like a clock)</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_suspend.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_suspend.sh</td>
      <td>This script is run when system suspends.  It contains the actual suspend call.
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_rotate.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_rotate.sh</td>
      <td>This script is called when we rotate.  $1 is the new orientation (normal, left, right).
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_icons.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_icons.sh</td>
      <td>This script is called every time we load a script.  You can override icons here.
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_contextmenu.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_contextmenu.sh</td>
      <td>This script is called when a menu is loaded.  You may override or add new menu options here.
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/$DEVICENAME/sxmo_hook_inputmenu.sh [^1]</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/*devicename*/sxmo_hook_inputmenu.sh</td>
      <td>This script is called when a (hardware) button is pressed or a touchscreen gesture occurs.  
	You can override the default button mappings here.
      </td>


@@ 739,11 758,6 @@ refer to [the changelog](./CHANGELOG.md).

Note: `$XDG_CONFIG_HOME` by default is equal to `~/.config`

[^1]: If a user-defined hook file does not exist on activity, sxmo will run the
corresponding project defined default hook from `/usr/share/sxmo/default_hooks/`.
For example, if you pickup a call and `$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_pickup.sh` does
not exist, `/usr/share/sxmo/default_hooks/sxmo_hook_pickup.sh` will be run. More details
about hooks in SYSTEMGUIDE.


### **Logging**


@@ 780,7 794,7 @@ The following environment variables can be set in `~/.config/sxmo/profile`:
      <td>$TERMCMD</td>
      <td>Terminal to launch on double-clicking power button and used in scripts. Defaults to `foot` (wayland) or `st` (Xorg).</td>
    </tr>
h    <tr>
    <tr>
      <td>$BROWSER</td>
      <td>Browser to launch on triple-clicking/holding power-button and used in scripts. Defaults to `surf`.</td>
    </tr>