FLTK Widgets and GUI controllers

Widgets allow the design of a custom Graphical User Interface (GUI) to control an orchestra in real-time. They are derived from the open-source library FLTK (Fast Light Tool Kit). This library is one of the fastest graphic libraries available, supports OpenGL and should be source compatible with different platforms (Windows, Linux, Unix and Mac OS). The subset of FLTK implemented in Csound provides the following types of objects:

Containers

FLTK Containers are widgets that contain other widgets such as panels, windows, etc. Csound provides the following container objects:

  • Panels
  • Scroll areas
  • Pack
  • Tabs
  • Groups

Valuators

The most useful objects are named FLTK Valuators. These objects allow the user to vary synthesis parameter values in real-time. Csound provides the following valuator objects:

  • Sliders
  • Knobs
  • Rollers
  • Text fields
  • Joysticks
  • Counters

Other widgets

There are other FTLK widgets that are not valuators nor containers:

  • Buttons
  • Button banks
  • Labels
  • Keyboard and Mouse sensing

Also there are some other opcodes useful to modify the widget appearance:

There are also these general opcodes that allow the following actions:

Below is a simple example of Csound code to create a window. Notice that all opcodes are init-rate and must be called only once per session. The best way to use them is to place them in the header section of an orchestra, before any instrument. Even though placing them inside an instrument is not prohibited, unpredictable results can occur if that instrument is called more than once.

Each container is made up of a couple of opcodes: the first indicating the start of the container block and the last indicating the end of that container block. Some container blocks can be nested but they must not be crossed. After defining all containers, a widget thread must be run by using the special FLrun opcode that takes no arguments.

<CsoundSynthesizer>
<CsOptions>
; Select audio/midi flags here according to platform
; Audio out   Audio in    No messages
-odac           -iadc     -d     ;;;RT audio I/O
; For Non-realtime ouput leave only the line below:
; -o linseg.wav -W ;;; for file output any platform
</CsOptions>
<CsInstruments>
;*******************************
sr=48000
kr=480
ksmps=100
nchnls=1

;*** It is recommended to put almost all GUI code in the
;*** header section of an orchestra

        FLpanel         "Panel1",450,550 ;***** start of container
; some widgets should contained here
        FLpanelEnd      ;***** end of container

        FLrun           ;***** runs the widget thread, it is always required!
instr 1
;put some synthesis code here
endin
;*******************************
</CsInstruments>
<CsScore>
f 0 3600 ;dummy table for realtime input
e

</CsScore>
</CsoundSynthesizer>

The previous code simply creates a panel (an empty window because no widgets are defined inside the container).

The following example creates two panels and inserts a slider inside each of them:

<CsoundSynthesizer>
<CsOptions>
; Select audio/midi flags here according to platform
; Audio out   Audio in    No messages
-odac           -iadc    ; -d     ;;;RT audio I/O
; For Non-realtime ouput leave only the line below:
; -o linseg.wav -W ;;; for file output any platform
</CsOptions>
<CsInstruments>
;*******************************
sr=48000
kr=480
ksmps=100
nchnls=1

        FLpanel         "Panel1",450,550,100,100 ;***** start of container
gk1,iha FLslider        "FLslider 1", 500, 1000, 0 ,1, -1, 300,15, 20,50
        FLpanelEnd      ;***** end of container

        FLpanel         "Panel2",450,550,100,100 ;***** start of container
gk2,ihb FLslider        "FLslider 2", 100, 200, 0 ,1, -1, 300,15, 20,50
        FLpanelEnd      ;***** end of container

        FLrun           ;***** runs the widget thread, it is always required!

instr 1
; gk1 and gk2 variables that contain the output of valuator
; widgets previously defined, can be used inside any instrument
printk2 gk1
printk2 gk2   ;print the values of the valuators whenever they change
endin
;*******************************
</CsInstruments>
<CsScore>
f 0 3600 ;dummy table for realtime input
e

</CsScore>
</CsoundSynthesizer>

All widget opcodes are init-rate opcodes, even if valuators output k-rate variables. This happens because an independent thread is run based on a callback mechanism. It consumes very few processing resources since there is no need of polling. (This differs from other MIDI based controller opcodes.) So you can use any number of windows and valuators without degrading the real-time performance.

FLTK Containers

The opcodes for FLTK containers are: