The Alternative Csound Reference Manual
Previous | Instrument Control | Next

# Introduction to FLTK Widgets and GUI controllers

Written by Gabriel Maldonado (http://csounds.com/maldonado)

Widgets allow the design of a custom Graphical User Interface to control an orchestra in real-time. They are derived from the open-source library FLTK (Fast Light Tool Kit). Such 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

- Valuators

- Other widgets

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

- Panels

- Scroll areas

- Pack

- Tabs

- Groups

The most useful objects are named 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

There are other widgets that are not valuators nor containers:

- Buttons

- Button banks

- Labels

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

- Updating widget value.

- Setting primary and selection colors of a widget.

- Setting font type, size and color of widgets.

- Resizing a widget.

- Hiding and showing a widget.

At last, there are three important opcodes that allow the following actions:

- Running the widget thread.

- Loading snapshots containing the status of all valuators of an orchestra.

- Saving snapshots containing the status of all valuators of an orchestra.

Here is an example preview of Csound code for a window containing a valuator. 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, externally to 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.

Here is an example of creating a window:

    ;*******************************
    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
    ;*******************************

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:

    ;*******************************
    sr=48000
    kr=480
    ksmps=100
    nchnls=1

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

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

            FLrun           ;***** runs the widget thread, it is always required!
    instr 1
    ;put some synthesis code here
    ; gk1 and gk2 variables that contain the output of valuator
    ; widgets previously defined, can be used inside any instrument
    endin
    ;*******************************

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.

Since FLTK toolkit is still in evolution process, opcode syntax provided in Csound could be modified in future version. This could cause some incompatibilities between orchestras of a determinate version. However it should not be hard to modify early orchestras in order to make them compatible with later versions.

For more information, see the following sections.

## FLTK Containers

The opcodes for FTLK containers are FLgroup, FLgroupEnd, FLpack, FLpackEnd, FLpanel, FLpanelEnd, FLscroll, FLscrollEnd, FLtabs, and FLtabsEnd.

## FLTK Valuators

The opcodes for FLTK valuators are FLcount, FLjoy, FLkeyb, FLknob, FLroller, FLslider, and FLtext.

## Other FLTK Widgets

Other FLTK widget opcodes are FLbox, FLbutBank, FLbutton, FLprintk, FLprintk2, and FLvalue,

### Modifying FLTK Widget Appearance

Opcodes one can use to modify FLTK widget appearance are FLcolor2, FLcolor, FLhide, FLlabel, FLsetAlign, FLsetBox, FLsetColor2, FLsetColor, FLsetFont, FLsetPosition, FLsetSize, FLsetText, FLsetTextColor, FLsetTextSize, FLsetTextType, FLsetVal, FLsetVal_i, and FLshow.

### General FLTK Widget-related Opcodes

The general FLTK widget-related opcodes are FLgetsnap, FLloadsnap, FLrun, FLsavesnap, FLsetsnap, and FLupdate.

### FLTK Slider Bank

The opcode for the FLTK slider bank is FLslidBnk.

Previous | Home | Next
Duration Control Statements | Up | Instrument Invocation