spacemacs/layers/+os/osx/README.org

#+TITLE: OSX layer

[[file:img/apple.png]]

* Table of Contents                                         :TOC_4_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#philosophy][Philosophy]]
- [[#install][Install]]
  - [[#layer][Layer]]
    - [[#use-with-non-us-keyboard-layouts][Use with non-US keyboard layouts]]
    - [[#define-words-using-os-x-dictionary][Define words using OS X Dictionary]]
  - [[#coreutils][Coreutils]]
- [[#key-bindings][Key Bindings]]
- [[#future-work][Future Work]]

* Description
Spacemacs is not just emacs+vim. It can have OSX keybindings too! This layer
globally defines common OSX keybindings.

** Features:
  - ~⌘~ is set to ~hyper~ and ~⌥~ is set to ~meta~
  - In =dired= use =gls= instead of =ls=
  - Fix separator colors of Spaceline mode-line

* Philosophy
While this layer enables common OSX bindings, it does not implement OSX
navigation keybindings. Spacemacs is meant to be used with evil, and we
encourage you to do so :)

* Install
** Layer
Layer has been updated for new config variables. The variable =osx-use-option-as-meta=
is still available for backwards compatibility and will take precedence if set.

To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =osx= to the existing =dotspacemacs-configuration-layers= list in this file.
The different modifier keys can be set as follows:

#+BEGIN_SRC emacs-lisp
  (setq-defaults dotspacemacs-configuration-layers '(
     (osx :variables osx-command-as       'hyper
                     osx-option-as        'meta
                     osx-control-as       'control
                     osx-function-as      nil
                     osx-right-command-as 'left
                     osx-right-option-as  'left
                     osx-right-control-as 'left))
#+END_SRC

These are also the default values. Setting the right modifier to =left=
will equal the left modifier. Allowed values are: =super=, =meta=, =control=,
=alt= and =nil=.
Setting =nil= for modifiers will leave the left modifiers as emacs default.

*** Use with non-US keyboard layouts
If you need the ~⌥~ key to type common characters such as ={[]}~= which is usual
for e.g. Finnish and Swedish keyboard layouts, you'll probably want to leave the
~⌥~ key unchanged by setting the =osx-option-as= variable to =none=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
     (osx :variables osx-option-as 'none)))
#+END_SRC

If you have problem entering symbols that are behind the ~⌥~ key you may want to
set the variables as follows. This will allow you to use
the right ~⌥~ key to write symbols. The left ~⌥~ key can be used as the Meta
key.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
     (osx :variables osx-option-as 'meta
                     osx-right-option-as 'none)))
#+END_SRC

*** Define words using OS X Dictionary
This layer by default enables defining words under point ~SPC x w d~ using OS X
Dictionary. In some cases you might want to manually setup dictionary to use.
For example,

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
     (osx :variables osx-dictionary-dictionary-choice "English")))
#+END_SRC

To get the list of available dictionaries call =osx/list-available-dictionaries=
function.

You can disable it by setting =osx-use-dictionary-app= variable to =nil=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
     (osx :variables osx-use-dictionary-app nil)))
#+END_SRC

** Coreutils
To get =gls= install coreutils homebrew:

#+BEGIN_SRC sh
  brew install coreutils
#+END_SRC

* Key Bindings

| Key Binding | Description                 |
|-------------+-----------------------------|
| ~⌘ =~       | Scale up text               |
| ~⌘ -~       | Scale down text             |
| ~⌘ q~       | Quit                        |
| ~⌘ v~       | Paste                       |
| ~⌘ c~       | Copy                        |
| ~⌘ x~       | Cut                         |
| ~⌘ a~       | Select all                  |
| ~⌘ w~       | Close window                |
| ~⌘ W~       | Close frame                 |
| ~⌘ n~       | New frame                   |
| ~⌘ `~       | Other frame                 |
| ~⌘ z~       | Undo                        |
| ~⌘ Z~       | Redo                        |
| ~⌃ ⌘ f~     | Toggle fullscreen           |
| ~SPC x w d~ | Define word under the point |

* Future Work
- Allow user to choose from either ~hyper~ or ~super~ as ~⌘~. This is an option
  that is supported cross-platform.
- Configurable option to keep the OSX and spacemacs clipboards separate