Skip to content

Ui

User Interface

FL Studio built-in module.

Allows you to control and interact with FL Studio's UI.

HELP WANTED

  • Many functions have undocumented return values. What do they mean?

closeActivePopupMenu()

Closes a currently-open popup menu (for example a rick-click or drop-down menu).

Included since API version 1.

closeAllMenu()

Close all visible windows, except for the most recently-used FL Studio window.

WARNING

  • This function is not officially documented

Included since API Version ???

copy()

Copy the selection.

Returns

  • int: ?

Included since API version 1.

crDisplayRect(left, top, right, bottom, duration, flags=0)

Displays a selection rectangle on the channel rack.

This rectangle is anchored using the top left corner, and a width and height.

Subsequent calls to this function will remove previously displaying rectangles.

Args

  • left (int): left position.

  • top (int): top position.

  • width (int): horizontal width.

  • height (int): vertical height.

  • duration (int): duration to display for (in ms). Or,

    • use midi.MaxInt to show indefinitely.

    • use 0 to hide.

  • flags (int, optional): a bitwise combination of:

    • CR_HighlightChannels: Display on channel list rather than on grid.

    • CR_ScrollToView: Scroll channel rack to specified position.

Included since API version 1.

cut()

Cut the selection.

Returns

  • int: ?

Included since API version 1.

delete()

Press the delete key.

Returns

  • int: ?

Included since API version 1.

down(value=1)

Press the down arrow key.

HELP WANTED:

  • What does the value variable do?

Args

  • value (int, optional): ???. Defaults to 1.

Returns

  • int: ?

Included since API version 1, with option parameter since API version 4

enter()

Press the enter key.

Returns

  • int: ?

Included since API version 1.

escape()

Press the escape key.

Returns

  • int: ?

Included since API version 1.

getFocused(index)

Returns whether an FL Studio window is focused (meaning it is the currently selected Window in FL Studio).

Note

  • this doesn't necessarily mean that it is the currently selected window in the host operating system.

Args

  • index (int): window index:

    • widMixer (0): Mixer.

    • widChannelRack (1): Channel Rack.

    • widPlaylist (2): Playlist.

    • widPianoRoll (3): Piano Roll.

    • widBrowser (4): Browser.

    • widPlugin (5): Plugin Window (note that this constant is only usable in this particular function).

    • widPluginEffect (6): Effect Plugin Window.

    • widPluginGenerator (7): Generator Plugin Window.

Returns

  • bool: whether the window is currently focused.

Included since API version 1.

getFocusedFormCaption()

Returns the caption (title) of the focused FL Studio window. This isn't necessarily the same as the plugin's name.

Returns

  • str: window title.

Included since API version 1.

getFocusedFormID()

Returns ID of the focused window.

Used to get the channel rack index or mixer plugin ID for plugins.

Returns

  • int: form ID:

    • Index in channel rack (zero indexed).

    • Plugin ID in mixer (track number * 4194304 + slot index * 65536, all zero indexed).

    • Window ID for mixer, channel rack, playlist, etc.

    • -1 for invalid plugin (eg. script output or settings window).

Included since API version 13.

getFocusedNodeCaption()

Returns the filename associated with the currently selected item in the browser.

Returns

  • str: node caption.

Included since API Version 20.

getFocusedNodeFileType()

Returns a value based on the type of the selected file in the browser.

Returns

  • int: One of the file type constants represented in the FL Studio constants.

Refer to the FL Studio manual.

Included since API Version 20.

getFocusedPluginName()

Returns the plugin name for the active window if it is a plugin, otherwise an empty string.

Returns

  • str: plugin name.

Included since API version 5.

getHintMsg()

Returns the current message in FL Studio's hint panel.

Returns

  • str: hint.

Included since API version 1.

getHintValue(value, max)

Returns value/max as a percentage.

Equivalent to:

f"{value/max:.0%}"

Args

  • value (int): the value.

  • max (int): the maximum value.

Returns

  • str: hint for value.

Included since API version 1.

getProgTitle()

Returns the title of the FL Studio window.

Returns

  • str: program title.

Included since API version 1.

getSnapMode()

Returns the current snap mode.

Although the official documentation states that this takes an argument value, it does not. This stub reflects the actual behavior.

Returns

  • int: index in the snap mode list:

    • 0: Line

    • 1: Cell

    • 2: Unused (separator)

    • 3: None

    • 4: 1/6 step

    • 5: 1/4 step

    • 6: 1/3 step

    • 7: 1/2 step

    • 8: Step

    • 9: 1/6 beat

    • 10: 1/4 beat

    • 11: 1/3 beat

    • 12: 1/2 beat

    • 13: Beat

    • 14: bar

Included since API version 1.

getStepEditMode()

Returns the value of the "step edit mode" within FL Studio.

Returns

  • bool: True if step editing is enabled, else False.

Included since API Version 28.

getTimeDispMin()

Returns True when the song position panel is displaying time, rather than bar and beat.

Returns

  • bool: whether song position is displaying time.

Included since API version 1.

getVersion(mode=4)

Returns the version number of FL Studio.

Args

  • mode (int, optional):

    • VER_Major (0): Major version number (as int) Eg: 20.

    • VER_Minor (1): Minor version number (as int) Eg: 8.

    • VER_Release (2): Release version number (as int) Eg: 4.

    • VER_Build (3): Program build number (as int) Eg: 2553.

    • VER_VersionAndEdition (4): Program version and edition (as str). Eg: "Producer Edition v20.8.4 [build 2553]"

    • VER_FillVersionAndEdition (5): Full version and edition (as str). Eg: "Producer Edition v20.8.4 [build 2553] - Signature Bundle - 64Bit".

    • VER_ArchAndBuild (6): Operating system and system architecture. Eg: "Windows - 64Bit [BETA]"

Returns

  • int or str: FL Studio version information.

Included since API version 1, with mode parameter since API version 7.

getVisible(index)

Returns whether an FL Studio window is currently open.

Note that this doesn't necessarily mean it is the active window.

Args

  • index (int): window index:

    • widMixer (0): Mixer.

    • widChannelRack (1): Channel Rack.

    • widPlaylist (2): Playlist.

    • widPianoRoll (3): Piano Roll.

    • widBrowser (4): Browser.

Returns

  • bool: whether it is visible.

Included since API version 1.

hideWindow(index)

Hides an FL Studio window specified by index.

Args

  • index (int): window index:

    • widMixer (0): Mixer.

    • widChannelRack (1): Channel Rack.

    • widPlaylist (2): Playlist.

    • widPianoRoll (3): Piano Roll.

    • widBrowser (4): Browser.

Included since API version 5.

horZoom(value)

Zoom horizontally by value.

Args

  • value (int): amount to zoom by. Negative zooms out, positive zooms in. Larger magnitudes zoom more, but the scale doesn't seem consistent.

Returns

  • int: ?

Included since API version 1.

insert()

Press the insert key.

Returns

  • int: ?

Included since API version 1.

isBrowserAutoHide()

Returns whether the browser is set to auto-hide.

Returns

  • bool: auto-hide status.

Included since API Version 20.

isClosing()

Returns True when FL Studio is closing.

Returns

  • bool: whether is closing.

Included since API version 1.

isInPopupMenu()

Returns True when a popup menu is open (for example a right-click or drop-down menu).

Returns

  • bool: whether a popup menu is open

Included since API version 1.

isLoopRecEnabled()

Returns whether loop recording is enabled.

Returns

  • bool: whether loop recording is enabled.

Included since API version 1.

isMetronomeEnabled()

Returns whether the metronome is enabled.

Returns

  • bool: whether metronome is enabled.

Included since API version 1.

isPrecountEnabled()

Returns whether precount is enabled.

Returns

  • bool: whether precount is enabled.

Included since API version 1.

isStartOnInputEnabled()

Returns whether start on input is enabled.

Returns

  • bool: whether start on input is enabled.

Included since API version 1.

jog(value)

Jog control. Used to map a jog wheel to selections.

Args

  • value (int): delta value (increment), for example:

    • 1: next.

    • -1: previous.

Returns

  • int: ?

Included since API version 1.

jog2(value)

Alternate jog control. Used to map a jog wheel to relocate.

Args

  • value (int): delta value (increment), for example:

    • 1: next.

    • -1: previous.

Returns

  • int: ?

Included since API version 1.

launchAudioEditor(reuse, filename, index, preset, presetGUID)

Launches an audio editor for track at index and returns the state of the editor. Set reuse to true (1) to reuse an already loaded audio editor.

HELP WANTED

  • How do I get this to work? I can only get it to open an empty window.

Args

  • reuse (int): whether to reuse an already open audio editor.

  • filename (str): filename to open?

  • index (int): mixer track index to open on.

  • preset (str): ???

  • presetGUID (str): ???

Returns

  • int: ???

Included since API version 1.

left(value=1)

Press the left arrow key.

HELP WANTED:

  • What does the value variable do?

Args

  • value (int, optional): ???. Defaults to 1.

Returns

  • int: ?

Included since API version 1, with option parameter since API version 4

miDisplayDockRect(start, length, dock_side, time)

Display a red guide rectangle on the mixer, but contained to one side of the dock.

Compare to: miDisplayRect().

Args

  • start (int): the index of the starting point, with 1 being the 1st track to be docked to that side, and 5 being the 5th track docked to that side.

  • length (int): the length of the rectangle to display, for example 1 means the rectangle will be 1 track wide.

  • dock_side (int): the dock side to show the rectangle on:

    • 0: left.

    • 1: middle.

    • 2: right.

  • time (int): the amount of time to display the rectangle for, or midi.MAXINT to display indefinitely and 0 to turn off.

Included since API Version 20.

miDisplayRect(start, end, duration, flags=0)

Displays a selection rectangle on the mixer.

Subsequent calls to this function will remove previously displaying rectangles.

Args

  • start (int): start track index.

  • end (int): end track index.

  • duration (int): duration to display for (in ms). Or,

    • use midi.MaxInt to show indefinitely.

    • use 0 to hide.

  • flags (int, optional): unknown.

Included since API version 13.

moveJog(value)

Used to relocate items with a jog control.

HELP WANTED

  • How does this differ from jog2()?

Args

  • value (int): delta value (increment).

Returns

  • int: ?

Included since API version 1.

navigateBrowser(direction, shiftHeld)

Navigates through the browser. direction can be 0 for previous or > 0 for next.

Shift held will cause the browser item to expand/open if it's a folder/collection ie Node Type <= -100, similar to keyboard navigation.

Args

  • direction (int): * 40: previous item * 41: next item

  • shiftHeld (bool): whether to expand the selected item if it is a folder.

WARNING

  • This doesn't seem to work very reliably, at least on my machine.

Returns

  • str: the name of the newly selected item in the browser.

Included since API Version 22.

navigateBrowserMenu(direction, shiftHeld)

Navigates through the browser. direction can be 0 for previous or > 0 for next.

Shift held will cause the browser item to expand/open if it's a folder/collection ie Node Type <= -100, similar to keyboard navigation.

WARNING

  • This function is undocumented.

  • This appears to be a duplicate of ui.navigateBrowser. Consider using it instead.

Args

  • direction (int): * 40: previous item * 41: next item

  • shiftHeld (bool): whether to expand the selected item if it is a folder.

Returns

  • str: the name of the newly selected item in the browser.

Included since API Version 22.

navigateBrowserTabs(direction)

Navigates between browser tabs, returning the name of the newly selected tab.

The direction should be one of the MIDI FPT direction constants.

Args

  • direction (int): one of: * midi.FPT_Left (42): change tabs left * midi.FPT_Right (43): change tabs right * any other value: navigate to first tab

Returns

  • str: name of the newly selected tab.

Included since API Version 22.

next()

Move selection to next element.

  • in mixer: select next track.

  • in channel rack: select next channel.

  • in browser: scroll to next item.

  • in plugin: switch to next preset (since API version 9).

Returns

  • int: ?

Included since API version 1.

nextWindow()

Switch to the next window.

Returns

  • int: ???

Included since API version 1.

no()

Press the n key.

Returns

  • int: ?

Included since API version 1.

openEventEditor(eventId, mode, newWindow=0)

Launches an event editor for eventId.

See the event mapping tutorial for more information on REC events.

Args

  • eventId (int): event ID.

  • mode (int): Refer to the FL Studio manual.

  • newWindow (int, optional): whether to open in a new window. Defaults to 0.

Returns:

  • int: ???

Included since API version 9.

paste()

Paste the selection.

Returns

  • int: ?

Included since API version 1.

previewBrowserMenuItem()

Preview the highlighted item in the browser.

This will play a selected audio clip.

Included since API Version 20.

previous()

Move selection to previous element.

  • in mixer: select previous track.

  • in channel rack: select previous channel.

  • in browser: scroll to previous item.

  • in plugin: switch to previous preset (since API version 9).

Returns

  • int: ?

Included since API version 1.

right(value=1)

Press the right arrow key.

HELP WANTED:

  • What does the value variable do?

Args

  • value (int, optional): ???. Defaults to 1.

Returns

  • int: ?

Included since API version 1, with option parameter since API version 4

scrollWindow(index, value, directionFlag=0)

Scrolls on the window specified by index. Value is index for whatever is contained on that window (eg channels for the Channel Rack or tracks for the Mixer).

Args

  • index (int): window index:

    • widMixer (0): Mixer.

    • widChannelRack (1): Channel Rack.

    • widPlaylist (2): Playlist.

    • widPianoRoll (3): Piano Roll.

    • widBrowser (4): Browser.

  • value (int): index to scroll to:

    • on mixer: track number.

    • on channel rack: channel number.

    • on playlist: playlist track number.

    • on playlist: bar number (when directionFlag is set to 1).

Included since API version 13.

selectBrowserMenuItem()

Selects the currently highlighted browser menu item, which is the equivalent of clicking it.

WARNING:

  • This function appears to open the File menu, rather than navigating the browser.

Included since API Version 20.

selectWindow(shift)

Switch to the next window, like pressing the Tab key. If shift is True, switch to the previous window by pressing Shift and Tab.

Args

  • shift (bool): whether the shift key is pressed.

Returns

  • int: ???

Included since API version 1.

setBrowserAutoHide(value)

Toggle whether the browser is set to auto-hide.

Args

  • value (bool): whether the browser should auto-hide (True) or not (False).

Included since API Version 20.

setFocused(index)

Sets which FL Studio window should be focused (meaning it is the currently selected Window in FL Studio).

Note

  • This doesn't necessarily mean that it will be the currently selected window in the host operating system.

Args

  • index (int): window index:

    • widMixer (0): Mixer.

    • widChannelRack (1): Channel Rack.

    • widPlaylist (2): Playlist.

    • widPianoRoll (3): Piano Roll.

    • widBrowser (4): Browser.

Included since API version 2.

setHintMsg(msg)

Sets the current hint message in FL Studio's hint panel to msg.

For information about using icons within hint messages, refer to the hint message icon tutorial.

Args

  • msg (str): new message.

Included since API version 1.

setSnapMode(value)

Set the snap mode using an absolute value.

This can be used on a controller to have different buttons map to different modes. To increment or decrement the value, use snapMode.

Args

  • value (int): new mode - one of the values listed in getSnapMode().

setStepEditMode(newValue)

Sets the value of the "step edit mode" within FL Studio.

Args

  • newValue (bool): True if step editing should be enabled, else False.

Included since API Version 28.

setTimeDispMin()

Toggles whether the song position panel is displaying time or bar and beat.

Included since API version 1.

showNotification(notificationId)

Show a notification to the user, which is chosen from a set of notification strings. This notification appears in the hint panel, much like with ui.setHintMsg(), except with less customization. Currently there is no apparent way to link these to the Script output window.

WARNING

  • This function appears to cause FL Studio's scripting environment to crash when used under Wine on Linux.

Note

  • This function is not documented.

Args

  • notificationId (int): Notification ID, the identifier of the notification string to send.

    • 0: "Now firmware is available for your MIDI device"

    • 1: "New version of script is available"

Included since API Version 20

showWindow(index)

Shows an FL Studio window specified by index.

Args

  • index (int): window index:

    • widMixer (0): Mixer

    • widChannelRack (1): Channel Rack.

    • widPlaylist (2): Playlist.

    • widPianoRoll (3): Piano Roll.

    • widBrowser (4): Browser.

Included since API version 1.

snapMode(value)

Changes the snap mode, by shifting it by value in the list of modes.

This can be used by controls such as jog wheels or arrow buttons to select a snapping mode. To select a value directly, use setSnapMode.

Args

  • value (int): increment (1 for next, -1 for previous).

Returns

  • int: ???

Included since API version 1.

snapOnOff()

Toggle whether snapping is enabled globally.

Returns

  • int: ?

Included since API version 1

strip(value)

Used by touch-sensitive strip controls.

HELP WANTED

  • What controls does this apply to?

Args

  • value (int): ???

Returns

  • int: ?

Included since API version 1.

stripHold(value)

Touch-sensitive strip in hold mode.

Args

  • value (int):

    • 0: release.

    • 1: 1-finger centered mode.

    • 2: 2-fingers centered mode.

    • -1: 1-finger jog mode.

    • -2: 2-finger jog mode.

Returns

  • int: ?

Included since API version 1.

stripJog(value)

Touch-sensitive strip in jog mode.

Args

  • value (int): delta value (increment).

Returns

  • int: ?

Included since API version 1.

up(value=1)

Press the up arrow key.

HELP WANTED:

  • What does the value variable do?

Args

  • value (int, optional): ???. Defaults to 1.

Returns

  • int: ?

Included since API version 1, with option parameter since API version 4.

verZoom(value)

Zoom vertically by value.

Args

  • value (int): amount to zoom by. Negative zooms out, positive zooms in. Larger magnitudes zoom more, but the scale doesn't seem consistent.

Returns

  • int: ?

Included since API version 1.

yes()

Press the y key.

Returns

  • int: ?

Included since API version 1.