Important Methods and Utilities (Addons)
Introduction
This document summarizes some of the most useful methods and utilities for developing addons. See the API reference for a more comprehensive list.
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:
localRequirejs('local');
requirejs('actions');
loads actions.js
from the main directory, as in the previous example, but then loads local.js
from within the addon itself.
Note: Make any necessary localRequirejs
calls before using requirejs
. Because other addons' _add scripts can be included in the code run by requirejs
, the global variable __scriptName
may change, leading to MediaMonkey attempting to load the incorrect local file.
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.title | string | no | Title of the message dialog. |
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);
Custom Object Methods/Properties
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.