Custom Elements

Sample Projects

Exploring any one of the sample projects is a good way to understand how custom elements work.

Defining Your Custom Elements

Custom elements are defined in a class that descends from CustomElementsSuperclass. The recommended file name is VgcCustomElements.swift and the recommended class name is CustomElements.

Here is the custom elements file from the sample projects - explanations contained in in-line comments:

import Foundation
import VirtualGameController

///
/// Create a case for each one of your custom elements, along with a raw value in
/// the range shown below (to prevent collisions with the standard elements).

public enum CustomElementType: Int {
    
    case FiddlestickX   = 50
    case FiddlestickY   = 51
    case FiddlestickZ   = 52
    case Keyboard       = 53
    
}

///
/// Your customElements class must descend from CustomElementsSuperclass
///
public class CustomElements: CustomElementsSuperclass {

    override init() {
        
        super.init()
        
        ///
        /// CUSTOMIZE HERE
        ///
        /// Create a constructor for each of your custom elements.  
        ///
        /// - parameter name: Human-readable name, used in logging
        /// - parameter dataType: Supported types include .Float, .String and .Int
        /// - parameter type: Unique identifier, numbered beginning with 100 to keep them out of collision with standard elements
        ///
        
        customProfileElements = [
            CustomElement(name: "Fiddlestick X", dataType: .Float, type:CustomElementType.FiddlestickX.rawValue),
            CustomElement(name: "Fiddlestick Y", dataType: .Float, type:CustomElementType.FiddlestickY.rawValue),
            CustomElement(name: "Fiddlestick Z", dataType: .Float, type:CustomElementType.FiddlestickZ.rawValue),
            CustomElement(name: "Keyboard", dataType: .String, type:CustomElementType.Keyboard.rawValue)
        ]

    }

}

Initializing Your Custom Elements

Your custom element class must be passed into the startAs used to initialize VirtualGameController functionality in your app, and it must be done for each of the app roles (Peripheral, Central and Bridge) that you have in use:

 VgcManager.startAs(.Central, appIdentifier: "vgc", customElements: CustomElements(), customMappings: CustomMappings())

Note that when this method is used for start-up, you cannot pass nil to customMappings, and so you should include a customMappings class without any mappings, as described here.

Using Your Custom Elements in a Peripheral

The syntax for setting the value of a custom element is:

custom[CustomElementType.FiddlestickX.rawValue] = 1.0

Using Your Custom Elements in a Bridge or Central

If you are working with an element, you can obtain the value of a custom element this way:

controller.elements.custom[element.identifier]?.value

If you need to access it by name:

controller.elements.custom[.FiddlestickX]?.value

Setting a Value Changed Handler

You set a value changed handler on the custom profile the same way you do for the standard profiles:

Elements.customElements.valueChangedHandler = { (controller, element) in
    
    // Do something here
    
}

If You Don't Need Custom Elements

You can pass a customElements() with no elements defined to startAs.