# FontLab/Scripting/Setup
## Installing Python on Mac OSX

* FontLab 4.6.x requires the Mac OS 9/Carbon version of the Python interpreter, not the native Mac OS X version.
* The 2.x series of Python releases are the Carbon versions. e.g. Version 2.3.3 works OK on Tiger.
* Download Python from the FontLab site here or from the Python site 2.2.1 or 2.3.3 or from the Mac Python page here.
* The Python installer places the “Python 2.x.x” folder in the Applications folder under Mac OS X e.g.
* Read the installer instructions. After installing there is a "Configure Python" app that has to be run to hook everything up. The script which the app invokes can also be run directly. If the 2.3.3 version of "Configure Python" freezes, you will need to force-quit it and try again. If this fails repeatedly, then install Python 2.2.1 instead and then try running it again.
* Test Python is running by launching the Python Interpreter. If the interpreter terminal window doesn't come up, backtrack.

## Activating Python in FontLab

* Once Python is up and running on your system, launch FontLab and enable Python scripting in the application preferences: To do this, go to FontLab/Preferences.../General tab and set the "Enable Python scripting" checkbox option; then restart.
* Verify that FontLab can see Python. You can test this in two ways:
* View the Properties palette with no font file open. To do this, select /Edit/Properties... With no font open, the properties panel displays the application version and Python install status - as illustrated.
* Check that the "Macro" menu item at /View/Toolbars/Macro is enabled: If it is grayed out, then FontLab thinks Python is not installed. Try re-booting FontLab if you know Python is running OK.
* EDITORIAL NOTE: These sections will eventually migrate to their own pages in the Book hierarchy.

## Installing Macros

* FontLab (version 4.6.x) stores macros in
Within this folder, the sub-directories correspond to the first menu in the Macro Toolbar (ignoring the left-most "tool" menu) and the Macro names appear in the second menu. The first menu lists 3 items: Top Level (Any macros in the root level), Effects and Export. There is a hidden sub-directory called "System" within which you can hook your code into the various context menus and application events (see below).
* FontLab Studio (version 5.x) stores macros in a different location:
* Add your own directory to group your macros together. e.g.
Your folder named "MyMacros" will appear in the first macro toolbar menu along with other sub-directories like this:
* Drop your python script files into /MyMacros/ and they will appear in the menu.
* Macro files must have the .py suffix to be recognized. e.g. HelloWorld.py
* The directory structure is scanned at launch time. Therefore, after creating a new sub-directory, you have to re-launch FontLab.
* The files in a directory are scanned when you select it. Therefore, to use a newly installed macro, you only need to move out of the directory and back to it via the first menu. e.g. move out of "MyMacros" to "Top Level" and then back again.

## Using Macros

* Macros can only be accessed by the toolbar initially, so this needs to be on-screen.
* Select it at /View/Toolbars/Macros. The Macro bar looks like this:
* Executing a macro manually is a 3-mouse-step action:
* select "<yourFolderName>" in 1st Menu; (The default example is "Top Level")
* select desired macro in 2nd Menu; (The default example is "Family generator)
* click the "play" arrow button to the right of the 2nd menu
* The macro selection persists, so subsequent uses of the same macro only require step #3 (i.e. click the Play button). However, if you hit the RESET MACRO button, the selection will revert to the default - usually the first item.
* For frequent use macros keyboard shortcuts can be defined.

## Adding Keyboard Shortcut Assignments

* The right-most icon on the toolbar contains a menu of 10 Keyboard shortcut slots you can fill with Macros.
* The slots are the ten digit key combinations Option-Shift-0 through Option-Shift-9.
* To assign a key combination, select the macro you want in the normal way and then select a slot on the Key menu.
* The key combination is then immediately available.

## Naming Macros

* By default, macros appear in the menu with the name of their file minus the .py suffix.
* The default menu name can be overridden in the first line of the file using the format
* e.g. The default macro pre-installed in 4.6.x has a filename "testing.py", but appears in the menu as "Testing Macro".

## Editing Macros

* The "Edit" icon button in the toolbar opens the selected Python script in a text editor window.
* The default internal editor window in 4.x is pretty basic and always floats over the font windows.
* To select a better editor, go to FontLab/Preferences/General/Use external Python editor and select an app like BBEdit.

## File Permissions

* FontLab 4.6.x internal script editor fails to warn you if it can't save your edits to a locked (i.e. read-only) python script file.
* If you have copied Python script files from another location, check that they have read & write permissions set.
* Do this by selecting the file and /File/Get Info (Command-I) and changing the Ownership & Permissions pop-up to Read & Write if necessary.

## System Macros

* The macro folder called System contains special place-holder macros and directories that you can use to hook into various parts of FontLab:
Context Menu Macros
* The table below lists all the contextual (Cmd-click) menus that you can add your macro to:
| Font | Font window context menu |
| Glyph | Glyph window context menu |
| Bitmap | Context menu when the bitmap background manipulating tool is active |
| Component | Context menu when the component editing tool is active |
| FontsList | Popup menu that appears when you click on the [ABCD] button in the Fonts panel |
| Metrics | Metrics window context menu |
| Node | Node context menu |
| Selection | Selection (in the Glyph window) context menu |
| TTH | TrueType hinting tool context menu |
Event Macros
* The table below lists events which you can add code to:
| Modules | Put here Python libraries you want to use in your macro programs |
| init.py | #FLM: Init Macro |
| new.py | this program is run afer new font is created |
| open.py | this macro program is run after font is opened |
| save.py | this program is run before font is saved |
| done.py | put here code that needs to be executed when FontLab Studio is closed |
Other Macros
* Other things in /Macros/System/ and any info from the 4.5.x manual documentation:
| Tool | Macro Bar compiled tools |
| Guide | ? |
| Hint | ? |
| Kerning | ? |
| OpenType | ? |
| Sample | placeholder.py |
| Text | placeholder.py macro to extend Metrics window working in the text-editing mode |
| preview.py | Macro working on Anchors and accents |