Differences

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

--- pluginapi:xtensionclasssettings [2023/06/11 18:35] – [Accessing your info.json File:] James Sentman
+++ pluginapi:xtensionclasssettings [2023/06/12 15:04] (current) – James Sentman
@@ Line 1: / Line 1: @@
-=====XTension Class: Settings and Top Level Helper Functions=====
+=====XTension Class: Working With Settings=====
 The XTension class holds a reference to an xData object that is kept in sync with the database in XTension. In this database are all the settings from XTension and some other useful information bits that you can access. It is possible to set values into this for local persistent storage but do so via the set xtension data commands below and not by directly accessing the data class.
@@ Line 7: / Line 7: @@
 In addition to any data that XTension adds or is part of the non-dynamic interface all of your user interface keys setup in the dynamic interface portion of the interface setup will be here. You’ll want to create constants for the keys you used when setting it up via the Interface Builder so that you can pull the values out as needed. An additional feature of the xData class is that you can subscribe to specific keys and get a callback just before their value is changed when syncing from XTension.
-=====Writing To The XTension Log:=====
+For more info on getting a callback when a setting value has changed see the forthcoming documentation on the xData object.
->**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.
@@ Line 67: / Line 49: @@
 XTension.writeLog( f’The Unique ID of this database is: {XTension.rootDatabaseId})
 </code>
 =====Keys into the Settings Object=====
-Much more data is available in the settings object at **XTension.settings** which is all the user interface data along with many useful things added by the program itself to aid your plugin in finding things that might be helpful and knowing about other user settings that might affect what you do. Most of these will have keys defined in the xtension_constants.py file.
+Much more data is available in the xData object at **XTension.settings** which is all the user interface data along with many useful things added by the program itself to aid your plugin in finding things that might be helpful and knowing about other user settings that might affect what you do. Most of these will have keys defined in the xtension_constants.py file.
+You can get any value with the .get() function of the xData object. This is not the same as the overridden regular dictionary accessor that powerers the [] selector. Do not use the regular doctionary selector. Use the .get method.
+Pass the key to the get method and an optional second parameter that is the default if there is no key by that name. If the default is not specified and there is no key None is returned.
+  myValue = XTension.settings.get( myKeyAsSetupInInterfaceBuilder, “some default to return”)
@@ Line 115: / Line 109: @@
 >**xtKeyUse24HourTime ‘use24hourtime’** Boolean - Due to potential difficulties with python localization it can be difficult to properly format a time for the User with their default computer preferences. If this is set to true then the default settings on the computer say to use a 24 hour time format, otherwise use a 12 hour format.
+-----
+=====Connection and Port Settings=====
+If you’re using the default port or outgoing/incoming address portions of the UI in XTension then these values can also be read out of the settings object.
+====xtKeyPortName====
+The **xtKeyPortName** is the key that holds the serial port name, or one of other constants that will point to the fact that incoming or outgoing tcp has been selected. This can be read from the settings with something similar to:
+  portName = XTension.settings.get( xtKeyPortName, xtKeyPortNameNone)
+The current valid constants that may be returned are:
+>**xtPortNameNone** - The “None” value was selected for the port, or no port has been selected at all.
+>**xtPortNameOutgoingTCP** - An outgoing connection has been selected, you can get the address and port info with the keys below.
+>**xtPortNameListen** - A listening server has been requested. The Port will be placed in the same xtRemotePort key that us used for the outgoing TCP.
+If the portName is not one of those constants, or if you have disabled those portions of the port selection system with the keys above, then this will contain the name of the serial port that has been selected. The name will be just the system name for the port and not the entire path as needed by the Python serial library. To turn it into a valid string to pass to serial.Serial() use something like this:
+  serialPortPath = f’/dev/tty.{XTension.settings.get( xtKeyPortName)}'
+which will make it valid for passing as the port parameter to serial.Serial()
+====Outgoing TCP Keys====
+If an outgoing TCP connection is selected then the portName key above will match the **xtPortNameOutgoingTCP** constant. The address they have entered and the port will be available via the keys:
+>**xtKeyRemotePort** - Contains the port to connect to. This may be a string or if set from default a number so please do an explicit conversion to integer before sending it to a Socket.
+  workPort = int( XTension.settings.get( xtKeyRemotePort, 80)
+>**xtKeyRemoteAddress** - Contains the IP address or DNS name that the user has entered into the Address field.
+  workAddress = XTension.settings.get( xtKeyRemoteAddress, “127.0.0.1”)
+====Listening Connection Keys====
+Many serial to ethernet adaptors and other devices you may wish to connect to do not listen for incoming connections, but will want to be configured to make a connection to your machine. If that is the case the User make select Incoming as the connection method. In which case they UI will ask them for the port to listen on. It will be stored in the same key **xtKeyRemotePort** that is used for the port for an outgoing connection.
+>**xtKeyRemotePort** - Contains the port to listen on. This may be a string if set by the user or a number if set from defaults so make sure to do an explicit cast to an integer before trying to pass it to the socket.
+  listenPort = int( XTension.settings.get( xtKeyRemotePort, 5089)
+------
+=====All Dynamic Interface Keys====
+When you create a dynamic interface at the top level of the info.json file you must assign string keys to all the fields and controls. To get to that information from your plugin use the key and access them from the settings object just like any of the above. They will be stored at the root level of the settings.
+Assuming you created an interface with a text field and the key set to “jamie.weatherslam.hello” and then created a constant in the plugin where keyHelloMessage was also set to “jamie.weatherslam.hello” then you could get the user setting for that field from the plugin like this:
+  myHelloMessage = XTension.settings.get( keyHelloMessage, “Hello World!”)
+-----
+=====Saving Data In the Settings Data Store=====
+You can also send new values or change values stored in the XTension.settings object. Make sure to use proper path names for the values so that they dont interfere with any XTension constants. The command to set data updates the local data store and then sends a message to XTension asking it to set the same value in the database for this Interface. You can save data with any key in any simple data format, strings, integers, floats and dates. For more complex structures please convert to JSON or some other formatting method and save them as a string, knowing you have to load them from JSON to get the data back out again.
+Any data that you set in this way will be updated locally in your plugin immediately and sent to XTension where it will be saved in the persistent storage of the database for this interface. There are no limits placed on the length of keys or value strings however keep in mind that any info you save here must be written to disk and transferred back and forth between XTension and the plugin while being stored in memory and so forth. Make sure that none of your data structures can grow over time without a mechanism to clean them up. See also the next section on manually removing or adding keyed values from the database.
+>**setXTensionData( key, value)** - key must be a string, value can be strings, numbers, or datetime objects.
+  XTension.setXTensionData( “jamie.weatherslam.hello”, “Greetings to all world leaders!”)
+-----
+=====Manually Removing and Adding Database Entries=====
+As of this moment there is not a helper command in the plugin API to delete keys from the Interface database object. There is for managing data at the Unit level. If this is something that you need please let me know it can be implemented.
+There are scripting commands in XTension to do this however. For testing you can set keyed values and delete keyed values via the single line apple script command line window in the app.
+>**To Manually Delete A Keyed Value:**
+  tell xInterface “name of your plugin instance” to xtremovedata( “your key”)
+>**To Manually Set A Keyed Value:**
+  tell xInterface “name of your plugin instance” to xtsetdata( “your key”)
+Those 2 commands can also be sent to a Unit class in the same way but telling the xUnit object with the proper name.
+Next: [[pluginapi:xtensionhelpers]]