Important Methods and Utilities (Addons)

Globally accessible methods

requirejs

Includes a JS file. Uses window.eval(), so that the content is executed in the 'window' context and also immediatelly available for the following code. '.js' extension isn't necessary and is added if missing. Duplicates (including those from <script> tag) are automatically ignored. Usage:

requirejs('actions');
requirejs('controls/listview');

The above example loads actions.js and then controls/listview.js, both from the MediaMonkey source (including all relevant _add scripts from addons).

localRequirejs

Similar to requirejs, but for local files within an addon. For example, in an addon with local.js and init.js inside the root:

requirejs('actions');
localRequirejs('local');

loads actions.js from the main directory, but then loads local.js from within the addon itself.

messageDlg

The messageDlg method is used whenever important information needs to be presented to the user, or they need to be prompted for a yes/no answer. Usage: messageDlg(text, type, buttons, options, callback);

Parameter/Attribute	Type	Required?	Description
text	string	yes	The text to display in the dialog.
type	string	yes	Determines the icon that displays in the dialog. Most common options are: Information, Error, Warning, and Confirmation. However, any icon can be used, from the /skin/icon folder.
buttons	Array<string or object>	yes	The buttons that will display on the dialog. You can use existing buttons by specifying their id. Common button ids are: btnOK, btnYes, btnNo, and btnCancel; All pre-existing can be found in buttons.js. You can also create a custom button by passing an object with btnID and caption attributes (e.g. { btnID: 'customBtn', caption: 'Custom Button' }). Can be an empty array.
options	object	no*	Options for messageDlg.
options.defaultButton	string	no	ID of the default button, if specified The default button is highlighted, and it is automatically pressed if the user presses enter.
options.chbCaption	string	no	If specified, a checkbox will appear in the dialog, with the specified caption.
options.checked	boolean	no	If true, and chbCaption is specified, then the dialog checkbox will initialize as checked.
callback	function	no	Callback that executes after the user closes the dialog or presses any of the buttons. Callback is given one parameter (result), which is an object. It contains btnID, string, the button ID that was pressed; and if there is a checkbox, then it contains checked, boolean. If the user clicks the X, btnID is set to btnCancel and result will not contain the attribute checked.

*If not specified, parameter must be declared as undefined.

divFromSimpleMenu

The divFromSimpleMenu method is defined in utils.js. It is used to create checkboxes and radio options straight from JS, without having to create HTML. Usage:

divFromSimpleMenu(divToFill, items);

Parameter	Type	Required?	Description
divToFill	Element	yes	The HTML element that will contain the new menu.
items	Array<Object>	yes	The HTML element that will contain the new menu.

Items:

Attribute	Type	Required?	Description
title	string	yes	The label that appears on the checkbox/radio button.
execute	function	no	Function that executes when the item is clicked.
radiogroup	string	no*	The radiobutton group that this item will belong to. If specified, then the item will appear as a radio button. Mutually exclusive with checkable.
checkable	boolean	no*	If specified, then the item will appear as a checkbox. Mutually exclusive with radiogroup.
checked	boolean	no	Can be specified to determine whether the item starts off checked. When the user changes what is checked by clicking, this attribute will be updated.
order	number	no	The order in which this item will appear. Items with unspecified order will appear first.
grouptitle	string	no	The items will all be grouped inside a fieldset (with a border). If grouptitle is specified, then they will be grouped into fieldsets with titles. Must include grouporder to take effect.
grouporder	number	no	Order in which the group will appear. Must be specified with grouptitle. Ungrouped items will be given a grouporder of 1000.
visible	boolean	no	Determines whether the item is visible. Can be a getter function instead of boolean.

*If neither radiogroup nor checkable is specified, then the item will not appear.

ODS

The global debug-log function is ODS. Messages are only logged on debug builds of MM5, for performance reasons. To view debug messages, use Microsoft's DebugView program: https://docs.microsoft.com/en-us/sysinternals/downloads/debugview Usage:

ODS(message);
where message is a string.

whenReady

window.whenReady calls the specified function when all scripts are loaded, the whole DOM is processed by our parser and all controls are initialized. I.e. at this point everything is ready to be used. So both window.onLoad and window.whenLoaded events occur before this one. If called after this event, the callback function is executed immediatelly. Usage:

window.whenReady(callback);

q, qs, qid, ...

• q(s) = document.querySelector(s)
• qs(s) = document.querySelectorAll(s)
• qid(id) = document.querySelector('data-id=' + id + ']')
• qclass(cls) = document.getElementsByClassName(cls)
• qeclass(e, cls) = e.getElementsByClassName(cls)
• qtag(tg) = document.getElementsByTagName(tg)
• qetag(e, tg) = e.getElementsByTagName(tg)
• qe(e, s) = e.querySelector(s)
• qes(e, s) = e.querySelectorAll(s)
• qeid(e, id) = qe(e, 'data-id=' + id + ']')

[window/control].requestTimeout

the requestTimeout function is both accessible globally and as a part of control classes. It automatically checks whether the window/controlclass still exists, and does not call the callback when the window/controlclass has already been destroyed, to avoid crashes. Usage:

requestTimeout(callback, timeout);
x.controlClass.requestTimeout(callback, timeout);

[window/control].requestFrame

Like requestTimeout, the requestFrame function is both accessible globally and as a part of control classes. It automatically checks whether the window/controlclass still exists, and does not call the callback when the window/controlclass has already been destroyed, to avoid crashes. Usage:

requestFrame(callback);
x.controlClass.requestFrame(callback);

getAllUIElements

Returns an object containing all HTML elements with a data-id, contained within the provided root element. This allows a script to not need to execute qid[/qeid for all elements. If no root element is specified, then it defaults to document. Example: var UI = getAllUIElements(pnlDiv);

UI.chbOption1.controlClass.checked = this.config.option1;
UI.chbOption2.controlClass.checked = this.config.option2;

instead of:

qid('chbOption1').controlClass.checked = this.config.option1;
qid('chbOption2').controlClass.checked = this.config.option2;

initializeControls

Initializes all UI controls below a particular HTML element. This means loading a necessary JS and all the initialization code. This is normally done automatically on window load by mminit.js inclusion. Usually only needed if you manually load HTML. Usage:

var html = loadFile('myFile.html');
initializeControls(html);

loadFile

The function loadFile loads file contents synchronously. (Do not use this function during startup.) Usage:

var contents = loadFile(filename, callback, params);

Parameters:

Parameter	Type	Required?	Description
filename	string	yes	Filename to load.
callback	function	no	Callback to execute after file is loaded.
params	object	no	Options
params.required	boolean	no	Whether file is required. Default is yes.

closeWindow

The function closeWindow closes the current dialog. Do not use on the main window.

notifyLayoutChange

Must be called whenever some layout change is made to a document, e.g. visibility or dimension of an element is changed. This way other controls can adjust their specific properties by listening to the 'layoutchange' event.

Usage:

notifyLayoutChange();

Usage of layoutchange event:

app.listen(window, 'layoutchange', callback);

Override

MM5 gives all objects an "override" method, which allows addons to easily add their code to it. The syntax is as follows:

myObject.override({
    myFunction: function($super, param1, param2) {
        $super(param1, param2);
        // do my new code
    }
})

• Pass an object to the override method, with each item in the object being the function you wish to override.
• All parameters will be passed to the function as normal, except the first parameter ($super) will contain the original function that is being overridden.
• To execute the original function, simply call $super with the right parameters.

UITools

The uitools object contains a myriad of general-purpose methods, mostly centered around manipulating the UI. Most are defined inside actions.js, mainwindow.js, and mminit.js. Below are some of the most commonly used methods/objects.

uitools.toastMessage.show

uitools.toastMessage is an instance of the ToastMessage class: https://www.mediamonkey.com/webhelp/MM5Preview/classes/ToastMessage.html Use uitools.toastMessage.show to display a toast message. These are non-critical messages that display at the bottom of the screen for a short period of time. Usage:

uitools.toastMessage.show(text, options);

where text is a string with the text to display, and options is an object with the following optional attributes:

Attribute	Type	Description
callback	function	Function called after the end of displaying toast message, returns true if "Undo" was not pressed
disableUndo	boolean	If true, do not display "Undo" button in the message
disableClose	boolean	If true, do not display "Close" button in the message
delay	number	Display time in ms, default is 12000.

uitools.openDialog

Opens a dialog window. Usage:

uitools.openDialog(dialogName, params, callback);

Parameters:

Parameter	Type	Required?	Description
dialogName	string	yes	Name of the dialog as defined by its filename (e.g. dlgOptions)
params	object	no	Options
params.modal	boolean	no	Open as a modal (subordinate) window.
callback	function	no	Callback that executes after window closes, if params.modal is true.

uitools.getCanEdit

Returns a boolean of whether things are editable. In Party Mode, tracks and options can not be edited.

uitools.openWeb

Open a webpage.

Parameter	Type	Required?	Description
url	string	yes	URL to open
internal	boolean	no	Whether to show in an internal dialog instead of a web browser.
modal	boolean	no	Whether to show in a modal (subordinate) dialog window.

uitools.getDocking

Returns the window's docking controls.

uitools.getSelectedTracklist

Returns a list of the currently selected tracks.