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 forvalue
.
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, elseFalse
.
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 (asint
) Eg:20
. -
VER_Minor
(1
): Minor version number (asint
) Eg:8
. -
VER_Release
(2
): Release version number (asint
) Eg:4
. -
VER_Build
(3
): Program build number (asint
) Eg:2553
. -
VER_VersionAndEdition
(4
): Program version and edition (asstr
). Eg:"Producer Edition v20.8.4 [build 2553]"
-
VER_FillVersionAndEdition
(5
): Full version and edition (asstr
). 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
orstr
: 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, with1
being the 1st track to be docked to that side, and5
being the 5th track docked to that side. -
length
(int
): the length of the rectangle to display, for example1
means the rectangle will be1
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, ormidi.MAXINT
to display indefinitely and0
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 to1
).
-
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 ingetSnapMode()
.
setStepEditMode(newValue)
Sets the value of the "step edit mode" within FL Studio.
Args
newValue
(bool
):True
if step editing should be enabled, elseFalse
.
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.