Preset del telecomando API

Se si crea un livello personalizzato, è possibile includere nel livello anche le preimpostazioni di controllo personalizzate. Questo è utile se il livello ha dei pulsanti che controllano il comportamento del livello quando è attivo.

Struttura dei dati

La seguente struttura di dati è un esempio di output che deve essere presente nella composizione sotto la chiave di output della struttura `tvOut_ControlRepresentations`:

{
  "tvOut_ControlRepresentations": [
    {
      "title": "Compact Cut's",
      "buttons": [
        {
          "actions": [
            {
              "layerId": "03627C25-CC8A-474F-A738-C4DEB3353FA4",
              "variantId": "F6F52194-06DE-462E-983A-8D505C533A69",
              "type": "signal",
              "signalKey": "tvGroup_Control__Cut_1_TypeSignal",
              "signalName": "Cut 1"
            }
          ],
          "liveState": {
            "layerId": "03627C25-CC8A-474F-A738-C4DEB3353FA4",
            "variantId": "F6F52194-06DE-462E-983A-8D505C533A69",
            "dynamicSourceId": "tvIn_VideoSourceAImage"
          },
          "sourcePreview": {
            "layerId": "03627C25-CC8A-474F-A738-C4DEB3353FA4",
            "variantId": "F6F52194-06DE-462E-983A-8D505C533A69",
            "dynamicSourceId": "tvIn_VideoSourceAImage"
          },
          "color": "#BBBBBB",
          "width": 1,
          "height": 1,
          "x": 0,
          "y": 0,
          "icon": "facetime-video",
          "dynamicText": {
            "template": "{{inputputValues.tvIn_VideoSourceAName}}",
            "layerId": "03627C25-CC8A-474F-A738-C4DEB3353FA4",
            "variantId": "F6F52194-06DE-462E-983A-8D505C533A69"
          }
        }
      ]
    }
  ]
}

Una preimpostazione ha un "titolo" e un array di "pulsanti", ma va bene anche un singolo pulsante.

Utilizzo della preimpostazione del telecomando API in Quartz Composer

I livelli incorporati di mimoLive utilizzano un LUA per generare dinamicamente questa struttura di dati, perché Quartz Composer non supporta la generazione di strutture di dati da solo. Il LUA contiene una funzione complessa addButton() che può essere utilizzata per creare la struttura di un singolo pulsante. Di solito è sufficiente utilizzare questa funzione e non è necessario modificarla. È quindi abbastanza facile creare nuove impostazioni predefinite del telecomando per il proprio livello.

Ad esempio, questo è il LUA per generare i controlli remoti per il livello Stop Watch. Si noti che è possibile adottare questo codice modificando semplicemente le righe da 15 a 29 del codice.

inLayerIdentifier = QC_STRING
inVariantIdentifier = QC_STRING
outControlRepresentations = QC_STRUCT
main = function()
  controlRepresentations = {}
  -- first representation
  controlRepresenation = {}
  -- {
    controlRepresenation["Title"] = "Stop Watch"
    buttons = {}
    -- {
      -- addButton(buttonsTable, buttonTitle, subTitle, positionX, positionY, width, height, color, icon, actionTarget, liveStateSource, previewSource)
      -- first row
      addButton(buttons, "{{outputValues.tvOut_TimeString}}", "", 0, 0, 2, 1, "#333333", "", "", "", "")
      addButton(buttons, "Live", "{\{name\}}", 2, 0, 1, 1, "#333333", "", "toggleLive", "layerVariant", "")
      -- second row
      addButton(buttons, "Start", "", 0, 1, 1, 1, "#33cc33", "play", "tvGroup_Control__Start_TypeSignal", "", "")
      addButton(buttons, "Stop", "", 1, 1, 1, 1, "#cc3333", "pause", "tvGroup_Control__Stop_TypeSignal", "", "")
      addButton(buttons, "Reset", "", 2, 1, 1, 1, "#cccc33", "stop", "tvGroup_Control__Reset_TypeSignal", "", "")
    -- }
    controlRepresenation["buttons"] = buttons
  -- }
  table.insert(controlRepresentations , controlRepresenation)
  outControlRepresentations = controlRepresentations
end
function addButton(buttonsTable, buttonTitle, buttonSubTitle, positionX, positionY, width, height, color, icon, actionTarget, liveStateSource, previewSource)
  local button = {}
  -- {
  if #buttonTitle > 0 then
    if string.find(buttonTitle, "{{") then
      -- dynamic titel
      local dynamicText = {}
      -- {
        dynamicText["layerId"] = inLayerIdentifier
        dynamicText["variantId"] = inVariantIdentifier
        dynamicText["template"] = buttonTitle
      -- }
      button["dynamicText"] = dynamicText
    else
      -- static title
      button["text"] = buttonTitle
    end -- if dynamic
  end -- if buttonTitle
  if #buttonSubTitle > 0 then
    if string.find(buttonSubTitle, "{{") then
      -- dynamic titel
      local dynamicSubText = {}
      -- {
        dynamicSubText["layerId"] = inLayerIdentifier
        dynamicSubText["variantId"] = inVariantIdentifier
        dynamicSubText["template"] = buttonSubTitle
      -- }
      button["dynamicSubText"] = dynamicSubText
    else
      -- static title
      button["subtext"] = buttonSubTitle
    end -- if dynamic
  end -- if buttonSubTitle
  button["x"] = positionX
  button["y"] = positionY
  button["width"] = width
  button["height"] = height
  if #color > 0 then
    button["color"] = color
  end -- if
  if #actionTarget > 0 then
    local actions = {}
    -- {
      local action = {}
      -- {
        action["layerId"] = inLayerIdentifier
        action["variantId"] = inVariantIdentifier
        if string.ends(actionTarget, "_TypeSignal") then
          action["type"] = "signal"
          action["signalKey"] = actionTarget
          action["signalName"] = buttonTitle
        elseif actionTarget == "toggleLive" then
          action["type"] = "toggleLive"
        else
          action["type"] = "toggleSwitch"
          action["toggleSwitchKey"] = actionTarget
          action["toggleSwitchName"] = buttonTitle
        end -- if
      -- }
      table.insert(actions , action)
    -- }
    button["actions"] = actions
  end -- if actionTarget
  if #liveStateSource > 0 then
    local liveState = {}
    -- {
      liveState["layerId"] = inLayerIdentifier
      liveState["variantId"] = inVariantIdentifier
      if string.starts(liveStateSource,"tvIn_VideoSource") then
        -- get the live state from a dynamic video source
        liveState["dynamicSourceId"] = liveStateSource
      elseif liveStateSource == "layerVariant" then
        -- nor more information needed
      else
        liveState["propertyPath"] = liveStateSource            end -- if
    -- }
    button["liveState"] = liveState
  end -- if liveState Source
  if #previewSource > 0 then
    local sourcePreview = {}
    -- {
      sourcePreview["layerId"] = inLayerIdentifier
      sourcePreview["variantId"] = inVariantIdentifier
      sourcePreview["dynamicSourceId"] = previewSource
    -- }
    button["sourcePreview"] = sourcePreview
  end -- if
  if #icon > 0 then
    -- See bottom of documentation page for list of avaiable icon names
    button["icon"] = icon
  end -- if
  -- }
  table.insert(buttonsTable, button)
end -- func
function string.starts(String,Start)
   return string.sub(String,1,string.len(Start))==Start
end
function string.ends(String,End)
   return End=='' or string.sub(String,-string.len(End))==End
end

Button Posizionamento

Quando si utilizzano più pulsanti, la disposizione dei pulsanti deve essere controllata manualmente. Ciò significa che i pulsanti vengono posizionati sulla griglia utilizzando gli attributi "x" e "y" che, proprio come gli attributi "larghezza" e "altezza", sono espressi in multipli di celle della griglia. Le posizioni sono relative alla cella della griglia in alto a sinistra su cui è stato trascinato il gruppo di pulsanti.

Button Azioni

Le Buttons possono avere più azioni, una singola azione o nessuna. Esistono diverse combinazioni valide di obiettivi e tipi di azione.
Si noti che le azioni "textInput" e "numericInput" dovrebbero essere indipendenti, poiché non è garantita un'esperienza utente coerente nel telecomando.

Obiettivi d'azione

Gli obiettivi di azione sono elementi all'interno del documento mimoLive. Sono indirizzati in modo gerarchico:

L'"ID documento" viene sempre disegnato in fase di esecuzione, quindi non deve essere presente nella preimpostazione.

• Se non vengono forniti né "layerId" né "variantId", l'azione verrà attivata sul documento stesso.
• Se viene dato "layerId", l'azione verrà attivata sul livello specificato.
• Se "layerId" e "variantId", l'azione sarà attivata sulla variante specificata. Solo in questo caso, è possibile specificare gli elementi aggiuntivi "toggleSwitchKey" o "signalKey" (vedere Tipi di azione di seguito).

Tipi di azione

Button Stato vivo

L'oggetto "liveState" può essere utilizzato per configurare lo stato della luce del conteggio del pulsante, che può essere acceso (marcatura rossa), in transizione (marcatura gialla) o spento (nessuna marcatura).

Fonti statali vive

Come per gli obiettivi delle azioni dei pulsanti, lo stato live può essere ottenuto da più fonti:

• L'"ID documento" viene sempre disegnato in fase di esecuzione, quindi non deve essere presente nella preimpostazione.
• Se non vengono forniti né "layerId" né "variantId", viene utilizzato lo stato live del documento (la mostra è iniziata o meno).
• Se viene fornito "layerId", viene utilizzato lo stato live del livello.
• Se vengono forniti "layerId" e "variantId", viene utilizzato lo stato live della variante.
  - Solo in questo caso, è possibile specificare l'ulteriore "propertyPath" per indicare che deve essere utilizzata una proprietà booleana sui valori di ingresso o di uscita della variante.
  - Un'altra possibilità (mutuamente esclusiva con propertyPath!) è quella di specificare una proprietà "dynamicSourceId" che reindirizza la ricerca dello stato live a una sorgente (recuperata per ID), che rispetta le modifiche dinamiche della sorgente selezionata (ad esempio, nel video switcher). Il valore di "dynamicSourceId" viene cercato nei valori di ingresso della variante.

*Indicare il percorso completo della proprietà, partendo dalla variante come radice, ad esempio "inputValues.some_Boolean_Property" o "outputValues.other_Property".

• Se viene fornito "sourceId", viene utilizzato lo stato live della sorgente.

Button Testo

I pulsanti di azione possono visualizzare linee di testo primarie e secondarie, entrambe di natura statica o dinamica.

Testo primario

Questo testo sarà l'indicatore principale di ciò che il pulsante farà per l'utente. Se la preimpostazione del pulsante contiene una proprietà text, si tratta di un testo statico che verrà visualizzato così com'è.

In alternativa, è possibile fornire un dynamicText che consente di includere le proprietà dei livelli o delle varianti di mimoLive utilizzando una semplice sintassi di template. Nella stringa del modello, i caratteri regolari possono essere combinati con i percorsi delle proprietà racchiusi tra parentesi graffe:

"template": "{\{propertyPath\}}"

I percorsi delle proprietà vengono valutati rispetto all'oggetto che viene risolto utilizzando "layerId", "variantId", "sourceId" e "filterId". La risoluzione dei target segue queste regole:

• L'"ID documento" viene sempre disegnato in fase di esecuzione, quindi non deve essere presente nella preimpostazione.
• Se non vengono forniti né "layerId" né "variantId", i percorsi delle proprietà vengono valutati relativamente al documento
• Se viene fornito "layerId" (e facoltativamente "variantId"), i percorsi delle proprietà vengono valutati rispetto a un layer/variante.
• È possibile accedere al livello padre di una variante iniziando un percorso con "layer", ad esempio "aslayer.name".

• Il testo statico avrà sempre la precedenza sul testo dinamico, perché questo consente agli utenti di sovrascrivere il testo dinamico con un testo personalizzato che potrebbe essere più utile nella loro situazione.

Testo secondario

Per fornire all'utente ulteriori informazioni su un pulsante, come il nome del livello padre, è possibile fornire un testo secondario utilizzando le proprietà "subtext" o "dynamicSubText".

La sintassi del template e la risoluzione degli oggetti seguono le stesse regole del testo primario.

Button Dimensione del testo e delle icone

Il testo e le icone dei pulsanti possono variare di dimensione a seconda del contesto. Con l'opzione "fontScale" è possibile specificare una scala relativa a una dimensione predefinita calcolata per la dimensione corrente dello schermo. "1" sarà la dimensione predefinita. Un valore inferiore a 1 (ad esempio 0,8) ridimensiona la dimensione del carattere, mentre un valore superiore a 1 (ad esempio 1,5) la aumenta.

Button Anteprima

I pulsanti di azione possono visualizzare un'immagine di anteprima della sorgente che controllano o di qualsiasi altra sorgente disponibile nel documento.

A seconda che la sorgente sia statica (solo le immagini trascinate in mimoLive), una sorgente statica PNG della sorgente che supporta un canale alfa. Per qualsiasi altra sorgente, viene caricata una rappresentazione JPEG La rappresentazione della sorgente viene aggiornata regolarmente. La frequenza di aggiornamento target per le sorgenti dinamiche è di 5 fotogrammi al secondo, ma questa frequenza viene ridotta quando la velocità della connessione di rete si rivela insufficiente per il caricamento ripetuto dei fotogrammi di anteprima.

Attualmente non è supportata la visualizzazione dell'output del programma del documento su un pulsante di azione. Le immagini predefinite del layer, anche se non visibili nell'elenco delle fonti, sono disponibili per l'anteprima.

Per specificare un'anteprima della sorgente, si utilizza un meccanismo di risoluzione degli oggetti:

• L'"ID documento" viene sempre disegnato in fase di esecuzione, quindi non deve essere presente nella preimpostazione.
• Se viene indicato "sourceId", per l'anteprima viene utilizzata la sorgente con quell'ID.
• Se tutti i valori di "layerId", "variantId" e "dynamicSourceId" sono indicati, l'ID della sorgente sarà cercato nella variante del livello specificato sotto la chiave in "dynamicSourceId". Questo può essere usato per fare riferimento a sorgenti come la sorgente A-G del video switcher, anche quando vengono modificate nel documento.

Button Colore

Utilizzando l'attributo "color", i pulsanti possono essere colorati con qualsiasi codice colore rappresentabile in HTML (ad esempio "#f80", "#ff0088", "arancione" o "rgb(255, 66, 88)").

Icona Button

Le Buttons possono visualizzare un'icona per indicare la loro funzionalità. Per visualizzare un elenco di tutte le icone disponibili, aprire http://localhost:8989/icons/demo.html mentre mimoLive è in esecuzione e i telecomandi sono abilitati.
Utilizzare il nome semplice dell'icona, ad esempio "indietro" o "freccia giù".