Mac Home Automation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====XTension Class: Helper Functions=====

The XTension class contains many helper functions to send commands to XTension without having to manually create the command object with the correct settings and targets. the **setXtensionData** command was already covered on the [[pluginapi:xtensionclasssettings|XTension Class Settings page]] Getting Unit references was already covered on the [[pluginapi:xtensionclass|XTension Managing Units]]

-----

=====Writing To The XTension Log:=====

Both the XTension class and the xtUnit class have writeLog and debugLog functions. If you use the correct one then the Log windows in XTension will be able to filter the log lines by the Interface or Unit that sent them. When something at the top level of the plugin is logging it should use the XTension.writeLog method. If something that is coming from or about a Unit is being logged that a User might like to setup a filter on the Unit to find more easily use the xtUnit.writeLog and debugLog functions.

Writing the log with the Red color is considered an “error” or urgent message. You should not spam the Errors Only filter with messages that are not on that level. Use a different or the default color of blue.




>**writeLog( StringToWriteToLog, (optional) log line color constant)** 
>**debugLog( StringToWriteToLog if in debug mode, (optional) log line color constant)**
<code python>
  XTension.writeLog( “stop pressing that button!”, xtLogRed)
  XTension.debugLog( “you’ll only see this if youre in debug mode!”, xtLogGreen)
  XTension.writeLog( “This will be logged in orange!”, “FFCC22”)
</code>

standard write log command writes to the log with a default color of blue. If you wish to write in one of the other constants they are:
  * xtLogBlack
  * xtLogBlue
  * xtLogGreen
  * xtLogRed

Alternatively you can pass a 6 character string of RGB hex values to log in a custom color. As long as it’s readable and you wish to see them in a different color from the norm it’s fine to use this. I normally only do when in debug mode. 

The debugLog call takes the same parameters but only ends up in the log if the User as put this interface into debug mode.


-----

=====Forcing a Shutdown and Restart=====

A plugin cannot tell XTension as a whole to shutdown, but it can shutdown itself. When XTension sees that a plugin instance has unexpectedly stopped, either on purpose or as the result of a crash it will wait 5 seconds or so and attempt to restart the plugin. If something has happened and the only reasonable way to recover from it is to restart as a fresh instance you can use the **doShutdown** command. If some system resource has caused a problem and stuck open is the only reason i’ve ever considered doing this. Something like a bluetooth resource or a USB device that you cannot recover without shutting down the process that remains attached to an otherwise failed or hung device.

>**doShutdown()** takes no parameters. Attempts a clean shutdown by calling all the handlers registered for the shutdown command and cleanly closing the pipe to XTension. If the User has not disabled the interface before the 5 second delay is up the Interface instance will be restarted.
  XTension.doShutdown()


-----
=====Managing Error and Status Display=====

Every running interface has both an error display colored disk which is displayed in many places as well as a status message which can just sit at a “Ready” message or can be used to show some other activity of the plugin. If the plugin is in an error state this status should be set to something that describes the problem. The space available in this window is limited so the status messages should be kept short. More information can be written to the log if necessary. 

>**setRunState**( newRunState - enumerated string, “Short Status Message” - String)
  XTension.setRunState( xtRunStateFail, “The government has revoked your stolen launch keys”)



The run state can be one of the following:

>**xtRunStateOK** - Displays the color green in the status disk that is displayed in the interface list window and in the Unit list windows Interface column. This is set automatically upon enabling the interface even if it was previously in an error state when it was disabled so you do not have to set it to OK upon startup. Though you can and you should add a “Ready” or “Connected to..” type message so the User can see that it’s actually running properly.


>**xtRunStateError** - The status display will be yellow. A short descriptive message about the problem should be added as the message. The Error state is generally used for something that you’re going to retry and might start working again. A disconnection from the server might set the error state and a message saying that you were attempting to reconnect. More info should be written to the log as needed.


>**xtRunStateFail** - Sets the status display to red. This is generally used for an error that is unlikely or impossible to recover from by just retrying. Something that will require User intervention to sort out. Like they failed to fill in the network address field, or the password was entered incorrectly or something like that. This is also the state that is displayed if you use the doShutdown command to force a restart while it is waiting to restart and during the same time if the plugin process actually crashes. More info should be written to the log as needed.


It is acceptable to call this with the same values as the current settings. Those are checked in the method and no commands are sent to XTension if the values are the same as what is already in our database.

It is fine to send this with an empty string for the message value in order to clear a previous message or error if you do not wish to immediately return to a ready type display. 


You can also set the status without updating the run state if you wish using the **setStatus** command:

>**setStatus( “new status text” String)** Pass any short descriptive string or an empty string to clear the entry. If the status is the same as the currently displayed value no command will be sent to XTension so it is not necessary to check that before calling unless you wish to avoid that overhead as well. Useful for messages such as “scanning for new devices...” and then “43 devices found, next scan at 04:30” or something similar. 
  XTension.setStatus( “7 Bit Coin were found this session!”)


-----
=====Showing More Info in a Window in XTension:=====

It is possible to open a window in XTension to display larger or more imprtant or persistent info or anything the user might ask for that is difficult to read out of the log as it scrolls by. Obviously there is a limit to how many windows you can open and not affect the running of the program so you should do this only if it is actually the correct way to display someting to the user. In the Amcrest camera API I use this to display a long list of camera capabilities but only when the user has requested to see this. They can then save that information as a text file or copy and paste into anything else from there. Or close the window themselves.

Since Windows are resource intensive you can use a unique id of some sort to target the same window you opened last time and replace the info in it, or append more data to it. If you supply a unique ID it will have the interfaces unique id appended to it before using it, so it is OK to use a short string to ID the window rather than putting something together that includes your interface ID. Just use “camera info” and not XTension.interfaceId + “camera info” or something like that. 

Appending forever when the User has never made it to the computer to notice is a very bad thing and you should not do that. If you do not supply a unique key then the ID of the interface instance will be used and every new attempt to show info in a window will overwrite the currently displayed info. There is no command to close the window automatically it will sit there until the User closes it or XTension quits. The contents of these windows are not restored after a restart. 

The window is a simple text field and cannot display colors or styled text or images or anything fancy. 


>**showWindow( theText String, uniqueId String optional, dataType String optional “txt”, windowTitle String optional, append boolean optional)** The dataType is the suffix that will be used if the user was going to save the file to disk. Defaults to “txt” but might be “json” or “xml” or whatever would make the most sense for the kind of text in the window. If you set append to true then the new text you send will be appended to the bottom of any contents already in the window with this ID, if any. 


-----

=====Executing A Script Handler In XTension:=====

Every interface has a script associated with it where the user can handle errors, perform scripting tasks when the interface is enabled or diabled and so forth. It also has the ability to run handlers under control of the plugin. 

Passing parameters to the handler is limited to simple data types that can be converted to a string. The handler must have as many parameters to it as you add to the command or it will not be found as a valid target for the command. Since the values that are sent to the script are always converted to a string the user must know if they need to convert to a number or other structure so make note of that in your script template.

The handlers that you support should be in the script template for the plugin type and/or added to the insert popup menu of available handlers. This is in the toolbar and holds all the standard callbacks and when selected the template for the event is added to the bottom of the script. This way the User knows what your plugin can do and gets a quick reminder of how to implement it. See the info.json file documentation for more info on defining this info for your plugin.

If the user has not implemented the handler the command will be ignored without error. There is no way currently to know if the User handled the command or if an error was generated. There is also currently no way to get any return data from the callback. The data flow is strictly one way.

The call takes 2 parameters, the first is the name of the handler that will be called, the second is an optional list of parameters to pass to it. If no list is included then the script handler without any parameters will be called.

>**runLocalInterfaceScriptHandler( handlerName String, listOfParameters optional list of string)**
  XTension.runLocalInterfaceScriptHandler( “importantMessage”, [“you have a new twitter follower”, “henchman302@gmail”])

would run a handler in the interface script that looked like this in AppleScript

  on importantMessage( theMessage, theEmail)
    say “you have a new important message: “ & theMessage
    say “and we have his email: “ & theEmail
  end importantMessage


-----

Next:[[pluginapi:subscriptions]]