Getting Text from the Active Window

These variables are replaced by text in the active window:

• %%%{PBXSelectedText}%%% is replaced by the selected text in the active text object.

• %%%{PBXAllText}%%% is replaced by the entire text in the active text object.

The text is expanded verbatim with no quotation marks. In most shells this would be a dangerous practice because the selection might include single or double quotation marks or any number of other special shell characters. One safe way to use this in a Bourne shell script, for example, is to have it expand within “here-doc” style input redirection like so:

cat << EOFEOFEOF

%%%{PBXSelectedText}%%%

EOFEOFEOF

The script above would simply print the selected text to the standard output.

Getting Information on the Contents of the Active Window

These variables are replaced by information on the text in the active window:

• %%%{PBXTextLength}%%% is replaced by the number of characters in the active text object.

• %%%{PBXSelectionStart}%%% is replaced by the index of the first character in the selection in the active text object.

• %%%{PBXSelectionEnd}%%% is replaced by the index of the first character after the selection in the active text object.

• %%%{PBXSelectionLength}%%% is replaced by the number of characters in the current selection in the active text object.

Getting the Pathname for the File in the Active Window

This variable Is replaced by the path to the file for the active text object if it can be determined:

%%%{PBXFilePath}%%%

This result may not be accurate. Xcode tries to find the file path first by walking up the responder chain looking for a window controller that has a document. If it finds one it uses the document’s filename. If it does not find one, it uses name of the window’s represented file. For more information, see NSWindowController and NSDocument.

Sometimes this variable expands to nothing and sometimes it may expand to a filename that is not really a text file containing the text of the active text object. In the Xcode text editor this works correctly. In other text areas in Xcode (like the build log or any text field) it does not do anything reasonable.

Getting the Pathname for the Utility Scripts

This variable is replaced by the path to the folder that contains a number of built-in utility scripts and commands:

%%%{PBXUtilityScriptsPath}%%%

These scripts and commands can be used from user scripts to provide functionality such as presenting a dialog to ask the user for a string or to ask the user to choose a folder or file, or to add to the menu bar of the host application. See Built-in Utility Scripts for descriptions of the available utility scripts.

Specifying a String

AskUserForStringDialog [default-string]

Displays a dialog in the active application and returns the string that the user enters. If supplied, default-string is the initial content of the text field.

Choosing an Existing File or Folder

AskUserForExistingFileDialog [prompt-string]

AskUserForExistingFolderDialog [prompt-string]

Displays a standard open dialog and returns the path of the file or folder that the user chooses. If supplied, prompt-string is the prompt in the dialog. Otherwise a default prompt is used.

Choosing a New File

AskUserForNewFileDialog [prompt-string [default-name]]

Displays a standard save dialog and returns the path of the new file. If supplied, prompt-string is the prompt in the dialog. Otherwise, a default prompt is used. If supplied, default-name is the default name for the new file.

Choosing an Application

AskUserForApplicationDialog [title-string [prompt-string]]

Displays an application picker dialog and returns the path of the application the user chose. If supplied, title-string is the title for the dialog. Otherwise, a default title is used. If supplied, prompt-string is the prompt in the dialog. Otherwise, a default prompt is used.

Adding a Menu Item from Any Script File

SetMenu add script script menu-title key-equiv input-treatment output-treatment index [menu-path ...]

Adds a menu item to an existing menu in Xcode. The menu item has the name menu-title, and the keyboard shortcut key-equiv. (Use "" for no keyboard shortcut.) When the user chooses this command, it invokes the script script, getting its input from input-treatment and placing its output in output-treatment. The new item is inserted at index in the menu identified by menu-path. If you don’t specify menu-path the item appears in the menu bar. menu-path contains the titles of menus and submenus that lead to the desired menu.

index is a zero-based index starting at the end of all the original items in the menu. For example, the index 0 in the File menu would generally be the first item after Print (usually the last item in the File menu of an application). Index 2 would be after the second custom item in a menu. Use negative indices to count from the end of a menu. Index -1 means “at the end,” and Index -2 means “right before the last item.”

The key-equiv, input-treatment, and output-treatment arguments use the same syntax as the values of the menu definition file directives PBXKeyEquivalent, PBXInput, and PBXOutput respectively. For example, if input-treatment is Selection, the selected text is the input for the new menu item's script.

This is the most complicated form of the SetMenu command. Usually it is better to use the form described inAdding a Menu Item from a Menu Definition Script in conjunction with menu script definition files.

Adding a Menu Item from a Menu Definition Script

SetMenu add scriptfile script-pathindex [menu-path ...]

Adds menu items to an existing menu in Xcode. The items are read from script-path. See Adding a Menu Item from Any Script File for details on the file format. Details such as the menu items keyboard shortcuts, and input and output treatment are defined within the file. The new items are inserted at the given index in the menu specified by menu-path. If you don’t specify menu-path, the item appears in the main menu bar. menu-path contains the titles of menus and submenus that lead to the desired menu.

index is a zero-based index starting at the end of all the original items in the menu. For example, the index 0 in the File menu would generally be the first item after the Print command (usually the last item in the File menu of an application). Index 2 would be after the second custom item in a menu. Use negative indices to count from the end of a menu. Index -1 means “at the end,” and Index -2 means “right before the last item.”

Adding a Submenu

SetMenu add submenu submenu-nameindex [menu-path ...]

Adds a submenu to an existing menu in Xcode. The submenu's title is submenu-name. Initially, it has no items. The new submenu is inserted at index in the menu specified by menu-path. If you don’t specify menu-path, the item appears in the main menu bar. menu-path contains the titles of menus and submenus that lead to the desired menu.

index is a zero-based index starting at the end of all the original items in the menu. For example, the index 0 in the File menu would generally be the first item after the Print command (usually the last item in the File menu of an application). Index 2 would be after the second custom item in a menu. Use negative indices to count from the end of a menu. Index -1 means “at the end,” and Index -2 means “right before the last item.”

Adding a Menu Separator

SetMenu add separator index [menu-path ...]

Adds a separator to an existing menu in Xcode. The new separator is inserted at index in the menu specified by menu-path. If you don’t specify menu-path, the item appears in the main menu bar. menu-path contains the titles of menus and submenus that lead to the desired menu.

index is a zero-based index starting at the end of all the original items in the menu. For example, the index 0 in the File menu would generally be the first item after the Print command (usually the last item in the File menu of an application). Index 2 would be after the second custom item in a menu. Use negative indices to count from the end of a menu. Index -1 means “at the end,” and Index -2 means “right before the last item.”

Removing a Custom Menu Item

SetMenu remove item index [menu-path ...]

Removes a custom item from an existing menu in Xcode. The custom item at index in the menu specified by menu-path. If you don’t specify menu-path, the item is removed from the main menu bar. menu-path contains the titles of menus and submenus that lead to the desired menu.

index is a zero-based index starting at the end of all the original items in the menu. For example, the index 0 in the File menu would generally be the first item after the Print command (usually the last item in the File menu of an application). Index 2 would be after the second custom item in a menu. Use negative indices to count from the end of a menu. Index -1 means “at the end,” and Index -2 means “right before the last item.”

Only items and submenus added by a SetMenu command can be removed by the SetMenu remove item command. You cannot remove the standard Xcode menu items.

Removing All Custom Menu Items from a Menu

SetMenu remove all [menu-path ...]

Removes all custom items from an existing menu in Xcode. All custom items in the menu identified by menu-path are removed. If you don’t specify menu-path, the item is removed from the main menu bar. menu-path contains the titles of menus and submenus that lead to the desired menu.

This command applies to items and custom submenus but does not recurse into original submenus. For example, if you add an item to the File menu and you add a menu called My Scripts to the main menu bar, SetMenu remove all removes the My Scripts menu but does not remove the custom item in the File menu. SetMenu remove all File removes the custom item from the File menu.

Only items and submenus added by a SetMenu command can be removed by the SetMenu remove all command. You cannot remove the standard Xcode menu items.