Description:

RJShortcut is a Smartphone 2002 Homescreen Plug-In that allows you to create a static iconbar in any homescreen definition. Although tested only on a Samsung i600, it should run on any standard Smartphone 2002 device.

Installation Notes:

Unzip the package in an empty directory on your PC, make sure your Smartphone is connected to your computer and ActiveSync is running, then simply run rjsetup.exe. Alternatively, you can copy the CAB file to your phone and execute it yourself. Either way, the plug-in and icon DLLs are copied to the /IPSM/Program Files/RJ directory, the plug-in DLL is registered, and the sample homescreen is copied to /IPSM/Application Data/Home. Speaking of which, this package contains a sample Homescreen named RJShort which contains an example of the plug-in's usage. Although the installer copies this Homescreen to your phone, it doesn't activate it. To do so, simply select "RJShort" in Settings/Home Screen.

Because there is no way to force unload a home screen plug-in once it's been loaded, you may be prompted to restart your Smartphone if you have used an earlier version.

You can uninstall this package by running the Add/Remove Programs tool from ActiveSync on your PC.

Usage Notes:

Simple: Select the icon with the left and right arrow keys and press "OK". One nice feature is that if you keep pressing the directional keys when you're at the end of the list you'll cycle around the list again instead of stopping at the end.

If you're an icon freak and need more than will fit on one line, simply add another plugin section to your homescreen XML file.

As with any changes to homescreen XML files, you must force the homescreen to reload if you make changes. Usually, changing the style in Settings/Home Screen does the trick.

Sample Home Screen:

The sample homescreen's default style is based on the standard "Orange" style but the plug-in does obey the styles currently in effect for the phone so any style should work fine. Of course, you can embed the plug-in in any other homescreen definition as well.

Examples:
Default StyleVerizon Wireless Style

ICONs:

More time was spent messing with icons that anything else. IMHO Smartphone 2002 is severely crippled in comparison to it's desktop cousins with regard to searching and extracting icons from resources. The workhorse ExtractIconEx API doesn't let you enumerate icons and you can't copy files from the phone's ROM down to your desktop and examine them there. So, that leaves you with some serious detective work to figure out which icons are in which dll/exe files and what their indexes are. Some you can get by examining DefaultIcon registry entry for the filetype in question but many I was just never able to find. After 3 days I gave up.

So where does that leave us? Most third-party applications have standard icons embedded in them so the plug-in should be able to extract and use them without further assistance. For the system functions and any third-party apps that don't show good icons, Ive included a DLL with about a hundred common Windows icons in it. Probably not a good idea but it's making up for a Smartphone deficiency so I don't feel too bad about it. To use the icons, set the "iconfile" parameter to "rjicons.dll" and set "iconindex" to the index shown in the picture below (including the minus sign but not the .ico extension).

Feel free to substitute icons, create your own DLLs, etc. Unfortunately you can't just copy ICO files to the phone and use them because of the API limitations and the time it would take me to develop a workaround.

If you want to see what the 32x32 icons look like, [Click here]

Limitations, Workarounds, etc.:

If you also use the MRU plug-in, you'll notice that it doesn't get updated when programs are started from the shortcut bar. I have no idea how the MRU is updated.

There currently doesn't appear to be a way to open a folder with the public APIs. If you create a shortcut to one, the phone will complain. If I figure it out, I'll add the capability. You CAN create a shortcut to the File Explorer if you want and pass the folder path as an argument. Doesn't look as nice as "Programs" though.

If you're trying out a new configuration that for some reason hangs the plug-in on bootup, you can get out of it fairly easily. At this point, the OS is actually running and if you wait long enough, the homescreen will timeout. If you don't want to wait, open the Explore window from ActiveSync and delete or rename the homescreen file in /IPSM/Application Data/Home and power cycle the phone.

As I said in the opening paragraph, the plug-in was testing only on a Samsung i600. It doesn't use any non-standard facilities so it should run on all other Smartphone 2002 based phones.

Plug-In XML Sample:

Full Home Screen XML 
	<!-- RJShortcut -->

	<!-- For this plugin, the height attribute is optional.  If supplied, it 
	is used to fix the height of the plug-in.  If not, the height will be 
	automatically set to the size of the icons (16 for small, 32 for large) 
	plus the top and bottom padding settings.
	-->
	
    <plugin clsid="{F3750050-8E30-4c61-A864-4301F5D7C065}" height="26">

    	<!-- border widths and border colors are the only attributes
    	allowed for the background element.
    	-->

		<background b-border-width="0">

			<!-- The background element may contain a single format element
			that describes the background color of the selected icon.  If not
			provided, the default for the currently applied style will be used.
			-->

			<format state="selected" bgcolor="#ff0000"/> 

		</background>

		<!-- A single format element may be supplied. The only allowed
		attributes are the padding attributes.  They control the padding 
		around the bar itself, not the individual icons.
		-->

		<format padding-left="6" padding-top="5" padding-bottom="5"/>	

		<!-- The shortcutbar element can take 2 attributes.  Icon-spacing 
		sets the number of pixels between icons. The default is 2. Icon-size 
		can be either "small" (16x16, the default) or "large" (32x32).  The 
		shortcutbar will be filled from left to right with shortcuts until full, 
		taking into account the icon size, icon spacing and padding.  Any 
		remaining shortcuts will be ignored.
		-->

		<shortcutbar icon-spacing="2" icon-size="small">
			
			<!-- Each shortcut element creates an icon in the shortcut bar.
			Allowable attributes are "target", which is required, and "args",
			"iconfile", and "iconindex" which are optional.
			"target" is the name of the executable or shortcut.
			"args" are any arguments to be passed to the target.
			"iconfile" is the name of an exe or dll that contains the icon
			for this shortcut.  If not specified, the target will be searched
			for the appropriate icon.
			"iconindex" is the index of the icon_group in the iconfile.  It must
			be "0" or a negative number.  If not specified, "0" will be used
			which retrieves the first icon_group in the resource.
			-->
			<shortcut target="settings.exe"/>
			<shortcut target="tasks.exe"/>
			<shortcut target="/IPSM/Windows/Start Menu/Inbox.lnk" 
				iconfile="rjicons.dll" iconindex="-110"/>
			<shortcut target="/IPSM/Windows/Start Menu/Contacts.lnk" 
				iconfile="rjicons.dll" iconindex="-109"/>
			<shortcut target="calendar.exe"/>
		</shortcutbar>
    </plugin>
</code>