Event Callbacks

About Events

In order to make it easier for others to add complex features, GM_config provides several events for which you can register callback functions. This page lists information about when these functions will be called, along with why they might be useful.

Passing to constructor

You can pass the callback functions the constructor:

let gmc = new GM_config(
{
  'id': 'MyConfig', // The id used for this instance of GM_config
  'title': 'Script Settings', // Panel Title
  'fields': // Fields object
  {
    ...
  },
  'events': // Callback functions object
  {
    'init': function() { alert('onInit()'); },
    'open': function() { alert('onOpen()'); },
    'save': function() { alert('onSave()'); },
    'close': function() { alert('onClose()'); },
    'reset': function() { alert('onReset()'); }
  }
});

All callback functions will be stored as a property of the GM_config object with the first letter capitalized and preceded by "on" (i.e. the "open" callback is stored as GM_config.onOpen). The code literally works like this, so if you want to add your own custom callbacks, have at it.

onInit()

This function will be called once GM_config has been completely initialized. Although, the configuration panel is not open yet, all values have been set. If you want to do some kind of serious modification of GM_config internals, this is probably the best time to do it.

onOpen(document, window, frame)

This function will be called once the configuration panel is open and completely loaded. All the fields have been created and added to the frame. This function is passed three helpful arguments: document (the document object the frame is in), window (the window of the frame), frame (the actual object containing the panel). There are endless possible ways you can modify the configuration panel with the callback.

Somewhat related, there is an isOpen property of GM_config that can be used to tell if the configuration panel is currently open.

onSave()

This function will be called once all the fields have been read and saved. This callback might be useful if you want use the altered values to change the page immediately in some way.

onClose()

This function will be called once the configuration panel has been destroyed. If you want to use the new values to potentially alter the page once the panel is closed, this callback is probably a better choice than onSave.

onReset()

This function will be called when values in the configuration panel are set to stored values. If you have some type of custom fields (like maybe a slider) that relies on a hidden field for data storage, you'll you need to plug into this callback to reset your custom field.