» GUI modular o_0!
This site relies heavily on Javascript. You should enable it if you want the full experience. Learn more.

GUI modular o_0!


by majortom

The idea

GUI system can become very robust if you want to include all kinds of controls like: buttons, sliders, counters, knobs, etc. Specially if you want to control different types of data like: Values, Colors, Strings... I have tried that and very soon I have found myself in a serious mess. I had a lot of subpatches connecting to all other and number of feedback connections forming crazy loops that soon enough rendered my patch unreadable. There was only one way out: Ctrl-A and Delete.

To start clean I deviced several rules for working GUI:

  • One central module should be used to manipulate all control values regardless of control type.
  • Modules that will provide values to the central module and use output results should interconnect in chains. Output from one module will be used as input for the other i.e. they will connect like DMX or MIDI devices avoiding messy patching.
  • There must be input/output modules that can handle spreads and central module should be able to work with any number of such modules without serious user attention.
  • Modules that display controls in DX window will not care about actual data. They will change apperance according to input control values and will provide quad transformations in projection space for mouse over (hover) detection.
  • The system of input and output data streams should be simple enough so users can create their own modules.
  • GUI should be able to display on separate window as well as like pull-out or pop-up on any DX window.

Basic concept

I have patched some modules for preview of the system. I tried to follow the rules but some modules are not so strict yet. Since this is an open project, you are welcomed to contribute on vvvvorum.

To start, download this patch (open TRY_GUI_modular.v4p):

tiki-download_file.php?fileId=1201TRY_GUI_modular.zip (103.93 Kb)

Several things to note about this patch:

  • Gauge and HoverControl modules are handling all control values, so they are not designed to interconnect with other modules yet.
  • Although I tried to make controls to react on right click & drag - like we used to in vvvv, they are controled with left click instead. This is due to a bug described here.
  • textures are png. You can edit them in fireworks or any other editor.



(Some definitions to follow while patching all modules.)

The core of the system is GUI CS module with its inputs and outputs. The structure of the input and output spreads should be defined in a certain way all other modules could follow.

  • GUI CS module receives control values and controller data, and dynamicaly maps controllers to GUI controls.
  • GUI CS module outputs resulting values, data for modules that display controls on the screen and feedback data for input modules.

Internaly, GUI CS takes care of controls' properties and slice counts.

GUI CS Module

Data Inputs

Control values & data

Pin (Data) Count slice Type description
Input Data n*3 Value float control value
Count integer spread count
Update bool forcing update of control value

n is total number of controls. Each control would take 3 slices in Input Data spread: value of current slice, total spread count and update flag. Update flag would bang '1' each time control value should be updated - for example when slice index changes.

According to order in the spread, each control will have its unique index - refered to as Control CH (Control channel) later in this text.

Controller (CTRL) data

Pin (Data) Count slice Type description
CTRL In c Value float output of controller modules

c is total number of controller channels.

For example:

MouseCTRL module could map mouse_x, mouse_y, mousewheel, leftbutton and mouse_y offset to five different channels.

Controller channel will be refered to as CTRL CH later in this text.

CTRL/Control Map

Pin (Data) Count slice Type description
Map var*3 CTRL CH integer Controller channel index
Control CH integer Control channel index
Data enum (Value, Slice)
Focus n bool

The map describes which control is listening to which CTRL CH and also sets if either control value or slice index shoud be controlled.

The map changes dinamicaly and it has variable (var) number of entries.

For example:

If we want to do something like in the basic concept patch, HoverCTRL module would listen certain CTRL CHs for mouse position and append one mapping for mousewheel (Slice) and one for mouse_y offset (Value) when leftbutton is pressed, both binding CTRL CHs to the same Control CH of control in focus.

Controlling several controls at once can also be achieved through mapping (to change slice index for grouped controls like vectors or colors), but this should also be possible using other modules on the output side as well.


Focus spread is normaly recieved from Hover controllers and copied to Control Data spreads. GUI CS module doesn't care about focus.

CTRL/Control Map can also hold default mappings, if for example we want to set one CTRL CH to change slice indices for all controls. This would be done by setting the Control CH to -1. Separate Mapping module should be used for more complex GUI setups.

Note about addressing Control and CTRL Channels
All channel addresses start with 1 and not with 0. This is both because of internal structure of GUI CS module and because of ease of handling.
Because the default state of value type nodes is always zero, maps and internal spreads that are not affected or initialized will always show zeros. If we wouldn't ignore zero channels the first Control and CTRL channels would allways interact.

Data Outputs

Output Value

Output Value is just a spread of float values with n slices - one for each control.

Control Data

Pin (Data) Count slice Type description
Control Out n*3 Control Value float Output Value * Ratio
Focus bool is controller in focus?
Bound bool is value being controlled?
CH Data n*2 Count Integer
Slice Integer

Control Data streams are used as inputs for display and other output modules. Ratio is control property.

I/O Control Output

I/O Control Data

Pin (Data) Count slice Type description
I/O Control n*2 Output Value float
Slice integer

I/O Control Data spread is used to control input modules (like SpreadControl module)

GUI CS Control Properties

There are several properties that should be set for each control.

Pin (Data) Count slice Type description
Type n enum (Copy, Slide, Push-Pull, Toggle, Bang)
Bounds n*2 Min float
Max float
Behaviour n enum (Float, Wrap, Mirror, Clamp)
Ratio n float Ratio between Output Value and Control Value

For more complex GUI systems we could use separate module that would allow us to set default properties for groups of controls and tune or override some properties for certain controls.

Input Modules


SpreadControl module grants control over choosen slice in input spread to GUI CS module and outputs all changes to output spread.


Pin (Data) Count slice Type description
Input var float Input spread
Input Data n*3 Value float control value
Count integer spread count
Update bool forcing update of control value
I/O Control n*2 Output Value float (from GUI CS module)
Slice integer (from GUI CS module)
Reset 1 bool resets output to input values
Control CH 1 integer existing Control channel to use


Pin (Data) Count slice Type description
Input Data n*3 Value float control value
Count integer spread count
Update bool forcing update of control value
I/O Control n*2 Output Value float copy of input pin
Slice integer copy of input pin
Reset 1 bool copy of input pin
Slice 1 integer current slice
Output var float Output spread

Input Data pin connects to the next input module or to GUI CS module. Data of choosen Control CH are changed.


...under construction ...


Controller Modules

Controller modules send controller output values to CTRL stream.


Pin (Data) Count slice Type description
CTRL In var float CTRL spread
Ratio var float
CTRL CH var integer one or more channels to use

...and other controller specific input pins like MIDI channel, mouse_x, etc.


Pin (Data) Count slice Type description
CTRL Out var float CTRL spread

If user selects non existing CTRL channel, controller module should add new slices to CTRL spread.
CTRL channel 0 will be ignored by GUI CS module!

Use this template for new controller modules: tiki-download_file.php?fileId=1228TemplateCTRL.v4p (6.28 Kb)</a>


tiki-download_file.php?fileId=1229MouseGlobalCTRL.v4p (9.44 Kb)</a>

tiki-download_file.php?fileId=1230MouseWindowCTRL.v4p (8.94 Kb)</a>

...under construction ...





CTRL Data Modules




Mapping Modules

Default Mapping


Multitouch Mapping


Output Modules

DX9 Controls



Demo patches

...under construction ...

anonymous user login


~3d ago

joreg: Workshop on 07.12: An Introduction to FUSE Signup here: https://thenodeinstitute.org/courses/ws23-vvvv-03-fuse-introduction/

~10d ago

joreg: Workshop on 30.11: Strategies for Sound Reactive Graphics: How to control everything through sound Signup here: https://thenodeinstitute.org/courses/ws23-vvvv-02-how-to-control-everything-through-sound/

~20d ago

joreg: The vvvv winter semester course program is out, starting with a free course on November 23rd: https://thenodeinstitute.org/ws23-vvvv-intermediates

~20d ago

LCA: ravazque, this guy is working on this v3 since ever. check: https://nuitrack.com/

~1mth ago

~2mth ago

karistouf: done with vvvv beta :) https://vimeo.com/872242439

~2mth ago

joreg: Mapping festical call for projects: https://mappingfestival.com/en/call-for-projects

~3mth ago

joreg: Starting October 16: vvvv beginner class winter 23/24 Sign up here: https://thenodeinstitute.org/courses/ws23-vvvv-beginner-class/