AddFolderIcon

InstallShield 2009 » InstallScript Language Reference

The AddFolderIcon function inserts or replaces an icon in the program folder specified by szProgramFolder. If that program folder does not exist, AddFolderIcon creates it. szProgramFolder can specify a subfolder in a multi-level cascading menu. If the subfolder does not exist, AddFolderIcon creates the subfolder and, if necessary, its parent folders.

When adding icons to groups under Windows NT or Windows 2000, call first to establish the group as either COMMON or PERSONAL. By default, the folder icon is added under COMMON.

Syntax

AddFolderIcon ( szProgramFolder, szItemName, szCommandLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, nFlag );

Parameters

AddFolderIcon Parameters 

Parameter	Description
szProgramFolder	Specifies the name of the folder to which to add the icon. If the folder does not exist, InstallShield creates it. To add the icon to a specific folder, specify the fully qualified path, for example, C:\\WINNT\\Profiles\\All Users\\Start Menu\\Programs. To add a shortcut icon to the Start Programs menu, pass a null string (“”) in this parameter. You can also pass one of the following InstallScript system variables in this parameter: FOLDER_DESKTOP—Adds the shortcut to the desktop. FOLDER_STARTUP—Adds the shortcut to the Startup menu. FOLDER_STARTMENU—Adds the shortcut to the Start menu. FOLDER_PROGRAMS—Adds the shortcut to the Start\Programs menu. You can also specify a path relative to a folder identified by an InstallShield system variable, for example, FOLDER_PROGRAMS ^ “ACCESSORIES\\GAMES”
szItemName	Specifies the name of the icon to add to the folder. The name will appear beneath the icon. Calling AddFolderIcon to add an icon to a program folder also creates a link file in the links directory specified by szCommandLine. Note that Explorer shell does not allow the following characters in item names: /, \, :, ?, <, >, or |.
szCommandLine	Specifies one of the following: The fully qualified name of the executable associated with the icon, including any command-line parameters. To add a shortcut icon to the Windows 95 or later Start Programs menu, enter the fully qualified path of the links directory, which is where your application stores its icon link files. The fully qualified path if szItemName is a subfolder. If the command line includes a long file name, it must be enclosed in quotes. Command-line parameters, however, should not be surrounded with quotation marks. For that reason, it is advisable to build the szCommandLine string from two separate strings.
szWorkingDir	Specifies the directory where the application's program files are located. (This is not applicable if szItemName is a subfolder.) To make the directory that contains the program file the working directory, pass a null string (“”) in this parameter. Do not call LongPathToQuote to enclose this path in quotation marks. InstallShield automatically encloses these paths in quotation marks.
szIconPath	Specifies the fully qualified icon file path. This is not applicable if szItemName is a subfolder. Do not call LongPathToQuote to enclose this file name in quotation marks. InstallShield automatically encloses these paths in quotation marks.
nIcon	Specifies the icon ordinal in the Windows executable specified by szIconPath. (Not applicable if szItemName is a subfolder.) Icon ordinal numbers begin at 0, so to display the first icon in the executable file, specify 0; to display the second, specify 1, and so on. If you are not using a Windows icon, specify 0 in this parameter.
szShortCutKey	Specifies the shortcut key (in the form of a string) that allows the end user to start the application quickly. For example, if you wanted to be able to open the application by depressing the “Ctrl,” the “Alt,” and then the “1” key, pass “Ctrl + Alt + 1” in this parameter. (Not applicable if szItemName is a subfolder.)
nFlag	Specifies icon appearance. Pass one or more of the following predefined constants in this parameter. To pass two or more predefined constants in this parameter, combine those constants with the bitwise OR operator ( | ). REPLACE—Indicates that the current icon or item in the folder is to be replaced. RUN_MAXIMIZED—Indicates that the program should be maximized when launched. RUN_MINIMIZED—Indicates that the program should be minimized when launched. NULL—Indicates no options.

Return Values

AddFolderIcon Return Values 

Return Value	Description
0	Indicates that the function successfully added or replaced the shortcut in the specified folder and associated the executable with it.
< 0	Indicates that the function was unable to add or replace the shortcut and associate the executable with it. You can obtain the error message text associated with a large negative return value—for example, -2147024891 (0x80070005)—by calling .

 

 

 

 

 

 

AddFolderIcon Example 1

InstallShield 2009 » InstallScript Language Reference

Note

To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

/*-----------------------------------------------------------*\

*

* InstallShield Example Script

*

* Demonstrates the AddFolderIcon function.

*

* This example places a shortcut to an executable file on the

* Start menu and the Start Programs menu.

*

* Note: Before running this script, set the preprocessor

*       constants so that they reference the fully qualified

*       names of the Windows Notepad executable and a valid

*       text file on the target system.

*

\*-----------------------------------------------------------*/

#define PROGRAM "C:\\Windows\\Notepad.exe"

#define PARAM   "C:\\Windows\\Readme.txt"

// Include Ifx.h for built-in InstallScript function prototypes.

#include "Ifx.h"

export prototype ExFn_AddFolderIcon(HWND);

function ExFn_AddFolderIcon(hMSI)

    STRING szProgramFolder, szItemName, szCommandLine, szWorkingDir;

    STRING szShortCutKey, szProgram, szParam, szIconPath;

    NUMBER nIcon;

begin

    // Set up parameters for call to AddFolderIcon.

    szProgramFolder = FOLDER_STARTMENU;

    szItemName      = "Notepad Example 1";

    szProgram       = PROGRAM;

    szParam         = PARAM;

    LongPathToQuote (szProgram, TRUE);

    LongPathToShortPath (szParam);

    szCommandLine = szProgram + " " + szParam;

    szWorkingDir  = "";

    szIconPath    = "";

    nIcon         = 0;

    szShortCutKey = "";

    // Add a shortcut to the Start menu.

    if (AddFolderIcon (szProgramFolder, szItemName, szCommandLine, szWorkingDir,

                      szIconPath, nIcon, szShortCutKey, REPLACE) < 0) then

        MessageBox ("AddFolderIcon failed.", SEVERE);

    else

        SprintfBox (INFORMATION, "AddFolderIcon", "%s created successfully.",

                   szItemName);

    endif;

    szProgramFolder = "";

    szItemName    = "Notepad Example 2";

    // Add a shortcut to the Programs menu.

    if (AddFolderIcon (szProgramFolder, szItemName, szCommandLine, szWorkingDir,

                      szIconPath, nIcon, szShortCutKey, REPLACE) < 0) then

        MessageBox ("AddFolderIcon failed.", SEVERE);

    else

        SprintfBox (INFORMATION, "AddFolderIcon", "%s created successfully.",

                   szItemName);

    endif;

end;

 

 

 

AddFolderIcon Example 2

InstallShield 2009 » InstallScript Language Reference

Note

To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

/*-----------------------------------------------------------*\

*

* InstallShield Example Script

*

* Demonstrates the AddFolderIcon function.

*

* This example creates a cascading submenu on the StartUp menu

* and adds an icon to it.

*

* Note: Before running this script, set the preprocessor

*       constants so that they reference the fully qualified

*       names of the Windows Notepad executable and a valid

*       text file on the target system.

*

\*-----------------------------------------------------------*/

#define PROGRAM "C:\\Windows\\Notepad.exe"

#define PARAM   "C:\\Windows\\Readme.txt"

// Include Ifx.h for built-in InstallScript function prototypes.

#include "Ifx.h"

export prototype ExFn_AddFolderIcon(HWND);

function ExFn_AddFolderIcon(hMSI)

    STRING  szProgramFolder, szItemName, szCommandLine, szWorkingDir;

    STRING  szIconPath, szShortCutKey, szProgram, szParam;

    NUMBER  nIcon, nFlag, nResult;

begin

    // Set the fully qualified name of the StartUp submenu.

    szProgramFolder = FOLDER_STARTUP ^ "SubMenu Example";

    // Construct the icon's command line property.

    szProgram  = PROGRAM;

    szParam    = PARAM;

    LongPathToQuote (szProgram, TRUE);

    LongPathToShortPath (szParam);

    szCommandLine = szProgram + " " + szParam;

    // Set up the icon's other properties to pass to AddFolderIcon.

    szItemName = "Notepad Example1";

    szWorkingDir  = "";

    szIconPath    = "";

    nIcon         = 0;

    szShortCutKey = "";

    nFlag         = REPLACE|RUN_MAXIMIZED;

    // Add the icon to the submenu; create the submenu if necessary.

    nResult = AddFolderIcon (szProgramFolder, szItemName, szCommandLine,

                            szWorkingDir, szIconPath, nIcon,

                            szShortCutKey, nFlag);

    // Report the results.

    if (nResult < 0) then

        MessageBox ("AddFolderIcon failed.", SEVERE);

    else

        SprintfBox (INFORMATION, "AddFolderIcon", "%s created successfully.",

                   szItemName);

    endif;

end;

 

 

 

 

AddFolderIcon Example 3

InstallShield 2009 » InstallScript Language Reference

Note

To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

/*-----------------------------------------------------------*\

*

* InstallShield Example Script

*

* Demonstrates the AddFolderIcon function.

*

* This example places a subfolder on the desktop and an icon

* pointing to an executable in the new folder.  The folder is

* a shortcut that points to an actual directory.  From this

* folder the user can execute a shortcut that runs the program.

*

* Note: Before running this script, set the preprocessor

*       constants so that they reference the fully qualified

*       names of the Windows Notepad executable and a valid

*       text file on the target system.

*

\*-----------------------------------------------------------*/

#define FOLDER     "C:\\Windows\\"

#define PROGRAM    "C:\\Windows\\Notepad.exe"

#define PARAM      "C:\\Windows\\Readme.txt"

// Include Ifx.h for built-in InstallScript function prototypes.

#include "Ifx.h"

export prototype ExFn_AddFolderIcon(HWND);

function ExFn_AddFolderIcon(hMSI)

   STRING  szProgramFolder, szItemName, szCommandLine, szWorkingDir;

    STRING  szIconPath, szShortCutKey;

    STRING  szProgram, szParam, szFolderDir;

    NUMBER  nIcon, nFlag, nResult;

begin

   // szProgramFolder is the Desktop on the local system.

   szProgramFolder = FOLDER_DESKTOP;

   szItemName      = "Example folder";

   // Create the folder which the folder icon will point to.

   szFolderDir = FOLDER ^ szItemName;

   CreateDir(szFolderDir);

   // The command line for the folder icon must be the folder path, and

   // it must be enclosed in quotation marks if the path is longer than

   // eight characters.

   szCommandLine = szFolderDir;

   LongPathToQuote(szCommandLine, TRUE);

   szWorkingDir  = "";

   szIconPath    = "";

   nIcon         = 0;

   szShortCutKey = "";

   nFlag         = REPLACE|RUN_MINIMIZED;

   // Create the folder icon, and show the folder it points to.

   nResult = AddFolderIcon (szProgramFolder, szItemName, szCommandLine,

                            szWorkingDir, szIconPath, nIcon, szShortCutKey,

                            nFlag);

   if (nResult < 0) then

      MessageBox("AddFolderIcon failed.", SEVERE);

   else

      SprintfBox (INFORMATION, "AddFolderIcon", "%s created successfully.",

                  szItemName);

   endif;

   // Display the folder just created.

   ShowProgramFolder (szFolderDir, SW_SHOW);

   // Add the Example icon to the newly created folder.

   szProgramFolder = szFolderDir;

   szItemName      = "Notepad Example";

   // Make sure the white space is not seen as a delimiter.

   szProgram       = PROGRAM;

   LongPathToQuote (szProgram, TRUE);

   szParam = PARAM;

   LongPathToShortPath (szParam);

   szCommandLine = szProgram + " " + szParam;

   szWorkingDir  = "";

   szIconPath    = "";

   nResult = AddFolderIcon (szProgramFolder, szItemName, szCommandLine,

                            szWorkingDir, szIconPath, nIcon, szShortCutKey,

                           nFlag);

   if (nResult < 0) then

      MessageBox ("AddFolderIcon failed.", SEVERE);

   else

      SprintfBox (INFORMATION, "AddFolderIcon", "%s created successfully.",

                 szItemName);

   endif;

end;