User Tools

Site Tools


xtension_manual:extendinginterface

Extending The User Interface with Custom Script Actions

You can extend the user interface of XTension in several useful ways for adding special actions or scripts for specific units or groups of units.

Get Contextual Handlers

Whenever a contextual menu is about to open, or a detailed unit controls window is about to open either in the app or on the web interface, a unit a handler in the Unit’s On script named “GetContextualHandlers” will be called. Based on the current state of the unit you can return a list of things you’d like to be presented. If the user selects one then the corresponding handler in your units On script will be run for you to take custom action. To add this handler to your units On script you can just type it in manually or you can use the “Insert” toolbar button to insert it with some comments of documentation and all ready to accept the rest of your code.

The simplest example might be to just always return the same thing no matter what.

on getContextualHandlers()
  return {“Flash Twice”, “Flash 10 times”}
end getContextualHandlers

This will add 2 items to any contextual menu or detailed unit controls dialog as shown to the right.

If these are selected XTension will try to run a handler with the same name in the selected Units On script. Since you can’t have spaces in a handler name in AppleScript any spaces will be removed before it tries to find a handler. So “Flash Twice” will run a handler called “FlashTwice” and “Flash 10 Times” will run a handler named “Flash10Times” so your resultant script might be something like:

on flashTwice()
    repeat 2 times
        toggle (thisUnit)
    end repeat
end flashTwice

on flash10Times()
    repeat 10 times
        toggle (thisUnit)
    end repeat
end flash10Times
    

In addition to triggering that from the user interface any other script can tell the unit to do it as well by telling the Unit directly like this:

tell xUnit “name of the unit with the handlers” to flash10Times()

Flash Warning

If you have some Phillips Hue or other color capable devices you may wish to be able to use them for signaling when something has happened. You could extend the interface of your hue bulb to flash a warning for a second and then return to the current normal setting. We’ll call this handler “Flash A Warning”

In the On script of the color capable device add the following script:

on getContextualHandlers()
  return {“Flash A Warning”}
end getContextualHandlers

on flashAWarning()
   brighten (thisUnit) to 100 rgb color “FF0000” for 4 * seconds
end flashWarning

You might wish to extend that further to support more of the Hue device features like the color looping. You can add any number of handlers and they will show up in the Detailed Unit Controls as shown to the right. To also add color looping to the bulb in question you can do the following:

on getContextualHandlers()
  return {“Flash A Warning”, “Begin Color Loop"}
end getContextualHandlers

on flashAWarning()
   brighten (thisUnit) to 100 rgb color “FF0000” for 4 * seconds
end flashWarning

on beginColorLoop()
    blink (thisUnit) rate “colorloop"
end beginColorLoop

Also Works on the Web Interface

The same interface running through the Web Interface would look like this. As of this writing there is no contextual menu support on the web interface but the buttons will appear on the web version of the Detailed Unit Controls. XTension version 9.4.3 brings full support for these menus to both the desktop web remote and the Mobile Web Remote.


Using Groups

While that works great for individual or special units it’s also possible to add the same handlers to multiple units and add the code in only one place rather than repeatedly in each and every Unit’s On script. All events like these start in the Unit’s On script, and if the handler does not exist, or if you have not returned True from the handler, then the events will start to trickle up. Any Group that the Unit is a member of will also receive the event, but with thisUnit set to the name of the unit to which the event was originally sent so that you can use that to properly control the target unit.

See Also

See the tutorial for adding a Battery Changed date field to a unit list.

xtension_manual/extendinginterface.txt · Last modified: 2023/02/13 14:52 by 127.0.0.1