User Tools

Site Tools


plugins

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revisionBoth sides next revision
plugins [2018/08/11 15:37] – added language support info James Sentmanplugins [2018/08/11 16:02] James Sentman
Line 17: Line 17:
 While there is no current interface to creating plugin specific menu items beyond the contextual ones mentioned below, you can create a submenu in the Global Scripts menu and add items to that if you wish. This is the mechanism used in the Database Sharing when a global script is shared to a receiving XTension implementation. Your script can add items to this menu though the interface might be slightly confusing depending on what the script will be doing. Adding a plugin menu that you can add submenus to is also on my list, if that is something you need sooner please let me know. While there is no current interface to creating plugin specific menu items beyond the contextual ones mentioned below, you can create a submenu in the Global Scripts menu and add items to that if you wish. This is the mechanism used in the Database Sharing when a global script is shared to a receiving XTension implementation. Your script can add items to this menu though the interface might be slightly confusing depending on what the script will be doing. Adding a plugin menu that you can add submenus to is also on my list, if that is something you need sooner please let me know.
  
-===Plugin Units vs Database Sharing===+====Plugin Units vs Database Sharing====
 There are 2 modes that a plugin can operate in. The regular mode is for providing an interface to some physical device. This lets you create units in XTension that are linked to a specific plugin instance. You do not have access to the rest of the database but can only control your units. There are 2 modes that a plugin can operate in. The regular mode is for providing an interface to some physical device. This lets you create units in XTension that are linked to a specific plugin instance. You do not have access to the rest of the database but can only control your units.
  
 You can add the Database Sharing option to your info.json file and in that case the user will be presented with options for choosing what units will be sent to your interface instance. This is for plugins that might wish to provide a bridge to some other functionality like sharing units to an Alexa or HomeKit or just creating a PubSub or MMQT interface to portions of the database. As of V2.0 of the API you can ask for Units and Global Scripts to be shared. The user will be able to select either to share the entire database or to select from lists of Units and select individual Global Script. This is the interface that is used for the built in [[supported_hardware:databasesharing|Database Sharing]] plugin. You can add the Database Sharing option to your info.json file and in that case the user will be presented with options for choosing what units will be sent to your interface instance. This is for plugins that might wish to provide a bridge to some other functionality like sharing units to an Alexa or HomeKit or just creating a PubSub or MMQT interface to portions of the database. As of V2.0 of the API you can ask for Units and Global Scripts to be shared. The user will be able to select either to share the entire database or to select from lists of Units and select individual Global Script. This is the interface that is used for the built in [[supported_hardware:databasesharing|Database Sharing]] plugin.
  
-===Sharing well known ports or UDP sockets with other plugins===+====Sharing well known ports or UDP sockets with other plugins====
 This is particularly a problem with programs that want to respond to or listen for things like UPNP packets. Only one program on a machine can be listening the specific UDP socket that UPNP happens over. XTension gets around this problem by providing for certain networking functions in the App itself. You can send commands to XTension that request a UDP port be opened and added to a broadcast group and then your app will receive any receptions of packets over the XTension API and so will any other plugins that have asked for that particular socket or broadcast group. You can also broadcast packets the same way by wrapping them in a command to XTension. This way many plugins may service different kinds of UPNP devices, or even provide UPNP sharing of XTension units. This is particularly a problem with programs that want to respond to or listen for things like UPNP packets. Only one program on a machine can be listening the specific UDP socket that UPNP happens over. XTension gets around this problem by providing for certain networking functions in the App itself. You can send commands to XTension that request a UDP port be opened and added to a broadcast group and then your app will receive any receptions of packets over the XTension API and so will any other plugins that have asked for that particular socket or broadcast group. You can also broadcast packets the same way by wrapping them in a command to XTension. This way many plugins may service different kinds of UPNP devices, or even provide UPNP sharing of XTension units.
  
-===Contextual Menu Handlers===+====Contextual Menu Handlers====
 You can add contextual menu handlers to any unit through your plugin. You can define these in the info.json handler for the specific unit type. When the user selects them an execute handler command will be sent to your plugin with the name of the function selected. These menu items are also available as buttons in the advanced unit control windows though I may separate the two things in a future API version. You can add contextual menu handlers to any unit through your plugin. You can define these in the info.json handler for the specific unit type. When the user selects them an execute handler command will be sent to your plugin with the name of the function selected. These menu items are also available as buttons in the advanced unit control windows though I may separate the two things in a future API version.
  
-===Adding Script Commands===+====Adding Script Commands====
 While Python is used for plugin development, internal to XTension AppleScript is used as the scripting language. XTension supports the AppleScript Object Model and any unit may be wrapped in a tell block. There are many commands and settings that can be sent to a unit this way. Any commands received through such a script that are not one of the reserved commands or well known handlers that are built into XTension will be sent to the Units On script. The user can create their own handlers there to extend functionality themselves. Any handler request that is not handled by the unit’s ON script will be forwarded to the plugin instance that the unit belongs to. These events can be trapped in your subclass of the xtUnit object of your plugin code. The same mechanism is used for Interface level scripting. If the Interface object in XTension is told to do something and the handler name is not a known command then the request to handle it is passed to the AppleScript attached to the Interface. If the command is not handled there by the user then it will also be forwarded to the plugin code. You can trap those in a similar way by adding a handler to the root XTension object. This enables you to extend the scripting dictionary by doing something like: While Python is used for plugin development, internal to XTension AppleScript is used as the scripting language. XTension supports the AppleScript Object Model and any unit may be wrapped in a tell block. There are many commands and settings that can be sent to a unit this way. Any commands received through such a script that are not one of the reserved commands or well known handlers that are built into XTension will be sent to the Units On script. The user can create their own handlers there to extend functionality themselves. Any handler request that is not handled by the unit’s ON script will be forwarded to the plugin instance that the unit belongs to. These events can be trapped in your subclass of the xtUnit object of your plugin code. The same mechanism is used for Interface level scripting. If the Interface object in XTension is told to do something and the handler name is not a known command then the request to handle it is passed to the AppleScript attached to the Interface. If the command is not handled there by the user then it will also be forwarded to the plugin code. You can trap those in a similar way by adding a handler to the root XTension object. This enables you to extend the scripting dictionary by doing something like:
  
Line 38: Line 38:
  
  
-===Installing and Un-Installing Plugins===+====Installing and Un-Installing Plugins====
 XTension provides a mechanism to install a plugin. Once the user has downloaded your plugin file and decompressed it or mounted the disk image they can select “Install Plugin” from the Database menu. That will open a select folder dialog which they can use to select your plugin folder. XTension will copy the folder into the Plugins folder in the database and load all it’s info.json file so that it will be available in the popup of interface types in the Edit Interface window. If the user us upgrading a plugin the older version will be moved to the trash and replaced with the new folder. Any interfaces that are currently running that older version will be recycled so that they come back up with the new version.  XTension provides a mechanism to install a plugin. Once the user has downloaded your plugin file and decompressed it or mounted the disk image they can select “Install Plugin” from the Database menu. That will open a select folder dialog which they can use to select your plugin folder. XTension will copy the folder into the Plugins folder in the database and load all it’s info.json file so that it will be available in the popup of interface types in the Edit Interface window. If the user us upgrading a plugin the older version will be moved to the trash and replaced with the new folder. Any interfaces that are currently running that older version will be recycled so that they come back up with the new version. 
  
 The XTension interface to managing plugins is a work in progress, there is no way as of 9.4.8 to check plugins for available updates or to install or remove them. To remove a plugin select “Reveal Plugins Folder In This Database” from the Database menu and the database bundle will be opened and the Plugins folder within it highlighted. Drag the plugin you wish to remove out of that folder to the trash. Then delete any configured instances of that plugin. The XTension interface to managing plugins is a work in progress, there is no way as of 9.4.8 to check plugins for available updates or to install or remove them. To remove a plugin select “Reveal Plugins Folder In This Database” from the Database menu and the database bundle will be opened and the Plugins folder within it highlighted. Drag the plugin you wish to remove out of that folder to the trash. Then delete any configured instances of that plugin.
  
-===Blocking and Non-Blocking Plugins===+====Blocking and Non-Blocking Functions====
 Since the plugin runs as a separate process from XTension you can use any combination of blocking or threaded operations without worrying about blocking the host app. If you perform a blocking action in response to a received command from XTension that should be bumped out to a separate thread to await it’s return. XTension will regularly send a ping to your interface that needs to be returned or it will recycle your interface thinking it had hung up. You should not block in any event received from XTension. Since the plugin runs as a separate process from XTension you can use any combination of blocking or threaded operations without worrying about blocking the host app. If you perform a blocking action in response to a received command from XTension that should be bumped out to a separate thread to await it’s return. XTension will regularly send a ping to your interface that needs to be returned or it will recycle your interface thinking it had hung up. You should not block in any event received from XTension.
  
  
 NEXT: [[plugins:01_files|]] NEXT: [[plugins:01_files|]]