Read Me About LoginItemsAE

==========================

1.0

This sample shows how to manipulate the list of login items, that is, the items that are launched when you log in [1].  The sample operates by sending Apple events to the "System Events" process, which has an AppleScript dictionary for manipulating login items.  The sample allows you to:

o get a list of login items

o add a login item to the end of the list

o remove a login item

The sample is structured as a GUI test application with a core library of reusable code that you can copy into your application.

This sample requires Mac OS X 10.2 or higher, which is when the scriptable login items were introduced.

This sample is a standalone replacement for MoreLoginItems, part of MoreIsBetter.  On the other hand, it is in no way related to the LoginItemsAPI code that has been distributed by DTS on a one-to-one basis in the past.

[1] On Mac OS X 10.2.x and earlier systems, these are called "login items" and edited via the Login Items panel of System Preferences.  On Mac OS X 10.3 they changed to "startup items", edited in the Startup Items tab of the Accounts panel of System Preferences.  On Mac OS X 10.4, the name has changed back to "login items", but they're still edited in the Accounts panel.

Packing List

------------

The sample contains the following items:

o Read Me About LoginItemsAE.txt -- This file.

o LoginItemsAE.h -- Header for the reusable library.

o LoginItemsAE.c -- Implementation of the reusable library.

o LoginItemsAETest -- A folder containing a test program that demonstrates the library.  The following items are within that folder:

o LoginItemsAETest.xcodeproj -- An Xcode 2.1 project for the test program.

o build -- A folder of pre-built binaries.

o LoginItemsAETest.c -- Source for the test program

o LoginItemsAETest.nib -- The user interface for the test program.

o Info.plist -- A property list file for the test program.

o LoginItemsAETest.pch -- A prefix file for the test program.

Using the Sample

----------------

To use the sample, simply double click "LoginItemsAETest" within the "build" folder.  This displays a list of the current login items.  You can click the Add button to add a login item, the Remove button to remove one, and the Refresh button to refresh the list (see the Caveats section below).

Building the Sample

-------------------

The sample was built using Xcode 2.1 on Mac OS X 10.4.  You should be able to just open the project, select the "LoginItemsAETest" target, and choose Build from the Build menu.  This will build the LoginItemsAETest application in the "Build" directory.  This is a universal binary that requires Mac OS X 10.4 or later.

There is also a "LoginItemsAETest-compat" target that builds a PowerPC-only version that works all the way back to Mac OS X 10.2.x.

How it Works

------------

The core reusable library works by sending Apple events to the "System Events" process.  These Apple events exactly mirror the events that are sent when you execute AppleScripts like:

tell application "System Events"

    make new login item at end 

        with properties {path:"/Applications/TextEdit.app", hidden:false}

end tell

tell application "System Events"

    properties of every login item

end tell

tell application "System Events"

    delete login item 1

end tell

It is perfectly reasonable to not use the C code from this sample, but instead embed these AppleScripts in your program and run them using OSAExecuteEvent.  See DTS Q&A 1111 "Calling an AppleScript and providing parameters from an Application" for an example of how to do that.

  <http://developer.apple.com/qa/qa2001/qa1111.html>

Caveats

-------

In the GUI test application, the list of login items only updates if it was changed by the test application itself.  If other applications (for example, System Preferences) change the list of login items, the test application's UI does not update to reflect those changes.

There are ways to hack around this problem (for example, polling the list), but they have all have drawbacks (for example, relying on information that Apple considers to be private).

Under Mac OS X 10.2.x, the Login Items panel in System Preferences does not change as you modify the list using LoginItemsAE (or indeed using AppleScript).  This is a bug in Mac OS X 10.2.x that was fixed in Mac OS X 10.3.

Due to a limitation of AESendMessage on Mac OS X 10.2.x, you should only call more LoginItemsAE routines from the main thread.  This isn't a problem on Mac OS X 10.3 and later.  You can work around this restriction by modifying LoginItemsAE' call to AESendMessage using the technique documented in Technote 2053.

<http://developer.apple.com/technotes/tn2002/tn2053.html#TN001208>

Due to a bug <rdar://problem/4052117> in Mac OS X 10.4 and later (up to including 10.4.2, which is the latest release at the time this was written), LoginItemsAE can't handle hidden login items properly.  That is, the value of kLIAEHidden is always false and you can't add a hidden login item.  This bug does not affect earlier systems.

Credits and Version History

---------------------------

If you find any problems with this sample, mail <dts@apple.com> and I'll try to fix them up.

1.0 (Sep 2005) was the first shipping version of this sample.  It is based on MoreLoginItems 1.0.2.

Share and Enjoy.

Apple Developer Technical Support

Networking, Communications, Hardware

20 Sep 2005

$Log: Read\040Me\040About\040LoginItemsAE.txt,v $

Revision 1.4  2005/09/28 19:59:59  eskimo1

Added comments describing each of the targets.

Revision 1.3  2005/09/28 13:57:46  eskimo1

Change yet another grammo.

Revision 1.2  2005/09/28 10:23:34  eskimo1

Fixed some grammos.

Revision 1.1  2005/09/27 12:29:41  eskimo1

First checked in.