Skip to content

How to add custom scripts

Jump to bottom
Sam edited this page May 13, 2023 · 47 revisions

This quick guide explains how to add custom scripts to Auto Dark Mode that trigger on light or dark theme switches respectively. Currently, this feature is meant to be set up using a yaml configuration file. Rudimentary UI is available (enabling/disabling and opening of the config file via UI). We may eventually provide full UI support for this at a later point. Please do not ask for an ETA.

Are there any ready-to-use scripts available?

Please check our GitHub Discussions scripts section and look for a green scripts tag: Custom script repository

How do I find the scripts config file?

Open the Auto Dark Mode App, navigate to the Scripts section and click "Open script config".

Alternatively you may

  • Open the Auto Dark Mode config folder (right click the tray icon and select "Open Config Directory" or go to the Settings page in the app and select "Open config folder").
  • Open the scripts.yaml file.

Note: If you mess up your scripts.yaml file, you can delete it and restart the service. That will create a new file.

Guide

Once you open the file with your favorite editor, you will see an already defined example. Below there are some comments describing what each entry is for:

# If you want to make use of the scripts feature, set this to true
Enabled: false
Component:
  Scripts:
  - Name: MyApp
    # Command is the path to the executable, it can be something in your PATH, or a full file path
    Command: C:\Users\Mypath\MyExecutable.exe
    # The working directory is optional.
    # You can omit it if you don't care about where your script is executed
    WorkingDirectory: C:\Users\YourUserName\AppData\Roaming\AutoDarkMode
    # The arguments that are passed when the script is called for light and dark mode.
    # They can be omitted as well if not needed.
    # You can either use flow style which is comma separated...
    ArgsLight: [--light, I am another light command]
    # ...or the normal syntax
    ArgsDark: 
      - --dark
      - I am another dark command
    # Specifies the allowed switch sources for better control when to run scripts
    AllowedSources: [Any, TimeSwitchModule, BatteryStatusChanged, SystemResume, Manual]
    # the maximum allowed time each script is allowed to run in milliseconds. Default is 10000 if omitted
    TimeoutMillis: 10000

  - Name: Powershell Example
    Command: powershell 
    ArgsLight: [C:\test.ps1, -message light -emotion 'happy']
    ArgsDark: [C:\test.ps1, -message dark -emotion 'happy']
    AllowedSources: [Any]

  - Name: MyOtherApp
    # Example for calling cmd silently
    # You can replace the "echo I am a dark command" with a patch to a batch file
    # This will call the batch file without displaying a console window
    Command: cmd
    ArgsLight: 
      - /c
      - echo I am a light command
    ArgsDark: [/c, echo I am a dark command]

  - Name: MyMinimalAppNoParameters
    Command: C:\Users\MyUsername\test.exe

Each argument in ArgsLight or ArgsDark is wrapped with "" when called by default.

Auto Dark Mode will then run the scripts when the theme switches or on the next timer tick if the configuration file was changed. It is possible to run any script.

Please note that we will not provide support if your script doesn't work or if you don't escape your arguments or commands properly. The burden of proof that Auto Dark Mode is at fault if your script doesn't run is on you.

Allowed Sources

The script event handler is aware of which module within Auto Dark Mode performed the switch.

The different events are:

  • Any - permits all sources (default)
  • TimeSwitchModule - permits script to run if the source is a timed switch (at sunrise/sunset)
  • NightLightTrackerModule - permits script to run if the source is windows night light
  • BatteryStatusChanged - permits script to run if the source was a battery charge state event
  • SystemResume - permits script to run if the source was a system resume event (wakeup from sleep)
  • Manual - permits script to run if the source was a manual user-invoked event (hotkeys, notifications, in the UI, via shell on --switch)
  • ExternalThemeSwitch - permits script to run if the source is an external switch not invoked by ADM
  • Startup - permits script to run if the source is the first switch when ADM starts up
  • SystemUnlock - permit script to run if the source is a system unlock event
  • Api - permit script to run if the source is a theme swap, force or explicit theme set (light or dark) via the shell

When in doubt, you can always check the switch source by opening the log file and looking for the ThemeManager event. It always includes the switch source.

Output

In the service.log file, Auto Dark Mode will show your script's error and standard output streams including all thrown exceptions by the process runner, should you be in need of debugging.

Clone this wiki locally