Building GUIs With Fusion's UI Manager

User avatar
AndrewHazelden
Fusionator
Posts: 1260
Joined: Fri Apr 03, 2015 3:20 pm
Location: West Dover, Nova Scotia, Canada
Been thanked: 28 times
Contact:

Button with Icon

#46

Post by AndrewHazelden » Thu Sep 28, 2017 8:11 am

Overview

This script is a Fusion Lua based example that works in Fusion 9.0.1+ that shows how you can attach an image to a ui:Button with a ui:Icon resource.

The "Button with Icon Checked.lua" version of the script shows buttons that can be toggled on/off.

Download
Button-with-Icon.zip
Screenshot
button-with-icon.png
Installation

Step 1. Create a new "UI Manager" folder inside the Fusion user preferences "Scripts/Comp/" folder.

Step 2. Copy the "Button with Icon.lua" and "Button with Icon Checked.lua" scripts and the "fusion-logo.png" image into the "UI Manager" folder.

Step 3. In Fusion select the "Script > UI Manager > Button with Icon" menu item.

Notes

If you want to make a button that can be toggled and left visibly in a Pressed/Unpressed state, that is done with the addition of a "Checkable = true," entry when you create the ui:Button like this:
checked-button-state.png

Code: Select all

ui:Button{
  ID = 'IconButton1', 
  Flat = true,
  IconSize = {64,64},
  Icon = ui:Icon{File = 'Scripts:/Comp/UI Manager/fusion-logo.png'},
  Checkable = true,
},
You do not have the required permissions to view the files attached to this post.

Tags:

User avatar
theotheo
Fusionista
Posts: 300
Joined: Thu Aug 07, 2014 8:35 am
Been thanked: 9 times

Re: Building GUIs With Fusion's UI Manager

#47

Post by theotheo » Fri Sep 29, 2017 10:58 am

Lots of really really useful stuff in here Andrew, thanks a bunch!

User avatar
AndrewHazelden
Fusionator
Posts: 1260
Joined: Fri Apr 03, 2015 3:20 pm
Location: West Dover, Nova Scotia, Canada
Been thanked: 28 times
Contact:

Dynamic Hotkeys

#48

Post by AndrewHazelden » Sat Sep 30, 2017 3:29 am

Overview
This script is a Fusion Lua based UI Manager example that works in Fusion 9.0.1. The app:AddConfig() command will capture the "Control + W" / "Control + F4" hotkeys on Windows/Linux, or the "Command + W" / "Command + F4" hotkeys on Mac so they will close the "Dynamic Hotkeys" window instead of closing the foreground composite.

Download
Dynamic Hotkeys.lua
Screenshot
dynamic-hotkeys.png
Installation
Copy the "Dynamic Hotkeys.lua" script into your Fusion user preferences "Scripts/Comp/" folder.

Usage
In Fusion you can then run the script from inside Fusion's GUI by selecting the "Script > Dynamic Hotkeys" item.
You do not have the required permissions to view the files attached to this post.

User avatar
AndrewHazelden
Fusionator
Posts: 1260
Joined: Fri Apr 03, 2015 3:20 pm
Location: West Dover, Nova Scotia, Canada
Been thanked: 28 times
Contact:

OFX Blacklist Generator

#49

Post by AndrewHazelden » Sat Sep 30, 2017 7:48 am

Overview
This script is a Fusion Lua based UI Manager example that works in Fusion 9.0.1.

The tool scans the OFX Plugins directory and returns a list of all of the plugin libraries found. This list is used to quickly create a FusionOFX.blacklist file that lets Fusion know it should skip loading the OFX plugins at startup.

The OFX blacklist file is stored at: "Profile:/FusionOFX.blacklist".

WARNING: If you are manually creating an FusionOFX.blacklist file by hand you need to have an extra newline character added to the end of the document. This means if you are only adding a single OFX module to the blacklist document you will need to add an extra blank line to the end of the textfile! Failure to do this will cause the FusionOFX.blacklist file entry to be ignored.

Download
Version 1.1 - 2017-11-28
OFX Blacklist Generator.lua
Screenshot
OFX Blacklist Generator.png
Installation
Copy the "OFX Blacklist Generator.lua" script into your Fusion user preferences "Scripts:/Comp/" folder.

Usage
You can run the script from inside Fusion's GUI by selecting the "Script > OFX Blacklist Generator" item.

You need to manually delete the OFX plugins you want to load in Fusion from the "OFX Directory Contents:" section. Then click the "Save Blacklist" button.

OFX Plugin Folder Location

Windows:
C:\Program Files\Common Files\OFX\Plugins\

Mac:
/Library/OFX/Plugins/

Linux:
/usr/OFX/Plugins/
You do not have the required permissions to view the files attached to this post.

User avatar
AndrewHazelden
Fusionator
Posts: 1260
Joined: Fri Apr 03, 2015 3:20 pm
Location: West Dover, Nova Scotia, Canada
Been thanked: 28 times
Contact:

Action Listener

#50

Post by AndrewHazelden » Sat Sep 30, 2017 4:03 pm

Overview
Action Listener v1.3 - Last Updated 2017-11-21

The Action Listener script uses the Fusion ActionManager and ui:AddNotify() functions to log events as they happen inside the Fusion GUI. Only a small percentage of the compositing tasks you carry out in Fusion will show up in the "Recorded Action Log" view since the window is only able to track tools and commands that are applied using the new "action" system.

This script makes use of the fact Lua is a dynamic programming language by creating new functions for handling each ui:AddNotify event on the fly. This script is a Fusion Lua based UI Manager example that works in Fusion 9.0.1.

Download

Action Listener.lua
Action Listener Hotkey.fu

Screenshot

Action Listener_v1_1_updated.png

Installation

Copy the "Action Listener.lua" script into your Fusion user preferences "Scripts/Comp/" folder.
Copy the "Action Listener.fu" hotkey file into your Fusion user preferences "Config/" folder.

Usage

In Fusion you can then run the script from inside Fusion's GUI by selecting the "Script > Action Listener" item.

Start adding nodes and carrying out compositing tasks to see the Recorded Action Log update and scroll.

If you install the "Action Listener.fu" hotkey file you can use the (Command + R) or (Control + R) hotkey to open the "Action Listener" window.

GUI Controls

Button Controls

The "Print Actions List" button will output a list of all the actions that are present in Fusion to the Console tab.

The "Clear Event and Actions Logs" button will clear the text fields in the Action Listener GUI and give you a fresh recording.

Checkbox Controls

The "Translate Actions to Lua" checkbox tries to convert the action commands to the nearest Lua approximation.

The "Print Action Log to Console" checkbox will print a running log of the Action and event logs to the Console tabs. When the "ev.Args.tool", "ev.Args.prev", "ev.Rets.tool", and "ev.sender" table items are printed to the console they will have their pointer values probed using :GetAttrs() to print out the extra details.

The "Track Elapsed Time" checkbox adds a pause that will match the speed of the original recorded actions.

Supported Action to Lua Translations

The process of translating each action event to its matching Lua script output is a manual process and will take a while to fully implement.

Here is a list of the Lua translated actions:

AddTool()
App_About()
AddSetting()
Comp_Abort()
Comp_Activate_Tool()
Comp_Redo()
Comp_Start_Render()
Comp_Render_Frame()
Comp_Save()
Comp_SaveAs()
Comp_SaveCopyAs()
Comp_SaveVersion()
Comp_Undo()
Execute()
Playback_Mode()
RunScript()
Time_Set()
Time_Step_Back()
Time_Step_Forward()
Time_Goto_GlobalStart()
Time_Goto_GlobalEnd()
Time_Goto_RenderStart()
Time_Goto_RenderEnd()
Viewer_3D_CentreSelected()
Viewer_3D_FitAll()
Viewer_3D_FitSelected()
Viewer_Lock()

You do not have the required permissions to view the files attached to this post.
Last edited by AndrewHazelden on Sat Apr 27, 2019 2:42 am, edited 3 times in total.

User avatar
AndrewHazelden
Fusionator
Posts: 1260
Joined: Fri Apr 03, 2015 3:20 pm
Location: West Dover, Nova Scotia, Canada
Been thanked: 28 times
Contact:

Running UI Manager GUIs from a Terminal FuScript Session

#51

Post by AndrewHazelden » Tue Oct 03, 2017 8:47 am

Fusion Studio comes with the FuScript program that allows you to run Fusion based Lua and python scripts from a terminal session. FuScript is a Fusion Studio (paid) feature that is not available in the base Fusion (Free) version. With FuScript you are able to use the terminal/command prompt to run scripts in a headless batch processing mode, or you can connect to an already running Fusion graphical session which allows a pipeline TD to automate and control Fusion based tasks externally. :buttrock:

For the official documentation on FuScript check out page 24/25 of the "Fusion 8 Script Manual.pdf" guide.

A neat trick with FuScript is that you can start and run a Lua script that uses a UI Manager GUI from a Terminal session, too. If FuScript was the process that created a Fusion UI Manager based window it will wait until the view is closed and the Lua script finishes running. Then the FuScript process will close and return a status code to the shell. This allows FuScript to be nested inside of a larger automation tool so the remaining tasks a Windows Command Prompt .bat script or Mac/Linux .sh shell script can run.

This concept of using FuScript + Fusion from the command prompt can allow a pipeline TD to develop some really creative and useful tools that are able to take advantage of Fusion's VFX tools in ways you might not have considered previously. This means you could use on Fusion Studio inside of a shell tool as a bigger and more full featured node based version of Imagemagick or FFMPEG. :popcorn:

FuScript is installed with Fusion Studio on Windows/Mac/Linux at the following location:

Windows Path:

Code: Select all

C:\Program Files\Blackmagic Design\Fusion 9\FuScript.exe
Linux Path:

Code: Select all

/opt/BlackmagicDesign/Fusion9/fuscript
Mac Path: (You need to browse inside the Fusion.app package contents to access this folder.)

Code: Select all

/Applications/Blackmagic Fusion 9/Fusion.app/Contents/MacOS/fuscript
fuscript-in-fusion-program-folder.png
Adding FuScript to the System PATH

The following terminal examples in this FuScript tutorial assume you have added the path to the FuScript program to your system %PATH% / $PATH environment variable.

On Windows you can add a new System %PATH% variable entry using the Control Panels > System > Environment Variables... window. You will need to add the "C:\Program Files\Blackmagic Design\Fusion 9\" folder to the end of the entries for the PATH variable.

On Mac you can add FuScript's parent folder to the System $PATH variable by adding this snippet to your $HOME/.bash_profile document:

Code: Select all

# Add fusion and fuscript to the system $PATH
export PATH="$PATH:/Applications/Blackmagic Fusion 9/Fusion.app/Contents/MacOS/"
On Linux you can add FuScript's parent folder to the System $PATH variable by adding this snippet to your $HOME/.bash_profile document:

Code: Select all

# Add fusion and fuscript to the system $PATH
export PATH="$PATH:/opt/BlackmagicDesign/Fusion9/"
After you have added the "Fusion9" folder to your environment PATH variable you will typically have to restart your system or login/logout to make those changes active in your current shell session.

If you haven't added the Fusion9 folder to your PATH variable then you will need to replace the short program name "fuscript" with the full absolute filepath to the fuscript executable when running the terminal commands in this tutorial. :)

Running FuScript for the First Time

To find out what options are provided by fuscript, you can run the fuscript program without supplying any additional arguments. This will print out details on how you can use the tool:

Code: Select all

fuscript
Usage: fuscript [opts] <script> [args]
   -i                   - Enter interactive mode
   -v                   - Print version information
   -s                   - Run as script server
   -S                   - Run as script server with no timeout
   -p [appname]         - Ping script apps
   -P [appname]         - Ping script apps (longer timeout)
   -q                   - Be quiet
   -b                   - Run with commandline debugger
   -l <lang>            - Explicitly set language, from:
      lua
      py2 or python2
      py3 or python3
   -x <string>          - Execute string
If you want to run FuScript in an interactive lua shell session you would add the "-i" argument when FuScript is launched. Pressing Control + C twice will exit you from the Lua interactive session.

Run in an interactive mode:

Code: Select all

fuscript -i
running-fuscript-interactive-prompt.png
Fuscript can run a single line string of lua code like this:

Code: Select all

fuscript -x "print([[Hello Fusion World!]])"
This results in the FuScript terminal displaying the following output:

Code: Select all

Fusion Script Interpreter
Copyright (C) 2005 - 2017 Blackmagic Design Pty. Ltd.

Hello Fusion World!
fuscript-running-a-lua-string.png
Using FuScript with a Fusion Graphical Session

If you want FuScript to connect to an active Fusion graphical session and control it remotely you could use the "-x" argument along with a quoted chunk of Lua code that calls the Fusion() function. In this example a Blur node will be added to the current foreground comp. If you want to run multiple Lua commands at the same time from a string the easiest thing to do is to add semicolons to separate each command since the terminal/command prompt doesn't like to deal with line breaks.

Run a block of Lua code:

Code: Select all

fuscript -x "fusion = Fusion();fu = fusion;app = fu;composition = fu.CurrentComp;comp = composition;SetActiveComp(comp);blur = Blur();"
If FuScript is able to successfully connect to the Fusion GUI session and run the Lua string you will see a blur node added to your composite.
blur-node-added-to-fusion-composite.png
For FuScript to work correctly in this role your firewall rules have to be set to allow Fusion and FuScript to do inter-application communication. If FuScript has difficulty connecting to an existing Fusion graphical session you will get back an error message like this:

Code: Select all

"[string "???"]:1: attempt to index global 'fu' (a nil value)"
Starting the Fusion GUI session up first and then running the FuScript code will typically make that error message go away. If that doesn't fix the issue when you go to add a node to a comp from FuScript then you will have to explore your firewall settings. ;)

When you are using FuScript to carry out tasks, you will likely want to stop Loader/Saver node dialogs from opening up while a Lua script is running. You can do that by adding "comp:Lock()" to the FuScript launching command. After you have finished running your script commands, you can then add a final "comp:Unlock()" action to restore the dialog opening actions in the Fusion graphical session.

Running a Lua UI Manager Based Script

FuScript is able to run a Lua script off disk by adding the name of the script at the end of the launching arguments. The neatest thing about FuScript is you can also show UI Manager based GUIs when running FuScript with the help of the following terminal command example. In this example <script.lua> would be the absolute filepath to your lua script. Make sure to wrap the filepath in quotes if there are spaces in the folder/filenames in the path.

Run a Lua script off disk with UI Manager support enabled:

Code: Select all

"fuscript" -x "fusion = Fusion();fu = fusion;app = fu;composition = fu.CurrentComp;comp = composition;SetActiveComp(comp);" <script.lua>
Let's try this process out. For the next example we are going to download the "myfirstwindow.lua" script that is included below and save it to the Fusion user prefs "Scripts:/Comp/" folder. The "myfirstwindow.lua" script was one of the first examples in the UI Manager tutorial series and it creates a simple UI Manager based window.
Code: [Select all] [Expand/Collapse] [Download] (myfirstwindow.lua)
  1. -- Create a new window
  2. local ui = fu.UIManager
  3. local disp = bmd.UIDispatcher(ui)
  4. local width,height = 400,200
  5.  
  6. win = disp:AddWindow({
  7.   ID = 'MyWin',
  8.   WindowTitle = 'My First Window',
  9.   Geometry = {100, 100, width, height},
  10.   Spacing = 10,
  11.  
  12.   ui:VGroup{
  13.     ID = 'root',
  14.    
  15.     -- Add your GUI elements here:
  16.     ui:Label{
  17.       ID = 'TextLabel',
  18.       Text = 'This is a Label',
  19.     },
  20.   },
  21. })
  22.  
  23. -- The window was closed
  24. function win.On.MyWin.Close(ev)
  25.   disp:ExitLoop()
  26. end
  27.  
  28. -- Add your GUI element based event functions here:
  29. itm = win:GetItems()
  30.  
  31. win:Show()
  32. disp:RunLoop()
  33. win:Hide()
  34.  
To move the "myfirstwindow.lua" script to the correct location on disk can quickly open the Fusion user prefs "Scripts:/comp" folder up using the following command in the Terminal/Command Prompt window:

Windows Explorer Folder Open Command:

Code: Select all

explorer "%appdata%\Blackmagic Design\Fusion\Scripts\Comp\"
Mac Finder Folder Open Command:

Code: Select all

open "$HOME/Library/Application Support/Blackmagic Design/Fusion/Scripts/Comp/"
Linux Nautilus Folder Open Command:

Code: Select all

nautilus "$HOME/.fusion/BlackmagicDesign/Fusion/Scripts/Comp/" &
You could also open the Fusion user prefs "Scripts:/comp" folder up using the following Fusion Console tab Lua command:

Code: Select all

bmd.openfileexternal("Open", comp:MapPath("Scripts:/Comp/"))
With the script saved in the correct folder, we can now run the fuscript program and have it launch the "myfirstwindow.lua" script. When you close the "My First Window" dialog in Fusion the Fuscript process will exit gracefully and the terminal session will go back to the shell.
running-fuscript-and-myfirstwindow-on-centos-linux.png
Windows Script Command:

Code: Select all

REM Run a Lua script off disk
fuscript -x "fusion = Fusion();fu = fusion;app = fu;composition = fu.CurrentComp;comp = composition;SetActiveComp(comp);" "%appdata%\Blackmagic Design\Fusion\Scripts\Comp\myfirstwindow.lua"
Linux Script Command:

Code: Select all

# Run a Lua script off disk
fuscript -x "fusion = Fusion();fu = fusion;app = fu;composition = fu.CurrentComp;comp = composition;SetActiveComp(comp);" "$HOME/.fusion/BlackmagicDesign/Fusion/Scripts/Comp/myfirstwindow.lua"
Mac Script Command:

Code: Select all

# Run a Lua script off disk
fuscript -x "fusion = Fusion();fu = fusion;app = fu;composition = fu.CurrentComp;comp = composition;SetActiveComp(comp);" "$HOME/Library/Application Support/Blackmagic Design/Fusion/Scripts/Comp/myfirstwindow.lua"
running-fuscript-myfirstwindow-dialog.png

Running FuScript Code on Remote Systems

FuScript also has an RPC like remote connection option that lets you connect from your FuScript program's local terminal session to a copy of Fusion running on another server/workstation. This can let an artist workstation tie into a high powered server to finish rendering a shot or it allows you to have maintenance functions run as part of a regular pipeline automation task.

To use this remote connection approach in FuScript you simply need to change the Fusion connection function from "fusion = Fusion()" to the scriptapp version of "fusion = bmd.scriptapp('Fusion', 'localhost')". You would also need to write in the actual remote system hostname you want to use in place of "localhost" so you can make the initial Fusion GUI socket connection.

In this example I will perform a remote FuScript connection to a system with a hostname of "Pine":

Code: Select all

fuscript -x "fusion = bmd.scriptapp('Fusion', 'Pine');fu = fusion;app = fu;composition = fu.CurrentComp;comp = composition;SetActiveComp(comp);dump(fu:GetAttrs())" 
FuScript then responds with the host name details since I added "dump(fu:GetAttrs())" to the end of the Lua code string and that command will list information about the fu process.
FuScript wrote: Fusion Script Interpreter
Copyright (C) 2005 - 2017 Blackmagic Design Pty. Ltd.

table: 0x0c5c7988
FUSIONS_CLVendor = AMD
FUSIONS_FileName = /Applications/Blackmagic Fusion 9/Fusion.app/Contents/MacOS/Fusion
FUSIONH_CurrentComp = Composition (0x0x7fa6e3e70a00) [App: 'Fusion' on 127.0.0.1, UUID: ae048308-4eac-4546-be76-da29dfbe2c46]
FUSIONI_PhysicalRAMTotalMB = 16384
FUSIONS_CLVersion = OpenCL 1.2 1.2 (Jun 15 2017 18:41:53)
FUSIONI_VersionLo = 65543
FUSIONS_MachineType = IA32
FUSIONI_PhysicalRAMFreeMB = 9729
FUSIONI_VersionHi = 589824
FUSIONB_IsManager = false
FUSIONS_Version = 9.0.1
FUSIONS_CLType = GPU
FUSIONS_CLDevice = AMD Radeon R9 M370X Compute Engine
FUSIONI_SerialHi = 000000000 (Blanked out by Andrew for security reasons)
FUSIONI_VirtualRAMTotalMB = 16384
FUSIONS_GLVendor = ATI Technologies Inc.
FUSIONS_GLVersion = 2.1 ATI-1.51.8
FUSIONI_VirtualRAMUsedMB = 6654
FUSIONB_IsRenderNode = false
FUSIONS_GLDevice = AMD Radeon R9 M370X OpenGL Engine
FUSIONI_NumProcessors = 8
FUSIONI_SerialLo = 0
By the end of this tutorial you should be able to run your own Lua scripts from a FuScript terminal session and will be able to take control of a graphical Fusion session. :cheer:
You do not have the required permissions to view the files attached to this post.
Last edited by AndrewHazelden on Wed Oct 04, 2017 6:47 am, edited 9 times in total.

User avatar
Dunn
Moderator
Posts: 474
Joined: Mon Aug 04, 2014 4:27 am
Location: Hamburg, Germany
Been thanked: 2 times
Contact:

Re: Building GUIs With Fusion's UI Manager

#52

Post by Dunn » Tue Oct 03, 2017 9:05 am

Oh man! have you ever thought about bring out a book, "Learn: Fusion UI Manager in 24 hours" :D
. sure the title is open for debate :) ... this is totally amazing ! We are so glad to have you onboard man!

User avatar
AndrewHazelden
Fusionator
Posts: 1260
Joined: Fri Apr 03, 2015 3:20 pm
Location: West Dover, Nova Scotia, Canada
Been thanked: 28 times
Contact:

Apple Scripting Fusion Studio???

#53

Post by AndrewHazelden » Tue Oct 03, 2017 9:27 am

Dunn wrote:We are so glad to have you onboard man!
Hi Dunn.

I'm just happy to have people following along with the series. It has been a fun adventure exploring what is possible with Fusion 9 and the UI Manager system.

After checking out FuScript today I think it *might* be possible for a 3rd party developer to use this approach to create a Fusion Studio on MacOS Apple Events bridge. In theory that would let Apple Scripts / Apple Events / Automator Actions be used to control the current Fusion graphical compositing session. I'm quite excited by this possibility. :D

User avatar
AndrewHazelden
Fusionator
Posts: 1260
Joined: Fri Apr 03, 2015 3:20 pm
Location: West Dover, Nova Scotia, Canada
Been thanked: 28 times
Contact:

FuScript Post Updated with Remote Connection Details

#54

Post by AndrewHazelden » Wed Oct 04, 2017 3:51 am

I wanted to highlight the fact I updated the "Running UI Manager GUIs from a Terminal FuScript Session" post with an additional topic at the end labelled "Running FuScript Code on Remote Systems".

FuScript has an RPC like remote connection option that lets you connect from your FuScript program's local terminal session to a copy of Fusion running on another server/workstation. This can let an artist workstation tie into a high powered server to finish rendering a shot or it allows you to have maintenance functions run as part of a regular pipeline automation task.

User avatar
SirEdric
Fusionator
Posts: 1738
Joined: Tue Aug 05, 2014 10:04 am
Answers: 1
Real name: Eric Westphal
Been thanked: 77 times
Contact:

Re: Building GUIs With Fusion's UI Manager

#55

Post by SirEdric » Wed Oct 04, 2017 9:13 pm

Fantastic stuff, Andrew!
Thanks a bunch for sharing.

User avatar
AndrewHazelden
Fusionator
Posts: 1260
Joined: Fri Apr 03, 2015 3:20 pm
Location: West Dover, Nova Scotia, Canada
Been thanked: 28 times
Contact:

Creating a UI Manager GUI Inside of a Node's UserControls Interface

#56

Post by AndrewHazelden » Fri Oct 06, 2017 2:48 am

This example shows how a compact Lua UI Manager based GUI window can be packed inside of a Fusion node's UserControls interface element.

Fusion 9.0.1 is required to use this example since I used the new fu:GetMousePos() command to read the current mouse position which allows the window to be created intelligently next to your mouse pointer, and a ui:Font tag was used to add a custom font and font size adjustment on the GUI element displayed in the UI Manager window. If you didn't need these niceties it would be possible to do everything else shown in this example using Fusion 8.2.1.

The UI Manager based view that is shown has a single GUI element of a ui:Button with the placeholder text "That is all. Thank You". This button can be clicked to close the tiny popup window. This UI Manager code is self contained in the node and lives 100% in the Fusion ".comp" file so it travels with the rest of your composite data as it makes it way through your pipeline with no external file dependencies or paths to break.
loader-button-control-based-ui-manager-window.png
A practical use for this type of UI Manager view that is nested inside of a node is that you can use it to adjust preferences or settings that are saved via Lua's fusion:SetData()/comp:SetData() and fusion:GetData()/comp:GetData() functions. I haven't tested it but I think you can also try saving your custom settings using self:SetData()/self:GetData() too in the node. These new preferences configured in a UI Manager based ButtonControl are then accessible by an Intool script, a utility tool/comp script, simple hotkey bindings/actions added to a Config:/hotkeys.fu file, or other scripted UserControls on the node. It's hard to express just how useful this could be if you wanted to really customize how each of your Fusion nodes are configured for performing specialized tasks quickly and efficiently. :)

When you select the Loader node in your comp that is added by the "LoaderButtonControl.setting" example you will see a "Show UI Manager Dialog" button in the Tools UI at the bottom of the File tab section.

This button was embedded in the Loader node using a UserControls code block with a handcrafted "ButtonControl" element. The ButtonControl GUI element has a chunk of Lua code added inline that is run when the button is pressed.

For simplicity of delivering this example via a WSL forum post I placed the Lua code into the file using a pair of double square brackets like [[ ]]. You could also use a single line lua code technique if you wanted to that would separate each newline with a semi-colon character.

You could also link to an external Lua script using a ButtonControl tag like 'BTNCS_Execute = "@scripts:/Tool/YourCustomScript.lua",' that would be run when the ButtonControl is clicked if you wanted to keep the code tidy and more managed. The only real downside to the external script approach is this adds a separate file dependency that has to be installed and managed on each of the artist's systems. Going for inline code vs an external Lua script file is a decision you would have to think about when you deploy your own UserControls based scripts based upon how often you need to update the script vs how far and wide you want to distribute the custom node without having to deal with any additional installation related tech support burden. :wip:

The WSL Forum has an archived copy of the classic Fusion VFXPedia reference site. You can click here to read the VFXPedia entry on UserControls. This will give you a better background on the ButtonControl syntax. :bowdown:

The "Fusion 8 Script Manual.pdf" document that comes with Fusion 8/9 also discusses UserControls/ButtonControl and going to page 27 will show a screenshot of the Fusion "Add Controls" dialog window being used to add a new ButtonControl.

The example file that is attached to this post is a raw macro ".setting" style copy/paste clipping of a Fusion Loader node. You can either paste this node text right into the Fusion flow area to have the loader node with the ButtonControl added to your comp, or you could download the file to disk and save this example to your Fusion user preferences "Macros:/" folder.
Code: [Select all] [Expand/Collapse] [Download] (LoaderButtonControl.setting)
  1. {
  2.     Tools = ordered() {
  3.         LoaderButtonControl = Loader {
  4.             Clips = {
  5.             },
  6.             CustomData = {
  7.                 HelpPage = "https://www.steakunderwater.com/wesuckless/viewtopic.php?f=6&t=1411&p=11562#p11562",
  8.             },
  9.             CtrlWZoom = false,
  10.             NameSet = true,
  11.             Inputs = {
  12.                 ["Gamut.SLogVersion"] = Input { Value = FuID { "SLog2" }, },
  13.             },
  14.             ViewInfo = OperatorInfo { Pos = { 1489, 117 } },
  15.             UserControls = ordered() {
  16.                 UIManagerButton = {
  17.                     LINKS_Name = "Show UI Manager Dialog",
  18.                     LINKID_DataType = "Number",
  19.                     INPID_InputControl = "ButtonControl",
  20.                     BTNCS_Execute = [[
  21. local ui = fu.UIManager
  22. local disp = bmd.UIDispatcher(ui)
  23. local width,height = 300,200
  24. local x = fu:GetMousePos()[1]
  25. local y = fu:GetMousePos()[2]
  26.  
  27. win = disp:AddWindow({
  28.   ID = 'ButtonControlWin',
  29.   TargetID = 'ButtonControlWin',
  30.   WindowTitle = 'A ButtonControl Window',
  31.   Geometry = {x-(width/2), y+8, width, height},
  32.   Spacing = 10,
  33.  
  34.   ui:VGroup{
  35.     ID = 'root',
  36.  
  37.     ui:Button{
  38.       ID = 'DoneButton',
  39.       Text = 'That is all. Thank you.',
  40.       Font = ui:Font{
  41.         Family = 'Droid Sans Mono',
  42.         StyleName = 'Regular',
  43.         PixelSize = 18,
  44.         MonoSpaced = true,
  45.         StyleStrategy = {ForceIntegerMetrics = true},
  46.       },
  47.     },
  48.  
  49.   },
  50. })
  51.  
  52. function win.On.ButtonControlWin.Close(ev)
  53.   disp:ExitLoop()
  54. end
  55.  
  56. function win.On.DoneButton.Clicked(ev)
  57.   disp:ExitLoop()
  58. end
  59.  
  60. itm = win:GetItems()
  61. win:Show()
  62. disp:RunLoop()
  63. win:Hide()
  64. ]],
  65.                     INP_Integer = false,
  66.                     ICS_ControlPage = "File"
  67.                 },
  68.             }
  69.         }
  70.     },
  71.     ActiveTool = "LoaderButtonControl"
  72. }
Edit: Thanks Midgardsormr for the formatting suggestion. It is a lot easier to have the code displayed this way for an example script people are going to learn from and study. :)
You do not have the required permissions to view the files attached to this post.
Last edited by AndrewHazelden on Fri Oct 06, 2017 9:59 am, edited 4 times in total.

User avatar
Midgardsormr
Fusionator
Posts: 1001
Joined: Wed Nov 26, 2014 8:04 pm
Answers: 1
Location: Los Angeles, CA, USA
Been thanked: 47 times
Contact:

Re: Building GUIs With Fusion's UI Manager

#57

Post by Midgardsormr » Fri Oct 06, 2017 8:40 am

If you want a complex script inline on your button but don't want to deal with trying to convert it into a single-line string, you can use Lua's literal string delimiter: [[ ]].

Code: Select all

 
BTNCS_Execute = [[
  local ui = fu.UIManager
  local disp = bmd.UIDispatcher(ui)
  local width,height = 300,200
  local x = fu:GetMousePos()[1]
  local y = fu:GetMousePos()[2]
  
  win = disp:AddWindow({
      ID = 'ButtonControlWin',   
      TargetID = 'ButtonControlWin',   
      WindowTitle = 'A ButtonControl Window',  
      Geometry = {x-(width/2), y+8, width, height},   
      Spacing = 10,     
      ui:VGroup{     
          ID = 'root',     
          ui:Button{       
              ID = 'DoneButton',       
              Text = 'That is all. Thank you.',      
              Font = ui:Font{         
                  Family = 'Droid Sans Mono',         
                  StyleName = 'Regular',         
                  PixelSize = 18,        
                  MonoSpaced = true,         
                  StyleStrategy = {ForceIntegerMetrics = true},       
              }, -- font    
          }, -- button   
      }, --vGroup 
  }) --AddWindow
  
  function win.On.ButtonControlWin.Close(ev) 
    disp:ExitLoop()
  end
  
  function win.On.DoneButton.Clicked(ev) 
    disp:ExitLoop()
  end
  
  itm = win:GetItems()
  win:Show() 
  disp:RunLoop()
  win:Hide()
]], -- BTNCS_Execute

User avatar
AndrewHazelden
Fusionator
Posts: 1260
Joined: Fri Apr 03, 2015 3:20 pm
Location: West Dover, Nova Scotia, Canada
Been thanked: 28 times
Contact:

Re: Building GUIs With Fusion's UI Manager

#58

Post by AndrewHazelden » Fri Oct 06, 2017 9:14 am

Midgardsormr wrote:If you want a complex script inline on your button but don't want to deal with trying to convert it into a single-line string, you can use Lua's literal string delimiter: [[ ]].

Thanks for the code formatting suggestion Midgardsormr! I re-arranged the code block in the example so it would be clearer to read and decode.

User avatar
AndrewHazelden
Fusionator
Posts: 1260
Joined: Fri Apr 03, 2015 3:20 pm
Location: West Dover, Nova Scotia, Canada
Been thanked: 28 times
Contact:

Using Compiled Lua Modules With Fusion on macOS

#59

Post by AndrewHazelden » Thu Oct 12, 2017 7:54 am

This tip is aimed at the small group of Fusion 9.0.1 on macOS based technical artists who are on WSL. If you use the Brew package manager + LuaRocks to add compiled Lua modules to your Fusion system then the following details might be helpful:

If you want to run Lua modules from inside a Comp or Tool script you can add your custom Lua modules to Fusion 9.0.1's own personal application package based internal Lua Modules folder using the following (rough but effective) approach in the Terminal:

Code: Select all

# Create the required Fusion 9.0.1 folder for loading Lua binary and .lua script based modules:
sudo mkdir -p "/Applications/Blackmagic Fusion 9/Fusion.app/Contents/MacOS/Modules/Lua/"
sudo chmod -R 755 "/Applications/Blackmagic Fusion 9/Fusion.app/Contents/MacOS/Modules/"
open "/Applications/Blackmagic Fusion 9/Fusion.app/Contents/MacOS/Modules/"

# Copy the system wide Lua 5.1 precompiled .so library and raw .lua script based modules to the same folder:
cp -R /usr/local/share/lua/5.1/* "/Applications/Blackmagic Fusion 9/Fusion.app/Contents/MacOS/Modules/Lua/"
cp -R /usr/local/lib/lua/5.1/* "/Applications/Blackmagic Fusion 9/Fusion.app/Contents/MacOS/Modules/Lua/"
Note: Fuses that are trying to access Lua modules on Fusion 9.0.1 on macOS should still put their uncompiled .lua script files in the "/usr/local/share/lua/5.1/" folder, and the .so files in the "/usr/local/lib/lua/5.1/" folder.

Trying Out Your First Lua Module

You can try the Fusion RSS Headlines Script out if you want to see this workflow in action since it has a pre-compiled Lua Module dependency.
Last edited by AndrewHazelden on Thu Oct 12, 2017 7:56 am, edited 1 time in total.

User avatar
Chad
Fusionator
Posts: 1381
Joined: Fri Aug 08, 2014 1:11 pm
Been thanked: 8 times

Re: Building GUIs With Fusion's UI Manager

#60

Post by Chad » Thu Oct 12, 2017 7:55 am

Neat. Now we can add copy protection to scripts and fuses.