Class AbstractActionType

• C#
• Visual Basic

public abstract class AbstractActionType

Inheritance

System.Object

AbstractActionType

AbstractActionType2

Inherited Members

System.Object.ToString()

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: HomeSeer.PluginSdk.Events

Assembly: PluginSdk.dll

---

The base implementation of a plugin action type available for users to select in HomeSeer

Inherit from this class to define your own action types and store them in your plugin's ActionTypeCollection

Basic Usage

Define a class in your plugin that inherits from AbstractActionType and implements the required members

• AbstractActionType.GetName()
• AbstractActionType.OnNewAction()
• AbstractActionType.IsFullyConfigured()
• AbstractActionType.OnConfigItemUpdate(AbstractView)
• AbstractActionType.GetPrettyString()
• AbstractActionType.OnRunAction()
• AbstractActionType.ReferencesDeviceOrFeature()

public class MyCustomActionType : AbstractActionType {
    
	//All of these constructors must be implemented as is
	protected MyCustomActionType(int id, int subTypeNumber, int eventRef, byte[] dataIn, ActionTypeCollection.IActionTypeListener listener) : base(id, subTypeNumber, eventRef, dataIn, listener) { }
	protected MyCustomActionType() {}
	//No code should be contained within these constructors
	
	//Return the display name of this action type
	protected override string GetName() => "My Custom Action Type";
	
	protected override void OnNewAction() {
		//Initialize the config page for a new action of this type
	}
	
	public override bool IsFullyConfigured() {
		//Return whether the action is fully configured or not
	}
	
	protected override bool OnConfigItemUpdate(AbstractView configViewChange) {
		//React to changes to the action configuration
	}
	
	public override string GetPrettyString() {
		//Return a string describing the action to take
	}
	
	public override bool OnRunAction() {
		//Execute the action
	}
	
	public override bool ReferencesDeviceOrFeature(int devOrFeatRef) => false;
}

and add it to the ActionTypeCollection implementation in your plugin class

protected override void Initialize() {
    ...
    ActionTypes.AddActionType(typeof(MyCustomActionType));
    ...
 }

Lifecycle

It is important to not include any additional code in the constructors for custom action types because the lifecycle of actions is managed by the HomeSeer platform. Methods like AbstractActionType.OnNewAction(), AbstractActionType.IsFullyConfigured(), and AbstractActionType.OnConfigItemUpdate(AbstractView) are called by HomeSeer throughout the life of the action. Include the corresponding logic for your custom action type in the relevant methods.

The typical lifecycle of an action can be seen in the following diagram.

** Edits made to InputViews are not automatically captured like other ViewTypes and will only call OnConfigItemUpdate() when the user clicks the Save button.

Constructors

AbstractActionType()

Initialize a new, unconfigured AbstractActionType

This is called through reflection by the ActionTypeCollection class if a class that derives from this type is added to its list.

Declaration

• C#
• Visual Basic

protected AbstractActionType()

AbstractActionType(Int32, Int32, Byte[], ActionTypeCollection.IActionTypeListener)

Initialize a new AbstractActionType with the specified ID, Event Ref, and Data byte array. The byte array will be automatically parsed for a Page, and a new one will be created if the array is empty.

This is called through reflection by the ActionTypeCollection class if a class that derives from this type is added to its list.

You MUST implement one of these constructors in any class that derives from AbstractActionType

Declaration

• C#
• Visual Basic

protected AbstractActionType(int id, int eventRef, byte[] dataIn, ActionTypeCollection.IActionTypeListener listener)

Parameters

Type	Name	Description
System.Int32	id	The unique ID of this action in HomeSeer
System.Int32	eventRef	The event reference ID that this action is associated with in HomeSeer
System.Byte[]	dataIn	A byte array containing the definition for a Page
ActionTypeCollection.IActionTypeListener	listener	The listener that facilitates the communication with AbstractPlugin

AbstractActionType(Int32, Int32, Byte[], ActionTypeCollection.IActionTypeListener, Boolean)

Initialize a new AbstractActionType with the specified ID, Event Ref, and Data byte array. The byte array will be automatically parsed for a Page, and a new one will be created if the array is empty.

This is called through reflection by the ActionTypeCollection class if a class that derives from this type is added to its list.

You MUST implement this constructor in any class that derives from AbstractActionType

Declaration

• C#
• Visual Basic

protected AbstractActionType(int id, int eventRef, byte[] dataIn, ActionTypeCollection.IActionTypeListener listener, bool logDebug = false)

Parameters

Type	Name	Description
System.Int32	id	The unique ID of this action in HomeSeer
System.Int32	eventRef	The event reference ID that this action is associated with in HomeSeer
System.Byte[]	dataIn	A byte array containing the definition for a Page
ActionTypeCollection.IActionTypeListener	listener	The listener that facilitates the communication with AbstractPlugin
System.Boolean	logDebug	If true debug messages will be written to the console

AbstractActionType(Int32, Int32, Int32, Byte[], ActionTypeCollection.IActionTypeListener)

Initialize a new AbstractActionType with the specified ID, Event Ref, and Data byte array. The byte array will be automatically parsed for a Page, and a new one will be created if the array is empty.

This is called through reflection by the ActionTypeCollection class if a class that derives from this type is added to its list.

You MUST implement one of these constructors in any class that derives from AbstractActionType

Declaration

• C#
• Visual Basic

protected AbstractActionType(int id, int subTypeNumber, int eventRef, byte[] dataIn, ActionTypeCollection.IActionTypeListener listener)

Parameters

Type	Name	Description
System.Int32	id	The unique ID of this action in HomeSeer
System.Int32	subTypeNumber	The action subtype number
System.Int32	eventRef	The event reference ID that this action is associated with in HomeSeer
System.Byte[]	dataIn	A byte array containing the definition for a Page
ActionTypeCollection.IActionTypeListener	listener	The listener that facilitates the communication with AbstractPlugin

Fields

_configPage

Declaration

• C#
• Visual Basic

Page _configPage

Field Value

Type	Description
Page

_data

Declaration

• C#
• Visual Basic

byte[] _data

Field Value

Type	Description
System.Byte[]

_eventRef

Declaration

• C#
• Visual Basic

readonly int _eventRef

Field Value

Type	Description
System.Int32

_id

Declaration

• C#
• Visual Basic

readonly int _id

Field Value

Type	Description
System.Int32

_inData

Declaration

• C#
• Visual Basic

readonly byte[] _inData

Field Value

Type	Description
System.Byte[]

Properties

ActionListener

An interface reference to the plugin that owns this action type.

Define your own interface that inherits from ActionTypeCollection.IActionTypeListener and then cast this as the type you defined to get a reference to your plugin that can handle any methods you wish to define.

This is usually used to have the plugin handle running the action.

Declaration

• C#
• Visual Basic

public ActionTypeCollection.IActionTypeListener ActionListener { get; }

Property Value

Type	Description
ActionTypeCollection.IActionTypeListener

ConfigPage

The Page displayed to users to allow them to configure this action.

The Name of this page is not used or displayed anywhere and is not important.

Declaration

• C#
• Visual Basic

protected Page ConfigPage { get; set; }

Property Value

Type	Description
Page

Remarks

The ID of this page must be equal to the automatic PageId.

Data

The byte[] describing the current state of the ConfigPage for the action.

Declaration

• C#
• Visual Basic

public byte[] Data { get; }

Property Value

Type	Description
System.Byte[]

EventRef

The reference ID of the event the action is associated with.

Declaration

• C#
• Visual Basic

public int EventRef { get; }

Property Value

Type	Description
System.Int32

Id

The unique ID for the action.

Declaration

• C#
• Visual Basic

public int Id { get; }

Property Value

Type	Description
System.Int32

LogDebug

Used to enable/disable internal logging to the console

When it is TRUE, log messages from the PluginSdk code will be written to the Console

Declaration

• C#
• Visual Basic

public bool LogDebug { get; set; }

Property Value

Type	Description
System.Boolean

Name

The generic name of this action type that is displayed in the list of available actions a user can select from on the events page.

Declaration

• C#
• Visual Basic

public string Name { get; }

Property Value

Type	Description
System.String

PageId

Use this as a unique prefix for all of your JUI views and as the ID for the ConfigPage

Declaration

• C#
• Visual Basic

protected string PageId { get; }

Property Value

Type	Description
System.String

SelectedSubActionIndex

The currently selected sub-action index

Declaration

• C#
• Visual Basic

protected int SelectedSubActionIndex { get; }

Property Value

Type	Description
System.Int32

Remarks

-1 if it is not set

Methods

ConvertLegacyData(Byte[])

Called when legacy action data needs to be converted to the new format.

Override this if you need to support legacy actions. Convert the UI to the new format and save it in the ConfigPage. Finally, return Data to automatically serialize the ConfigPage to byte[]. Use DeserializeLegacyData<TOutObject>(Byte[], Boolean) to deserialize the data using the legacy method.

Declaration

• C#
• Visual Basic

protected virtual byte[] ConvertLegacyData(byte[] inData)

Parameters

Type	Name	Description
System.Byte[]	inData	A byte array describing the current action configuration in legacy format.

Returns

Type	Description
System.Byte[]	A byte array describing the current action configuration in new format.

Remarks

This is also called if there was an error while trying to deserialize the modern data format as a fallback

Equals(Object)

Declaration

• C#
• Visual Basic

public override bool Equals(object obj)

Parameters

Type	Name	Description
System.Object	obj

Returns

Type	Description
System.Boolean

Overrides

System.Object.Equals(System.Object)

GetData()

Declaration

• C#
• Visual Basic

virtual byte[] GetData()

Returns

Type	Description
System.Byte[]

GetHashCode()

Declaration

• C#
• Visual Basic

public override int GetHashCode()

Returns

Type	Description
System.Int32

Overrides

System.Object.GetHashCode()

GetName()

Called by HomeSeer to obtain the name of this action type.

Declaration

• C#
• Visual Basic

protected abstract string GetName()

Returns

Type	Description
System.String	A generic name for this action to be displayed in the list of available actions.

GetPrettyString()

Called by HomeSeer when the action is configured and needs to be displayed to the user as an easy to read sentence that flows with an IF... THEN... format.

Declaration

• C#
• Visual Basic

public abstract string GetPrettyString()

Returns

Type	Description
System.String	An easy to read, HTML formatted string describing the action as it would follow a THEN...

InflateActionFromData()

Declaration

• C#
• Visual Basic

void InflateActionFromData()

IsFullyConfigured()

Called to determine if this action is configured completely or if there is still more to configure.

Declaration

• C#
• Visual Basic

public abstract bool IsFullyConfigured()

Returns

Type	Description
System.Boolean	TRUE if the action is configured and can be formatted for display, FALSE if there are more options to configure before the action can be used.

OnConfigItemUpdate(AbstractView)

Called when a view on the ConfigPage has been updated by a user and needs to be processed.

Declaration

• C#
• Visual Basic

protected abstract bool OnConfigItemUpdate(AbstractView configViewChange)

Parameters

Type	Name	Description
AbstractView	configViewChange	The new state of the view that was changed

Returns

Type	Description
System.Boolean	TRUE to update the view in the ConfigPage and save the change, or FALSE to discard the change.

OnEditAction(Page)

Called when an action of this type is being edited and changes need to be propagated to the ConfigPage

Declaration

• C#
• Visual Basic

protected virtual void OnEditAction(Page viewChanges)

Parameters

Type	Name	Description
Page	viewChanges	A Page containing changes to the ConfigPage

OnNewAction()

Called when a new action of this type is being created. Initialize the ConfigPage to the action's starting state so users can begin configuring it.

Initialize a new ConfigPage and add views to it so the user can configure the trigger. Any JUI view added to the ConfigPage must use a unique ID as it will be displayed on an event page that could also be housing HTML from other plugins. It is recommended to use the PageId as a prefix for all views added to ensure that their IDs are unique.

Declaration

• C#
• Visual Basic

protected abstract void OnNewAction()

OnRunAction()

Called when this action needs to be executed.

Declaration

• C#
• Visual Basic

public abstract bool OnRunAction()

Returns

Type	Description
System.Boolean

ProcessData(Byte[])

Declaration

• C#
• Visual Basic

virtual byte[] ProcessData(byte[] inData)

Parameters

Type	Name	Description
System.Byte[]	inData

Returns

Type	Description
System.Byte[]

ProcessPostData(Dictionary<String, String>)

Declaration

• C#
• Visual Basic

bool ProcessPostData(Dictionary<string, string> changes)

Parameters

Type	Name	Description
System.Collections.Generic.Dictionary<System.String, System.String>	changes

Returns

Type	Description
System.Boolean

ReferencesDeviceOrFeature(Int32)

Called by HomeSeer to determine if this action references the device or feature with the specified ref.

Declaration

• C#
• Visual Basic

public abstract bool ReferencesDeviceOrFeature(int devOrFeatRef)

Parameters

Type	Name	Description
System.Int32	devOrFeatRef	The unique Ref to check for

Returns

Type	Description
System.Boolean	TRUE if the action references the specified device/feature, FALSE if it does not.

ToHtml()

Called by ActionTypeCollection when ActionBuildUI(TrigActInfo) is called to get the HTML to display to the user so they can configure the action.

This HTML is automatically generated by the ConfigPage defined in the action.

Declaration

• C#
• Visual Basic

public string ToHtml()

Returns

Type	Description
System.String	HTML to show on the HomeSeer events page for the user.