BlowTorch - DRAFT version 1
Plugin Anatomy

Table of Contents

Overview

Introduction

A plugin for BlowTorch is a collection of files in a directory on the sdcard (or internal memory). A plugin contains a unique set of triggers, timers, aliases, scripts and windows. Each plugin has an individual Lua state that is used to load and run scripts. The BlowTorch main settings file contains any internal plugins that are loaded as part of the main loading sequence, as well as a list of externally linked plugins; essentially a list of paths to xml files to load as part of the boot up sequence. The core will call certain global functions if defined in the plugin's Lua state at points during core operation.

General Construction

A plugin is loaded via an XML file that defines the configuration, behavior and content it carries. Multiple plugins may be grouped into a single file. The general structure of a plugin looks like the following: 

<blowtorch xmlversion="2">
   <plugins>
      <plugin name="Test Plugin" id="88743">
         <author>Author Name</author>
         <description>A short description.</description>
         <version>3</version>
         <triggers>
            <trigger name="foo" pattern="bar">
               <gag>
            </trigger>
         </triggers>
      </plugin>
   </plugins>
</blowtorch>

It essentially looks like a settings file without the root level global configuration nodes. Examining and editing data elements such as triggers, timers, or aliases, can be done in client by filtering the items from the extended options button in the appropriate selection dialog.

ex_filters.png

Plugin Scripts

Each plugin has a number of scripts that are associated with it. Each script is defined in the pluin settings file as a <script> node with attributes for a name and weather or not it should be executed when the plugin is loaded. 

<blowtorch xmlversion="2">
   <plugins>
      <plugin name="Stat Window" id="3343459">
         <script name="stat_window_ui" execute="false>
         <![CDATA[
         Note("Stat window UI code loading.")
         dofile("stat_window_ui.lua")
         ]]>
         </script>
         <script name="stat_window_server execute="true">
         <![CDATA[
         Note("Starts when plugin is loaded")
         dofile("stat_window_server.lua")
         ]]>
         </script>
      </plugin>
   </plugins>
</blowtorch>
Note
There is no <scripts> node in the plugin settings files. Script nodes are children of the plugin node.
The search path for require("...") has the directory that the plugin's xml descriptor file exits in automatically appended to it.

Loading Plugins

Load plugins using the MENU->Plugins->Load button. Use the Load menu to select valid XML plugin files from the [external memory folder]/BlowTorch/plugins folder. Once loaded, plugins may display description and author information. Invalid plugins will display the parse error to assist with debugging. Already loaded plugins should be indicated through the following icons:

plugin_load_states.png

Custom Options

Options/settings can be added in the plugin description file. These settings are available under the MENU->[Your plugin name]. Settings are saved when the BlowTorch core rewrites the plugin descriptor file in the save sequence. Settings are identified via the key property, which must be unique. When settings are changed from the the Options menu, it will call the global function OnOptionsChanged if defined in the plugin's Lua state. OnOptionsChanged is also called during the settings loading routine, once for every option that the plugin defines. This gives the opportunity for scripts to appropriately act on the setting value before windows are loaded or normal program operation starts.

<blowtorch xmlversion="2">
   <plugins>
      <plugin name="Plugin Options" id="556783">
         <options title="Custom Plugin Options" summary="Click to explore.">
             <boolean title="Boolean Option" key="bool_option" summary="Checkbox widget">true</boolean>
             <string title="String Option" key="string_option" summary="Click to edit.">Test string.</boolean>
             <integer title="Integer Option" key="int_option" summary="Click to edit, value shown in widget.">6</integer>
             <list title="List Option" key="list_option" summary="A list of values, click to edit.">
                     <value>0</value>
                     <item>Item 1</item>
                     <item>Item 2</item>
                     <item>Item 3</item>
             </list>
             <color title="Color Option" key="color_option" summary="Click to edit the value in the color picker.">#FFFF0000</color>
             <callback title="Callback Option" key="callback_option" summary="Click to call a function in the plugin.">callbackTest</callback>
         </options>
      </plugin>
   </plugins>
</blowtorch>
custom_options.png
Note
color picker values should aways be in the form of #<alpha><red><blue><green>, thus #FFFF0000 is 100% opaque red.

Custom Menu Items

Plugins can add custom menu items to the action bar or menu button list depending on the operating system version. Unfortunatly at this time only foreground windows can add menu items to the global menu or manuplate the menu stack. See the section on the PopulateMenu api call. Foreground windows also can create an entire new Action Bar or menu item list and temporarily replace the default menu items with the new menu. See the functions PushMenuStack and PopMenuStack.

Windowing System

The windowing system is going to have its own specific documentation but it is worth noting how the structure of the XML looks. As it appears in system overview diagram, each window contains its own configuration data. The configuration data looks like following: 

<blowtorch xmlversion="2">
   <plugins>
       <plugin name="layout_manager" id="494">
         <windows>
            <window name="vitals_window" id="1010" script="vitalsWindowScript">
               <layoutGroup target="large">
                  <layout orientation="landscape" below="6022" width="200" height="50">
                  <layout orientation="portrait" width="fill_parent" height="fill_parent">
               </layoutGroup>
               <layoutGroup target="xlarge">
                  <layout orientation="landscape" below="6022" width="400" height="100">
                  <layout orientation="portrait" width="fill_parent" height="fill_parent">
               </layoutGroup>
               <options>
                  <option key="font_size">13</option>
                  <option key="line_extra">2</option>
               </options>
            </window>
         </windows>
      </plugin>
   </plugins>
</blowtorch>

The window tag has the following attributes and child nodes:

Generated on Fri May 4 2018 10:17:57 for BlowTorch by   doxygen 1.8.3.1