-
Notifications
You must be signed in to change notification settings - Fork 0
/
macros.html
144 lines (142 loc) · 10.7 KB
/
macros.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
<head>
<link rel="stylesheet" type="text/css" href="Assets/css/markdown.css">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Noto+Sans">
</head>
<h1 id="macros-guid-for-macos">MACROS Guide for MacOS</h1>
<p><strong>Author: Rhys Shaw</strong></p>
<p>Date: 18/04/2023</p>
<hr>
<p>This is a short guide to programing macros on MacOS with a secondary keyboard. You will need the following:</p>
<ol>
<li>MacOS computer.</li>
<li>A secondary Keyboard Plugged in to your computer.</li>
<li>Some exposure to JSON (essential) and scripting (recommeneded).</li>
</ol>
<h2 id="why-macros-">Why MACROS?</h2>
<p>Macros are a powerful tool in computer programming that allow developers to automate repetitive tasks and streamline their workflow. A macro is essentially a sequence of instructions that can be executed with a single command or keystroke. Macros are commonly used in applications such as Microsoft Excel and Word to automate repetitive tasks, such as formatting data or generating reports. In programming languages like C++, macros are used to define constants, simplify complex code, and create reusable code snippets. Macros work by recording a series of actions and then replaying them whenever the macro is executed. They can be customized to perform specific tasks and can be shared among different users or projects. Overall, macros are an invaluable tool for developers looking to increase productivity and efficiency in their programming work.</p>
<h3 id="how-can-we-make-our-own-macros-">How can we make our own macros?</h3>
<p>We will be using a utility tool called Karabiner <a href="https://karabiner-elements.pqrs.org">Download Here!</a>.</p>
<p>Karabiner is a powerful utility tool for macOS that allows users to customize their keyboard and create macros. With Karabiner, users can create macros by recording a series of keystrokes and assigning them to a custom hotkey or shortcut. This feature is especially useful for automating repetitive tasks or performing complex operations with a single keystroke. For example, a user could create a macro that types out their full name and email address whenever they press a specific key combination. Karabiner also offers advanced customization options, allowing users to create complex macros that include conditional statements, delay commands, and more. With its intuitive interface and powerful capabilities, Karabiner is a great tool for anyone looking to streamline their workflow and increase productivity on their macOS device.</p>
<h3 id="how-does-this-work-">How does this work?</h3>
<p>No matter how many keyboards you have plugged into your computer MacOS will interperate them as a single keyboard. It cannot distingusih between which one is being pressed. This means to add a different keyboard that has custom prgrammed keys we need to intercept the single bewtween the keyboard and MacOS and change it. This is exatly what Karabiner does. </p>
<h3 id="what-functionality-can-i-program-to-macros-">What functionality can I program to Macros?</h3>
<p>We can program alot of things as a Macro these can include.</p>
<ol>
<li>Swapping key assignments, e.g. j key now types --> 2.</li>
<li>Executing exsiting hotkeys on the machine, e.g. open finder, chnage display brighteness, play and skip media buttons.</li>
<li>Run apple scripts or shell scripts to do what ever you want.</li>
</ol>
<h2 id="tutorial">Tutorial</h2>
<ol>
<li>To begin make sure you have downloaded the karabiner program from above.</li>
<li>Load the application and head over to Devices. Disable your main keyboard (this makes sure any changes only apply to the secondary one).</li>
</ol>
<p><img src="Assets/images/macros_1.png" alt="Karabine Elements settings"></p>
<ol>
<li>Now we can make basic changes in the Simple Modifications section. Select your secondary keyboard and add an item. Here you can set keys to default functionality like brightness, volumne open some basic apps and switch around some key types.</li>
</ol>
<p><img src="Assets/images/macros_2.png" alt="Karabine Elements settings"></p>
<p>These macros/keybindings can be selected with the drop down tabs.</p>
<ol>
<li><p>Adding Complex Modifications; Now to increase functionality to be almost endless with possibilites we will made complex modifications. To begin head over to the Complex Modifications Section.</p>
</li>
<li><p>Select Add rule at the bottom. This will take you to the follwowing menu.</p>
</li>
</ol>
<p><img src="Assets/images/marcos_3.png" alt="Karabine Elements settings"></p>
<ol>
<li><p>Try Enabling the Examples to see that it works. It should be implemented as soon as you enable the feature.</p>
</li>
<li><p>You can also seach the karabiner rules libary to look for premade solutions for your needs. (personally non of these were useful for me).</p>
</li>
<li><p>What we really want is to make our own. To do this head over to the configureation directory on your machine that Karabiner uses to load modification. You can see where this is for you on the 'Misc' tab, under Export & import. Head to $YOURPATH/assets/complex_modifications and open the folder in a text editor. We will be creating a JSON file.</p>
</li>
<li><p>Create a blank JSON file here, the name of the file is not important. <code>your_custom_mods.json</code>. Copy the following contents.</p>
</li>
</ol>
<pre><code class="lang-json">{
<span class="hljs-attr">"title"</span>: <span class="hljs-string">"<Title Linking all hotkeys together>"</span>,
<span class="hljs-attr">"rules"</span>: [
{
<span class="hljs-attr">"description"</span>: <span class="hljs-string">"<USEFUL DECRIPTION HERE>"</span>,
<span class="hljs-attr">"manipulators"</span>: [
{
<span class="hljs-attr">"type"</span>: <span class="hljs-string">"basic"</span>,
<span class="hljs-attr">"from"</span>: {
<span class="hljs-attr">"key_code"</span>: <span class="hljs-string">"<YOUR KEY_CODE HERE>"</span>
},
<span class="hljs-attr">"to"</span>: [
{
<span class="hljs-attr">"key_code"</span>: <span class="hljs-string">"<YOUR COMMAND HERE>"</span>,
<span class="hljs-attr">"modifiers"</span>: <span class="hljs-string">"<YOUR MODIFIER HERE>"</span>
}
]
}
]
}
]
}
</code></pre>
<ol>
<li>Here we will contain multiple MACROS in <code>your_custom_mods.json</code>. The <code>title</code> should be indenifyable for this macro layout. We add muliple elements to <code>rules</code> for each macro we want to make. Here is an example of two marcos.</li>
</ol>
<pre><code class="lang-json">{
<span class="hljs-attr">"title"</span>: <span class="hljs-string">"Custom App Opening"</span>,
<span class="hljs-attr">"rules"</span>: [
{
<span class="hljs-attr">"description"</span>: <span class="hljs-string">"G to open ~/ VScode"</span>,
<span class="hljs-attr">"manipulators"</span>: [
{
<span class="hljs-attr">"type"</span>: <span class="hljs-string">"basic"</span>,
<span class="hljs-attr">"from"</span>: {
<span class="hljs-attr">"key_code"</span>: <span class="hljs-string">"g"</span>
},
<span class="hljs-attr">"to"</span>: [
{
<span class="hljs-attr">"shell_command"</span>: <span class="hljs-string">"open -a 'Visual Studio Code'"</span>
}
]
}
]
},
{
<span class="hljs-attr">"description"</span>: <span class="hljs-string">"Notebook: Clear All"</span>,
<span class="hljs-attr">"manipulators"</span>: [
{
<span class="hljs-attr">"type"</span>: <span class="hljs-string">"basic"</span>,
<span class="hljs-attr">"from"</span>: {
<span class="hljs-attr">"key_code"</span>: <span class="hljs-string">"c"</span>
},
<span class="hljs-attr">"to"</span>: [
{
<span class="hljs-attr">"key_code"</span>:<span class="hljs-string">"i"</span>,
<span class="hljs-attr">"modifiers"</span>: [<span class="hljs-string">"command"</span>, <span class="hljs-string">"option"</span>, <span class="hljs-string">"control"</span>]
}
]
}
]
}
]
}
</code></pre>
<p>I have implemented two function here. A Macro to open VScode, and anouther to clear all outputs when working on a jupiter notebook. For the Notebook I had to assign the hotkey <code>cmd+ctrl+opt+i</code> as the clear function (i did this is VScode <code>settings</code>). Now I assign the <code>c</code> on my secondary keyboard to the hotkey combo. </p>
<p>The Function to open VScode is quite different. Here I implemented a shell command that will open vscode. This same command works when exicuted in the terminal, utilising the <code>open</code> MacOS command, <code>-a</code> allows for it to work with apps this is followed by the name of the app.</p>
<ol>
<li>Now we have created a <code>.json</code> file, we will now see all these modifiation in the complex modifaction tab {ref image above}. Enable your Macros to test. IF you edit the macros you will have to remove and enable for the changes to be implemented.</li>
</ol>
<p>Now you should beable to start programing your own Macros. The following will help with some more advanced features of using <code>shell_command</code>.</p>
<h2 id="shell_command">shell_command</h2>
<p>Shell commands can be tempermental depedning on what you are trying to do. The best way to utilise this function is to get it to execute a <code>bash/shell/zsh</code> script. To lauch a terminal executing a script you need to do the following command.</p>
<pre><code class="lang-json"><span class="hljs-comment">"shell_commmand"</span>:<span class="hljs-comment">"open -a iterm ~/scripts/my_script.sh"</span>
</code></pre>
<p><code>~/scripts/my_script.sh</code>:</p>
<pre><code class="lang-shell"><span class="hljs-built_in">echo</span> <span class="hljs-string">"Your task is starting"</span>
sleep 10
<span class="hljs-comment"># your shell script here</span>
<span class="hljs-variable">$shell</span>
</code></pre>
<p>The code will be executed in the terminal app you specify, I have called <code>iterm</code> (which is not nessesarily installed use <code>terminal</code> instead). <code>$SHELL</code> tells the terminal to stay open when the task has been completed (starts a new shell actually) this can be ignored.</p>
<p>With these tools you have the abilities to Macro just about anything. </p>
<p>Enjoy!</p>
<p>Rhys</p>
<p>If there are any spelling mistakes..... keep them to yourselves :-| </p>