source: trunk/appswitch/appswitch/appswitch.1@ 331

.Dd Sun May 16 2004      \" DATE 
.Dt APPSWITCH 1 LOCAL    \" Program name and manual section number 
.Os appswitch 1.0.1
.Sh NAME
.Nm appswitch
.Nd switch, hide, show, quit, kill or list Mac OS X applications
.Sh SYNOPSIS
.Nm appswitch
.Op Fl sShHqkKFlLP       \" [-sShHqkKFlLP]
.Op Fl c Ar creator      \" [-c creator]
.Op Fl i Ar bundleID     \" [-i bundleID]
.Op Fl a Ar name         \" [-a name]
.Op Fl p Ar pid          \" [-p pid]
.Op Ar path              \" [path]
.Sh DESCRIPTION
.Nm
controls the ordering and visibility of Mac OS X application windows.
.Nm
can also list or kill running applications.
.Ss Matching options
Matching identifies one or more applications to manipulate.
.Bl -tag -width -indent
.It Fl c Ar creator
Match by creator (a four-character code, also known as a signature).
.It Fl i Ar bundle ID
Match by bundle identifier, usually consisting of the reversed dot
(.)-separated components of the application developer's Internet domain
name, followed by the application name.  For example, the Finder's
bundle identifier is
.Ar com.apple.Finder .
Bundle identifiers are not case-sensitive.
.Pp
If you're extremely concerned about the speed of matching, any other
match method is faster than a match by bundle identifier.
.It Fl p Ar pid
Match by process identifier, a positive integer.
.It Ar path
Match by bundle path.  For packaged applications, this is the package
directory whose name typically has the .app extension, for example
.Ar /Applications/TextEdit.app
for the default installation location of TextEdit.  For non-packaged
applications, this is the path to the executable itself.
.El
.Ss Application actions
These actions apply to the matched application. If multiple
applications match the supplied criteria, only the first matching
application is acted upon.  The list option
.Fl l
displays all matching applications.
.Bl -tag -width -indent
.It Fl s
Show the application, making the application's windows frontmost.  Do
not switch to the application.
.It Fl h
Hide the application's windows.
.It Fl q
Quit the application.
.It Fl k
Kill (force quit) the application.  Sends the
.Dv SIGINT
signal to the application, which the application may
ignore.  Equivalent to selecting 
.Dq Force Quit
from an application's menu in the Dock for the first time.
.It Fl K
Kill (force quit) the application.  Sends the
.Dv SIGKILL
signal to the application, which the application may not ignore.
Equivalent to selecting
.Dq Force Quit
from an application's menu in the Dock for the second time.
.It Fl l
List applications in a format similar to that of
.Xr ps 1 .
The columns of the listing are as follows:
.Bl -tag -width indent
.It PSN
The process serial number of the application.  Process serial numbers
are unique identifiers among both native Mac OS X and Classic
applications.
.It PID
The process identifier, a positive integer which uniquely identifies
native Mac OS X processes, usable with the
.Fl p
matching option.  Because all Classic applications run inside
TruBlueEnvironment, a single Mac OS X process, their process
identifiers appear as -1.
.It TYPE
The four-character code identifying the application's type,
usually 
.Ql APPL
for most applications or
.Ql FNDR
for the Finder.
Classic applications include additional types such as
.Ql appe
and
.Ql APPC
for applications which perform the functions of extensions
and control panels, respectively.
.It CREA
The four-character code identifying the application's creator, usable with the
.Fl c
matching option. Some Mac OS X applications have no creator, appearing
as 
.Ql ???? ;
for these applications you must use the bundle identifier,
name or path as match criteria.
.It NAME
The user-visible application name, usable with the
.Fl a
matching option. This field is truncated to 20 characters; the
remainder of longer application names is not displayed.
.It PATH
The path to the application bundle, usable with the
.Ar path
matching option. This field is truncated to the window width, or to 80
characters if the window width cannot be determined.
.El
.It Fl L
List applications in a format similar to that of
.Xr ps 1 .
The columns of the listing are as above, but the path field is not
truncated to the window width, and a bundle identifier is added in
parentheses after the path, usable with the
.Fl i
matching option.
.It Fl P
Print the application's process identifier (PID), a positive integer
and unique identifier for all applications except Classic
applications.
.El
.Ss Actions
These actions affect all applications currently running.
.Bl -tag -width -indent
.It Fl S
Show all applications, layering the windows of initially hidden
applications on top.
.It Fl H
Hide windows of all applications other than the matched application,
or the frontmost application if no application has been matched.
.It Fl F
Order the current application's windows to the front.
.El
.Sh SEE ALSO 
.\" List links in ascending order by section, alphabetically within a section.
.\" Please do not reference files that do not exist without filing a bug report
.Xr open 1 ,
.Xr launch 1 ,
.Xr ps 1 ,
.Xr kill 1 ,
.Xr GetFileInfo 1
.Sh BUGS              \" Document known, unremedied bugs
The
.Fl F
option may be unreliable if issued immediately after another show or
hide command; try inserting a
.Xr sleep 1
command before it.
.Pp
The
.Fl q
option is very slow on Mac OS X 10.2.8 and earlier; this is an
acknowledged bug in AECreateAppleEvent with no known workaround.
The bug is fixed in Mac OS X 10.3.
.Sh AUTHOR
.An "Nicholas Riley" Aq appswitch@sabi.net
.\" .Sh HISTORY           \" Document history if command behaves in a unique manner