Very confused by keybindings and the keymap.cson structure


#1

I have just started using atom for the first time and am a newbie programmer on a Macbook, I was trying to create a shortcut for page up and page down but i am really puzzled by which selector/element to use to specify the text editor (I’ve seen a version using mini and I don’t know what that is). I’m then not sure which command to give the keybinding.

I’d like to use the alt-up arrow for page up and I’ve tried various combinations of this but it doesn’t seem to work or is being overridden by a package called emmet which also uses alt-up. I’m very lost and have spent an hour trying to get this to work. Any help would be appreciated :slight_smile:


#2

It works the same way CSS does, so you can use anything, but specificity matters because it factors into how Atom determines the priority of keybindings.

I’m then not sure which command to give the keybinding.

Under Settings -> Keybindings, you can see all of the keys and their commands. Searching for pageup indicates that its command is core:page-up.

Before we continue, hit up Packages -> Keybinding Resolver -> Toggle. It will provide a visual to explain the rest.

The default selector to address text is atom-text-editor, so if I want a keybinding to modify text but don’t care about where it is, it will look something like this:

'atom-text-editor':
  'alt-up': 'core:page-up'
  'alt-down': 'core:page-down'

If you try that right now, you’ll see that it doesn’t work. The Keybinding Resolver shows you why: the binding from Emmet is more specific. The fact is, atom-text-editor is also used for things like the Find and Replace field. This command is specific to the text buffer, and the selector for that is

'atom-text-editor:not([mini])':
  'alt-up': 'core:page-up'
  'alt-down': 'core:page-down'

If you try it again like this, you’ll see that your binding finally takes precedence. Now it’s at the same level of specificity, and keymap.cson gets read late into the cascade, so it has a chance to overrule any packages.


#3

Hey that’s a great reply thanks. ok I’m with you as far as the css selector thing but with css I know that to change a paragraph I use

but here how do I know that it’s atom-text-editor and not something else like .body which I saw used for another keybinding.

What did you mean by the bit where you said modify text but don’t care where it is?

Also what is the difference between the text-editor and the not([mini]) version - I’ve heard it stands for minimized, but minimized in what sense, for instance completely minimized so you don’t see the atom application at all?

One other thing I noticed was alt-up also has another keybinding with a command of native! what does that mean?

Many thanks for your help


#4

You can check it by opening the developer tools (View -> Developer -> Toggle Dev Tools, or opening a window in dev mode, right clicking, and selecting Inspect Element). The majority of Atom’s DOM is defined by semantic tags, so selectors that talk in terms of atom-text-editor, atom-workspace, atom-panel-container and the like are preferable. I know some of the core keybinds do otherwise, but the difference between body and atom-workspace is nonexistent unless you start doing something weird.

What did you mean by the bit where you said modify text but don’t care where it is?

If there’s a command that you could use in any text field, regardless of where it is.

Also what is the difference between the text-editor and the not([mini]) version

atom-text-editor:not([mini]) is just what it says it is: not mini. If you look at the Find and Replace panel, you’ll see that the text boxes are defined with an empty mini attribute, just sitting there. That’s what not([mini]) is checking for.

<atom-text-editor class="editor mini" tabindex="-1" data-grammar="text plain null-grammar" mini="" data-encoding="utf8"></atom-text-editor>

One other thing I noticed was alt-up also has another keybinding with a command of native! what does that mean?

That’s covered in the docs.


#5

Hey thanks again for some clear answers. Just some questions off the back of this discussion:

1 - What is the ::shadow selector, I’ve seen this a few times in some keybindings but I couldn’t understand it from the docs.

2 - So instead of using the tag atom-text-editor is it possible to just use the class name of .editor? is that a shorthand thats ok to use?


#6

Check out the dev tools window (View -> Developer -> Toggle Dev Tools) and you’ll see some shadow DOM instances, specifically inside of the main atom-text-editor tag. In order to get to the TextBuffers where code resides, you first have to address atom-text-editor::shadow. By forcing you to explicitly address the shadow DOM, it’s easier to make CSS rules that only apply to the UI.

2 - So instead of using the tag atom-text-editor is it possible to just use the class name of .editor? is that a shorthand thats ok to use?

It’s less clear. If someone looks at atom-text-editor, they know exactly what you’re talking about.


#7

Thanks, I’m still a bit unclear on 1, under atom-text-editor :slight_smile:

<atom-text-editor class="editor" tabindex="-1" data-grammar="source coffee" data-encoding="utf8" style=""></atom-text-editor>

I found an id of #shadow-root but it was just filled with a bunch of styles, which didn’t make sense to me.


#8

It’s not an ID. It’s a whole other DOM root inside that tag. The buffer is within div.editor--private.