Home Forums General Programming Lua Basics for Ctrlr – Beginners


This topic contains 48 replies, has 5 voices, and was last updated by  human fly 8 months, 1 week ago.

Viewing 20 posts - 1 through 20 (of 49 total)
  • Author
  • #71822

    human fly

    here’s a getting started with Lua topic- online videos and manuals help
    a bit but don’t deal directly with things you want to do in Ctrlr.

    i have managed to get a couple of methods working, by copying and modifying
    what i’ve seen in examples, and getting help from other forum users – that
    was encouraging, but i still don’t really understand much. i don’t expect
    to build really complex things at this stage, but it would be useful to go
    through principles and simple examples.

    as a test, i tried to make something simple: a button that
    turns on a LED. i know i can do that with ‘Link to Modulator’, and
    tested my image to check it’s working and that i’ve loaded it correctly.

    it seemed like it would be simple, but it isn’t working, so i want to
    go through step by step.


    human fly

    i’ll illustrate this better: here is a method that works, for
    showing/hiding a modulator with a button, using setVisible()
    setVisible3 = function(mod, value)
    button = panel:getModulatorByName(“LED button”):getValue()
    item = panel:getModulatorByName(“LED”)
    button == 0 then

    i don’t know how to send ‘give a value to…’…i’ve seen
    setValue, so i’ve tried that, different ways: trying to
    give the modulator a numerical value, or a bools state.
    i need a run-through on this, i did not understand the
    replies i got previously – this, for instance does NOT work:
    setValue1 = function (mod,value)
    button = panel:getModulatorByName(“LED button”)
    item = panel:getModulatorByName(“LED”)
    button:getValue() == 0 then
    button:getValue() == 1 then


    human fly

    btw: 2nd one: i know i’ve done ‘getModulatorByName()’ twice there;
    i’ve tried it just using those names ‘button’ and ‘item’ as well.
    same problem: i don’t know what i’m supposed to have there, or
    what each element is doing.

    all this is supposed to do is, when you toggle the button, the
    LED goes on/off. ie: sending a value, or state, instead of the
    show/hide function.



    I’m a beginner.
    I’m fluent in multiple languages.
    Now my question is, where do you write that code 🙂
    And i guess a modulator is anything you put on the panel, right?


    human fly

    you write methods in the Lua editor:
    get to this via Panel>Lua editor or call up methods
    on several parameters on the properties panel – create/edit
    new methods using ‘add’.

    everything seems to be called ‘modulator’ – even groups.

    so what is ‘Component’?
    ie: getComponent() vs getModulator()



    This is what I can tell so far:

    The objects you can add to the panel are called components.
    Right-click on the panel and you will get an ‘Add component’ dialog.
    A component’s properties are divided into multiple sections such as ‘Modulator’, ‘MIDI’, ‘Component generic’ and ‘Component’.
    Yes components have a property section called component. :-).
    Now here is the weird part. All components have a modulator property but you can only view a ‘modulator list’. You might think that modulators are a property of the components but wait, when you’re at the ‘modulator list’ window, click the ‘View’ menu item and select ‘Switch to Tree’. Now in the tree view you will see the objects you’ve added to the panel, the ones we thought were components are listed as ‘modulator’ and under those modulators listed are ‘MIDI’ and ‘Component’ 😀
    WOW What’s going on??? Nothing is what it seems… 🙂

    I think the tree is the best place to understand what really is going on.

    So it seems that you are actually not adding components to the panel (even though that’s what the dialog says) but you’re adding an object called a modulator, which has a group of properties called a ‘component’, ‘MIDI’ and also another group of properties called, wait for it… a ‘modulator’. 🙂

    You can confirm this. Add an object to the panel, select it, in it’s properties dialog look at ‘Modulator’ property group, you will see a property called ‘Link to what type of MODULATOR property’ click its associated drop-down list and you will see the 3 selection options, which are ‘Modulator’, ‘Component’, ‘MIDI Message’. This also tells me that modulator is a modulator property. 🙂 ‘Component’ seems to be a graphical sub-object of a modulator object. In the tree list, it almost seems like you should be able to delete, cut, copy, add or paste a component (or midi) object to a modulator object but it doesn’t work like that. Maybe in a future version…

    So in consideration of all these information i think, the property groups such as component and midi are actually midi object and component object added to a modulator object and all those three objects have their own properties. So in theory, since the only object added to the panel is a modulator and since there is no add modulator function and you can not add a modulator without a component, it might make sense to have a dialog that says ‘add component’ since it will actually add a modulator object but then add the selected component (together with a midi object) to that modulator object.

    Anyways, the next thing i was able to figure out is that the Modulator property group of a modulator object is where you link a Lua code or function to that Modulator object to do different things or behave in different ways.

    So what is an expression and a method and what is the difference?
    As far as i can tell, methods are names of files that hold functions written in lua code. You can see/list these when you open menu item ‘Panel’->’Lua Editor’
    It seems like the convention is to have one function per method and both having the same name. Meaning, if you make function called splitBytes you will have a method called splitBytes and in that method you will have a function called splitBytes. This again seems like having the same mentality as having a modulator parameter of a modulator object but it’s probably how ctrlr uses lua… seems a bit strange to me. I mean why not have a single file that holds all the lua functions so you won’t have to call them ‘methods’ and you wont have to keep them in separate files too???
    Probably this will make sense to me when i learn more about lua and how its used in ctrlr. Anyways, these methods can be called from the following three properties of a modulator object:
    1.’Called to calculate the MIDI value to send’,
    2.’Called to calculate new modulator value from a MIDI value’,
    3.’Called when the modulator value changes’
    And also methods could be called from 17 properties of the panel (+5 in editor section).

    The next thing is expressions. Here is a list of expressions:
    http://ctrlr.org/expressions-in-ctrlr-2/ they are little functions. Ctrlr is based on Juce (www.juce.com) and these expressions are a Juce class. They are different from lua code. The juce documentation explains it in the following way:
    [A class for dynamically evaluating simple numeric expressions.
    This class can parse a simple C-style string expression involving floating point numbers, named symbols and functions. The basic arithmetic operations of +, -, *, / are supported, as well as parentheses, and any alphanumeric identifiers are assumed to be named symbols which will be resolved when the expression is evaluated.]

    In ctrlr they are only entered into 3 specific properties of a modulator object:
    1.’Expression to evaluate when calculating the midi message value from the madulator value’,
    2.’Expression to evaluate when calculating the modulator value from the midi message value’,
    3.” (the third parameter does not have a name and i have no idea what it is, maybe it’s similar to the third property about methods).

    Another concept is global vaiables and local variables which i have not figured out yet. Maybe someone else can post here about those 🙂

    hope this helps someone.

    • This reply was modified 9 months, 1 week ago by  Mr.ToR.
    • This reply was modified 9 months, 1 week ago by  Mr.ToR.
    • This reply was modified 9 months, 1 week ago by  Mr.ToR.

    human fly

    the way i understand it/conceive of it:

    a ‘modulator’ is any ‘object’ you can create on the workspace.
    (i’m a bit cagey about using the term ‘object’ in case it has
    another meaning in programming), and it is like a generic container
    that gives an ID with a name and has ‘properties'(parameters).

    ie: you can create a button, a slider, a UIgroup, a UItabs, etc.
    and they will all be called ‘modulator’ initially (until you
    attribute names to them)

    within this generic ‘object’, there subsections in the properties
    list: ‘modulator’, ‘midi’, ‘component generic’, ‘component’.

    ‘modulator’ is where the object (correct term: ‘modulator’) is
    defined by name and vst index number. you can ‘link’ to another
    modulator and property (ie: ‘value’), define actual(midi) value
    vs. displayed value (ie: if you need to show -7<0>+7 range, but
    midi value is 0-14, you use ‘expression to evaluate when calculating
    midi message from modulator view’, and the entry will be:
    ‘modulatorValue-7’ eg: offset -7 )

    and this is where you find the main Lua/method entry:
    ‘called when value changes’. if you want something to happen
    when you change any onscreen control, you can create/add a
    method here that is triggered when there is a value-change

    there are 2 lua/method entries before this: one is for
    panel-to-MIDI send, and the other is MIDI-to-panel receive

    i’m concentrating on the value-change lua entry for the time
    being. ie: adding functionality to onscreen controls/events.

    the next section is ‘MIDI’ – simplest use is first to select
    ‘midi message type'(sysex/midi cc/etc.).

    if you are using sysex, there’s a sysex message box where you
    enter the entire sysex string including F0,etc.header and F7 end.
    the value variable is represented by ‘xx’, and checksum is ‘zn’,
    where ‘n’ is the number af bytes that need to be checksummed,
    ie: usually address bytes plus value byte/s
    -so if you have a 3-byte address, and a 1-byte value, you use ‘z4’
    for the checksum byte (3+1).

    you can disable this and use your lua method to send the sysex
    string if you need an unconventional value order, and use the lua
    to govern what gets sent. (then, the format for sysex/hex values
    becomes 0x00..etc.)

    after MIDI, you’ve got 2 sections called ‘component’:
    ‘component generic’ are basic parameters for the type of component
    -including *note* another name entry. this is the name displayed.
    i tend to just make this the same as the ‘modulator’ name unless
    there’s a name/title display issue.

    ‘component’, which defines colours, value range etc

    that’s broadly it. you get confused between the 2 component
    sections because you’re always scrolling up/down, and entries
    are not always in the same order – but you do get used to it.

    i never touch a lot of the entries, don’t use them. you will
    discover what you need to use every time when you start creating
    and defining ‘modulators'(the term to use for ‘objects’).

    HOWEVER, the term ‘component’ comes back when you start writing
    methods: expressions can be ie: ‘getModulatorByName()’ or
    ‘getComponent()’. i have just realised this, so i’m not sure
    what the distinction is yet.


    human fly

    so, to create a new lua method for example, with an empty workspace,
    create a eg: slider, then go to ‘called when the modulator value changes’:

    the selection box shows ‘none’. click ‘add new’ and give your method a name.
    now select it on the dropdown list. now click ‘edit selected method’, and
    your lua editor opens, with an empty lua template. you can also call up the
    lua console, from the menu: panel>lua console


    human fly

    i resolved my problem with the ‘setValue’ method mentioned above.
    the version that works is:
    (for switching on/off a led, with a button)

    — Called when a modulator value changes
    — @mod http://ctrlr.org/api/class_ctrlr_modulator.html
    — @value new numeric value of the modulator

    toggle_led3 = function(–[[ CtrlrModulator –]] mod, –[[ number –]] value, –[[ number –]] source)

    led = panel:getModulatorByName(“LED”)

    if value == 1 then
    led:setValue(1, false)
    led:setValue(0, false)

    it does not work without ‘,false’ there. i need to look up
    what that is for. this is about as simple as it gets.
    i’ve declared the ‘LED’ modulator, and attributed its name
    in the script as ‘led’. if the value(of the button) is equal
    to 1, the led has value=1; if not, =0.

    one difficulty is knowing how/where your code ties in to Ctrlr
    parameters – it seems you get 2 types of error messages: if
    your method has compiled successfully without errors but is
    still wrong for hooking up to the panel parameter, you will
    either get a syntax-related error message telling you what
    line/s is the problem, or you just get a Callback Error,
    when you activate the modulator calling the method/function.

    using ‘setVisible()’ it was getComponent(). and using
    ‘setValue()’ i had to ‘getModulatorByName()’. still not
    sure why/what/etc.


    human fly

    nb: Lua is case sensitive, do not use spaces in function names
    (use ‘_’), and avoid capitals when declaring and giving local

    i do not know the distinction between ‘local’ and ‘global’
    ‘variables’ yet.

    i have some beginners’ confusion with terms such as ‘string’,
    variable, ‘value’ vs. ‘num’, statements, arguments, operators,
    etc. – ie: have not mastered ‘jargon’/terminology fluently yet.


    human fly

    d*mn, i’m so proud of that led.
    i just keep clicking that button…



    human fly

    ok, so i tried OR. 2 buttons and a led

    mini-panel demo with lua here:

    (any thoughts on how i can make a led from the Ctrlr
    onboard UI stuff?)


    Hi human fly, just following in diagonal your long posts…
    Seems you are learning programming, learning Lua and learning Ctrlr at the same time…
    Nice effort!

    What are you trying to do?
    I have now one week off and will attack the Step by step guide 2.0 (I know I said that since some time but sometimes I wish having 48 hrs a day).

    The answer to a lot of your questions are in:
    – lua.org web site
    – Juce class index: https://www.juce.com/doc/classes
    – Ctrlr code (end of .h files list the available functions and arguments) https://sourceforge.net/p/ctrlrv4/code/HEAD/tree/nightly/Source/
    – the existing panels. For example for LEDs, look at my Pro2 panel. Take the image from your temp directory, use it in your panel with same frame size and copy the methods by securing also the assignments I’m doing with other methods).


    human fly

    (that OR is wrong: i cheated and used ~= for a quick result,
    but it doesn’t give a proper OR output)

    hi Goodweather, yeah sorry, some long posts, and i’ve been a
    bit all over the place trying to kick on to the next stage.
    trying to get a bit more focused interpreting what i’m seeing
    in lua methods. best description is that i’m trying to learn
    a bit of programming using lua from within ctrlr which i’m
    pretty familiar with now.

    tbh, i find those references confusing..*the entire JUCE class
    index*.. i will have another look. i will have a look at those
    .h files but i’m not sure what i’m looking for.
    and yes, of course i look at other panels. working examples have
    been most useful so far.

    for the led, yes, i can nick your led ! or make one -but then
    i have to bundle it as a resource file with any panel file
    i post as an example; i was wondering if any Ctrlr object
    could be adapted to act as a led by itself, but it seems not.
    i’m making logic gate luas today, just to get a bit of practice.
    (curious how to combine them ..)


    human fly


    Human fly,

    There is no need to be cagey about calling modulators or components objects. Juce is an object oriented framework. Ctrlr is based on Juce. Components are Juce graphical objects and Modulators are Ctrlr objects which contain graphical objects properly called components. An object is an instantiation of a class. In the case of components, when you add a graphical object in ctrlr, it’s actually an instance of the component class. That’s why they’re called objects. If you want, you can even call them an instance of a juce component class.

    • This reply was modified 9 months, 1 week ago by  Mr.ToR. Reason: added the tree image



    human fly

    yeah, good. i don’t think there’s a problem conceiving of the
    ‘modulator’ as a kind of container created for each component
    added, and having some properties/parameters. such name, vst
    index etc.

    eg: you add a ‘component’, and the modulator is created for it

    i haven’t tried ‘replace with’ yet, within the Add Component
    dialog, but that should bear this out: once you’ve created
    a modulator-with-component object, you can/could swap out the
    component type for another, eg: change a slider to a button,
    and still keep the same modulator number and properties.


    human fly

    i have not found a use for Tree view yet. but Modulator List
    is very useful. (you have to be careful what you edit in there,
    especially the Group and Tab columns, because you can really
    mess up a project – best to edit those in the properties pane,
    to be sure of what you’re doing)

    i’m reasonably clear on the modulator/component hierarchy.
    it is seeing both referred to in lua(‘in methods’?’in scripts’?etc.?)

    and i have a notion that these two are different:

    but i’m going to study the .h files Goodweather pointed to,
    because there seem to be more items/commands than listed on that
    expressions page. (just had a quick skim read so far )

    this, after seeing what people have used in panels, thinking
    ‘where did they get that from?’, where’s the list of all those
    functions you can use? – properly called? classes?

    ha, you see, it is a first for me, looking at one of those .h
    files, looking for something specific. didn’t know you could
    do that.


    human fly

    here’s a (‘prefab’?) little panel with the basic logic gates.


    just messing around with buttons and leds.

    (hope you’re enjoying my crappy led graphic, included in zip
    – Ctrlr could do with an onboard ‘led’ component, would look
    really nice, being able to adjust colour and opacity – if it’s
    not too much of a cpu-hit. vector graphics are cool.)

Viewing 20 posts - 1 through 20 (of 49 total)

You must be logged in to reply to this topic.

Comments are closed.