Fernsteuerungsvoreinstellungen API

Wenn Sie eine benutzerdefinierte Ebene erstellen, können Sie sogar benutzerdefinierte Steuervorgaben in Ihre Ebene aufnehmen. Dies ist praktisch, wenn Ihre Ebene über Drucktasten verfügt, die das Verhalten der Ebene steuern, wenn sie live ist.

Datenstruktur

Die folgende Datenstruktur ist eine Beispielausgabe, die in Ihrer Komposition unter dem Ausgabeschlüssel der Struktur "tvOut_ControlRepresentations" vorhanden sein muss:

{
  "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"
          }
        }
      ]
    }
  ]
}

Eine Voreinstellung hat einen "Titel" und eine Reihe von "Schaltflächen", aber eine einzelne Schaltfläche ist auch in Ordnung.

Verwenden der Fernbedienungsvoreinstellung API in Quartz Composer

Die eingebauten Schichten von mimoLive verwenden eine LUA Skript, um diese Datenstruktur dynamisch zu generieren, da der Quartz Composer die Generierung von Datenstrukturen nicht selbst unterstützt. Die LUA Skript enthält eine komplexe Funktion addButton(), die verwendet werden kann, um die Struktur für eine einzelne Schaltfläche zu erstellen. Normalerweise kann man diese Funktion einfach verwenden und muss sie nicht verändern. Daher ist es recht einfach, neue Fernbedienungs-Standardeinstellungen für Ihre eigene Ebene zu erstellen.

Dies ist zum Beispiel die LUA Skript, um die Fernbedienungen für die Stoppuhr-Ebene zu erzeugen. Bitte beachten Sie, dass Sie diesen Code übernehmen können, indem Sie einfach die Zeilen 15 bis 29 des Codes ändern.

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 Positionierung

Bei der Verwendung mehrerer Schaltflächen muss das Layout der Schaltflächen manuell gesteuert werden. Das bedeutet, dass die Schaltflächen mit den Attributen "x" und "y" auf dem Raster positioniert werden, die ebenso wie die Attribute "Breite" und "Höhe" in Vielfachen von Rasterzellen angegeben werden. Die Positionen sind relativ zu der linken oberen Gitterzelle, auf die die Schaltflächengruppe gezogen wurde.

Button-Aktionen

Buttons kann mehrere Aktionen, eine einzige Aktion oder gar keine Aktion haben. Es gibt verschiedene gültige Kombinationen von Aktionszielen und Aktionstypen.
Beachten Sie, dass die Aktionen "textInput" und "numericInput" für sich allein stehen sollten, da eine einheitliche Benutzererfahrung in der Fernbedienung nicht gewährleistet ist.

Aktionsziele

Aktionsziele sind Elemente innerhalb des mimoLive-Dokuments. Sie werden in einer hierarchischen Weise adressiert:

Die "Dokument-ID" wird immer zur Laufzeit gezeichnet, sie muss also nicht in der Voreinstellung vorhanden sein.

• Wenn weder "layerId" noch "variantId" angegeben werden, wird die Aktion für das Dokument selbst ausgelöst.
• Wenn "layerId" angegeben wird, wird die Aktion auf der angegebenen Ebene ausgelöst.
• Wenn "layerId" und "variantId" angegeben sind, wird die Aktion für die angegebene Variante ausgelöst. Nur in diesem Fall kann der zusätzliche "toggleSwitchKey" oder "signalKey" angegeben werden (siehe Aktionstypen unten).

Aktionsarten

Button Live State

Mit dem "liveState"-Objekt kann der Zustand der Kontrollleuchte der Schaltfläche konfiguriert werden, die eingeschaltet (rote Markierung), im Übergang (gelbe Markierung) oder ausgeschaltet (keine Markierung) sein kann.

Live-Status-Quellen

Ähnlich wie bei den Tastenaktionszielen kann der Live-Status aus mehreren Quellen bezogen werden:

• Die "Dokument-ID" wird immer zur Laufzeit gezeichnet, sie muss also nicht in der Voreinstellung vorhanden sein.
• Wenn weder "layerId" noch "variantId" angegeben werden, wird der Live-Zustand des Dokuments verwendet (Show hat begonnen oder nicht).
• Wenn "layerId" angegeben wird, wird der Live-Status der Ebene verwendet.
• Wenn "layerId" und "variantId" angegeben werden, wird der Live-Status der Variante verwendet.
  - Nur in diesem Fall kann der zusätzliche "propertyPath" angegeben werden, um anzuzeigen, dass eine boolesche Eigenschaft der Ein- oder Ausgabewerte der Variante verwendet werden muss.
  - Eine weitere Möglichkeit (die sich mit propertyPath gegenseitig ausschließt!) ist die Angabe einer "dynamicSourceId"-Eigenschaft, die die Suche nach dem Live-Status auf eine Quelle umleitet (die über die ID abgerufen wird), die dynamische Änderungen der ausgewählten Quelle (z. B. im Videoumschalter) berücksichtigt. Der Wert von "dynamicSourceId" wird in den Eingabewerten der Variante nachgeschlagen.

*Geben Sie den vollständigen Pfad zur Eigenschaft an, beginnend mit der Variante als Wurzel, z. B. "inputValues.some_Boolean_Property" oder "outputValues.other_Property".

• Wenn "sourceId" angegeben wird, wird der Live-Status der Quelle verwendet.

Button Text

Aktionsschaltflächen können primäre und sekundäre Textzeilen anzeigen, die beide statischer oder dynamischer Natur sein können.

Primärer Text

Dieser Text ist der Hauptindikator dafür, was die Schaltfläche für den Benutzer tun wird. Wenn die Schaltflächenvorgabe eine Texteigenschaft enthält, handelt es sich um einen statischen Text, der so angezeigt wird, wie er ist.

Alternativ kann ein dynamicText angegeben werden, der die Einbeziehung von mimoLive-Ebenen- oder -Varianteneigenschaften unter Verwendung einer einfachen Vorlagensyntax ermöglicht. In der Vorlagenzeichenfolge können reguläre Zeichen mit in geschweiften Klammern eingeschlossenen Eigenschaftspfaden kombiniert werden:

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

Eigenschaftspfade werden relativ zu dem Objekt ausgewertet, das mit "layerId", "variantId", "sourceId" und "filterId" aufgelöst wird. Die Zielauflösung folgt diesen Regeln:

• Die "Dokument-ID" wird immer zur Laufzeit gezeichnet, sie muss also nicht in der Voreinstellung vorhanden sein.
• Wenn weder "layerId" noch "variantId" angegeben werden, werden die Eigenschaftspfade relativ zum Dokument ausgewertet
• Wenn "layerId" (und optional "variantId") angegeben wird, werden die Eigenschaftspfade relativ zu einer Ebene/Variante ausgewertet.
• Auf die übergeordnete Ebene einer Variante kann man zugreifen, indem man einen Pfad mit "Ebene" beginnt, z. B. "aslayer.name".

• Der statische Text hat immer Vorrang vor dem dynamischen Text, denn so können die Benutzer den dynamischen Text mit einem benutzerdefinierten Text überschreiben, der in ihrer Situation nützlicher sein könnte.

Sekundärer Text

Um dem Benutzer weitere Informationen über eine Schaltfläche zu geben, wie z. B. den Namen der übergeordneten Ebene, kann ein sekundärer Text mit den Eigenschaften "subtext" oder "dynamicSubText" angegeben werden.

Die Syntax der Vorlagen und die Auflösung der Objekte folgen genau denselben Regeln wie der Primärtext.

Button Text und Icon Größe

Der Text und die Icons auf den Schaltflächen können je nach Kontext in der Größe variieren. Mit der Option "fontScale" können Sie eine relative Skalierung zu einer Standardgröße angeben, die für die aktuelle Bildschirmgröße berechnet wird. "1" ist die Standardgröße. Kleiner als 1 (z.B. 0.8) verkleinert die Schriftgröße und größer als 1 (z.B. 1.5) vergrößert sie.

Button Vorschau

Aktionsschaltflächen können ein Vorschaubild der Quelle anzeigen, die sie steuern, oder jede andere im Dokument verfügbare Quelle.

Je nachdem, ob es sich um eine statische Quelle handelt (nur Bilder, die in mimoLive gezogen wurden), kann eine statische PNG Repräsentation der Quelle geladen wird, die einen Alphakanal unterstützt. Für jede andere Quelle wird eine JPEG Die Darstellung der Quelle wird regelmäßig aktualisiert. Die angestrebte Aktualisierungsrate für dynamische Quellen beträgt 5 Bilder pro Sekunde. Diese Rate wird jedoch reduziert, wenn die Geschwindigkeit der Netzwerkverbindung für das wiederholte Laden der Vorschaubilder nicht ausreicht.

Es wird derzeit nicht unterstützt, die Programmausgabe des Dokuments auf einer Aktionsschaltfläche anzuzeigen. Die Standardbilder der Ebene sind zwar nicht in der Liste der Quellen sichtbar, aber für die Vorschau verfügbar.

Zur Angabe einer Quellenvorschau wird ein Objektauflösungsmechanismus verwendet:

• Die "Dokument-ID" wird immer zur Laufzeit gezeichnet, sie muss also nicht in der Voreinstellung vorhanden sein.
• Wenn "sourceId" angegeben wird, wird die Quelle mit dieser ID für die Vorschau verwendet.
• Wenn alle Werte von "layerId", "variantId" und "dynamicSourceId" angegeben werden, wird die ID der Quelle in der Variante der angegebenen Ebene unter dem Schlüssel in "dynamicSourceId" nachgeschlagen. Dies kann verwendet werden, um Quellen wie die Quelle A-G des Videoumschalters zu referenzieren, auch wenn sie im Dokument geändert werden.

Button Farbe

Durch die Verwendung des Attributs "color" können Schaltflächen mit jedem Farbcode eingefärbt werden, der sich in HTML (z.B. "#f80", "#ff0088", "orange", oder "rgb(255, 66, 88)").

Button-Symbol

Buttons können ein Icon anzeigen, um ihre Funktionalität anzuzeigen. Um eine Liste aller verfügbaren Icons zu sehen, öffnen Sie http://localhost:8989/icons/demo.html, während mimoLive läuft und die Fernbedienungen aktiviert sind.
Verwenden Sie den einfachen Namen des Symbols, z. B. "Rückwärts" oder "Pfeil nach unten".