Plugin

How to create a minimap plugin?

A Minimap is basically just another Atom packages that will interact with the Minimap API, so you can just starts with the Generate Package command.

Minimap Plugin Interface

In addition of the initial Atom packages interface a Minimap plugin must implement the following methods:

• activatePlugin - A function called to activate the plugin
• deactivatePlugin - A function called to deactivate the plugin
• isActive - A function returning a boolean that indicates the activation state of the plugin.

These methods enable plugins to be activated/deactivated by the Minimap package independently of their activation as a package.

All Minimap plugins are activated by default.

A Minimal Minimap Plugin

module.exports = 
  # The atom package activation method. It retrieves the minimap package and registers itself
  # as a minimap plugin. That way, the plugin will be available in the minimap package settings.
  activate: ->
    minimapPackage = atom.packages.getLoadedPackage('minimap')
    return @deactivate() unless minimapPackage?

    @minimap = require minimapPackage.path
    @minimap.registerPlugin 'my-plugin', this

  # The atom package deactivation method.
  deactivate: ->
    @minimap.unregisterPlugin 'my-plugin'
    @minimap = null

  # Minimap Plugin Interface
  active: false
  isActive: -> @active

  # Method called by the Minimap package when the plugin is activated through the minimap settings
  activatePlugin: ->
    return if @active
    @active = true
    
    # This is where the real plugin activation takes place
    @minimap.on 'activated', => # Do something when the minimap is toggled on
    @minimap.on 'deactivated', => # Do something when the minimap is toggled off

  # Method called by the Minimap package when the plugin is deactivated through the minimap settings
  deactivatePlugin: ->
    return unless @active
    @active = false

    # This is where the real plugin deactivation takes place

Minimap Plugin API

The Minimap package provides a simple API for plugins:

• registerPlugin(name, plugin) - Registers plugin as a minimap plugin. The given name will be used to access the plugin as well as a key for the associated minimap setting. When called the Minimap package will proceed as follow:
  • It will create a minimap.plugins.{name} setting. If there was no previous setting with that name, the default value will be set to true, otherwise the value of the setting is retrieved from the Atom config object.
  • It will create a minimap:toggle-{name} command that allow to activate/deactive the plugin through the command palette.
  • It will emit a plugin:added event with an object such as {name, plugin}.
  • It will activate/deactive the plugin accordingly with its associated setting value.
• unregisterPlugin(name) - Unregisters the plugin registered with the given name. When called it will proceed as follow:
  • It will stop observing the setting created for the plugin.
  • It will remove the command palette created for the plugin.
  • It will emit a plugin:removed event with an object such as {name, plugin}.
• versionMatch(expectedVersion) - If a plugin needs a specific version of the Minimap package to work with it can use the versionMatch method to test the Minimap version against a semver version. In that case, the plugin activate method could be written as:

  activate: ->
    minimapPackage = atom.packages.getLoadedPackage('minimap')
    return @deactivate() unless minimapPackage?
  
    @minimap = require minimapPackage.path
    return @deactivate() unless @minimap.versionMatch('1.x')
  
    @minimap.registerPlugin 'my-plugin', this

Minimap Views API

A Minimap plugin will probably want to access the minimap views created in the editor, to do so it can use the following methods:

• eachMinimapView(iterator) - Will call iterator for each present and future Minimap views. The iterator function will be called with an object with the following property:
  • view: The MinimapView instance.
• minimapForEditorView(editorView) - Returns the MinimapView associated with the passed-in EditorView.
• minimapForEditor(editor) - Returns the MinimapView associated with the passed-in Editor.

Minimap Events

The minimap module will trigger the following events:

• activated - Triggered when the Minimap package is toggled on
• deactivated - Triggered when the Minimap package is toggled off
• minimap-view:created - Triggered when a MinimapView was created. It dispatch an object with the following property:
  • view - The MinimapView instance.
• minimap-view:will-be-destroyed - Triggered before a MinimapView destruction. It dispatch an object with the following property:
  • view - The MinimapView instance.
• minimap-view:destroyed - Triggered after a MinimapView destruction. It dispatch an object with the following property:
  • view - The MinimapView instance.
• plugin:added - Triggered when a plugin was added using the registerPlugin method. It dispatch an object with the following properties:
  • name - A String corresponding to the name of the plugin specified in the registerPlugin calls.
  • plugin - The plugin instance.
• plugin:removed - Triggered when a plugin was removed using the unregisterPlugin method. It dispatch an object with the following properties:
  • name - A String corresponding to the name of the plugin specified in the registerPlugin calls.
  • plugin - The plugin instance.
• plugin:activated - Triggered when a plugin was activated. It dispatch an object with the following properties:
  • name - A String corresponding to the name of the plugin specified in the registerPlugin calls.
  • plugin - The plugin instance.
• plugin:deactivated - Triggered when a plugin was deactivated. It dispatch an object with the following properties:
  • name - A String corresponding to the name of the plugin specified in the registerPlugin calls.
  • plugin - The plugin instance.

MinimapView Methods

A MinimapView instance exposes the following methods:

• getLineHeight - Returns the line height of the minimap in pixels.
• getLinesCount - Returns the number of lines in the display buffer of the minimap.
• getMinimapHeight - Returns the height of the minimap in pixels. The returned value correspond to the height of the minimap before transformation through the CSS scale function.
• getMinimapScreenHeight - Returns the height of the minimap in the editor transposed into the transformed coordinates space.
• getMinimapHeightInLines - Returns the number of lines visible into the minimap.
• getFirstVisibleScreenRow- Returns the index of the first visible screen row.
• getLastVisibleScreenRow- Returns the index of the Last visible screen row.
• addLineClass(line, cls) - Adds a class to the specified line DOM element.
• removeLineClass(line, cls) - Removes a class from the specified line DOM element.
• removeAllLineClasses(classesToRemove...) - Removes all custom classes added to all every lines of the minimap. If arguments are passed to the function, only the specified classes will be removed.