Differences

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

--- pluginapi:infounits [2023/06/08 17:29] – created James Sentman
+++ pluginapi:infounits [2023/06/11 14:29] (current) – Added menu handlers section and hasQuery key James Sentman
@@ Line 3: / Line 3: @@
 It is not required that a plugin implement any Unit definitions. If this is left out then you will not be able to create any Units associated with the plugin instance. If this is present then when creating a new Unit and assigning the new unit to this plugin instance these unit types will be available in the edit unit window to select from. This is also where you would include any custom interfaces for the specific Edit Unit window or the 2 different sizes of specific control windows.
-The **deviceTypes** block is a list of json dictionaries each with the keys necessary to describe a kind of Unit the plugin will use.
+The **deviceTypes** block is a list of json dictionaries each with the keys necessary to describe a kind of Unit the plugin will use. All the below keys are to be used inside a dictionary in the list of "deviceTypes"
 An example of what a unit definition block in the info.json file might look like:
@@ Line 43: / Line 43: @@
 This defines 3 Units each with a unique tag which is required and used internally for indexing and re-assigning this unit type popup and controlling which unit subclass you create in your plugin and so forth.
+The popup is not sorted and will be presented in the order that you put them into the deviceTypes list. You can also add an entry with the name set to “separator” and no other settings to create a standard line separator in the popup. This can be useful to block different types of Unuits together when it makes more sense than just putting them all in alphabetical order. You can see a separator in the example above.
 =====Required Keys:=====
@@ Line 62: / Line 64: @@
 =====Unit Behavior Keys:=====
 These keys are not required and are not permanent for the Unit. They can be edited at any time by the user or set programattically from your plugin. These settings offer a default setup for the Unit when created by the User. If you create them automatically from inside your plugin you still need to include the appropriate keys for the behavior you wish.
+>**hasQuery** Boolean - defaults to false. If this is set then the interface will present an option to send a query where appropriate. If this is set then the contextual menu for the Unit in any list will also have an option to query the Unit.
+  “hasQuery”:true,
 >**dimmable** Boolean - defaults to false. With this set to true the Unit will be “dimmable” or just able to hold a numerical value. Without this the Unit will be discrete just being able to be turned on or off. Corresponds to the checkbox of the same name.
@@ Line 125: / Line 131: @@
 >**dimmableType** Enumerated String - must be one of the following types: “simple”, “simulated” or “smart”
   “dimmableType”:”simulated”,
+-----
+=====Addressing Options:=====
+Unit addressing internally to XTension is done by a path of information. The unique ID of the Interface/Plugin Instance that it is assigned to, then the “tag” that shows what type of unit it is, and finally the Address of the Unit as entered usually by the user in the Edit Unit dialog, or when automatically creating a Unit. On each interface only one Unit of each “tag” type can have the same address. There can only be 1 Unit of tag “mything.temperature” with the address of “1” but there can be an address of “1” for each type on that interface, a “mything.temperature” address “1”, a “mything.humidity” with address “1” an a “mything.lux” with address “1”.
+It is not required to add any addressing information to the info.json file. If it is not specified then any new units the User creates will have the regular empty text field to fill in. Any Units you create automatically from the plugin are not affected and can have their addresses set any way you choose.
+There are 2 values you can assign to the optional “address” key. If it is a JSON list of strings then the user will be presented with a popup menu with those options rather than an empty text field. This is only useful if there are a limited number of possibilities. It can also be the string “auto” in which case it will not be required that the User enter an address at all. When the Unit with an empty address is saved an automatically generated unique ID will be assigned to the Address and then the unit saved and indexed.
+This last auto setting makes sense if the address is not really part of the system to find and work with the Unit inside the plugin. I have used this in places like for the Calendar plugin where the User may create any number of event search Units. It doesn’t make sense to force them to put the search string into the address or keep count of how many they are or something, so this lets them create any number of Units and not worry about it.
+>**address** String: “auto” - used when the User may create any number of units and a unique address would not be related to anything internal to the plugin where you would be looking the Unit up by address. Just walking the list of all the units of that type to process.
+  “address”:”auto”,
+>**address** JSON List of String - used where there are a limited number of selections for the Units to provide a popup menu rather than an empty address field.
+  “address”:[“1”, “2”, “3”, “4”, “5”, “6”],
+>or possibly something like:
+  “address”:[“UP”, “DOWN”, “LEFT”, “RIGHT”],
+-----
+=====Menu Handlers:=====
+You can also add callbacks to the plugin by adding items to the contextual menu for the Unit. This is the same technique that you can use to add menu items to the contextual menu of the Interface itself. In this case the “menuHandlers” key is inside the deviceType dictionary rather than in the root of the info.json where they would be assigned to the Interface as a whole. Items added in this way are also given a button in the Advanced Controls (see dynamic interface section below) so the user can access these from the web remotes or via that mechanism as well as through the contextual menu. Note that there is no way to pass any information to plugin from these handlers. They are simply run with no parameters.
+The data in this key is a json list of lists. Each of the inner lists has 2 items, first the name of the action as you wish it to appear in the menu, the human readable version, and the second is the name of the script handler callback that will be run when the user selects this.
+Use the Unit parent class “addScriptHandler” command to register a callback to be run when that action name is run by the user.
+  “menuHandlers”:[[“Open The Door”, “openTheDoor”], [“Knock On the Door”, “knockOnTheDoor”], [“Run Away”, “runAway”], ...]
+-----
+=====Dynamic Interfaces:=====
+There are 3 places you can create dynamic interfaces specific to a Unit type inside these definitions. The most commonly used one is the “editControls” block in the example above. These controls are shown in the first tab of the Edit Unit Dialog. The Height is adjusted and the window is either resized or a scrollbar is displayed to the user if there is not enough space. While these can be generated by hand it would be much easier to use the [[pluginapi:interfacebuilder|Dynamic Interface Builder]] app.
+The “Small Controls” window can be added to this with the key of “smallControls” and the “Advanced Controls” can be added to this with the key of “controls” These are the Popup controls that appear when you click on the icon of a Unit in any of the lists or displays.
+The small controls and advanced controls may be toggled between by the user by clicking the disclosure triangle/carrot just below the name of the Unit in the popup. The same interface is shown in the application as well as created in the web remotes. The selection of small or advanced is remembered for the Unit and the same will be presented first the next time you open this window.
+====The Edit Unit Controls====
+{{:pluginapi:edit_unit_controls.png?600 |}} The “editControls” key will be rendered on the first page of the Edit Unit dialog. The width of the control pane is fixed to 586px but the height can be anything reasonable. The Edit unit window will resize itself to accommodate the extra height and if there is not enough screen display room then a scrollbar will be presented to the user.
+The dynamic content is placed below the Unit Scripts groupbox and runs to the bottom of the tab panel section which ends above the Cancel/Apply/Save buttons.
+The spacing left right and top and bottom are taken care of by the program so when creating your interfaces in the Interface Builder app please use the entire window there. You can see in this example that I did not bring my group boxes all the way to the edge and so they do not line up properly with the rest of the windows content. I’ll be adding that to my list of stuff to get around to fixing momentarily...
+This is generally the place you would put settings that need to be saved in the data object for this Unit. They will be available to your plugin via the UnitSubclass.data object which is an instance of the xData class. You can read and write to this as it will always be in sync with the database in XTension. You can also set callbacks to any of the keys you use or that are used by XTension to know when the User has changed those settings while the plugin is running. That information is documented in the [[pluginapi:xdata|xData documentation]].
+If the plugin is running you can also create buttons here that will send a scripting command event to the plugin. If you have a handler registered for the action name you define in the Interface Builder then it will be run and sent all the settings from the screen as a keyed dictionary. This way you can take into account any changes the user has made to any of the settings on the page, but also still access the currently live saved data in the xData class for the Unit. So it would be possible to have turn on, turn off buttons on this page, though it would be a very questionable design choice.
+====The Small Controls Window====
+{{:pluginapi:small_controls_example.png?263 |}}An example of the small control window. By default this is what is in the window. Any controls you create with the “smallControls” tag will be added below the block/edit buttons but before the Done button. Note the disclosure triangle control just below the Unit Name on the right.
+The controls segment width is limited to 200px. There is no height limit. The window in the interface builder app is already set to this width, do not change the width, but make it any height you need to in order to display the controls you wish to here.
+In the appplication they are shown in a dark “hud” styled partially transparent window. Something similar is done in the Web Remote.
+====The Advanced Controls Window====
+{{:pluginapi:advanced_controls_example.png?337 |}} An example of the Advanced Controls window from the Haiku Flans plugin. It offers more default controls and information as well as any of the dynamic elements you have added to the Unit type.
+This window is slightly wider than the simple controls window. The dynamic controls portion has a fixed width of 272px. The controls will automatically be placed inside the grouping rectangle with the proper spacing on the sides. In the Interface Builder use the entire space to the edges of the window there as you do not have to honor the normal spacing, this will be done for you.
+In this example the “requiresInterface” key has been turned on (this is a checkbox/switch setting in the Interface Builder) and since the interface these units are assigned to is not running or enabled at the moment you cannot change these settings. For changing settings that shoudli be saved when the interface is not running it’s generally the right thing to do to put those on the Edit Unit dynamic interface portion of the Edit Unit dialog and not here.
+-----
+Next: [[pluginapi:interfacebuilder|]]