Important Methods and Utilities (Addons)

From MediaMonkey Wiki
Revision as of 03:55, 5 January 2021 by Drakinite (talk | contribs) (Important methods and utilities)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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('local');

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.

&ast;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.

&ast;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.