December 17, 2014

Key Codes for Function and Special Keys in Applescript

Using Applescript to simulate keypresses can prove handy when doing automation. You can enter regular text with:

 tell application "System Events" to keystroke "testing"

This passes a string to the frontmost app. However, you can also simulate single key presses (Function keys, Right arrow, and other Special keys, etc.) such as a Tab:
 tell application "System Events" to key code 48

You can also add modifiers, so if you wanted the degree symbol °, which is option+shift+8:
 tell application "System Events" to key code 28 using {option down, shift down}

It's not possible to make any sense out of key code assignments; here's an exhaustive list of all Key Codes, including standard ascii keys, Modifier keys, Function keys and other special keys.

Name Symbol Code
Zero 0 29
One 1 18
Two 2 19
Three 3 20
Four 4 21
Five 5 23
Six 6 22
Seven 7 26
Eight 8 28
Nine 9 25
A 0
B 11
C 8
D 2
E 14
F 3
G 5
H 4
I 34
J 38
K 40
L 37
M 46
N 45
O 31
P 35
Q 12
R 15
S 1
T 17
U 32
V 9
W 13
X 7
Y 16
Z 6
SectionSign § 10
Grave ` 50
Minus - 27
Equal = 24
LeftBracket [ 33
RightBracket ] 30
Semicolon ; 41
Quote ' 39
Comma , 43
Period . 47
Slash / 44
Backslash \ 42
Keypad0 0 82
Keypad1 1 83
Keypad2 2 84
Keypad3 3 85
Keypad4 4 86
Keypad5 5 87
Keypad6 6 88
Keypad7 7 89
Keypad8 8 91
Keypad9 9 92
KeypadDecimal . 65
KeypadMultiply * 67
KeypadPlus + 69
KeypadDivide / 75
KeypadMinus - 78
KeypadEquals = 81
KeypadClear 71
KeypadEnter 76
Space 49
Return 36
Tab 48
Delete 51
ForwardDelete 117
Linefeed ? 52
Escape 53
Command 55
Shift 56
CapsLock 57
Option 58
Control 59
RightShift 60
RightOption 61
RightControl 62
Function fn 63
F1 122
F2 120
F3 99
F4 118
F5 96
F6 97
F7 98
F8 100
F9 101
F10 109
F11 103
F12 111
F13 105
BrightnessDown F14 107
BrightnessUp F15 113
F16 106
F17 64
F18 79
F19 80
F20 90
VolumeUp ? 72
VolumeDown ? 73
Mute ? 74
Help/Insert ? 114
Home 115
End 119
PageUp 116
PageDown 121
LeftArrow 123
RightArrow 124
DownArrow 125
UpArrow 126

The unassigned key codes are:
54, 66, 68, 70, 77, 93, 94, 95, 102, 104, 108, 110, 112
Several of these insert some unidentified control character in some apps.

The few codes with a ? are broken or are unreliable.

Note that because the key codes refer to the physical positions on a keyboard, the result of some key codes will vary when using something other than the standard English ISO keyboard layout.
If you have a French keyboard and are using the French keyboard layout, the key code 0 will produce a "q" instead of an "a", as will the reverse for key code 12.
The key codes that reference modifier and function keys, from "Space" and down on the list, should not be affected by different keyboard layouts.

July 06, 2014

Customizing window icons in your favorite program

Customizing a program's window icons

When you have a window open in your favorite program, most often the little widgets you see in the window interface—arrows, icons, symbols, etc.—are just a collection of images sitting in the Resources folder of the application bundle. That is to say, if you'd like to customize the look of the window, feel free to experiment with looking through the bundle and making your own alterations.
I will here demonstrate how to do so with everyone's favorite bible program, Accordance Bible Software. Accordance uses a pencil icon and a little note(s) icon in the right margin of a text to conveniently provide the user the opportunity to interact with their own user notes. Let's
explore how we could change the notes icon to something a little less subtle.
I have previously show how to customize the "Highlighting Symbols" that Accordance uses in "Taming the Symbols in Accordance". This process is very similar.

Note that altering the contents of a program bundle is certainly not something a program author should necessarily encourage. If you delete something accidentally, you will need to reinstall the app. Any changes you make inside an application bundle can likely get written over the next time you update the app.

Changing the notes icon in the margin in Accordance:

1. Quit Accordance.

2. Find the application file in Finder. It's probably in your /Application folder. (You can right-click (or ^ control-click) on the Accordance icon in the Dock and select ⇢More options⇢Show in Finder.

3. Right-click (or ^ control-click) on the Accordance app and select from the popup contextual menu ⇢Show package contents. You will see inside this new folder the innards of the application (that's technical jargon).

4. Navigate to the folder /Contents/Resources/Icons/  This folder contains all the images that the program uses to build it's interface. Scrolling down, you will find the pencil icon image is 11255.png. The Note image is 11260.png and the Notes image is 11261.png.

5. Select 11260.png and 11261.png in the Icons folder and copy them to your desktop or elsewhere for safe keeping, so you can always go back. Because these are in a application bundle, the files have extra protection, so you'll have to hold down the ⌥ option key to copy them. (A plus sign will show up as you drag. You down want the arrow sign which only creates an alias link to the files.)

6. Once again, select 11260.png and 11261.png in the Icons folder and delete them. Because of the special protections, you may be asked to authorize as an administrator with privileges.

7. Choose a replacement icon. You may want to use one of the other images in this /Icons folder. I like 10331.png as a little notes icon, or perhaps you'd like to use a small diamond dot, which is 294.png. You can even search the web for your own icon. Searching for "web dot png", I found a simple little round dot you could drag to the desktop. If you find your own image, keep it within the size of the original, which is 14 pixels wide x 18 pixels high.

8. Select the new image you want to use in Finder. Duplicate the file twice in menu ⇢File⇢Duplicate (assuming you wish to use the same image for a single note and multiple notes).

9. Select the file and rename it to 11260.png and another as 11261.png and move then into the /Contents/Resources/Icons/ folder if they are not already there.

10. Notice that there is also a folder beside the /icons/ folder called /icons@2x/. These are slightly larger versions of many of the same images for higher resolution uses. You can also do the same process for the images in this folder. The Notes images are within 28x40 pixels.

11. Restart Accordance and enjoy the new look. Don't like it? Change it.

If you wish to change the Notes image, chances are you also don't want the original Pencil image. You can change it as well, although there is an option to remove it all together in Accordance Preferences…/User Files/Hide Add User Note pencil.

Note: Here's an example of doing the same kind of thing for Dropbox, just altering the image files in the application bundle.

July 05, 2014

Creating a New Automation Service for Accordance

As of Accordance 10.4.3, Automator Actions are now included that allow you to build your own OSX Services as well as other Automator Workflows. The best starting place is to download the sample Services from Accordance, and get familiar with those, including the Instruction file included with them.
This is a tutorial on how you could go about building a new Service workflow, one that queries you for a verse reference in a dialog box and then inserts the full text of that reference in whatever document you're in. (This tutorial uses OSX 10.9.)

1. Launch which is located in the /Applications folder.

2. When the dialog box for a new workflow shows up (you may have to select menu File/New), choose the option to create a new "Service". A Service is a special type of Automator Workflow that gets installed in the system-wide Services menu for quick access to automation tasks from inside other programs.

This opens a new Workflow in Automator. A Workflow is the palette that you can create individual steps for the Workflow to run that results in automated tasks being accomplished. The pane on the right is the canvas where you create the steps. The top pane on the left are the individual Automator Actions. These actions represents a large number of single tasks that can be added to the Workflow (by dragging them over). They are the building blocks of your automation Workflow. The pane below on the left shows the description of each Action... what kind of input it works on, what it accomplishes, what the results will be. As you add Actions to the Workflow on the right, the results (output) of one Action get passed on to the next Action in the Workflow.

3. Select menu File/Save and name the Service something descriptive of what it will accomplish. We will name this service "Acc - Query Insert Verses". The 'Acc' will group it with other Accordance Services, the 'Query' indicates it will first ask you for input, and the rest describes that it will insert the full text of the verses.

4. For creating our Service, the first task we need to accomplish is bringing up a dialog box to allow us to input the verse references we want to insert. There is an Automator Action called "Ask for Text", which brings up a dialog box. This Action is flawed, however, in that once it pops up you still have to click on it to type in it. So, we won't use it. We can overcome this flaw with a little Applescript. Find the Action titled "Run Applescript" and drag it into the Workflow space.

5.  Change the text of the default Applescript content to bring up a dialog box. You don't need to know anything about scripting to accomplish this. You might observe that the script will run every command between the words "on run" and "end run". So, let's change what the text runs.
Delete the line that says:
return input
(You can also delete the "(* Your script goes here *)" line if you like. It's just a comment.)
Paste the following command onto its own line, in between the "on run" and "end run" lines.
return text returned of (display dialog "Enter a verse reference:" default answer "")
Note that this text is all one paragraph. The result should look like this:

6. Next, find the Accordance Actions. You can do so by typing "acc" in the search bar above the Actions. You will see two Accordance actions. One is "View Text in Accordance". This Action building block is for taking references and searches and bring Accordance forward in order to run those searches in a new text or tool of you choosing. Find the Action called "Get Text From Accordance" and drag it underneath your Applescript action in the Workflow.

7. Select the options you desire in the "Get Text from Accordance" Action. The popup menu will populate with the short name of all the Text Modules you have installed in Accordance. I'm going to select "First Text Module" which will pull the verses from the module at the top of my module list in the Accordance Library. You can also choose whether the text is to be formatted using the Citation format you stipulate in Accordance Preferences, or if you prefer it to just use one verse per paragraph.

8. At the top of the Workflow, change the option to display "Service receives no input". This means that the Service does not require you to have anything selected in order to activate it (because you will be providing the input in a dialog box.)

9. Close to that option, select the option for "Output replaces selected text". This is what instructs the Service to insert the results of the Workflow into the current cursor/selection of your current document. This means that our Services will only be available in the Services menu when the current selection is a type of document that you can in fact edit/type into.

10. Save the Service Workflow and quit Automator, and you're done.

Now, you can be in a text document/email/etc. and insert verses quickly by:
1. Placing the curser where you want and invoking the Service "Acc - Query Insert Verses":

2. Enter a valid verse reference in the dialog box:

3. Enjoy the textual goodness that results:

You can peruse the Actions in Automator (especially those in the "Text" section) to get an idea of the possibilities of what you can create.
Note that the Service you just created, as well as the sample Accordance Services you should have installed, are located in ~/Library/Services/. If you want to add a new Service that's only a slight change from one you already have, you can select the file in that folder, duplicate it, open it in Automator by double-clicking, change the options (such as selecting "Second Text Module", rename the file and save and quit.
Note also, that if you have a Service you end up using often, do yourself a favor and add a global keyboard shortcut using the Apple Preferences / Keyboard Preferences.
You can find more information about this in the Instructions that come bundled with the sample Accordance Services.

July 03, 2014

Automation in Accordance 10.4.3

Accordance 10.4.3 has added new features that have opened up new avenues for automation. These new capabilities are the primary feature enhancement for this point upgrade.  I am delighted in their efforts.

The new features are:
1. A URI protocol that allows creators to embed links into web pages/pdfs/emails/other documents that will open Accordance to the specified text or tool, even searching the specified field for the specified text. This link will open your default text module and search for "Joseph": accord://search/;Words?Joseph

2. New Services that allow for
  • selecting text in some other document and searching for and viewing it in Accordance
  • inserting full text into your document
3. Two new Automator Actions that allow any number of automation applications (of which the above mentioned Services are actually just beginning examples of what can be created in Automator).

Since I have Applescripts and Services and Actions etc. floating around out there that have tried to fill the gap to date, I thought it would be helpful to update users on the new situation regarding automation.

I have for years produced the Accordance Script Library for automating Accordance. When users drug this into their ~/Library/Scripts folder, they could then use other scripts/services/actions  created by me and other industrious users for doing the same kinds of things the new Services make possible.

My Accordance Script Library pulled text out of Accordance invisibly using Applescript APIs (hooks that allow you to programmatically get data from a process). This capability will not change.
The Library also allowed for bringing Accordance to the front, opening a Tool of choice and running a search, but it accomplished all this through [quite] clever uses of User Interface Scripting—simulating menu selections, key presses and mouse-clicks through scripts. It was always clunky. The new URI protocols now accomplishes much of the same thing and makes it much more robust. A short Applescript can use the URI protocol to interact with Accordance, using the 'open location' command:

    open location "accord://search/;Words?Joseph"

In time, I will be rewriting the Accordance Script Library to use the URI protocols where appropriate to interact with Accordance.

One note, however, is that my previous Accordance Services are now obsolete. I will this weekend be removing them from my Downloads section, and join others in supporting Accordance's new options using Automator to create the Services you might like.

April 01, 2014

An Anxious Ale is Now Published

After many grueling nights getting the drafts finished and the proofs proofed, I'm happy to announce that final proofs were accepted and my book is finally published.

"An Anxious Ale:  A post-colonial survey of the semiotics of beer and other fermented consumables in the Bible."
by Dr. Joseph A. Weaks

I'm pleased with the results. The central chapter on foam and the Holy Spirit, I hope, will represent a sea change on the contextualization of PNEUMA. I even like how the cover turned out. The mug is the Shinerus Flagon from the dig at Miletus in 1999. The book will be available for Kindle April 21, and to ship in print in May.

It has been a long journey on this project, which began with an idea scribbled on a napkin at the Flying Saucer in downtown Fort Worth years ago. I'm grateful to Heidelberg Academic Press for accepting the project and to the Eltsac-Wen Fellows Program for the grant.
I also want to thank my many colleagues who have walked by my side during years of research on this topic. Your support and companionship has meant everything.

January 29, 2014

Collecting INFER & SearchBack Results in Accordance via Applescript

Accordance has a great INFER command that let's you find phrases in the corpus of one tab that 'seem similar to' the corpus in a second tag. Think searching out intertextuality echoes.
The Search Back feature let's you select a verse in the results, and see back to where that phrase is in the original source corpus.
Here is a batch script example of how to compile each of those results alongside each other in a text document.
I provide this Applescript with lots of comments so that Accordance users and with some scripting capacity can follow the flow and learn how to roll their own.
Here's a video demonstrating what on earth I'm talking about.

And here's the code:

-- Collect INFER and Search Back results in Accordance
property textApp : "TextEdit" -- name of your word processor or text editor
set d to 0 -- set global delay to 1 or more to observe the process, for troubleshooting purposes
set r to 100 -- max number of verses to iterate through

-- start the script with insertion point in Accordance in position 0, in front of the first marked verse of the INFER source tab (tab2) in the text window

set n to 1 -- counter for searches
set sourceVerse to ""
repeat r times
    tell application "Accordance" to activate
    delay 0.1
    delay d
    tell application "System Events"
        tell process "acord"
            click menu item "Search Back Linked Text" of menu 1 of menu bar item "Amplify" of menu bar 1
            delay 1
            -- Accordance moves to tab4
            -- Check Search Back results Search Criteria to make sure an errant string search wasn't conducted
            key code 123 -- left arrow to collapse any selection
            keystroke tab -- highlight search box
            keystroke "c" using {command down} -- copy Search Back search criteria
            delay 0.3
            delay d
            set searchBackCriteria to the clipboard -- save Search Back search criteria to variable
            -- go to source tab
            keystroke tab using {control down} -- go to tab1
            keystroke tab using {control down} -- go to tab2
            delay d
            key code 124 using {shift down, command down} -- Cmd Shft Rt to select entire source verse
            delay d
            keystroke "c" using {command down} -- copy
            delay 0.3
            delay d
            set previousSourceVerse to sourceVerse
            set sourceVerse to the clipboard
            delay 0.1
        end tell
    end tell
    if sourceVerse = previousSourceVerse then
        display dialog "Last source verse searched:" & return & sourceVerse
        exit repeat -- would just be repeating the last Source Verse
    end if
    if word 1 of searchBackCriteria is "INFER" then -- a valid Source Verse was used for the Search Back result (i.e. didn't search for a word from a wrapped line)
        -- paste the Source Verse in a word processing app or text editor
        tell application textApp to activate
        delay 0.1
        delay d
        tell application "System Events"
            tell process textApp
                keystroke return
                keystroke (n as string) -- add a iteration notation for each new entry
                keystroke " =========="
                keystroke return
                delay d
                keystroke "v" using {command down} -- paste source verse
                delay 0.3
                delay d
                key code 124 -- right arrow collapse selection
                keystroke return
                keystroke " --------"
                keystroke return
                delay d
            end tell
        end tell
        tell application "Accordance" to activate
        delay 0.1
        delay d
        tell application "System Events"
            tell process "acord"
                -- go to the results tab
                keystroke tab using {control down} -- go to tab3
                keystroke tab using {control down} -- go to tab4
                delay d
                -- go copy the results
                keystroke tab using {option down, shift down} -- place insertion point in the text pane
                delay d
                keystroke "a" using {command down} -- select all
                delay 0.1
                delay d
                keystroke "c" using {command down} -- copy Search Back results
                delay 0.3
                delay d
                -- go to the source tab
                keystroke tab using {control down} -- go to tab1
                keystroke tab using {control down} -- go to tab2
                delay d
            end tell
        end tell
    end if
    -- Accordance is already front app
    tell application "System Events"
        tell process "acord"
            -- prepare the Accordane window for the next verse search
            key code 125 -- down arrow to go to the next verse
            -- sometimes this will go to the next LINE of a single wrapped verse, but not always
            delay d
            key code 123 using {command down} -- Cmd left arrow to put insertion point at beginning of line
            delay d
        end tell
    end tell
    tell application textApp to activate
    delay 0.1
    delay d
    tell application "System Events"
        tell process textApp
            keystroke "v" using {command down} -- paste Search Back results
            delay 0.5
            delay d
            keystroke return
            delay d
            delay d
            set n to n + 1
        end tell
    end tell
end repeat