Command description keys
for customizing OnMyCommand
Description format version 3.0 (backward compatible with version 2.0)
 |
Table of Contents |
 |
|
What is new in
version 3.0 of command description format (OMC v. 3.0 final) |
|
All Rows in Nib Table:
New special word to obtain all row values from table in custom nib dialogs:
__NIB_TABLE_NNN_COLUMN_MMM_ALL_ROWS__ /
$OMC_NIB_TABLE_NNN_COLUMN_MMM_ALL_ROWS
System Services:
NS_SERVICE_ITEM is the new key that holds system service settings for given command. The content of this dictionary is added by OMCEdit to service items in ~/Library/Services/OMCService.service/Contents/Info.plist when you hit "Build Service" button in "Services" tab.
OMCEdit generates the content of this dictionary for you. If you wish to edit it manually, you need to get familiar with services plist format
described by Apple here.
OMCService.service expects a couple of special settings in there:
NSMessage must be a string "runOMCService"
NSPortName must be a string "OMCService"
NSUserData is a string with given command name to execute
OMCService.service uses your main ~/Library/Preferences/com.abracode.OnMyCommandCMPrefs.plist to find a command and execute it.
Droplets also may advertise a system service, in this case OMCEdit puts the content of
NS_SERVICE_ITEM dictionary in your Droplet.app/Contents/Info.Plist and the command description is in regular location: Droplet.app/Contents/Resources/Command.plist
|
What is new in
version 2.9.4 of command description format (OMC v. 2.3 final) |
|
USE_PATH_CACHING
A new option for navigation dialogs to allow or disallow sharing of the same selected path between subcommands.
Previous behavior was to always share the path and never ask again (default value is true).
The new option allows each subcommand to have a separate path, effectively asking the user with navigation dialog for a different path.
Just set the path caching option to false:
<key>CHOOSE_FILE_DIALOG</key>
<dict>
<key>USE_PATH_CACHING</key>
<false/> {default is true if key not present}
</dict>
This option is available for SAVE_AS_DIALOG, CHOOSE_FILE_DIALOG, CHOOSE_FOLDER_DIALOG and CHOOSE_OBJECT_DIALOG.
|
What is new in
version 2.9.3 of command description format (OMC v. 2.2 final) |
|
Localization Support
1. Localization support has been added with
LOCALIZATION_TABLE_NAME key. It is a
string value and should not include ".strings" extension. This can be
used in droplets or external ".omc" modules for localization. If
LOCALIZATION_TABLE_NAME key is not
present in command description, no attempt is made to localize strings.
The following strings in command description are localizable:
NAME and NAME_PLURAL
INPUT_DIALOG
MESSAGE
OK_BUTTON_NAME
CANCEL_BUTTON_NAME
DEFAULT/DEFAULT_VALUE
INPUT_MENU each string
Warning dialog strings:
WARNING
WARNING_EXECUTE
WARNING_CANCEL
Navigation dialogs strings:
SAVE_AS_DIALOG/CHOOSE_FILE_DIALOG/CHOOSE_FOLDER_DIALOG/CHOOSE_OBJECT_DIALOG
DEFAULT_FILE_NAME
MESSAGE
END_NOTIFICATION
TITLE
MESSAGE
Progress dialog:
PROGRESS
DETERMINATE_COUNTER
STATUS
DETERMINATE_STEPS
in STEPS array each STATUS string
Output window:
OUTPUT_WINDOW_SETTINGS
WINDOW_TITLE
2.
loco tool for shell
script localization. It is available in
/Library/Frameworks/Abracode.framework/Support.
loco takes 2 optional
parameters:
"-bundle" and "-table" and the string is the always the last
(mandatory) param.
If you don't specify the bundle, loco gets the current working
directory and tries to find our the closest enclosing bundle.
If you don't specify the table, loco assumes you want to find the text
in "Localizable" table. For "-table" param you pass the name without
".strings" suffix.
In simplest form, if your current path is in a bundle and your string
is in "Localizable.strings" file you can use loco just like echo:
"$OMC_OMC_SUPPORT_PATH/loco" "Hello World"
Custom Cocoa Nib dialog changes:
OMC has a support for separate subcommand execution for each row in
table view. It is analogous to separate or combined command execution
for multiple file selection. Normally the value of the control is just
text but if you have multiple rows selected you have to combine text
values for single execution (how it is combined, it can be specified in
OMCTableView custom interface builder inspector) or tell OMC to iterate
the selection and execute given subcommand separately for each selected
row. Now the problem was how to associate the subcommand (or
subcommands) which should be iterated and executed separately. In
Carbon DataBrowser control you put a subcommand id or list of ids in
custom control parameters of your data browser control. Those were '
ite!' and '
rev!' tags
(look in below in
Nib
dialogs section). When using Cocoa OMCTableView, instead of putting
a list of iterated subcommands in the control description, the
association is reversed: now the subcommand itself has a new tag to
tell that it wants to be executed separately for given table view. It
needs to specify which table view it is. The syntax is:
<key>NIB_CONTROL_MULTIPLE_SELECTION_ITERATION</key>
<dict>
<key>CONTROL_ID</key>
<integer>1
</integer>
<key>IS_REVERSE</key>
<false/> {default value}
</dict>
Cocoa custom dialog support:
Added omc_set_value_from_stdin as an option to
omc_dialog_control to work around the problem of long value text
exceeding allowable command-line option length. Such long string makes
sense for text view control but this new form of setting the dialog
control value through piping might be convenient in some cases. Example
use:
echo "Hello World" | "$OMC_OMC_SUPPORT_PATH/omc_dialog_control"
$OMC_NIB_DLG_GUID 2 omc_set_value_from_stdin
|
What is new in
version 2.9.2 of command description format (OMC v. 2.1 final) |
|
Progress
Dialog:
Cocoa implementation of progress dialog with enhancements.
The enhancements are for translating command output text into a
determinate progress in GUI dialog. These new options work only with
popen() execution.
There are 2 modes of operation for getting progress info from output
text.
A. First mode is "steps": fixed percentage number when certain text
appears in output. We can assign percentage progress number to each of
these steps and compose a progress dialog based on this. If you don't
like the output from the command line tool, you can replace it with
your own status string (optional).
<key>PROGRESS</key>
<dict>
<key>DETERMINATE_STEPS</key>
<dict>
<key>MATCH_METHOD</key>
<string>match_exact</string>
<string>match_contains</string>
{default value}
<string>match_regular_expression</string>
<key>COMPARE_CASE_INSENSITIVE</key>
<false/> {default value}
<key>SUPPRESS_NON_MATCHING_TEXT</key>
<false/> {default value}
<key>STEPS</key>
<array>
<dict>
<key>STRING</key> { a string to match
in output line }
<string>Starting</string>
<key>VALUE</key> { integer
percentage progress value for this step: from 0 to 100 }
<integer>0<integer>
<key>STATUS</key> { a replacement
text to display in progress dialog instead of original line }
<string>Zero</string>
</dict>
<dict>
<key>STRING</key>
<string>Warming
Up</string>
<key>VALUE</key>
<integer>10<integer>
<key>STATUS</key>
<string>Ten</string>
</dict>
</array>
</dict>
</dict>
B. The second mode is to detect the "counter" in some formed
string using grep substrings. The parenthesis in regular expression
mark substrings (aka sub groups). When designing your determinate
counter progress, you need to write the regular expression pattern with
subgroups extracting the interesting numbers and you need to tell OMC
which subgroup contains the counter, which contains the range end and,
optionally, which is the range start. You put subgroup indexes in
SUBSTRING_INDEX_FOR_COUNTER, SUBSTRING_INDEX_FOR_RANGE_END,
SUBSTRING_INDEX_FOR_RANGE_START. Some tools output numeric value in
known range (assumed but not explicitly printed out), in most cases it
will be a percentage value from 0 to 100. In this case you will not use
regular expression subgroups to tell OMC about the range start and end
and you will need to assign absolute values to RANGE_START and
RANGE_END. The defaults are 0 and 100 respectively so you don't even
have to bother with it when the tool outputs the percent value in 0 to
100 range.
<key>PROGRESS</key>
<dict>
<key>DETERMINATE_COUNTER</key>
<dict>
<key>REGULAR_EXPRESSION_MATCH</key> { a string to match
in output line with subgroups for counter numbers }
<string>Completed
task
(.+)
of
(.+)</string>
<key>STATUS</key>
<string>Task
$1
of
$2
done.</string> { a replacement text to display
in progress dialog instead of original line }
<key>SUPPRESS_NON_MATCHING_TEXT</key> { an option to not
display lines }
<false/> {default value}
<key>SUBSTRING_INDEX_FOR_COUNTER</key>
<integer>1<integer>
<key>SUBSTRING_INDEX_FOR_RANGE_END</key>
<integer>2<integer>
<key>SUBSTRING_INDEX_FOR_RANGE_START</key>
<integer>0<integer>
<key>IS_COUNTDOWN</key> { a variant where
range start is equal to first counter value }
<false/>
<key>RANGE_START</key>
<real>0</real>
{default value}
<key>RANGE_END</key>
<real>100</real>
{100 is default value for non-countdown case. 0 is default in countdown
case }
</dict>
</dict>
Cocoa custom dialog enhancements:
Added new messages to omc_dialog_control and new message
targets: omc_window, omc_application, omc_workspace
omc_select — brings dialog window to front
omc_terminate_ok — close dialog with OK message
omc_terminate_cancel — close dialog with
Cancel message
omc_resize — for dialog window or controls
omc_move — for dialog window or controls
omc_scroll — scroll a view within
NSScrollerView
omc_invoke — send an Obj-C message to control,
window, application or workspace
Example usage of new messages:
"$OMC_OMC_SUPPORT_PATH/omc_dialog_control" $OMC_NIB_DLG_GUID omc_window
omc_resize 600 200
"$OMC_OMC_SUPPORT_PATH/omc_dialog_control" $OMC_NIB_DLG_GUID omc_window
omc_move 50 30
"$OMC_OMC_SUPPORT_PATH/omc_dialog_control" $OMC_NIB_DLG_GUID omc_window
omc_terminate_ok
"$OMC_OMC_SUPPORT_PATH/omc_dialog_control" $OMC_NIB_DLG_GUID omc_window
omc_select
"$OMC_OMC_SUPPORT_PATH/omc_dialog_control" $OMC_NIB_DLG_GUID 1
omc_resize 160 22
"$OMC_OMC_SUPPORT_PATH/omc_dialog_control" $OMC_NIB_DLG_GUID 2
omc_scroll 0 0
The syntax for omc_invoke is that you specify parts of the method name
and arguments separated by spaces:
"$OMC_OMC_SUPPORT_PATH/omc_dialog_control" $OMC_NIB_DLG_GUID 1
omc_invoke someMethod: arg1 andMore: arg2.
This equivalent to calling ObjC:
[myObject1 someMethod:arg1 andMore:arg2];
In most cases you will deal with methods taking only one argument, for
example a command sent to NSTextField control with tag 1:
"$OMC_OMC_SUPPORT_PATH/omc_dialog_control" $OMC_NIB_DLG_GUID 1
omc_invoke setEditable: NO
is equivalent to calling:
[editField1 setEditable:NO];
OMC supports several types of arguments you can pass when calling ObjC
message. All types of numbers are supported (int, float, double, long
long, etc). Enum values are also supported but not by the enum name and
rather by its value - you need to find the actual integer value in
documentation or headers. BOOL values can be set as 1/0 or YES/NO or
true/false (case insensitive). Most common structures are also
supported:
NSRange = {location, length}
NSPoint = {x, y}
NSSize = {width, height}
NSRect = {{x, y}, {width, height}}
When passing a structure argument you pass a string of numbers
separated by commas but not spaces so in command line they appear as
one argument when invoking omc_dialog_control:
"$OMC_OMC_SUPPORT_PATH/omc_dialog_control" $OMC_NIB_DLG_GUID 2
omc_invoke setFrame: 20,20,200,200
equivalent to
[view2 setFrame: NSMakeRect(20, 20, 200, 200)]; //BTW, remember Cocoa
coordinate system starts at bottom-left and positive y goes up
omc_invoke also supports passing strings as arguments. They end up as
NSString * in method call. Unfortunately there is currently no way to
pass other types of Coca objects as arguments. So for example you
cannot pass NSColor or NSFont objects. With some extra work this
limitation might be overcome if there is enough interest in the
omc_invoke feature.
If you want to use nil for calls which take optional objects you can do
it using omc_nil special word, for example:
"$OMC_OMC_SUPPORT_PATH/omc_dialog_control" $OMC_NIB_DLG_GUID 3
omc_invoke performClick: omc_nil
omc_invoke messages may be directed not only to controls in the dialog
but also to the dialog window itself (omc_window, NSWindow), the host
application (omc_application, NSApplication), or user workspace shared
object (omc_workspace, NSWorkspace). The last target handles messages
that affect the system or Finder.
omc_invoke is very powerful but also dangerous: you can easily crash
the host app if you call some method incorrectly. You may also cause
leaks if you call a method that creates some object. In general
omc_invoke method ignores the return value from the call. It would be
hard to return this value to sender because the message travels
asynchronously across processes. So it really does not make sense to
call any "getter" methods but rather some "setter" methods.
Additional limitation is that you can only call instance methods of
supported targets (denoted with -), not class methods (denoted with +).
|
What is new in
version
2.9.1 of command description format (OMC v. 2.0 final) |
|
OMC 2.0 Abracode.framework paths:
OMC 2.0 features separation of common code and resources into
Abracode.framework. There are 2 new special words for for accessing
resources and helper applications:
__OMC_SUPPORT_PATH__ /
$OMC_OMC_SUPPORT_PATH =
Abracode.framework/Support/
__OMC_RESOURCES_PATH__ /
$OMC_OMC_RESOURCES_PATH
= Abracode.framework/Resources/
More information in
Special Words section.
Cocoa nib dialogs support:
Starting with version OMC 2.0 you can create custom dialogs using Cocoa
nibs. You need to specify
IS_COCOA key
in
NIB_DIALOG subdictionary
:
<key>NIB_DIALOG</key>
<dict>
<key>IS_COCOA</key>
<true/>
</dict>
More information about it is in
Nib Dialogs
section in
Cocoa Dialogs.
|
What is new in version
2.9 of command description format (OMC v. 1.9 final) |
|
STANDARD_INPUT_PIPE
Allows piping of context information to a tool executed in
COMMAND. The tool needs to be ready
to accept piped input.
STANDARD_INPUT_PIPE
tag takes array of objects and sends it to whatever open pipe is ready
to take it. Special objects are allowed in the input pipe but only the
inline flavor (__XXX__ style) , not environment variable ($OMC_XXX
style). It works only with popen family of execution methods
(including exe_shell_script).
The advantages of this are:
- no escaping issues and no parsing on shell side
- small script may take big text objects without making the huge script
with in-place (as it is the case when classic
__OBJ_TEXT__
is used)
- secure transport of passwords (to sudo or similar)
Below is an example code printing lines containing word "hello" from
selected text. Previously you could try to do something like this with:
echo "
__OBJ_TEXT__" | grep hello. Of
course you would run into escaping and line break issues
. With the new feature, you can write:
<key>COMMAND</key>
<array>
<string>grep hello
2>&1
</string>
</array>
<key>STANDARD_INPUT_PIPE</key>
<array>
<string>__OBJ_TEXT__</string>
</array>
<key>TEXT_REPLACE_OPTION</key>
<string>txt_replace_cr_with_lf</string>
<key>EXECUTION_MODE</key>
<string>exe_popen_with_output_window</string>
Environment variables export
Special words can now be exported as environment variables in
popen-based execution modes. It does not work for system() or
AppleScript execution modes.
The naming convention is that inline special objects which take form of
__XXX__ now become OMC_XXX for environment variables, for example
__OBJ_PATH__ becomes
OMC_OBJ_PATH and can be used in scripts as "
$OMC_OBJ_PATH" or
"
${OMC_OBJ_PATH}".
More information in special objects section on
environment variables:
POPEN_SHELL
POPEN_SHELL allows
customization of the shell (and flags) executed by popen. The default
popen() shell is "sh" and is invoked as:
/bin/sh -c <command>
POPEN_SHELL key takes an array of strings. First string is the path to
the shell, next strings are shell command-line options. As the last
argument, OMC will append the command string itself (you don't include
it in the array).
For example, if you want to invoke tcsh shell, you may write:
<dict>
<key>COMMAND</key>
<array>
<string>env
</string>
</array>
<key>EXECUTION_MODE</key>
<string>exe_popen_with_output_window</string>
<key>POPEN_SHELL</key>
<array>
<string>/bin/tcsh
</string>
<string>-c
</string>
</array>
</dict>
Activation by context data match
New activation option: checking file name, path or selected text for a
match. Now you can create commands that are visible when file name
includes some text or path matches some predefined path. This may also
work on text content (so you can have commands which show up only on
URL text selection for example). Regular expression matching is not
Unicode-aware. New activation mode XML tags:
<key>ACTIVATION_OBJECT_STRING_MATCH</key>
<dict>
<key>MATCH_STRING</key>
<string>Hello
</string> {required parameter}
<key>MATCH_METHOD</key>
<string>match_exact
</string> {default value}
<string>match_contains
</string>
<string>match_regular_expression
</string>
<key>FILE_OPTIONS</key>
<string>match_file_name
</string> {default value}
<string>match_file_path
</string>
<key>COMPARE_CASE_INSENSITIVE</key>
<false/> {default
value}
<true/>
</dict>
|
What is new in version
2.8 of command description format (OMC v. 1.8 final) |
|
DataBrowser control support in nib dialogs:
The new control support and new special word: __NIB_TABLE_NNN_COLUMN_MMM_VALUE__
See Nib dialogs
section for details.
Dynamic menu name:
NAME upgraded to array of
strings with special objects to allow dynamic names:
<key>NAME</key>
<array>
<string>Selected object
name: </string>
<string>__OBJ_NAME__</string>
</array>
Both forms of NAME key are
supported: simple string for static menu name and array of strings for
dynamic name.
NAME_PLURAL key defined so the
menu name may be different when more than one file is selected.
<key>NAME</key>
<string>One Object Selected</string>
<key>NAME_PLURAL</key>
<string>Multiple Objects Selected</string>
Key NAME is required, NAME_PLURAL is optional. NAME_PLURAL
must be a string. It is not dynamic.
Progress dialog:
Displays indeterminate progress bar for commands which do not operate
on objects, process only one object or process objects together. If
more than one object is processed separately, each ending task advances
the progress bar. Progress dialog displays last line of the the task
output as a status text under the progress bar.
<key>PROGRESS</key>
<dict>
<key>TITLE</key>
<string>Task in
progress</string>
<key>DELAY</key>
<real>2.0</real>
</dict>
DELAY key with time in seconds
may be used to defer the progress dialog
display — the dialog will not show up if the task ends before the
specified time passes. TITLE
is the window title. If not specified,
command name is used.
Task end notification:
Many tasks execute asynchronously in OMC 1.8 so the end notification
might be useful:
<key>END_NOTIFICATION</key>
<dict>
<key>TITLE</key>
<string>Task End</string>
<key>MESSAGE</key>
<string>This task
has ended</string>
</dict>
TITLE is the window title and
is optional. If keyword does not exist, command name is used for window
title. MESSAGE
is optional as well. If the keyword does not exist, the last status
line from finished task output is used.
exe_silent_system does not
produce any output text so it cannot be used this way.
Nib dialog termination handlers:
Called after dialog is closed but before returning to command
which invoked it. 2 types of termination handlers: one for OK and the
other for Cancel or window close. Default IDs are 'end!'
for
OK
and
'cnc!' for Cancel. Termination command IDs
can be overridden with the
following:
<key>NIB_DIALOG</key>
<dict>
<key>END_OK_SUBCOMMAND_ID</key>
<string>end!</string>
<key>END_CANCEL_SUBCOMMAND_ID</key>
<string>cnc!</string>
</dict>
Non-blocking nib dialog:
<key>NIB_DIALOG</key>
<dict>
<key>IS_BLOCKING</key>
<false/>
</dict>
The default behavior is blocking (modal) dialog and this is how it was
implemented in previous OMC versions. In this mode the dialog blocks
the main thread of host application, running its own modal loop, until
it is dismissed (closed, canceled, OK-eyed) and then the main command
which invoked the dialog is executed (most likely using some control
values from the dialog).
In the new, non-blocking mode, the dialog does not run the modal loop
and returns the control to host application immediately. The side
effect is that the command which invoked the dialog executes
immediately — in this case you will probably want to leave the main
command empty and perform the task you want in subcommand invoked when
closing the dialog. OMC nib dialog defines 2 default termination
handlers: 'end!'
when dialog is OK-eyed and 'cnc!' when dialog is
canceled. In most cases you will want to create a subcommand with
'end!' ID and
perform your closing task here. Those IDs can be
overridden with END_OK_SUBCOMMAND_ID
and END_CANCEL_SUBCOMMAND_ID
tags.
Showing invisible files and folders
in Navigation dialogs:
<key>CHOOSE_FILE_DIALOG</key>
<dict>
<key>SHOW_INVISIBLE_ITEMS</key>
<true/>
</dict>
This option is available for SAVE_AS_DIALOG,
CHOOSE_FILE_DIALOG,
CHOOSE_FOLDER_DIALOG, CHOOSE_OBJECT_DIALOG
Setting default location for navigation dialogs:
<key>CHOOSE_FOLDER_DIALOG</key>
<dict>
<key>MESSAGE</key>
<string>Select Folder</string>
<key>DEFAULT_LOCATION</key>
<array>
<string>__OBJ_PARENT_PATH__</string>
</array>
</dict>
Inline special words allowed. Tilde in front of the path resolved as
user's
home folder. Example above opens navigation dialog in parent folder of
control-clicked object.
External bundle special word:
__MY_EXTERNAL_BUNDLE_PATH__
special object pointing to path defined by EXTERNAL_BUNDLE_PATH tag (redundant,
but much needed for portability)
<key>COMMAND</key>
<array>
<string>echo
</string>
<string>__MY_EXTERNAL_BUNDLE_PATH__</string>
</array>
<key>EXTERNAL_BUNDLE_PATH</key>
<string>~/Library/Application
Support/OnMyCommand/My
Command.omc</string>
If explicit path EXTERNAL_BUNDLE_PATH
in command description is not specified, __MY_EXTERNAL_BUNDLE_PATH__ resolves to default external bundle location which
is: /Users/you/Library/Application
Support/OnMyCommand/CurrentCommandName.omc where "CurrentCommandName"
is the name of the command (and menu item). This will allow easy access
to private command resources (nibs, images, scripts, etc.). The net
result is that if you place a ".omc" bundle of the same name as your
command in ~/LibraryApplication Support/OnMyCommand/, it will be found
automatically.
DropletBuilder is able to install the .omc bundle for you in default
location and copy the command from "Command.plist" to your main list of
commands. Just drag the .omc bundle on the DropletBuilder icon. This
way the self-contained command with resources (images, nibs, external
scripts, etc.) may be distributed as .omc bundle and is easy to install.
Multiple objects sorting:
<key>MULTIPLE_OBJECT_SETTINGS</key>
<dict>
<key>SORT_METHOD</key>
<string>sort_by_name</string>
<key>SORT_OPTIONS</key>
<dict>
<key>SORT_ASCENDING</key>
<true/>
<key>COMPARE_CASE_INSENSITIVE</key>
<true/>
<key>COMPARE_NONLITERAL</key>
<true/>
<key>COMPARE_LOCALIZED</key>
<true/>
<key>COMPARE_NUMERICAL</key>
<true/>
</dict>
</dict>
SORT_METHOD: sort_none
(default), sort_by_name
SORT_OPTIONS (only valid if SORT_METHOD is different from
sort_none):
SORT_ASCENDING - default true: a-z, 0-9 , if false:
z-a, 9-0
All other options are corresponding to
CFStringCompareFlags. See description in Apple
documentation.
COMPARE_CASE_INSENSITIVE
— if true: Finder-like. Default is false: case sensitive, Unix-like
COMPARE_NONLITERAL
— default is false: literal
COMPARE_LOCALIZED
— default is false: not locale-aware
COMPARE_NUMERICAL
— if true: numeric values compared so "version 2" < "version 2.5",
default is false: alphabetical
Additional positioning method for
output window:
FRACT_POSITION_LEFT and FRACT_POSITION_TOP are the new
positioning methods for output window. The value is a floating
point number between 0.0 and 1.0 and describes approximate
position on screen. 0.0 is top or left, 1.0 is right or bottom, 0.5 is
center, etc. This method places the center of the output window in
desired location but also makes sure the whole window is visible on the
screen (placing window at {0.0, 0.0} will not place its center in top
left corner of the screen but rather places top left corner of the
window there). This method takes menu bar and dock into account so the
window is placed correctly within available area.
For example, positioning a window about 1/3 of the screen height from
the top and 2/3 of the screen width from the left:
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>FRACT_POSITION_LEFT</key>
<real>0.66</real>
<key>FRACT_POSITION_TOP</key>
<real>0.33</real>
<key>WINDOW_POSITION</key>
<string>absolute</string>
</dict>
Task manager settings:
<key>MAX_PARALLEL_TASK_COUNT</key>
<integer>1</integer>
If tag is not present the default value is 0. 0 is a special
value and it means the maximum number of concurrent tasks depends on
the number of CPUs (or cores) in your computer and the maximum task
count is calculated as 2 x CPU count. So single processor, single core
will run 2 tasks, single processor dual core machine will run 4 tasks
at a time. If you know that the process you are going to start is very
processor-intensive, you will probably want to set this value to 1 so
there will be only one task running at a time and if there are more
objects to be processed, they will be scheduled one after another.
This option is under "Misc" tab in OMCEdit.
Statically assigned next command id:
In previous versions of OMC the next command could be set using
command line tool: omc_next_command. In many cases, however, it may be
easier to assign the next command statically in command description
itself. In this case the next command will be executed unconditionally,
provided the previous command succeeded and was not canceled. The new
tag is:
<key>NEXT_COMMAND_ID</key>
<string>NeXT</string>
If you use both statically assigned next command id and dynamic one,
assigned at runtime with omc_next_command tool, the dynamic id is used.
This way you can override static assignment if needed.
This option is at the bottom of the main edit window in OMCEdit.
New ESCAPE_SPECIAL_CHARS option:
esc_with_percent_all
The behavior of previously available esc_with_percent
is that it escapes only illegal URL chars (as defined by RFC 2396). The
new method escapes all illegal URL chars plus legal non-alphanumeric
chars. The additional escaped characters are: !$&'()*+,-./:;=?@_~.
Those chars need to be escaped in order to avoid conflicts in shell
execution. The end result is that only A-Z, a-z, 0-9 are left
unescaped.
iTerm startup shell support:
<key>ITERM_SHELL_PATH</key>
<string>/bin/bash</string>
|
What is new in
version 2.7.2 of command description format (OMC v. 1.7.2 final) |
|
Dynamic command ids in nib dialog controls
omc_dialog_control now allows you to change
command ids of nib dialog controls on the fly. This way a button in a
dialog can perform different actions depending on other controls state.
Suppose you have an "Run" button in dialog, now depending on popup menu
choice in this dialog it may execute different commands because we are
able to change the command ID of the "Run" button when the popup menu
choice changes. This can be done by invoking omc_dialog_control with
new option: omc_set_command_id and provide four character code as a
command id, for example:
omc_dialog_control __NIB_DLG_GUID__
1 omc_set_command_id "Exec"
|
What is new in
version 2.7.1 of command description format (OMC v. 1.7.1 final) |
|
Dialog autoclose on success only
New tag is introduced for output windows which use autoclose timeout:
AUTO_CLOSE_ON_SUCCESS_ONLY. It is a Boolean value with "true" as
default.
In most cases you will probably prefer to autoclose result window when
the task finished successfully but you'd rather want it to stay open in
case of error. This is the default behavior now, you don't have to add
this tag if you want it, but if you really prefer window autoclose
regardless of result, you need to set the value to false.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>AUTO_CLOSE_TIMEOUT</key>
<real>1.0</real>
<key>AUTO_CLOSE_ON_SUCCESS_ONLY</key>
<true/>
</dict>
You can test it with the following commands:
echo "This should autoclose"
echo "This should not autoclose"; exit 1
New ESCAPE_SPECIAL_CHARS option:
esc_wrap_with_single_quotes_for_shell
This is a special quoting method for use with shell. The behavior is to
wrap the text with single quotes and work around the problem of any
possible single quote inside. The text:
Don't do it
will become wrapped as:
'Don'\'' do it'
omc_list_append_items_from_file & omc_list_append_items_from_stdin
omc_dialog_control gets two new methods for
adding menu items to popup menus: reading from file or standard
input/pipe. Each non-empty line is treated as one item to add. The
stdin method is especially useful for accepting piped output from awk,
sed, grep, ls, cat, plister or other tools.
Example usage:
omc_dialog_control __NIB_DLG_GUID__
4 omc_list_append_items_from_file menu_items.txt
ls | omc_dialog_control __NIB_DLG_GUID__
4 omc_list_append_items_from_stdin
|
What is new in version
2.7 of command description format (OMC v. 1.7 final) |
|
Dialog autoclose timeout
Timeout is in seconds. Negative values mean "don't autoclose". Default
value when tag not present: -1.0.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>AUTO_CLOSE_TIMEOUT</key>
<real>2.0</real>
</dict>
Default "save as" filename
</key>SAVE_AS_DIALOG</key>
<dict>
<key>DEFAULT_FILE_NAME</key>
<array>
<string>__OBJ_NAME_NO_EXTENSION__</string>
<string>.txt</string>
</array>
</dict>
DEFAULT_VALUE
Default text for input dialog is now an array of strings instead of
single string and resolves inline special objects
DEFAULT_VALUE key deprecates old DEFAULT key:
<key>INPUT_DIALOG</key>
<dict>
<key>DEFAULT_VALUE</key>
<array>
<string>__OBJ_NAME_NO_EXTENSION__</string>
<string>.txt</string>
</array>
</dict>
Two new special objects:
__FRONT_APPLICATION_NAME__ Front
application name.
__FRONT_PROCESS_ID__ This is a Unix
process ID of the front application as obtained by running ps in
Terminal.
Version requirements
If the Mac OS X or OMC version requirement is not met, a warning dialog
will be displayed.
<key>REQUIRED_OMC_VERSION</key>
<string>1.7</string>
OMC is backward compatible so this means: minimum OMC version required
to run this command. Default value: "1.3.1"
<key>REQUIRED_MAC_OS_MIN_VERSION</key>
<string>10.2</string>
Minimum Mac OS X version to run the command. Default value "10.1"
<key>REQUIRED_MAC_OS_MAX_VERSION</key>
<string>10.2.8</string>
Last Mac OS X version supporting given feature. The default value is
infinite. Don't put if not needed.
Categories
This keyword is for organizing commands into logical groups. Does not
affect the command execution.
<key>CATEGORIES</key>
<array>
<string>Clipboard</string>
<string>Command Line</string>
<string>Selection</string>
</array>
The submenu name is now a path, for example:
<key>SUBMENU_NAME</key>
<string>/Disk Image/Create</string>
The submenu path should start with "/". If it does not start with "/",
it is added by OMC.
If the submenu name is "/" - it is root. If the submenu name is ".." it
is root too.
If the keyword is missing, the default submenu is "On My Command". The
trailing "/" is ignored.
The key to disable command:
<key>DISABLED</key>
<true/>
The default value is false.
omc_list_append_items & omc_list_remove_all
omc_dialog_control gains new feature: ability
to populate lists for some controls. Currently it works for popup
button menu and combo box menu only.
Special value of omc_list_append_items tells omc_dialog_control that
there is variable length of arguments following. For example, if you
have a popup button with ID 4 and you want to add items to its menu,
you can do it like this:
omc_dialog_control __NIB_DLG_GUID__
4 omc_list_append_items "Item 1" "Item 2" "Item 3"
To remove items from list:
omc_dialog_control __NIB_DLG_GUID__
4 omc_list_remove_all
omc_live_update (obsolete)
omc_live_update is obsolete in version OMC 1.8
and higher.
It used to be a special parameter to tell remote dialog to update
control value immediately.
In version 1.8 omc_dialog_control always
tries to establish direct communication with the dialog and only if it
fails, the data is saved to a file and the dialog picks it after the
subcommand execution is finished.
|
What is new in
version 2.7b1 of command description format (OMC v. 1.7b1) |
|
Send Task to Background Application (OMCDeputy)
<key>SEND_TASK_TO_BACKGROUND_APP</key>
<true/>
Command is executed by OMCDeputy background app.
Custom output windows with shape and background defined by PNG
image.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>WINDOW_TYPE</key>
<string>custom</string>
<key>CUSTOM_WINDOW_PNG_IMAGE</key>
<string>Bezel.png</string>
</dict>
Textbox. Defines where the text should be placed in custom
window.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>CUSTOM_TEXTBOX_POSITION_TOP</key>
<integer>20</integer>
<key>CUSTOM_TEXTBOX_POSITION_LEFT</key>
<integer>20</integer>
<key>CUSTOM_TEXTBOX_WIDTH</key>
<integer>100</integer>
<key>CUSTOM_TEXTBOX_HEIGHT</key>
<integer>50</integer>
</dict>
Closebox. Defines the rectangle where mouse click closes the
window. Only for custom windows.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>CUSTOM_CLOSEBOX_POSITION_TOP</key>
<integer>0</integer>
<key>CUSTOM_CLOSEBOX_POSITION_LEFT</key>
<integer>0</integer>
<key>CUSTOM_CLOSEBOX_WIDTH</key>
<integer>16</integer>
<key>CUSTOM_CLOSEBOX_HEIGHT</key>
<integer>16</integer>
</dict>
Fade in and fade out for output windows. Can be used with any
type of window.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>WINDOW_OPEN_FADE_IN</key>
<true/>
<key>WINDOW_CLOSE_FADE_OUT</key>
<true/>
</dict>
Subcommands
Subcommands look just like regular commands but they have a unique four
character identifier: COMMAND_ID. Main command should not have
this tag or use 'top!' value. Subcommands must
have the same name as a
main command. Subcommands are not displayed in the contextual menu
because they are treated as a part of one command group. OMCEdit
displays subcommands in italic font.
<key>COMMAND_ID</key>
<string>Subc</string>
Subcommands can be triggered by controls in nib dialog or with omc_next_command. More information in
"Subcommands" section.
Next Command
Next command can be scheduled with omc_next_command
CLI tool so your script can decide at runtime if another subcommand
should follow. More information in "Next Command" section.
Nib Dialog Enhancements
omc_dialog_control command line tool to set
the control value. You may also enable/disable and show/hide controls.
More controls supported including pictures, icons, bevel buttons,
static text, progress controls, tab control. Controls can trigger
subcommands if command id is assigned in Interface Builder.
Icons & pictures. Custom icons & pictures can be displayed in
nib dialogs.
New special object: __NIB_DLG_GUID__. This
special word is replaced dynamically with current dialog unique id. It
is used with omc_dialog_control.
New keyword for nib dialog group: INIT_SUBCOMMAND_ID to use
initialization subcommand to set control values before the dialog shows
up.
<key>NIB_DIALOG</key>
<dict>
<key>NIB_NAME</key>
<string>dialog</string>
<key>WINDOW_NAME</key>
<string>Dialog</string>
<key>INIT_SUBCOMMAND_ID</key>
<string>ini!</string>
</dict>
External bundles for putting nibs and custom window PNG images
It is useful for contextual menu items using nib dialogs - you do not
have to put the nib inside OnMyCommandCM.plugin bundle.
<key>EXTERNAL_BUNDLE_PATH</key>
<string>/Users/Shared/OMC/Extension.omc</string>
The path to bundle should be absolute. You can use /Users/Shared/OMC/
folder for this. /Users/Shared/ is a very good place to put things and
it is often overlooked and not used by most OS X users. The advantage
is that everybody has a read-write permissions to this folder.
Option to replace line endings for __OBJ_TEXT__:
<key>TEXT_REPLACE_OPTION</key>
<string>txt_replace_none</string>
<string>txt_replace_lf_with_cr</string>
<string>txt_replace_cr_with_lf</string>
|
What is new in
version 2.6.1 of command description format (OMC v. 1.6.1 final) |
|
New EXECUTION_MODE options:
exe_shell_script
exe_shell_script_with_output_window
Full support for shell scripts. You do not need to put your shell
script in a separate file - just type the code in the body of your
command description. At the beginning of each shell script you need to
specify which shell to use. For example:
#!/bin/sh
Finally you can use perl, python or other scripting language directly
in your command. This execution mode creates a temporary script file:
/tmp/OMC/OMC_temp_script_XXX
and then "exec /tmp/OMC/OMC_temp_script_XXX" is called.
When editing the command manually, please make sure you have proper
line endings in your script. You need Unix linefeeds (LFs) instead of
Mac carriage returns (CRs).
New activation option to tell in which applications the command
should or must not show:
ACTIVATE_ONLY_IN or NEVER_ACTIVE_IN. Those 2 options are
logically exclusive. You can use one or the other but not both in one
command. You provide an array of application names like this:
<key>ACTIVATE_ONLY_IN</key>
<array>
<string>TextEdit</string>
<string>BBEdit
Lite</string>
</array>
The name of the application is what you see in menu bar when you launch
given application, not the name of the bundle (which may be different).
Nib Dialogs.
You can build a dialog in Interface Builder and access control
values via:
__NIB_DIALOG_CONTROL_N_VALUE__
"N" has to be replaced with control id number, for example __NIB_DIALOG_CONTROL_3_VALUE__
There are certain predefined rules how to design such dialog and which
controls are supported but basically you are able to use a completely
visual environment of Interface Builder to construct a dialog
and there is no limitation on the number of controls you want/need to
use. It requires no programming just putting together some resources to
obtain a very nice GUI for some script. The nib dialog settings have to
be explicitly present in command description to load the dialog. Two
parameters are required: NIB_NAME & WINDOW_NAME. For example:
<key>NIB_DIALOG</key>
<dict>
<key>NIB_NAME</key>
<string>mydialog</string>
<key>WINDOW_NAME</key>
<string>Dialog</string>
</dict>
Detailed information in "Nib dialogs" section of this manual.
|
What is new in version
2.6 of command description format (OMC v. 1.6 final) |
|
New EXECUTION_MODE options:
exe_popen_with_output_window
exe_applescript
exe_applescript_with_output_window
AppleScript is natively supported in OMC 1.6: you do not have to use
call osascript to execute AppleScript code,
just type it in command description and choose appropriate execution
mode.
Output window displays the result of command execution. Various output
window settings can be controlled in OUTPUT_WINDOW_SETTINGS
group described in "Output window settings" section of this document.
New ESCAPE_SPECIAL_CHARS option:
esc_for_applescript
Escape objects inserted into AppleScript command.
PASTE_AFTER_EXECUTION instruction. Tells OMC to paste clipboard
content in current context after command execution. Makes sense in text
context with pbcopy or AppleScript's set the clipboard to...
New objects:
__MY_BUNDLE_PATH__
__MY_HOST_BUNDLE_PATH__
These new words do not make much sense for contextual menus because
they point to OnMyCommandCM.plugin or host application but they might
be extremely useful for droplets because you may put things in bundle
resources and access them with __MY_HOST_BUNDLE_PATH__/Contents/Resources/
|
What is new in
version 2.5.4 of command description (OMC v. 1.5.4 final) |
|
Extensive reorganization of inline special words. The new naming scheme
is as
follows:
- context object words start with __OBJ_XXX__
(as it was before)
- dialog words start with __DLG_XXX__.
As a result the following existing words have been renamed:
__INPUT_TEXT__ --> __DLG_INPUT_TEXT__
__SAVE_AS_PATH__ --> __DLG_SAVE_AS_PATH__
__SAVE_AS_PARENT_PATH__ --> __DLG_SAVE_AS_PARENT_PATH__
__SAVE_AS_FILE_NAME__ --> __DLG_SAVE_AS_NAME__
The old style names are still supported but are no longer recommended. __PASSWORD__ is deprecated and has not been renamed
according to the new convention.
Three new Navigation Services dialogs have been added:
- choose file invoked by special word __DLG_CHOOSE_FILE_PATH__
& family
- choose folder invoked by special word__DLG_CHOOSE_FOLDER_PATH__
& family
- choose object (file or folder) invoked by special word __DLG_CHOOSE_OBJECT_PATH__ & family
Each navigation dialog object has new flavors: NAME_NO_EXTENSION and
EXTENSION_ONLY to match combinations available for context file objects
(__OBJ_XXX__)
Navigation services dialogs currently support only one option: text
message appearing on top of the dialog. If not defined, the dialog will
be displayed without any message text. For example, the message text
for "save as" dialog can be defined as follows:
<key>SAVE_AS_DIALOG</key>
<dict>
<key>MESSAGE</key>
<string>Save the new file
as:</string>
</dict>
__OBJ_PATH_NO_EXTENSION__ is deprecated
(although still supported) because it can be constructed easily from __OBJ_PARENT_PATH__ + __OBJ_NAME_NO_EXTENSION__
and redundant objects may create more confusion.
New execution modes have been added including basic support for iTerm
and silent execution with "system()" call. The old style silent
execution was done with "popen()" call. To learn more about popen &
system, open your terminal and type "man popen" and "man system".
New EXECUTION_MODE options:
exe_silent_popen
exe_silent_system
exe_terminal
exe_iterm
Old style exe_silent is still supported and
is equivalent to exe_silent_popen but no
longer recommended.
|
What is new in
version 2.5.3 of command description (OMC v. 1.5.3 final) |
|
Added new "Save As" dialog. The dialog has no additional settings
(yet). It is invoked when one of the following special words is
encountered in command text: __SAVE_AS_PATH__,
__SAVE_AS_PARENT_PATH__ or __SAVE_AS_FILE_NAME__.
For INPUT_DIALOG a new INPUT_TYPE is added: input_combo_box. The dialog is shown with edit
field and popup choice. Handy for pre-defined items but allows entering
custom value.
|
What is new in
version 2.5.2 of command description (OMC v. 1.4.3 final) |
|
Added new keyword: REFRESH_PATH for refreshing objects in
Finder. A common problem was that when some file or folder attribute
was changed by a command (file type and creator for example), Finder
was not refreshing the object. The new keyword takes a path to object
which needs refreshing. The path is an array of strings and can be
composed of the same elements which are used for main command
description (__OBJ_XXX__)
|
What is new in
version 2.5.1 of command description (OMC v. 1.4.2 final) |
|
Added 2 new options for ACTIVATION_MODE: act_folder_not_finder_window
and act_file_or_folder_not_finder_window.
The new activation modes are similar to corresponding act_folder and act_file_or_folder
options but exclude a context when user ctrl-clicks on a Desktop or
open Finder window. These options are useful for "dangerous" commands
like those deleting folders with their content. This is a safeguard
against accidental deleting of whole desktop folder!
|
What is new in version
2.5 of command description (OMC v. 1.4 final) |
|
Input dialog. Special word __INPUT_TEXT__ in
command description invokes a dialog where you can input text. Three
input methods are currently supported: clear text, password text, popup
menu choice. There is a new description format for customizing the
input dialog. Look below in section "Input dialog" for more information.
__PASSWORD__ keyword is deprecated now since
the same effect can be achieved with __INPUT_TEXT__
and proper dialog description. Please change your command descriptions.
VERSION keyword added for keeping track of incremental updates to
commands.
|
What is new in version
2.4 of command description (OMC v. 1.3.1 final) |
|
Version 1.3.1b1 was supposed to be feature complete, but...
This version brings new special word: __PASSWORD__.
When
it
is
encountered in command description, a password dialog is
displayed before execution. Useful for sudo commands or protected http
or ftp access. The second new feature is enhanced warning support with
two new keywords: WARNING_EXECUTE and WARNING_CANCEL.
These keywords define button names in warning dialog for further
customization.
|
What is new in version
2.3 of command description (OMC v. 1.3.1b1) |
|
Implemented __OBJ_COMMON_PARENT_PATH__ and __OBJ_PATH_RELATIVE_TO_COMMON_PARENT__ (finally).
Added WARNING keyword which may be provided for potentially
destructive commands. Added SUBMENU_NAME keyword so you may
place commands in submenu of your choice. This version is considered
feature complete and enters beta testing phase.
|
What is new in
version 2.2.1 of command description (OMC v. 1.3.1a9) |
|
Changes to ESCAPE_SPECIAL_CHARS behavior. Previously esc_with_backslash was never applied to __OBJ_TEXT__. As it has been demonstrated by some
code examples (thanks to Daniel A. Shockley) escaping text with
backslash is needed and desired in some cases. What's more, a problem
of text with multiple lines emerged so CR and LF characters have been
added to a list of characters being escaped with backslash. A subtle
but significant change is in default behavior (when ESCAPE_SPECIAL_CHARS
keyword is not present). Previously the default value for path objects
was esc_with_backslash while default value
for __OBJ_TEXT__ was esc_none.
Now
it
has
changed: the default value in both cases is esc_with_backslash
and it may affect already
existing commands. The general rule of the thumb is not to use any
escapes — explicitly set to esc_none
— when you enclose a path or text in quotes. If you pass raw
text or path, you should escape special chars, otherwise in some cases
your command will not work or its behavior will be undetermined. Do you
remember infamous iTunes 2.0 installer? They used rm -rf with non
escaped path to delete old version of iTunes. However if you had 2
disks: one named HD and the other named HD X (with space inside) you
ended up with your whole HD partition erased. This is the worst case
scenario but it is a good example. Stay alert.
|
What is new in version
2.2 of command description (OMC v. 1.3.1a8 private seed) |
|
Added two new keywords: TERM_OPEN_NEW_SESSION and TERM_BRING_TO_FRONT.
These
keywords
take
Boolean values and determine Terminal behavior for
a command. These keywords are ignored for silent execution.
|
What is new in
version 2.1.1 of command description (OMC v. 1.3.1a7) |
|
Implemented escaping special characters with percent for Internet URLs.
See description of ESCAPE_SPECIAL_CHARS for more details.
|
What is new in version
2.1 of command description (OMC v. 1.3.1a6) |
|
Added ACTIVATION_FILE_TYPES and ACTIVATION_EXTENSIONS
— or actually activated them, since 2.0 draft already had these
keywords.
Added support for treating multiple objects together — a lot is
done, but still in progress. Thanks to Mike Fischer for ideas on how to
make things more complicated :-) ... and powerful.
|
What is new in version
2.0 of command description (OMC v. 1.3.1a3) |
|
Command description syntax has been changed with version 1.3.1a3 of
OnMyCommand. Initial syntax was not not designed very well (in fact it
was not designed at all but done ad hoc). The new version is simpler,
more flexible and more powerful - it will be easier to develop and add
new features.
Unfortunately version 2.0 of command description syntax is not
compatible with version 1.0. You need to re-edit your commands. Sorry
about this but in long term it will be worthy to have a better
foundation to build upon and it also opens new possibilities for
complicated commands right now.
The main difference in version 2.0 is that command is composed of an
array of strings which will be glued together on execution. There are
also several pre-defined inline special words with a naming scheme of __OBJ_XXX__. These inline special words will be
replaced
with proper text on execution. Look below for more detailed description
of what is currently available.
|
Quick
Start |
|
Here is the quick manual how to edit command descriptions. Take one
command description as an example:
<dict>
<key>ACTIVATION_EXTENSIONS</key>
<array>
<string>gz</string>
<string>tgz</string>
</array>
<key>ACTIVATION_MODE</key>
<string>act_file</string>
<key>COMMAND</key>
<array>
<string>gzip
-d
</string>
<string>__OBJ_PATH__</string>
</array>
<key>EXECUTION_MODE</key>
<string>exe_silent_popen</string>
<key>NAME</key>
<string>Uncompress with gzip</string>
<key>NOTES</key>
<string>Look Ma, no Terminal for
uncompressing with GZip!</string>
<key>VERSION</key>
<integer>1</integer>
</dict>
|
The result will be as follows:
1. The name displayed in menu will be Uncompress with gzip.
2. The command executed will be gzip -d path/to/clicked/file.gz.
3. Special characters in inserted path will be escaped with backslash
(default behavior).
4. The command will be executed "silently", Terminal.app will not be
opened (controlled by EXECUTION_MODE).
5. The command will be available only when a file is control-clicked
(ACTIVATION_MODE).
6. The command will be available only when a file with "gz" or "tgz"
extension is control-clicked.
7. NOTES key is ignored by plugin but may contain additional
information (e.g. about requirements for given command or info about
the author).
8. VERSION key is ignored by plugin itself but is useful for OMCEdit.
9. This example does not demonstrate all possible keywords - it is just
a quick start guide.
|
Command Description Keys and Values |
|
|
Name of the command appearing
in menu |
<key>NAME</key>
<string>My Command</string>
This key is required.
Example:
<key>NAME</key>
<string>Compress with gzip</string>
|
New in 1.8:
NAME is upgraded to array of
strings with inline special objects to allow dynamic names:
<key>NAME</key>
<array>
<string>Selected object
name: </string>
<string>__OBJ_NAME__</string>
</array>
|
Both forms of
NAME key are
supported: simple string for static menu name and array of strings for
dynamic name.
NAME_PLURAL key defined so the
menu name may be different when more than one file is selected.
<key>NAME</key>
<string>One Object Selected</string>
<key>NAME_PLURAL</key>
<string>Multiple Objects Selected</string>
|
Key
NAME is required,
NAME_PLURAL is optional. NAME_PLURAL
must be a string. It is not dynamic.
|
Command itself |
<key>COMMAND</key>
<array>
<string></string>
</array>
Command is an array of strings which will be combined together before
execution. There are several predefined inline special strings which
will be
replaced by proper data before execution.
This key is required.
Example:
<key>COMMAND</key>
<array>
<string>gzip </string>
<string>__OBJ_PATH__</string>
</array>
|
|
Special Words |
Inline special words are in form of __SOMETHING_HERE__. There are 2
underscores at the beginning and 2 at the end. Spaces are not allowed
(substituted with underscore) and the word is all capital letters.
Please note that any inline special object in the body of command must
be the
only string in single <string></string> element and cannot contain
preceding or trailing spaces. You cannot compose a command like:
<string>cd __OBJ_PATH__; ls
-la</string>
What you should do is to split the command so __OBJ_PATH__
is a single element:
<string>cd </string>
<string>__OBJ_PATH__</string>
<string>; ls -la</string>
However, if you are using OMCEdit, you enter the command with
inline special words in one line and the application does the dirty
work of
splitting the command into appropriate chunks for you.
Important thing to note is that esc_with_backslash
option is the default escaping method for inserted objects so you
should not use quotes
around it to ensure proper path interpretation because every effort is
made to produce proper path string.
Currently available inline special words to be replaced at runtime are:
(assume that we clicked on object file://localhost/Users/tom/Desktop/My
Stuff/test.plist)
__OBJ_TEXT__
will be replaced at runtime with selected text or the text in clipboard;
when both selected text and clipboard are present, selected text takes
precedence;
if current context is a clicked file or folder, __OBJ_TEXT__
will insert clipboard content
__OBJ_PATH__
will be replaced at runtime with: /Users/tom/Desktop/My\
Stuff/test.plist
__OBJ_PATH_NO_EXTENSION__
will be replaced at runtime with:
/Users/tom/Desktop/My\ Stuff/test
This object is deprecated
(although still supported) because it can be constructed easily from __OBJ_PARENT_PATH__ + __OBJ_NAME_NO_EXTENSION__
__OBJ_PARENT_PATH__
will be replaced at runtime with:/Users/tom/Desktop/My\
Stuff
__OBJ_NAME__
will be replaced at runtime with: test.plist
__OBJ_NAME_NO_EXTENSION__
will be replaced at runtime with: test
__OBJ_EXTENSION_ONLY__
will be replaced at runtime with: plist
__OBJ_DISPLAY_NAME__
will be replaced at runtime with: test.plist
or test depending on the extension
visibility in Finder
__OBJ_COMMON_PARENT_PATH__
will be replaced with: /Users/tom/Desktop/My\ Stuff/
(notice slash at the end)
for multiple objects it will insert one path representing a parent
container for all selected objects
only one common parent path will be inserted regardless of processing
mode (together or separately)
__OBJ_PATH_RELATIVE_TO_COMMON_PARENT__
will be replaced with: test.plist
for multiple objects it will insert paths relative to a common parent
container
__DLG_INPUT_TEXT__ (old, deprecated name: __INPUT_TEXT__)
before execution you will be prompted to enter a string; three input
methods are currently supported: clear text, password text, popup menu
choice; there is a new description format for customizing the input
dialog; look below in section "Input dialog" for more information;
please note that this word does not belong to __OBJ_XXX__
family because it has nothing to do with current context
__PASSWORD__(deprecated, use __DLG_INPUT_TEXT__ password edit field instead)
before execution you will be prompted to enter a
password which then will be used in your command
please note that this word does not belong to __OBJ_XXX__ family
because it has nothing to do with current context
New in 1.5.3:
__DLG_SAVE_AS_PATH__ (old, deprecated name: __SAVE_AS_PATH__)
"Save As..." dialog will be displayed before execution. The path to
chosen save file will be inserted on execution.
__DLG_SAVE_AS_PARENT_PATH__ (old, deprecated
name: __SAVE_AS_PARENT_PATH__)
"Save As..." dialog will be displayed before execution. The path to
selected save location (parent folder) will be inserted on execution.
__DLG_SAVE_AS_NAME__ (old, deprecated name: __SAVE_AS_FILE_NAME__)
"Save As..." dialog will be displayed before execution. The file name
entered in this dialog will be inserted on execution.
All __DLG_SAVE_AS_XXX__ paths are escaped
according to settings provided in ESCAPE_SPECIAL_CHARS.
New in 1.5.4:
__DLG_SAVE_AS_NAME_NO_EXTENSION__
"Save As..." dialog will be displayed before execution. The file name
without extension entered in this dialog will be inserted on execution.
__DLG_SAVE_AS_EXTENSION_ONLY__
"Save As..." dialog will be displayed before execution. The extension
of the file name entered in this dialog will be inserted on execution.
__DLG_CHOOSE_FILE_PATH__
"Choose file" dialog will be displayed before execution. The path to
chosen file will be inserted on execution.
__DLG_CHOOSE_FILE_PARENT_PATH__
"Choose file" dialog will be displayed before execution. The path to
parent folder of chosen file will be inserted on execution.
__DLG_CHOOSE_FILE_NAME__
"Choose file" dialog will be displayed before execution. The name of
chosen file will be inserted on execution.
__DLG_CHOOSE_FILE_NAME_NO_EXTENSION__
"Choose file" dialog will be displayed before execution. The
name without extension of chosen file will be inserted on execution.
__DLG_CHOOSE_FILE_EXTENSION_ONLY__
"Choose file" dialog will be displayed before execution. The extension
of chosen file will be inserted on execution.
__DLG_CHOOSE_FOLDER_PATH__
"Choose folder" dialog will be displayed before execution. The path to
chosen folder will be inserted on execution.
__DLG_CHOOSE_FOLDER_PARENT_PATH__
"Choose folder" dialog will be displayed before execution. The path to
parent folder of chosen folder will be inserted on execution.
__DLG_CHOOSE_FOLDER_NAME__
"Choose folder" dialog will be displayed before execution. The name of
chosen folder will be inserted on execution.
__DLG_CHOOSE_FOLDER_NAME_NO_EXTENSION__
"Choose folder" dialog will be displayed before execution. The name
without extension of chosen folder will be inserted on execution.
__DLG_CHOOSE_FOLDER_EXTENSION_ONLY__
"Choose folder" dialog will be displayed before execution. The
extension of chosen folder will be inserted on execution.
__DLG_CHOOSE_OBJECT_PATH__
"Choose object" dialog (file or folder) will be displayed before
execution. The path to chosen file or folder will be inserted on
execution.
__DLG_CHOOSE_OBJECT_PARENT_PATH__
"Choose object" dialog will be displayed before execution. The path to
parent folder of chosen file or folder will be inserted on execution.
__DLG_CHOOSE_OBJECT_NAME__
"Choose object" dialog will be displayed before execution. The name of
chosen file or folder will be inserted on execution.
__DLG_CHOOSE_OBJECT_NAME_NO_EXTENSION__
"Choose object" dialog will be displayed before execution. The name
without extension of chosen file or folder will be inserted on
execution.
__DLG_CHOOSE_OBJECT_EXTENSION_ONLY__
"Choose object" dialog will be displayed before execution. The
extension of chosen file or folder will be inserted on execution.
New in 1.6:
__MY_BUNDLE_PATH__
The path pointing
to plugin or droplet bundle. Starting with OMC 2.0 it points to
Abracode.framework
__MY_HOST_BUNDLE_PATH__
The path pointing to host application or droplet bundle.
These new "bundle" paths do not make much sense for contextual menus
because they point to OnMyCommandCM.plugin or host application but they
might be extremely useful for droplets because you may put things in
bundle resources and access them with __MY_HOST_BUNDLE_PATH__/Contents/Resources/
One example is that you may put CLI executable in droplet resources and
run it from command description. This way you have everything you need
in one bundle and no additional installation is required.
__MY_BUNDLE_PATH__ is obtained using bundle
identifier, for example com.abracode.CommandDroplet. If used within
plug-in you may obtain a path where the plug-in is installed. If used
within droplet, it should return the droplet location. However, the
problem with this approach may be that if there are several droplets
with the same identifier (suppose you were not careful with changing
identifiers for them) it may point to a wrong place. The other method: __MY_HOST_BUNDLE_PATH__ obtains the location of
running application by querying process manager. If you use it in CM
plug-in you will obtain the path to host application. If you run it in
droplet, you will receive the path to droplet. Summarizing: both
methods should return the same result for droplet but __MY_HOST_BUNDLE_PATH__ should be more reliable
and is recommended.
New in 1.7:
__NIB_DLG_GUID__
This special word is replaced dynamically with current dialog unique
id. It is used for setting dialog control data in subcommands. For
example:
omc_dialog_control __NIB_DLG_GUID__
4 "Menu Item 1"
__CURRENT_COMMAND_GUID__
It returns the unique id for each command (subcommands are unique too).
It is different from regular command id (four char characters). __CURRENT_COMMAND_GUID__ is a globally unique ID -
guaranteed. It is used to identify which command is currently running
in order to avoid conflicts if more than one is running concurrently.
Potentially the globally unique ID can also be used for different
purposes - for example for saving a temporary file without worrying
that a file with the same name exists.
Example usage:
omc_next_command __CURRENT_COMMAND_GUID__
"NeXT"
New in 1.8:
__MY_EXTERNAL_BUNDLE_PATH__
It is a special object pointing to path defined by EXTERNAL_BUNDLE_PATH tag (redundant,
but much needed for portability)
<key>COMMAND</key>
<array>
<string>echo
</string>
<string>__MY_EXTERNAL_BUNDLE_PATH__</string>
</array>
<key>EXTERNAL_BUNDLE_PATH</key>
<string>~/Library/Application
Support/OnMyCommand/My
Command.omc</string>
|
If explicit path EXTERNAL_BUNDLE_PATH
in command description is not specified, __MY_EXTERNAL_BUNDLE_PATH__ resolves to default external bundle location which
is: /Users/you/Library/Application
Support/OnMyCommand/CurrentCommandName.omc where "CurrentCommandName"
is the name of the command (and menu item). This will allow easy access
to private command resources (nibs, images, scripts, etc.). The net
result is that if you place a ".omc" bundle of the same name as your
command in ~/LibraryApplication Support/OnMyCommand/, it will be found
automatically.
DropletBuilder is able to install the .omc bundle for you in default
location and copy the command from "Command.plist" to your main list of
commands. Just drag the .omc bundle on the DropletBuilder icon. This
way the self-contained command with resources (images, nibs, external
scripts, etc.) may be distributed as .omc bundle and is easy to install.
New in 1.9:
Environment variables export
Special words can now be exported as environment variables in
popen-based execution modes. It does not work for system() or
AppleScript execution modes.
The naming convention is that special objects which take form of __XXX__ are now becoming OMC_XXX for environment
variables,
for example __OBJ_PATH__
becomes OMC_OBJ_PATH
and can be used in scripts as "$OMC_OBJ_PATH"
or
"${OMC_OBJ_PATH}".
OMC scans the command, looking for those special words and exports them
as environment variables for the executed command.
The difference between __XXX__
and OMC_XXX is that the
former are replaced at runtime with proper values and inserted directly
into the script, while the latter are not changed - so the script
remains unmodified and gets values form environment variables. The
former usually needs escaping because the shell interprets the inserted
string, the latter is not escaped because it is not interpreted by the
shell and may be simply accessed by "$OMC_XXX". Any escaping
settings in the command are ignored for OMC_XXX variables.
<dict>
<key>COMMAND</key>
<array>
<string>echo
"$OMC_OBJ_NAME"</string>
</array>
<key>EXECUTION_MODE</key>
<string>exe_popen_with_output_window</string>
</dict>
Additional environment variables, both custom and special objects, can
be added explicitly to the ENVIRONMENT_VARIABLES
dictionary.
If you put a special word in this dictionary (like OMC_OBJ_PATH in example
below), the string you assigned to it is ignored and may be empty - it
is just a signal for OMC to export that special word's runtime value as
environment variable. This is useful if this variable is accessed in a
script indirectly invoked by your command - is such case OMC does not
know you need this variable because the main command does not include
it (yet the dependent script invoked from main command may use it)
<dict>
<key>ENVIRONMENT_VARIABLES</key>
<dict>
<key>TEST_CUSTOM_VARIABLE</key>
<string>OMC
test</string>
<key>OMC_OBJ_PATH</key>
<string></string>
</dict>
</dict>
New in 2.0:
OMC 2.0 features separation of common code and resources into
Abracode.framework. There are 2 new special words for for accessing
resources and helper applications:
__OMC_SUPPORT_PATH__
/ $OMC_OMC_SUPPORT_PATH
=
Abracode.framework/Support/
__OMC_RESOURCES_PATH__ /
$OMC_OMC_RESOURCES_PATH
= Abracode.framework/Resources/
__MY_BUNDLE_PATH__
One noteworthy change is that special inline object __MY_BUNDLE_PATH__ previously
used in droplets no longer points to droplet's bundle but to
Abracode.framework bundle. So if you were using __MY_BUNDLE_PATH__ to access
your resources in droplet, you need to change it. The usage of __MY_BUNDLE_PATH__ was
discouraged for droplets anyway and now it is slightly deprecated
because all you need to use is __OMC_SUPPORT_PATH__
and __OMC_RESOURCES_PATH__
for OMC resources and tools.
Droplets should use __MY_HOST_BUNDLE_PATH__
/ $OMC_MY_HOST_BUNDLE_PATH
to access its own private resources and if your droplet was using this
method even for accessing common resources and tools, nothing should be
broken because the new droplets have symbolic links to resources and
tool which are now moved to common framework.
|
The following option
controls when the command should show |
<key>ACTIVATION_MODE</key>
<string>act_always</string> (Default value assumed if key not
present)
Command active always.
<string>act_file</string>
Command active when file is control-clicked.
Extended checking is available for this activation mode via
ACTIVATION_FILE_TYPES and ACTIVATION_EXTENSIONS. Look below for more
details.
<string>act_folder</string>
Command active when folder is control-clicked.
Extended checking is available for this activation mode via
ACTIVATION_EXTENSIONS. Look below for more details.
<string>act_file_or_folder</string>
Command active when file or folder is control-clicked.
Extended checking is available for this activation mode via
ACTIVATION_FILE_TYPES and ACTIVATION_EXTENSIONS. Look below for more
details.
<string>act_finder_window</string>
Command active when open Finder window or desktop is control-clicked.
Extended checking is available for this activation mode via
ACTIVATION_EXTENSIONS. Look below for more details.
<string>act_selected_text</string>
Command active when a selected text is control-clicked.
<string>act_clipboard_text</string>
Command active when there is a text in clipboard.
<string>act_selected_or_clipboard_text</string>
Command active when a selected text is control-clicked or there
is a text in clipboard.
When both conditions are met - text is clicked and clipboard contains
text - the menu is displayed and clicked text takes precedence over
text in clipboard.
NEW in 1.4.2:
<string>act_file_or_folder_not_finder_window</string>
Command active when file or folder is control-clicked but not
open Finder window or Desktop.
<string>act_folder_not_finder_window</string>
Command active when folder is control-clicked but not open Finder
window or Desktop.
|
The following options
control WHERE your menu item should show |
<key>ACTIVATE_ONLY_IN</key>
<array>
<string></string>
</array>
<key>NEVER_ACTIVE_IN</key>
<array>
<string></string>
</array>
Starting with version 1.6.1 there is a
new activation option to tell in which applications the command should
or must not show:
ACTIVATE_ONLY_IN or NEVER_ACTIVE_IN. Those 2 options are
logically exclusive. You can use one or the other but not both in one
command. You provide an array of application names like this:
<key>ACTIVATE_ONLY_IN</key>
<array>
<string>TextEdit</string>
<string>BBEdit
Lite</string>
</array>
or:
<key>NEVER_ACTIVE_IN</key>
<array>
<string>Finder</string>
</array>
The name of the application is what you see in menu bar when you launch
given application, not the name of the bundle (which may be different).
|
The following
option controls how your command is executed |
<key>EXECUTION_MODE</key>
<string>exe_silent_popen</string> (Default value assumed if key not
present)
Execute silently using popen() call, only errors are output to
Console.app. Old, deprecated name was: exe_silent
Default shell in Mac OS 10.3.x & 10.4.x: sh
Executes asynchronously starting with OMC 1.8
<string>exe_silent_system</string>
Execute silently using system() call. Use with quick commands not
producing much result text.
Default shell in Mac OS 10.3.x & 10.4.x: sh
Executes synchronously, blocking the host during execution.
<string>exe_terminal</string>
Launch Terminal.app and execute the command there.
Default shell in Mac OS 10.3.x: bash
<string>exe_iterm</string>
Launch iTerm.app and execute the command there.
Default shell in Mac OS 10.3.x: bash
<string>exe_popen_with_output_window</string>
Execute command using popen() call and display result in output window.
Default shell in Mac OS 10.3.x: sh
Executes asynchronously starting with OMC 1.8
<string>exe_applescript</string>
The command must be an AppleScript code. Executes the code silently.
Executes synchronously.
<string>exe_applescript_with_output_window</string>
The command must be an AppleScript code. Displays result window.
Executes synchronously.
<string>exe_shell_script</string>
The command must be a shell script. At the beginning of each shell
script you need to specify which shell to use. For example: #!/bin/sh
Shell script is saved to temporary file before execution. Make sure
your line endings are Unix linefeeds (LFs).
Executes asynchronously starting with OMC 1.8
<string>exe_shell_script_with_output_window</string>
The command must be a shell script. Displays result window.
Executes asynchronously starting with OMC 1.8
Options exe_silent_popen, exe_silent_system
& exe_iterm are new or renamed in version 1.5.4.
Options exe_popen_with_output_window, exe_applescript & exe_applescript_with_output_window
are new in version 1.6.
Options exe_shell_script & exe_shell_script_with_output_window are new in version 1.6.1.
For execution modes with output window you may control various settings
of the window. The dictionary group is named: OUTPUT_WINDOW_SETTINGS.
Full
description
in
"Output window settings" section of this document.
Version 1.6 of OMC fixed a long standing bug with popen() call. The
symptom was that commands displaying several lines of result were
aborted prematurely. Now it should execute anything you throw at it.
Current recommendation is that you should use exe_silent_popen
or exe_popen_with_output_window modes for
commands which are time consuming and produce several lines of result.
One example is "hdiutil create" which can work for several seconds
displaying status in several lines. exe_silent_system
should be used for quick commands, for example: "touch some_file"
Version 1.6 add native support for AppleScript. A lot of commands used osascript
call to put AppleScript code in OMC item. Now you can write AppleScript
code directly in command description and choose exe_applescript
or exe_applescript_with_output_window
execution mode. You should use esc_for_applescript
for proper escaping of objects. You can use "POSIX file" to get access
to files with Unix path, for example:
<key>COMMAND</key>
<array>
<string>tell app "Finder"
move POSIX file "</string>
<string>__OBJ_PATH__</string>
<string>" to (path to documents folder)
end tell</string>
</array>
|
New in 1.7b1:
Send Task to Background Application (OMCDeputy)
<key>SEND_TASK_TO_BACKGROUND_APP</key>
<false/> - default value if key not
present
<true/> - command is executed by
OMCDeputy background app
This option is for commands with or without output window but it makes
sense when you have an output window or nib-based progress bar to
monitor the progress. Host app will no longer be blocked. It is very
handy for time consuming tasks started by contextual menu in Finder. It
is also very important for AppleScripts which try to talk back to the
host app. This option has no effect if command is sent to Terminal or
iTerm.
|
Escape characters option |
<key>ESCAPE_SPECIAL_CHARS</key>
<string>esc_with_backslash</string> (Default value for path objects
assumed if key not present)
Escape special characters with backslash (i.e. ~/My Folder/
will be replaced with ~/My\ Folder/)
Beginning with version 1.3.1a9 this type of escape is also applied to __OBJ_TEXT__. Another change in version 1.3.1a9 is
that line breaks LF (0x0A) and CR (0x0D) are escaped with backslash too.
<string>esc_none</string>
No change is made to added string
<string>esc_with_percent</string>
Internet URL style escape (i.e. Hello Friend.html will be
replaced with Hello%20Friend.html)
Escapes only illegal URL chars (as defined by RFC 2396)
This type of escape is applied to paths and __OBJ_TEXT__
as well.
<string>esc_with_percent_all</string>
This method escapes all illegal URL chars plus legal non-alphanumeric
chars. The additional escaped characters are: !$&'()*+,-./:;=?@_~.
Those chars need to be escaped in order to avoid conflicts in shell
execution. The end result is that only A-Z, a-z, 0-9 are left
unescaped.
<string>esc_for_applescript</string>
New in OMC 1.6. Escapes backslash and double quote mark only.
\ becomes \\
" becomes \"
<string>esc_wrap_with_single_quotes_for_shell</string>
This is a special quoting method for use with shell. The behavior is to
wrap the text with single quotes and work around the problem of any
possible single quote inside. The text:
Don't do it
will become wrapped as:
'Don'\'' do it'
NOTES:
"esc_with_backslash" option MUST NOT be used at the same time with
quotes around inserted object. You can use either way to make sure the
proper path is set but not together because such combination is not
going to work. cd ~/My\ Folder/ is going to work and cd
"~/My Folder/" is going to work, but cd "~/My\ Folder/"
will not work.
New in 1.7b1
__DLG_INPUT_TEXT__ is now escaped according
to the escape method described by ESCAPE_SPECIAL_CHARS
New in 1.8
You can override escaping method in nib controls. You may specify the
control property with creator 'OMC!', tag 'esc!' and
Unicode
text value
string like esc_none, esc_with_backslash, etc.
|
Line endings
replacement |
Option to replace line endings for __OBJ_TEXT__:
<key>TEXT_REPLACE_OPTION</key>
<string>txt_replace_none</string>
Default, no change
<string>txt_replace_lf_with_cr</string>
Change Unix line breaks to Mac line breaks
<string>txt_replace_cr_with_lf</string>
Change Mac line breaks to Unix line breaks
This is for replacement within __OBJ_TEXT__
object: selection or clipboard. This option was added in OMC 1.7b1.
|
The following key may
contain comments from command author |
<key>NOTES</key>
<string></string>
This keyword is ignored by plug-in but may contain additional
information (e.g. about requirements for given command or info about
the author).
|
Extended file/folder
type checking |
A. File type list. This extended checking is available when
ACTIVATION_MODE is act_file or act_file_or_folder.
You may provide a list of file types. If any of your types is matched,
your command will be activated.
Example:
<key>ACTIVATION_FILE_TYPES</key>
<array>
<string>TEXT</string>
<string>utxt</string>
</array>
|
NOTES:
File types are usually represented as four character code. If you
specify longer file type, only first four characters will be used. If
you specify shorter file type, the remaining characters are assumed to
be zero (true zero, not character '0').
B. Extension list. This extended checking is available when
ACTIVATION_MODE is act_file, act_folder,act_file_or_folder
or act_finder_window. You may provide a list
of extensions. If any of them matches the extension of a clicked object
the command will be activated.
Example:
<key>ACTIVATION_EXTENSIONS</key>
<array>
<string>htm</string>
<string>html</string>
<string>shtml</string>
</array>
|
NOTES:
1. Extension comparison is case insensitive.
2. Do not include dot preceding the extension.
If you specify both ACTIVATION_FILE_TYPES and ACTIVATION_EXTENSIONS
then any match is enough for activation.
For programmers: it is logical operator OR.
For laymen: if you specify file type 'TEXT' and extension "txt" then
the following documents will activate the command:
1. "document.txt" of any file type, including 'TEXT'
2. "document.ext" of type 'TEXT'
3. "document" of type 'TEXT'
However, a file named "document" or "document.ext" without file type
specified will not activate the command.
|
Multiple object insertion |
Subgroup with settings for multiple object processing. If key not
present, proc_separately is assumed.
<key>MULTIPLE_OBJECT_SETTINGS</key>
<dict>
<key>PROCESSING_MODE</key>
<string>proc_together</string>
<key>PREFIX</key>
<string></string>
<key>SUFFIX</key>
<string></string>
<key>SEPARATOR</key>
<string></string>
</dict>
<key>PROCESSING_MODE</key>
<string>proc_separately</string> (Default value assumed if key not
present)
Command is executed for each file or folder separately
<string>proc_together</string>
All objects are processed together by one command, inserted
paths are composed of
prefix+path+suffix+separator+prefix+path+suffix...etc.
<key>PREFIX</key>
(No prefix is used if key not present)
<string></string>
A prefix text to be inserted before every object
<key>SUFFIX</key>
(No suffix is used if key not present)
<string></string>
A suffix text to be inserted after every object
<key>SEPARATOR</key>
(No separator is used if key not present)
<string></string>
A separator text to be inserted between objects
Example:
Consider the following settings for multiple objects:
<key>MULTIPLE_OBJECT_SETTINGS</key>
<dict>
<key>PROCESSING_MODE</key>
<string>proc_together</string>
<key>PREFIX</key>
<string>"</string>
<key>SUFFIX</key>
<string>"</string>
<key>SEPARATOR</key>
<string> </string>
</dict>
|
When multiple files are clicked:
/Users/You/Folder1/file1.txt
/Users/You/Folder2/file2.txt
/Users/You/Folder3/file3.txt
and the command is:
<key>COMMAND</key>
<array>
<string>echo </string>
<string>__OBJ_PATH__</string>
</array>
|
The resulting command text will be as follows:
echo "/Users/You/Folder1/file1.txt"
"/Users/You/Folder2/file2.txt" "/Users/You/Folder3/file3.txt"
New in 1.8
Multiple objects sorting:
<key>MULTIPLE_OBJECT_SETTINGS</key>
<dict>
<key>SORT_METHOD</key>
<string>sort_by_name</string>
<key>SORT_OPTIONS</key>
<dict>
<key>SORT_ASCENDING</key>
<true/>
<key>COMPARE_CASE_INSENSITIVE</key>
<true/>
<key>COMPARE_NONLITERAL</key>
<true/>
<key>COMPARE_LOCALIZED</key>
<true/>
<key>COMPARE_NUMERICAL</key>
<true/>
</dict>
</dict>
SORT_METHOD: sort_none
(default), sort_by_name
SORT_OPTIONS (only valid if SORT_METHOD is different from
sort_none):
SORT_ASCENDING - default true: a-z, 0-9 , if false:
z-a, 9-0
All other options are corresponding to
CFStringCompareFlags. See description in Apple
documentation.
COMPARE_CASE_INSENSITIVE
— if true: Finder-like. Default is false: case sensitive, Unix-like
COMPARE_NONLITERAL
— default is false: literal
COMPARE_LOCALIZED
— default is false: not locale-aware
COMPARE_NUMERICAL
— if true: numeric values compared so "version 2" < "version 2.5",
default is false: alphabetical
|
Terminal behavior settings |
The following terminal settings are applied to each command
individually. They apply to Terminal or iTerm only and are ignored when
command is executed silently.
<key>TERM_OPEN_NEW_SESSION</key>
<true/> (Default value assumed if key not present)
Command will be executed in new terminal window.
<false/>
Command will be executed in frontmost terminal window. If there
is no window open, the command will not be executed. In Mac OS 10.1.x
Terminal.app is less advanced and does not support execution is
frontmost window, so a new session is always opened and TERM_OPEN_NEW_SESSION
setting is ignored.
<key>TERM_BRING_TO_FRONT</key>
<true/>(Default value assumed if key not present)
"Activate" event is sent to terminal after command event. This
brings terminal to front.
<false/>
The window with executed command will not come to front. Useful
for longer tasks like downloading files so you may stay in your context
while terminal does its job in background. If Terminal is not launched
yet, it will always go to front after launching regardless of this
setting.
New in 1.8:
iTerm startup shell support:
<key>ITERM_SHELL_PATH</key>
<string>/bin/bash</string>
The default shell for iTerm is tcsh for historical reasons. Now
you can override it.
|
Input dialog |
The special word __DLG_INPUT_TEXT__ for
command description invokes a dialog where you can input text. The
following input methods are currently supported: clear text, password
text, popup menu choice and combo box (clear text edit field plus popup
choice) . Here is a new description format for customizing the input
dialog.
Example:
<key>INPUT_DIALOG</key>
<dict>
<key>OK_BUTTON_NAME</key>
<string>Execute</string>
<key>CANCEL_BUTTON_NAME</key>
<string>Forget it</string>
<key>MESSAGE</key>
<string>Please input your text</string>
<key>INPUT_TYPE</key>
<string>input_clear_text</string>
<key>DEFAULT</key>
<string>Hello</string>
</dict>
|
INPUT_TYPE keyword defines the method of input desired. It can
be clear text, password or popup menu choice.
Available values for INPUT_TYPE keyword:
<string>input_clear_text</string>
<string>input_password_text</string>
<string>input_popup_menu</string>
New in 1.5.3:
<string>input_combo_box</string>
If keyword is not present, the default value of input_clear_text is assumed.
OK_BUTTON_NAME defines OK button name.
If keyword is not present, the default value of "OK" string for
OK button is assumed.
CANCEL_BUTTON_NAME defines cancel button name.
If keyword is not present, the default value of "Cancel" string for
cancel button is assumed.
MESSAGE defines static message text appearing in dialog. There
is a space for two lines of text available in dialog. If your message
is just one line you may consider putting a carriage return in front of
the text so it will appear lower in the dialog (it will look better).
If keyword is not present, the default value for static text is set as
follows:
for input_clear_text:
"Please enter the input text:"
for input_password_text:
"Please enter your password:"
for input_popup_menu:
"Please select an option:"
for input_combo_box:
"Please select an option:"
DEFAULT keyword defines the initial text for the edit field or
the initial menu choice for menu popup.
If keyword is not present, the initial text in edit field is empty.
When input type is input_popup_menu
or input_combo_box additional data is needed
to build the menu:
<key>INPUT_MENU</key>
<array>
<dict>
<key>NAME</key>
<string>Option
1</string>
<key>VALUE</key>
<string>1</string>
</dict>
<dict>
<key>NAME</key>
<string>Option
2</string>
<key>VALUE</key>
<string>2</string>
</dict>
</array>
|
Input menu description seems a little bit complicated but the design
goal is to provide a good user interface. Each menu item has its NAME
and VALUE keys. What end user sees in popup menu is NAME, what is
passed to command is VALUE. Unix commands sometimes require input
options which are not easy to understand and are not named in user
friendly manner. This way you can name the menu items as you want and
hide the ugly or complicated values they represent.
Here is an example of command description for input dialog with popup
menu:
<dict>
<key>ACTIVATION_MODE</key>
<string>act_file</string>
<key>COMMAND</key>
<array>
<string>gzip
</string>
<string>__DLG_INPUT_TEXT__</string>
<string> </string>
<string>__OBJ_PATH__</string>
</array>
<key>EXECUTION_MODE</key>
<string>exe_silent_popen</string>
<key>INPUT_DIALOG</key>
<dict>
<key>INPUT_TYPE</key>
<string>input_popup_menu</string>
<key>MESSAGE</key>
<string>Please
select
compression
level:</string>
<key>DEFAULT</key>
<string>Medium</string>
<key>INPUT_MENU</key>
<array>
<dict>
<key>NAME</key>
<string>Low</string>
<key>VALUE</key>
<string>-1</string>
</dict>
<dict>
<key>NAME</key>
<string>Medium</string>
<key>VALUE</key>
<string>-5</string>
</dict>
<dict>
<key>NAME</key>
<string>High</string>
<key>VALUE</key>
<string>-9</string>
</dict>
</array>
</dict>
<key>NAME</key>
<string>Compress with gzip...</string>
<key>NOTES</key>
<string>Control compression level
with menu choice</string>
<key>VERSION</key>
<integer>1</integer>
</dict>
|
New in 1.7b1:: __DLG_INPUT_TEXT__
is escaped
according to the escape method described by ESCAPE_SPECIAL_CHARS
|
Navigation Services Dialogs Options |
MESSAGE
This option specifies the text message
appearing on top of the dialog. If not defined, the dialog will be
displayed without any message text. The syntax is demonstrated below:
<key>CHOOSE_FILE_DIALOG</key>
<dict>
<key>MESSAGE</key>
<string>Choose file</string>
</dict>
<key>SAVE_AS_DIALOG</key>
<dict>
<key>MESSAGE</key>
<string>Save As</string>
</dict>
<key>CHOOSE_FOLDER_DIALOG</key>
<dict>
<key>MESSAGE</key>
<string>Select Folder</string>
</dict>
<key>CHOOSE_OBJECT_DIALOG</key>
<dict>
<key>MESSAGE</key>
<string>Select File or Folder</string>
</dict>
Showing invisible files and
folders
in Navigation dialogs:
<key>CHOOSE_FILE_DIALOG</key>
<dict>
<key>SHOW_INVISIBLE_ITEMS</key>
<true/>
</dict>
This option is available for SAVE_AS_DIALOG,
CHOOSE_FILE_DIALOG,
CHOOSE_FOLDER_DIALOG, CHOOSE_OBJECT_DIALOG
Setting default location for navigation dialogs:
<key>CHOOSE_FOLDER_DIALOG</key>
<dict>
<key>MESSAGE</key>
<string>Select Folder</string>
<key>DEFAULT_LOCATION</key>
<array>
<string>__OBJ_PARENT_PATH__</string>
</array>
</dict>
Inline special words allowed. Tilde in front of the path resolved as
user's
home folder. Example above opens navigation dialog in parent folder of
control-clicked object.
USE_PATH_CACHING
An option for navigation dialogs to allow or disallow sharing of the same selected path between subcommands.
Previous behavior was to always share the path and never ask again (default value is true).
The new option allows each subcommand to have a separate path, effectively asking the user with navigation dialog for a different path.
Just set the path caching option to false:
<key>CHOOSE_FILE_DIALOG</key>
<dict>
<key>USE_PATH_CACHING</key>
<false/> {default is true if key not present}
</dict>
This option is available for SAVE_AS_DIALOG, CHOOSE_FILE_DIALOG, CHOOSE_FOLDER_DIALOG and CHOOSE_OBJECT_DIALOG.
|
Refresh in Finder |
<key>REFRESH_PATH</key>
<array>
<string></string>
</array>
Refresh path is an array of strings which will be combined together
before sending it to Finder. You can use same special words as in COMMAND
keyword.
Example:
<key>REFRESH_PATH</key>
<array>
<string>__OBJ_PATH__</string>
<string>.gz</string>
</array>
|
There are several limitations:
1. You cannot refresh non-existing file/folder. This might sound
obvious, but some commands may create file or folder too late, after
the event has been sent to Finder, and this is not going to work.
2. You can provide only one path per command. This means that if some
command creates two files it cannot refresh both. However, if you
ctrl-click on several files, the refresh path will be processed for
each one of them.
3. The path is not passed to any Unix command but it is internally
converted to an alias description and sent to Finder. This means that
the path must be absolute and no Unix
tricks are allowed (like using star for several objects: /path/objects*
). The path must not be escaped with backslash and any escaping
settings for command are ignored.
4. The refresh is not executed for commands which do not take file or
folders as objects (like text selection).
5. The refresh path will not open the dialog for __DLG_INPUT_TEXT__
by itself. If __DLG_INPUT_TEXT__ is used in
command, the text received from dialog will be reused for REFRESH_PATH.
The general idea is that you can copy the path specified in command
structure and paste it into refresh structure and have the object
refreshed in Finder immediately.
New in 1.8:
If the path first character is a tilde ("~"), it is expanded to current
user folder, e,g. "~/" becomes "/Users/you/"
|
Output Window Settings |
All settings are gathered in OUTPUT_WINDOW_SETTINGS dictionary
group. Use for execution modes with output window. All settings below
are optional. Everything will fall back to default values if OUTPUT_WINDOW_SETTINGS
are not set.
Here is the example structure:
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>WINDOW_ALPHA</key>
<real>0.8</real>
<key>WINDOW_TITLE</key>
<string>Result</string>
<key>WINDOW_TYPE</key>
<string>regular</string>
<key>WINDOW_POSITION</key>
<string>absolute</string>
<key>ABSOLUTE_POSITION_TOP</key>
<integer>100</integer>
<key>ABSOLUTE_POSITION_LEFT</key>
<integer>200</integer>
<key>WINDOW_WIDTH</key>
<integer>500</integer>
<key>WINDOW_HEIGHT</key>
<integer>100</integer>
<key>BACKGROUND_COLOR</key>
<string>000000</string>
<key>TEXT_COLOR</key>
<string>00FF00</string>
<key>TEXT_FONT</key>
<string>Monaco</string>
<key>TEXT_SIZE</key>
<integer>10</integer>
</dict>
|
WINDOW_ALPHA
<real>1.0</real>
Transparency alpha. Valid range is 0.0 — 1.0 (inclusive). 0.0
is completely transparent, 1.0 is opaque. Default value is 1.0 if key
not present.
WINDOW_TITLE
<string></string>
Title for output window. If not present, the name of the command is
used as a window title.
WINDOW_TYPE
<string>regular</string>
<string>floating</string>
<string>global_floating</string>
<string>custom</string>
Floating window stays on top of windows in given application. It is
hidden when you switch to other application. Global floating always
stays on top of all windows. Regular window behaves like ordinary
document window. Custom windows are new in 1.7b1. See below for more
information.
Default: floating
WINDOW_POSITION
<string>absolute</string>
<string>alert</string>
<string>center</string>
<string>cascade</string>
Value for automatic window positioning. If value is absolute,
the
top
left
window coordinates are taken from ABSOLUTE_POSITION_TOP
and ABSOLUTE_POSITION_LEFT keys.
Default: alert
ABSOLUTE_POSITION_TOP
ABSOLUTE_POSITION_LEFT
<integer>50</integer>
Default: 50, 50
WINDOW_WIDTH
<integer>400</integer>
Default: 400
WINDOW_HEIGHT
<integer>200</integer>
Default: 200
BACKGROUND_COLOR
<string>FFFFFF</string>
Must be six hexadecimal characters in RRGGBB format (HTML-like)
For example: 000000 is black, FFFFFF is white, FF0000 is red, 00FF00 is
green, 0000FF is blue
Characters are case insensitive so it can also be abcdef
Default: white (FFFFFF)
TEXT_COLOR
<string>000000</string>
Six hex chars. Format the same as BACKGROUND_COLOR
Default: black (000000)
TEXT_FONT
<string>Monaco</string>
Font family name.
Default: Monaco.
TEXT_SIZE
<integer>10</integer>
Default: 10
LINE_OUTPUT_INTERVAL (obsolete)
<real>0.1</real>
This option is obsolete in OMC 1.8 and is ignored. It used to be
seconds between reading and displaying next line of output.
New in 1.7b1:
Output windows with custom shape and background defined by PNG image.
That type of window is drawn on top of everything. Window dimensions
are
the same as picture.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>WINDOW_TYPE</key>
<string>custom</string>
<key>CUSTOM_WINDOW_PNG_IMAGE</key>
<string>Bezel.png</string>
</dict> |
Default PNG image is none. If you set WINDOW_TYPE to custom and not provide the custom image, the
window size set in parameters is respected and the text is drawn in
completely transparent window, just as if it was drawn on top of
everything without any window.
Textbox. Defines where the text should be placed in custom window. The
text is not editable but may be copied to clipboard with Cmd+C.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>CUSTOM_TEXTBOX_POSITION_TOP</key>
<integer>20</integer>
<key>CUSTOM_TEXTBOX_POSITION_LEFT</key>
<integer>20</integer>
<key>CUSTOM_TEXTBOX_WIDTH</key>
<integer>100</integer>
<key>CUSTOM_TEXTBOX_HEIGHT</key>
<integer>50</integer>
</dict> |
Top & left values default to 0 if keys not present. Width and
height default to the whole custom window width and height.
Closebox. Defines the rectangle where mouse click closes the window.
Only for custom windows.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>CUSTOM_CLOSEBOX_POSITION_TOP</key>
<integer>0</integer>
<key>CUSTOM_CLOSEBOX_POSITION_LEFT</key>
<integer>0</integer>
<key>CUSTOM_CLOSEBOX_WIDTH</key>
<integer>16</integer>
<key>CUSTOM_CLOSEBOX_HEIGHT</key>
<integer>16</integer>
</dict> |
Top & left values default to 0 if keys not present. Width and
height default to the whole custom window width and height so the
out-of-the-box behavior is that a click in custom window closes it.
Other way to close the custom window is to use Cmd+W.
Fade in and fade for output windows:
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>WINDOW_OPEN_FADE_IN</key>
<true/>
<key>WINDOW_CLOSE_FADE_OUT</key>
<true/>
</dict> |
Default is false in both cases. Can be used with any type of window.
New in 1.8:
Additional positioning
method for
output window:
FRACT_POSITION_LEFT and FRACT_POSITION_TOP are the new
positioning methods for output window. The value is a floating
point number between 0.0 and 1.0 and describes approximate
position on screen. 0.0 is top or left, 1.0 is right or bottom, 0.5 is
center, etc. This method places the center of the output window in
desired location but also makes sure the whole window is visible on the
screen (placing window at {0.0, 0.0} will not place its center in top
left corner of the screen but rather places top left corner of the
window there). This method takes menu bar and dock into account so the
window is placed correctly within available area.
For example, positioning a window about 1/3 of the screen height from
the top and 2/3 of the screen width from the left:
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>FRACT_POSITION_LEFT</key>
<real>0.66</real>
<key>FRACT_POSITION_TOP</key>
<real>0.33</real>
<key>WINDOW_POSITION</key>
<string>absolute</string>
</dict>
|
|
Nib dialogs |
Starting with version 1.6.1 you can build a
dialog in Interface Builder and access control values via:
__NIB_DIALOG_CONTROL_N_VALUE__
"N" has to be replaced with control id number, for example __NIB_DIALOG_CONTROL_3_VALUE__
The nib dialog settings have to be explicitly present in command
description to load the dialog. Two parameters are required: NIB_NAME
& WINDOW_NAME. For example:
<key>NIB_DIALOG</key>
<dict>
<key>NIB_NAME</key>
<string>mydialog</string>
<key>WINDOW_NAME</key>
<string>Dialog</string>
</dict>
NIB_NAME is the name of the nib bundle. Do not include ".nib"
extension here.
WINDOW_NAME is not a window title but rather the name of the
window resource in nib bundle. This is the name that you see under
window icon when you open a nib in Interface Builder.
This option is for advanced users. You need Apple Developer Tools
installed to create and edit nibs. The instructions below might seem
complicated but it is all very easy once you see an example. Please
check example droplets provided with main OMC distribution and examine
nib resources inside, especially "Nib Dialog Demo" which contains all
possible controls with mappings.
Nib dialogs are very handy for droplet applications. You need to put
such custom nib into the "Resources" folder in droplet bundle.
If you want to use custom nib dialog in contextual menu you have to put
your nib resource inside OnMyCommandCM.plugin bundle resources.
When you create a new nib resource you have to choose a Carbon nib.
Cocoa nibs will not work here. You can use example nib dialogs provided
with the main distribution as a starting point for your own dialog.
OMC dialog code "listens" to 2 commands: 'ok '
and
'not!' usually sent
by "OK" and "Cancel" buttons. When user closes the dialog window
without sending any of those messages, it is considered as "Cancel".
Each control returning value must use a signature 'OMC!'
and
have
unique
ID
number.
Control Values
All control values are strings. When control values are not mapped (see
below for mapping) they return values as follows:
- Checkbox values are "0" and "1" for "off" and "on" state respectively.
- Radio button group returns the name of selected radio button.
- Popup menu returns the selected menu item name.
- Slider returns the selected number.
- Edit Text field, Search field, Combo box and Text View return the
current text they contain.
- Search field, Combo box and Text View require Mac OS 10.3.
- Clock/Date control returns nothing when format string is not provided
via control attributes or when used in Mac OS X older than 10.3.
Value Mapping
For some controls you can map values. This option works only in Mac OS
10.3 or higher because it requires setting control attributes.
Note that those mapping values are never seen by end user so you may
enter some cryptic configuration options and provide human-readable
description to users.
When you use "Show Info" option for selected control in Interface
Builder you will see "Properties" table in "Control" panel. The
table contains 4 columns. For "Creator" column you must always use
'OMC!'. In "Tag" column you need to put
original control value. "Type"
column must always be "U String" (Unicode). In "Value" column you type
the actual string you want to see returned for given control value.
- Checkbox values are "0" or "1" ("Tag" column) and you can map them
for example to "ON" and "OFF" ("Value" column).
- Popup menu values are from "1" to "N" where "N" is the number of menu
items ("Tag" column)
- Radio button group can be mapped for values from "1" to "N" where "N"
is the number of radio buttons in the group ("Tag" column). When you
have multiple rows and columns of checkboxes you need to remember that
radio buttons are numbered vertically in columns.
- Clock/Date control returns time or date but never both. This control
works only in Mac OS 10.3 or higher. You have to provide the format you
wish to obtain in result string. Use 'frmt'
as a "Tag" for properties.
In "Value" column enter a format string, for example "yyyyy-MM-dd" for
date control or "HH:mm:ss" for time control. The format used here is
defined by IBM ICU (International Components for Unicode) and is
similar to Excel date and time format. More information about the
format is available at ICU
website.
- Edit Text field, Search field, Combo box and Text View values cannot
be mapped, they always return the text they contain.
- Slider cannot be mapped and always returns the selected number.
Nib Dialog Enhancements in version 1.7b1
omc_dialog_control command line tool to set
the control value. You may also enable/disable, show/hide controls via
special values: omc_enable, omc_disable, omc_show, omc_hide. Example:
omc_dialog_control __NIB_DLG_GUID__
4 "hello world!"
This CLI tool is located
in both OnMyCommandCM.plugin and droplet
bundles in "Contents/MacOS/" subfolder. For example, you can access it
in your command with:
<string>__MY_BUNDLE_PATH__</string>
<string>/Contents/MacOS/omc_dialog_control
</string>
Starting with OMC 2.0 this CLI tool is located in
Abracode.framework/Support/. For example, you can access it
in your command with:
<string>"$OMC_OMC_SUPPORT_PATH/omc_dialog_control"</string>
The control value is set and refreshed after the subcommand
finishes.
It will not be refreshed immediately because the subcommand is executed
in the same thread and there is no way to set up a callback. However,
if the actual command is sent to the OMCDeputy you may use the 4th
argument "omc_live_update" to immediately refresh the control. For
example, if you have a progress bar with id {"OMC!",
10},
you
may
send
the following message to set it to 85%:
omc_dialog_control __NIB_DLG_GUID__
10 85 omc_live_update
For indeterminate progress bar you can use:
omc_dialog_control __NIB_DLG_GUID__
10 -1
If you have a chasing arrows control you may show it with:
omc_dialog_control __NIB_DLG_GUID__
11 omc_show
To disable a control, use:
omc_dialog_control __NIB_DLG_GUID__
3 omc_disable
__NIB_DLG_GUID__ is replaced dynamically with
current dialog unique id.
More controls supported including pictures, icons, bevel buttons,
static text, progress controls, tab control. Controls can trigger
subcommands if command id is assigned in Interface Builder.
Tab control. Tab control requires special contract with interface
designer: user panes within tab control must use special numbering,
starting with tab control number + 1 and be sequential. For example, if
the tab control id is {"OMC!", 100} the
first
pane must be {"OMC!",
101}, 2nd: {"OMC!", 102}, and so forth.
Icons & pictures. Custom icons can be displayed in image well, icon
control and bezel button. Icons are taken from ".icns" file. Icon can
be initialized statically in nib file adding control property {'OMC!',
'val!', "myicon.icns"} or dynamically using
omc_dialog_control
tool.
Icons require OS 10.3.
Images can be displayed in HIImageView control. Again, the control
property like {'OMC!', 'val!',
"/Users/you/Pictures/mypicture.png"}
defines
the
absolute
or relative path (relative means inside bundle).
JPEGs and PNGs can be displayed in Mac OS 10.2. In Mac OS 10.3 any
image supported by QuickTime can be displayed.
INIT_SUBCOMMAND_ID
Default value: 'ini!'
Nib dialog may use an initialization subcommand to set control values
before the dialog shows up.
<key>NIB_DIALOG</key>
<dict>
<key>NIB_NAME</key>
<string>dialog</string>
<key>WINDOW_NAME</key>
<string>Dialog</string>
<key>INIT_SUBCOMMAND_ID</key>
<string>ini!</string>
</dict>
If you have more than one dialog in your main command and subcommands
and you want to use dialog initialization you have to provide unique
ids for each initialization. If there is only one dialog, the default
'ini!' is assumed and does not need to be specified
explicitly.
New in 1.8:
Nib dialog termination handlers:
Called after dialog is closed but before returning to command
which invoked it. 2 types of termination handlers: one for OK and the
other for Cancel or window close. Default IDs are 'end!'
for
OK
and
'cnc!' for Cancel. Termination command IDs
can be overridden with the
following:
<key>NIB_DIALOG</key>
<dict>
<key>END_OK_SUBCOMMAND_ID</key>
<string>end!</string>
<key>END_CANCEL_SUBCOMMAND_ID</key>
<string>cnc!</string>
</dict>
DataBrowser control support for nib
dialogs:
It is the big new feature of 1.8 release. DataBrowser control
can be added to nib dialog as any other control and it needs to have
'OMC!' signature. Only table view is
supported (no nested multi-level
hierarchical view). In other words you can only have a table of columns
and rows. Table configuration and content of the table is defined
dynamically by omc_dialog_control tool with
the help of new options: omc_table_set_columns,
omc_table_set_column_widths, omc_table_add_rows. Currently only
tab-separated values are supported as an input row values because I
wanted to focus on new control functionality and not spend all my time
writing parsers for different data formats. Luckily you can convert
from any data format to tab-separated format using command-line tools
like awk (see examples). The value you obtain from table control is
defined as cell text from selected row and the column you specify. The
new special word object is __NIB_TABLE_NNN_COLUMN_MMM_VALUE__,
where NNN is the control id and MMM is the column number. Columns are
numbered from 1. If you put 0 as a column number you will receive
tab-separated data from all columns in the selected row. In fact you
can also use __NIB_DIALOG_CONTROL_N_VALUE__
the same as __NIB_TABLE_N_COLUMN_0_VALUE__:
it will return the same result. If your table has only one column you
don't have to worry about column number and you can use __NIB_DIALOG_CONTROL_N_VALUE__ as you would do for
any other control.
During the nib table implementation I ran across the multiple row
selection problem: how to return value of such selection in meaningful
way to command. One option was to disallow the multiple selections in
DataBrowser control but this would severely limit the usefulness of
this control. So I decided to solve this problem similarly to multiple
file selection handling: processing objects together or separately. The
default mode is to process selections together and return one tab
separated string. Let's explain it in an example. Assume we have a data
browser control with ID 5 and 1 column (let's call it "A"). We add 3
rows with values: "A1", "A2", "A3".
Now suppose we have a "Print" button which invokes the command with id
'Echo' which in turn prints the selected cell with
echo "__NIB_TABLE_5_COLUMN_1_VALUE__";
When all rows are selected the result will be "A1
A2 A3" string (tab separated). Analogously to what we
have in OMC for processing multiple files together, we can specify
custom prefix, separator and suffix for multiple selection using
control properties in InterfaceBuilder. Property signature is 'OMC!'
and tags are:
'pre!' - prefix string
'suf!' - suffix string
'sep!' - separator string
This way you can specify the returned selection text the way you need
for your command. For example, if we write an AppleScript line:
set tableSelection to { __NIB_TABLE_5_COLUMN_1_VALUE__
}
and
'pre!' = "
'suf!' = "
'sep!' = ,
the returned selection becomes an array:
set tableSelection to { "A1","A2","A3" }
The prefix and suffix property tags can also be used with other
controls but they are not as useful as in case of multiple selection in
table - because you can always put the prefix and suffix in the script
text itself.
The other option is to process selections separately. It can be done by
adding a special tag to DataBrowser control property in Interface
Builder. The tag is 'ite!' (for "iterate")
or
'rev!' (for reverse
iterator) and its value specifies the command ids of the OMC
subcommands which you designed to be invoked separately for each
selected row. The command ids are supposed to be 4 characters and
should be separated with one character. The separator character is not
important and is ignored. It can be a space, comma or other character -
it does not matter, the important is count pattern: 4-1-4-1-4-... This
way the designer may specify more than one command which should be
invoked separately for each selected row.
Assume we use the same "Print" button which invokes the 'Echo' command
but we set the iteration property in InterfaceBuilder for our
DataBrowser control like this:
'OMC!' 'ite!'
"U
String"
'Echo'
or for reverse iteration:
'OMC!' 'rev!'
"U
String"
'Echo'
The result of pressing our "Echo" button will be different now (still
considering the case of 3 selected rows). The command 'Echo' will be
invoked 3 times and it will print "A1" in 1st window, "A2" in 2nd
window and "A3" in 3rd window. For reverse iterator: "A3" in 1st
window, "A2" in 2nd, "A1" in 3rd one.
The limitation of this feature is that the main command, the one
invoking the nib dialog cannot be used as an iterated subcommand. It
has to be a separate subcommand invoked from the dialog.
You can also execute subcommand on selection change and on double
click. This is useful when you allow only one row selected at a time.
You can add the following properties in Interface Builder:
'OMC!' 'sel!'
"U
String"
'SelC'
'OMC!' 'dbl!'
"U
String"
'DblC'
In this case 'SelC' subcommand will be triggered on selection change,
'DblC' subcommand will be called when user double clicks the row.
Example usage is demonstrated in "Nib Dialog Demo".
Note: Do not use regular command ID on Data Browser (the one you can
set in Interface Builder for any control) because it triggers the
command only on mouse clicks but not when you navigate through the
table with arrow keys. The above 'sel!'
property works properly in both
cases.
Non-blocking nib dialog:
<key>NIB_DIALOG</key>
<dict>
<key>IS_BLOCKING</key>
<false/>
</dict>
The default behavior is blocking (modal) dialog and this is how it was
implemented in previous OMC versions. In this mode the dialog blocks
the main thread of host application, running its own modal loop, until
it is dismissed (closed, canceled, OK-eyed) and then the main command
which invoked the dialog is executed (most likely using some control
values from the dialog).
In the new, non-blocking mode, the dialog does not run the modal loop
and returns the control to host application immediately. The side
effect is that the command which invoked the dialog executes
immediately — in this case you will probably want to leave the main
command empty and perform the task you want in subcommand invoked when
closing the dialog. OMC nib dialog defines 2 default termination
handlers: 'end!'
when dialog is OK-eyed and 'cnc!' when dialog is
canceled. In most cases you will want to create a subcommand with
'end!' ID and
perform your closing task here. Those IDs can be
overridden with END_OK_SUBCOMMAND_ID
and END_CANCEL_SUBCOMMAND_ID
tags.
New in 2.0:
Cocoa
dialogs
When building Cocoa-based custom nib dialogs you should use a new key
in NIB_DIALOG dictionary: IS_COCOA which is boolean value with false as
default (false=Carbon). Also, you don't specify WINDOW_NAME key because
only one window per Cocoa nib is allowed in OMC (limitation of Cocoa
API which does not allow loading a window by its name specified in
nib). Example plist xml fragment for Cocoa dialog:
<key>NIB_DIALOG</key>
<dict>
<key>IS_COCOA</key>
<true/>
<key>NIB_NAME</key>
<string>Example</string>
</dict>
There are several differences between Carbon nib dialogs and Cocoa nib
dialogs in OMC.
OMC defines custom Cocoa controls which you should use when building UI
using Cocoa nibs. All OMC controls start with, you guessed it, OMC
prefix, replacing NS prefix. So we have OMCButton, OMCTextField, and so
on. They are very thin wrappers around standard controls allowing us to
set and store additional properties. OMC controls are available in
InterfaceBuilder only in Leopard through special plugin:
OMCInterfaceBuilderPlugin.ibplugin. The plug-in is located in
Abracode.framework's resources. In order to use the plug-in you need to
go to Interface Builder —> Preferences... —> Plug-ins and add the
plugin by pointing to /Library/Frameworks/Abracode.framework. When you
do this, the "Library" palette will gain a new group titled "OMC
Controls". The IB plug-in is available for Mac OS 10.5 only but the
dialogs built with are deployable in Mac OS 10.4 as well.
There are three main reasons why you need to use custom controls
instead of standard controls:
1. Connecting control action to subcommand happens by defining "Command
ID" for control. In standard Cocoa development you connect controls to
some actions in code. But using OMC you don't write any Obj-C code —
you just write action handlers using scripts: subcommands in OMC
jargon. When you write a subcommand with ID:
"do.something.useful" the connection with the button in nib dialog is
as easy as setting the control Command ID to "do.something.useful".
2. You need to identify controls to get or set the value through
control ids or tags (in Cocoa terminology). Those ids/tags are just
unique numbers assigned to each interesting control. For all NSControls
you can set the tag in InterfaceBuilder but some views do not have that
and this is where OMC custom views come to the rescue. Prime example is
OMCTextView. You get the control value exactly the same way as you used
to do it in Carbon dialogs: "$OMC_NIB_DIALOG_CONTROL_3_VALUE"
in
popen
shell
script or inline: __NIB_DIALOG_CONTROL_3_VALUE__
Setting control value is also the same, using omc_dialog_control, e.g:
"$OMC_OMC_SUPPORT_PATH/omc_dialog_control"
"$OMC_NIB_DLG_GUID" 3
"Hello OMC text view"
Refer to OMC Carbon dialogs instructions for more information about
building dialogs and getting and setting control values.
3. Additional control properties. OMC uses some additional properties
to make building commands even easier. The most important is probably
the super useful value control mappings which greatly simplify scripts.
You will notice that some controls do not have their OMC equivalents.
There are 2 reasons:
1. The work on custom Cocoa controls is not finished. Expect more
controls to join before release.
2. Some standard controls do not need to be customized because they
have the tag and don't need additional properties. For example NSBox
which just visually groups controls or vertical/horizontal dividers.
For some controls you may want to use standard version if you don't
require any additional properties. Prime example would be "Label"
(non-editable NSTextField) just to add some static text in the dialog
but not interact with it otherwise.
In Cocoa dialogs, command IDs are no
longer restricted to four characters. Some default ids have been
redefined for clarity.
Special dialog command IDs which close the dialog with OK or Cancel
message. You may specify those values for controls in Command ID field
in OMC control attributes in Interface Builder (using custom OMC
controls through OMCInterfaceBuilderPlugin.ibplugin).
omc.dialog.ok
=
'ok '
in
Carbon
dialogs
omc.dialog.cancel
=
'cncl'
in
Carbon dialogs
Dialog initialization default command ID. Subcommand with this ID, if
found, will be called automatically on dialog startup.
omc.dialog.initialize
=
'ini!'
in
Carbon dialogs
Dialog termination default command IDs. Subcommands with those IDs, if
found, will be called automatically when the dialog is closed with OK
or Cancel action respectively:
omc.dialog.terminate.ok
=
'end!'
in
Carbon
dialogs
omc.dialog.terminate.cancel
=
'cnc!'
in Carbon dialogs
|
Subcommands |
Subcommands look just like regular commands but they have a unique four
character identifier: COMMAND_ID. Main command should not have
this tag or use 'top!' value. Subcommands
must have the same name as a
main command. Subcommands are not displayed in the contextual menu
because they are treated as a part of one command group. OMCEdit
displays subcommands in italic font.
<key>COMMAND_ID</key>
<string>top!</string>
- reserved for main/top command
<string>ini!</string>
- reserved for nib dialog initialization subcommand
Subcommands can be triggered by controls in nib dialog or with omc_next_command.
Subcommands are new in OMC 1.7b1
|
Next Command |
omc_next_command is a CLI tool located in
"Contents/MacOS/" of the bundle (plugin or applet). It allows
scheduling next command so your script can decide at runtime if another
subcommand should follow. omc_next_command
takes 2 parameters: __CURRENT_COMMAND_GUID__
and <<next command id>>. The second parameter passed to omc_next_command is a four char code identifying
the next subcommand.
__CURRENT_COMMAND_GUID__ is a special object.
OMC replaces it with unique id for each command (subcommands are unique
too). It is different from regular command id (four char characters). __CURRENT_COMMAND_GUID__ is a globally unique ID -
guaranteed. It is used to identify which command is currently running
in order to avoid conflicts if more than one is running concurrently.
Globally unique ID can also be used for different purposes - for
example for saving a temporary file without worrying that a file with
the same name exists.
Example usage:
<string>cd </string>
<string>__MY_BUNDLE_PATH__</string>
<string>/Contents/MacOS/ ;</string>
<string>./omc_next_command
</string>
<string>__CURRENT_COMMAND_GUID__</string>
<string> "NeXT"</string>
If subcommand with given ID is not found, the command event is sent to
host application. For example, you may quit the host application by
sending 'quit' event.
CAUTION: omc_next_command must be executed
in synchronous execution mode - before the main OMC engine finishes. If
you send it Terminal, the main OMC code usually finishes before the omc_next_command is invoked. The same with any
execution with result window or OMCDeputy - it may be too late to tell
the main engine to execute next command because it already finished.
New in 1.8:
Statically assigned next command id:
<key>NEXT_COMMAND_ID</key>
<string>NeXT</string>
If you use both statically assigned next command id and dynamic one,
assigned at runtime with omc_next_command tool, the dynamic id is used.
This way you can override static assignment if needed.
This option is at the bottom of the main edit window in OMCEdit.
|
Other Settings |
<key>WARNING</key>
<string></string>
If your command is potentially destructive, you may protect
yourself ant others by adding a warning. A dialog with the string
provided for WARNING key and "Execute" & "Cancel" buttons
will be displayed before running the command.
If string is empty or keyword not present, no warning is displayed.
<key>WARNING_EXECUTE</key>
<string></string>
<key>WARNING_CANCEL</key>
<string></string>
Warning dialog has two buttons: "Execute" and "Cancel". You can
change their names with these keywords.
<key>SUBMENU_NAME</key>
<string></string>
If SUBMENU_NAME is defined and contains non-empty string, a
command is put into submenu of this name. Only one level of submenus is
allowed. If the name is a magic string of ".." (two dots without
quotes), the command "goes out" of "On My Command" submenu one level
up, to the root menu. Think of it as if you executed "cd .." and went
up one level in folder hierarchy.
<key>PASTE_AFTER_EXECUTION</key>
<true/> or <false/>
(default)
Tells OMC to paste clipboard content in current context after command
execution. Makes sense in text context with pbcopy
or AppleScript's set the clipboard to...
Example:
<dict>
<key>COMMAND</key>
<array>
<string>cd
~;
ls
-la
| pbcopy</string>
</array>
<key>EXECUTION_MODE</key>
<string>exe_silent_system</string>
<key>NAME</key>
<string>Paste
Home Folder listing</string>
<key>PASTE_AFTER_EXECUTION</key>
<true/>
<key>VERSION</key>
<integer>1</integer>
</dict>
|
<key>EXTERNAL_BUNDLE_PATH</key>
<string>~/Library/Application
Support/OnMyCommand/ExternalBundle.omc</string>
Define external bundle for putting nibs and custom window PNG images.
It is useful for contextual menu items using nib dialogs - you do not
have to put the nib inside OnMyCommandCM.plugin bundle.
New in 1.8:
If EXTERNAL_BUNDLE_PATH is
not defined, the default value is
/Users/you/Library/Application
Support/OnMyCommand/CurrentCommandName.omc
If you use ".omc" extension for external bundle, the DropletBuilder
will recognize it as an OMC bundle. Finder should assign OMC bundle
icon. Double click on such bundle will launch DropletBuilder which
will install this external bundle.
<key>VERSION</key>
<integer>1</integer>
VERSION is an integer value defining a version of given
command. Its value is ignored by the plug-in itself, but is used by
OMCEdit when downloading commands from Abracode's website.
