Distributing Custom Icons with Your Microsoft Office 2000 Applications

Microsoft Office 2000 Technical Articles

Lynn Shanklin and Brady Deal
Microsoft Corporation

February 8, 2000

Summary: This white paper shows you how to modify the code in your Setup application to distribute a custom icon and shortcut with your Microsoft Office 2000 application. (9 printed pages)

Introduction

If you used Microsoft® Office 97, Developer Edition, or earlier versions of the Microsoft Access Developer Tools, you could use the Access Setup Wizard to create custom run-time applications based on Microsoft Access. Because the earlier developer tools were primarily created to help you distribute Access run-time applications, the Setup Wizard was highly specific to building Access run-time Setups.

The Package and Deployment Wizard in Office 2000 Developer replaces the Microsoft Access Setup Wizard, and is designed for use with all Office products. The Package and Deployment Wizard helps you to create .cab files for your application, to group them into a package that contains all information needed for installation, and to deliver those packages to users.

In most cases, the Package and Deployment Wizard is the best way to package and distribute your application. However, the Package and Deployment Wizard does not have all the functionality that the Access Setup Wizard had. For example, the Package and Deployment Wizard does not have an option that allows you to automatically include an icon with your application.

If you want your application's Setup program to use features that are not provided by the Package and Deployment Wizard, you can modify the Setup Toolkit project. Like any other Visual Basic project, the forms, code, and functionality of this project can be modified or enhanced. This article shows you how to modify the code in your Setup application to distribute a custom icon and shortcut with your application.

Modifying the Setup Project

Note To modify the project created by the Package and Deployment Wizard, you must have Microsoft Visual Basic® 6.0 installed on your development computer. The Setup1 source code is written in, and must be compiled with, Visual Basic 6.0.

There are two Setup programs involved in the installation process—Setup.exe and Setup1.exe. The Setup.exe program performs pre-installation processing on the user's computer, including the installation of the Setup1.exe program and any other files needed for the main installation program to run. Setup1.exe acts as the main Setup program for your application. This executable file is included with your application by the Package and Deployment Wizard.

You can customize the installation program supplied by the Package and Deployment Wizard by modifying the Setup1.vbp project, which is also known as the Setup Toolkit. You use the Setup Toolkit by loading the Setup1.vbp file into Visual Basic and making modifications to the project. Only Setup1.exe is customizable through the Setup Toolkit.

Note The Microsoft Office 2000 Developer Package and Deployment Wizard does not use the files in the Setup Toolkit project, but you should always make a backup of the project before making any changes.

You can modify the Setup Toolkit project to contain any new prompts, screens, functions, code, or other information that you want to include. You write code in the Setup program just as you would in any other Visual Basic program. When you are finished, compile the project to create Setup1.exe. The steps in this article walk you through the process, and provide the code that you need to distribute a custom icon and shortcut with your application.

Steps to Modify the Setup Project

Insert your Microsoft Office 2000 Developer CD into your CD-ROM or DVD-ROM drive, and then copy the contents of the ODETools\v9\Samples\Unsupprt\Setup1 folder to a new folder on your hard disk. Name the folder "Setup1."
Insert your Microsoft Visual Basic 6.0 CD into the CD-ROM or DVD-ROM drive and then copy the contents of the Disk1\Common\Tools\VB\Unsupprt\Shelllnk folder to a new folder on your hard disk. Name the folder "Shelllnk."
Copy the Shelllnk class module, shelllnk.cls, from the Shelllnk folder on your hard disk to the Setup1 folder.
Open the Setup1 folder on your hard disk. On the Edit menu, click Select All. Right-click any file, select Properties, and click to clear the Read-Only and Archive check boxes.
Open the Setup1 project (Setup1.vbp) in Visual Basic. On the Project menu, point to Add Module, and then click Open.
On the View menu, click Properties Window. Rename the module to ShellLinkMod.

Save the project and save the module as ShellLinkMod.bas. Copy the following code into the ShellLinkMod module. This code registers your shortcut on the user's system, and ensures that your custom icon and caption are displayed. It also creates a shortcut on the user's Start menu. Note that you must give the icon the same name as your database with an .ico extension, and you must install it in the same path that you use for the installation of the database.

Option Explicit

'---------------------------------------------------------------
'- Public API Declares...
'---------------------------------------------------------------
#If UNICODE Then
         Public Declare Function SHGetPathFromIDList Lib "Shell32" Alias "SHGetPathFromIDListW" _
      (ByVal pidl As Long, ByVal szPath As Long) As Long
#Else
         Public Declare Function SHGetPathFromIDList Lib "Shell32" Alias "SHGetPathFromIDListA" _
      (ByVal pidl As Long, ByVal szPath As String) As Long
#End If

'---------------------------------------------------------------
'- Public constants...
'---------------------------------------------------------------
Public Const MAX_PATH = 255
Public Const MAX_NAME = 40

'-----------------------------------------------------------
' Function: StripTags
'
' Pulls out the extra tags from the Startup Group.
' Ex:  $(Programs) = Programs
'
' IN: [StrStrip] - Startup Group string
'
' OUT: String after the tags have been stripped out.
'
'-----------------------------------------------------------
'
Function StripTags(StrStrip As String) As String
      StripTags = Trim(Mid(StrStrip, 3, Len(StrStrip) - 3))
End Function
'-----------------------------------------------------------
' Function: CreateShortCut
'
' Adds an application's full pathname and per-app path to the
' system registry (this is currently only meaningful to
' Windows 95).
'
' IN:      [FileName] - Text caption for the link
'         [FilePath] - Full path to the target of the link
'            Ex: "c:\Program Files\My Application\MyApp.exe"
'         [DBPath] - Command-line arguments for the link
'            Ex: -f -c "c:\Program Files\My Application\MyApp.dat" -q
'
' OUT: Result of the operation; if it fails it outputs False.
'
'-----------------------------------------------------------
'
Function CreateShortCut(FileName As String, FilePath As String, ShortcutLocation As String, _
    StartMenuSubFolder As String, DBPath As String) As Boolean
    
CreateShortCut = True                           'Sets the function equal to true.
    
'---------------------------------------------------------------
Dim IconLoc As String                           'Holds the path to the icon file.
Dim TempStr As String                          'Holds a temporary string.
Dim sfPath As String                              'Holds the location of the Start Menu.
Dim WrkDir As String                             'Holds the location of the Working Directory.
Dim direc As Long                                  'Holds the return value of the GetSystemFolderPath function.
Dim sLnk As cShellLink
'---------------------------------------------------------------
Set sLnk = New cShellLink

On Error GoTo CreateShortCut_Err

'Checks for a command line switch.  Example:  "C:\My Documents" /runtime 
' If it exists then include it in the shortcut.
If InStr(CStr(DBPath), "/") = 0 Then
      TempStr = CStr(DBPath)
      'Strips out unneeded quotes in the TempStr string.
      TempStr = strUnQuoteString(TempStr)
Else
      TempStr = Left(CStr(DBPath), InStrRev(CStr(DBPath), "/") - 1)
      'Strips out unneeded quotes in the TempStr string.
      TempStr = strUnQuoteString(TempStr)
End If
'Gives the location of the icon file by determining the database location and concatenating
'.ICO on the end of the file name.  Example:  C:\Northwind.mdb = C:\Northwind.ICO
IconLoc = Left(TempStr, InStrRev(TempStr, ".") - 1) & ".ICO"
'Strips out unneeded quotes in the IconLoc string.
IconLoc = strUnQuoteString(IconLoc)
'Checks for a file name or whether the icon file exists in the given path.  If either are false
'then the function returns a false.
If Trim(FileName) = "" Or Dir(IconLoc) = "" Then
      CreateShortCut = False
Else
      'Gets the physical location of the Start Menu, based on the             operating system.
      direc = sLnk.GetSystemFolderPath(frmSetup1.hwnd, CSIDL_STARTMENU, sfPath)
      'Strips the tags out of the Startup Group.
      ShortcutLocation = StripTags(ShortcutLocation)
      'Combines each of the strings to give the path of the shortcut          file in the
      'Start Menu directory.
      ShortcutLocation = Trim(sfPath & "\" & ShortcutLocation & "\" & StartMenuSubFolder _
         & "\" & FileName & ".lnk")
      'If the shortcut already exists in that given path then delete          it.
      If Dir(ShortcutLocation) <> "" Then
         Kill ShortcutLocation
      End If
      'Get the location of the Working Directory.
      WrkDir = Left(DBPath, InStrRev(DBPath, "\"))
      'Calls the function that creates the shortcut in the Start Menu.  If it fails then the
      'function returns false.
      If sLnk.CreateShellLink(ShortcutLocation, FilePath, WrkDir,             DBPath, IconLoc, 0, 1) = False Then
         CreateShortCut = False
      End If
End If
    
CreateShortCut_CleanUP:
      Set sLnk = Nothing
Exit Function

CreateShortCut_Err:
      CreateShortCut = False
      Resume CreateShortCut_CleanUP
End Function

On the Project menu, click Add Class Module, and reference the existing shelllnk.cls module that you copied into the Setup1 folder. Note that you receive the error: "'cShellLnk' can not be public in this type of project. The item has been changed to Private." Click OK.
On the Project menu, click References, and select the VB 5 - IShellLinkA Interface (ANSI) type library. If this reference isn't in your list, click browse, change the Files of Type option to Type Libraries, find your ShellLnk folder, and select ShellLnk.tlb.

Double-click the basSetup1 module in the Project Window. Find the CreateShellLink function. One way to do this is to press CTRL+F and type CreateShellLink. Replace the existing CreateShellLink function with the following code:

Public Sub CreateShellLink(ByVal strLinkPath As String, ByVal strGroupName As String, ByVal strLinkArguments _
      As String, ByVal strLinkName As String, ByVal fPrivate As                Boolean, sParent As String, Optional ByVal fLog _
          As Boolean = True)
      Dim fSuccess As Boolean
      Dim intMsgRet As Integer
      Dim bdresult As Integer
    
If fLog Then
      NewAction gstrKEY_SHELLLINK, gstrQUOTE & strUnQuoteString(strGroupName) & gstrQUOTE _
         & ", " & gstrQUOTE & strUnQuoteString(strLinkName) & gstrQUOTE
      End If

      strLinkName = strUnQuoteString(strLinkName)
      strLinkPath = strUnQuoteString(strLinkPath)
Retry:
      bdresult = CreateShortCut(strLinkName, strLinkPath, sParent,             strGroupName, strLinkArguments)
      If bdresult = True Then
         fSuccess = True
      Else
         fSuccess = OSfCreateShellLink(strGroupName, strLinkName, strLinkPath, strLinkArguments, _
         fPrivate, sParent)  'the path should never be enclosed in double quotes
      End If
      If fSuccess Then
         If fLog Then
            CommitAction
         End If
      Else
         intMsgRet = MsgError(ResolveResString(resCANTCREATEPROGRAMICON, gstrPIPE1, _
            strLinkName), vbAbortRetryIgnore Or vbExclamation,                      gstrTitle)
         If gfNoUserInput Then
            intMsgRet = vbAbort
         End If
         Select Case intMsgRet
            Case vbAbort
               ExitSetup frmSetup1, gintRET_ABORT
               GoTo Retry
            Case vbRetry
               GoTo Retry
            Case vbIgnore
               If fLog Then
                  AbortAction
               End If
         End Select
      End If
End Sub

Save the module and the project.

Building the New Setup Project

You are now ready to build the new Setup program. On the File menu, click Make Setup1.exe.
Note The Setup1 project folder already includes a Setup1.exe, so don't create the new Setup1.exe with the same path as your Setup1 project folder.
Name the icon that you want to include with the same name as your database with an .ico extension. (Example: Northwind.mdb and Northwind.ico.)
Create the package by using the Package and Deployment Wizard. Be sure to include the icon file in your package during the Package and Deployment Wizard process. The icon file should be installed to the same location as your database, which can be determined by the $AppPath value.
Open the Support folder inside your package, and copy the new Setup1.exe into this folder. Click Yes when you are prompted to overwrite the existing file.
Find the batch file called <Your Database Name>.bat. Double-click on that batch file to re-create your .cab files, and include the new Setup1.exe.
Distribute your application.

For More Information

For the latest information about the Office 2000, Developer Edition, see the Microsoft Office Developer Web site at http://www.microsoft.com/office/developer.

To access Knowledge Base information, consult the Product Support section of the Microsoft Office Developer Web site.

For information about deploying custom solutions, consult the "Deploying Your Application" chapter in the Office 2000/Visual Basic Programmer's Guide.

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

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.

Microsoft is a registered trademark of Microsoft Corporation.

Other product or company names mentioned herein may be the trademarks of their respective owners.

Microsoft Corporation · One Microsoft Way · Redmond, WA 98052-6399 · USA