Package providing customisable toolbar for Atom
CSS JavaScript Shell
Clone or download
suda Merge pull request #234 from vkotovv/readme-usage
Add Organised to the list of packages that is using Tool-bar
Latest commit ae1b81b Jul 8, 2018

README.md

Atom Tool Bar

Travis CI Circle CI AppVeyor apm Chat

This package provides extensible tool bar for Atom.

Note: this package by itself adds an empty toolbar. To propagate it with icons you can install plugins.

Horizontal

Vertical

Different Sizes

Light Theme

Configuration

Position

On which edge of the editor should the tool bar appear. Possible options:

  • Top
  • Right
  • Bottom
  • Left

Icon size

  • Very Small (12px)
  • Small (16px)
  • Big (24px)
  • Large (32px)

Visibility

  • Visible
  • Hidden

Full Width (available in Atom >= 1.7)

When on top/bottom, expand to full window width.

Use TouchBar

If your computer is equipped with a TouchBar (only Apple MacBook Pro series currently) it can display up to seven tool bar buttons there.

Plugins

Packages using tool-bar

Integrating instructions

By itself this package shows an empty tool bar. To add buttons and spacers to the tool bar, follow the instructions below.

Package.json

Make sure the following properties are part of your package.json.

"consumedServices": {
  "tool-bar": {
    "versions": {
      "^0 || ^1": "consumeToolBar"
    }
  }
}

We recommend using Atom-Package-Deps in your package for installing dependency packages like this package.

Main package file

In your main package file, add the following methods and replace your-package-name with your package name.

let toolBar;

export function consumeToolBar(getToolBar) {
  toolBar = getToolBar('your-package-name');
  // Add buttons and spacers here...
}

export function deactivate() {
  if (toolBar) {
    toolBar.removeItems();
    toolBar = null;
  }
}

Example

let toolBar;

export function consumeToolBar(getToolBar) {
  toolBar = getToolBar('your-package-name');

  // Adding button
  toolBar.addButton({
    icon: 'octoface',
    callback: 'application:about',
    tooltip: 'About Atom'
  });

  // Adding spacer
  toolBar.addSpacer();

  // Using custom icon set (Ionicons)
  const button = toolBar.addButton({
    icon: 'gear-a',
    callback: 'application:show-settings',
    tooltip: 'Show Settings',
    iconset: 'ion'
  });

  // Disable button
  button.setEnabled(false);

  // Function with data in callback
  toolBar.addButton({
    icon: 'alert',
    callback(data) {
      alert(data);
    },
    tooltip: 'Show Alert',
    data: 'foo'
  });

  // Callback with modifiers
  toolBar.addButton({
    icon: 'octoface',
    callback: {
      '': 'application:cmd-1',      // Without modifiers is default action
      'alt': 'application:cmd-2',
      'ctrl': 'application:cmd-3',  // With function callback
      'shift'(data) {
        console.log(data);
      },
      'alt+shift': 'application:cmd-5',       // Multiple modifiers
      'alt+ctrl+shift': 'application:cmd-6'   // All modifiers
    },
    data: 'foo'
  });

  // Calling multiple callbacks at once
  toolBar.addButton({
    icon: 'octoface',
    callback: ['application:cmd-1', 'application:cmd-2']
  });  

  // Adding spacer and button at the beginning of the tool bar
  toolBar.addSpacer({priority: 10});
  toolBar.addButton({
    icon: 'octoface',
    callback: 'application:about',
    priority: 10
  });

  // Adding text button
  toolBar.addButton({
    text: 'hello',
    callback: 'application:about'
  });

  // Text buttons can also have an icon
  toolBar.addButton({
    icon: 'octoface',
    text: 'hello',
    callback: 'application:about'
  });

  // Text buttons can be html
  toolBar.addButton({
    icon: 'octoface',
    text: '<b>BIG</b> button',
    html: true,
    callback: 'application:about'
  });

  // Cleaning up when tool bar is deactivated
  toolBar.onDidDestroy(() => {
    this.toolBar = null;
    // Teardown any stateful code that depends on tool bar ...
  });
}

Methods

.addButton({icon, iconset, text, html, callback, priority, tooltip, data})

The method addButton requires an object with at least the property callback. The callback must be an Atom command string, a custom callback function or an object where the keys are key modifiers (alt, ctrl or shift) and the values are commands or custom functions (see example).

The remaining properties tooltip (default there is no tooltip), text (default there is no text), html (default false), icon (default there is no icon), iconset (defaults to Octicons), data, and priority (defaults 50) are optional.

The tooltip option may be a string or an object that is passed to Atom's TooltipManager

The return value of this method shares another method called setEnabled(enabled) to enable or disable the button.

.addSpacer({priority})

The method addSpacer has only one optional property priority (defaults 50).

.removeItems()

Use the method removeItems to remove the buttons added by your package. This is particular useful in your package deactivate method, but can be used at any time.

.onDidDestroy(callback)

The onDidDestroy method takes a function that will be called when the tool-bar package is destroyed. This is useful if your package needs to do cleanup when the tool-bar is deactivated but your package continues running.

Supported icon sets

Supported commands

  • tool-bar:toggle
  • tool-bar:position-top
  • tool-bar:position-right
  • tool-bar:position-bottom
  • tool-bar:position-left

Authors

Contributors

Issues and pull requests are very welcome. Feel free to write your own packages using this one. For all contributions credits are due: