INSTALLSHIELD internal library function 17 housing function
The shell function creates a new program folder, deletes the existing program folder, adds the item to the existing program folder. At the end of the installation, add an application to the appropriate program folder to allow users to immediately access your software. The following functions also support different icons options.
AddFoldericon
Add a icon to a folder.
CreateProgramfolder
Create a program folder.
CreateshellObjects
Create a folder and shortcut (or group and icon) in the Housing Object folder of the resource pane.
Deletefoldericon
Remove an icon or item from a program folder.
DeleteProgramfolder
Remove a program folder from the target system.
Getfoldernamelist
Retrieve all subfolders and shortcuts in the specified folder.
ProgDefgrouptype
The group identified as public or dedicated in the Windows NT environment.
QueryProgItem
Returns information about a specified program item or subfolder.
Queryshellmgr
Returns the name of the current housing manager.
ReplaceFoldericon
Replace an icon in the specified folder.
SELECTFOLDER
Present a dialog box allows the end user to select a folder from a program folder list.
ShowProgramfolder
Display the specified program folder.
17.1 AddFoldericon
Syntax: AddFoldericon (SzProgramFolder, Szitemname, Szcommandline, SzworkingDir,
SizConpath, NICON, SZSHORTCUTKEY, NFLAG;
Description: The AddFoldericon function is inserted or replaced with an icon in the program folder specified by SZProgramFolder. If the program folder does not exist, AddFoldericon creates it. SZProgramFolder can specify a subfolder in a multi-level class menu. If the subfolder does not exist, AddFoldericon will create the subfolder and create its parent folder if necessary.
When adding icons to the group under Windows NT, first call ProgDefGroupType to determine whether the group is public or dedicated. When default, the folder icon is intended to be public.
parameter:
SZProgramfolder
Specifies the name of the folder added to the icon. If the folder does not exist, INSTALLSHIELD creates it.
To add an icon to a specific folder, specify a fully qualified path, such as:
"C: // windows // startmenu // programs // accessories // Games".
To add a shortcut icon to the Windows 95 and a later version of the start program menu, pass an empty string ("") to this parameter.
Note that you can also pass one of the following installshield system variables in this parameter location:
Folder_Desktop: Add the icon to the desktop folder.
Folder_Startup: Add the icon to the startup menu folder.
Folder_StartMenu: Add the icon to the start menu folder.
Folder_Programs: Add the icon to the start menu / program folder.
You can also specify a path relative to a folder identified by the InstallShield system variable, for example,
Folder_Programs ^ "Accessories // Games"
Specifies the icon name to be added to the folder. This name will be displayed under the icon. Under Windows 95 and later, call AddFoldericon to create a link file in the link directory specified by SZCommandline when you add an icon to a program folder. Note that the developer shell is not allowed to have the following characters in the project name: /, /,:,?, <,>, Or. SZCommandline
Specify one of the following:
The fully qualified name of the executable of the interconnected file, including any command line parameters. To add a shortcut icon to the Windows 95 and a higher version of the start program menu, enter a full-qualified path to a link directory, where your app stores its icon link file.
A fully qualified path if SzItemName is a subfolder. (Only Windows 95 and later, Windows NT 4.0).
If the command line contains a long file name, it must be surrounded by quotation marks (enclose). For more information, please see the following annotation section.
Szworkingdir
Specifies the directory where the application file is located. (If SzItemName is a subfolder, it is not applicable). In order to make the directory containing the program files as the working directory, the parameter passes an empty string (""). Do not call LongPathToQuote to enclose the path (including) in quotation marks. For more information, please see the following annotation section.
SizConPath
The fully qualified file name of the icon to which you want to display. (If SzItemName is a subfolder, it is not applicable). Do not call LongPathToQuote to enclose the path (including) in quotation marks. For more information, please see the following annotation section.
NICON
Specifies the icon serial number of the executable execures specified by SZICONPATH in Windows. (If SzItemName is a subfolder, it is not applicable). The number of icon sequence numbers starts from 0, so for the first icon of the executable file, specify 0; to display the second, specify 1, so continued. If you don't use a Windows icon, specify 0 to this parameter.
SzshortcutKey
Specify shortcuts (in string form) allows the end user to quickly start the application. For example, if you want to open the application by pressing "Ctrl", "ALT" and then "1" button, deliver "Ctrl Alt 1" to this parameter. If SzItemName is a subfolder, it is not applicable).
Nflag
Specify the icon performance form. One or more of the following predefined constants are passed in this parameter location. In order to deliver two or more predefined constants for this parameter, those constants are combined with a bit or operator (|):
Replace: Indicates that the current icon or item in the folder is replaced.
Run_maximized: It must be maximized when the program is loaded.
Run_minimized: Indicates that the program must be minimized when the program is loaded.
NULL: Indicates that there is no option.
return value:
0: Indicates that the function successfully adds or replaces the icon in the specified folder and associates the executable file and icon.
<0: Indicates that the function does not add or replace the icon in the specified folder and associate executables and icons.
annotation:
· If the path to your application executable file contains a long path name, you must enclose the fully qualified file name from single quotation or double quotes. (If the file name has been assigned to a variable, the variable is passed to longPathToQuote to insert quotation marks.) Note that the command line parameters must be surrounded by quotation marks. Therefore, it is recommended to create an SZCommandline string from two separate strings.
• Do not call LongpathToQuote to get expressions as parameters szworkingdir and sziconpath. InstallShield automatically encloses these paths in quotation marks. 17.2 CreateProgramfolder
Syntax: CreateProgramFolder (Szfoldername);
Description: The CreateProgramFolder function creates a new folder in the target system. If the folder already exists, it is highlighted. In Windows 95 and higher, create to the folder in the Start Menu. When you create a program group under Windows NT, first call ProgDefGroupType to determine that the group is public or dedicated. The default setting is public.
parameter:
Szfoldername
Specifies the folder name to be added to the target system.
return value:
0: Indicates that the function successfully adds a folder to the target system or the folder already exists.
<0: Indicates that the function does not add the specified program folder.
17.3 CreateshellObjects
Syntax: CreateshellObjects (Szreserved);
Description: The CreateshellObjects function creates a housing object (folder or shortcut or group and icon) already specified on the current media. The current media name is saved in the system variable Media. The shell object is defined in the housing object folder of the resource pane. If you use an event-based script, any housing object that is linked to one or more file groups (file group properties using the case object) is automatically created when the file group is loaded.
Note: CREATESHELLOBJECTS does not create an empty folder (or group) on the target system. If a folder or group in the resource pane is empty, it will not be created by the installer. Similarly, if the shortcut specified in a folder in the resource pane is not created at runtime (because the file groups you associate are not loaded), then the folder is not created. To create an empty folder (or group), call CreateProgramFolder in your script.
parameter:
Szreserved
Pass a null string ("") to this parameter. Other values are not allowed.
return value:
0: Indicates that the function is successful.
-1: Unknown error.
-2: Call the function before calling the ComponentTransferData function. Note that in a installation of an event-based script, ComponentTransferData is automatically called.
-3: Text replacement failed.
-4: Create a shortcut failed.
-5: Create a folder failed.
-6: Create an Internet shortcut failed.
annotation:
· During the installation initialization, the value of the system variable MedIa is set to 'data'. If you modify the value of this variable to point to a script to create a component set, you must modify the value back to 'data' before calling createShellObjects.
This Function Should Be Called Only After ComponentTransferData Has Been Called.
This function can only be called after the COMPONENTTRANSFERDATA has been called.
17.4 Deletefoldericon
Syntax: DeleteFoldericon (SzProgramFolder, SzItemName);
Note: The DeleteFoldericon function deletes a program icon from a folder.
parameter:
SZProgramfolder
Specifies the folder name that contains the icon to delete.
SzItemName Specifies the icon name to be deleted.
return value:
0: Indicates that the function successfully deletes the specified icon.
<0: Indicates that the function does not delete the specified icon.
17.5 DeleteProgramfolder
Syntax: DeleteProgramFolder (Szfoldername);
Note: The DeleteProgramFolder function deletes a program folder and its content, including all folders located under the specified folder. It cannot delete the "program" folder.
parameter:
Szfoldername
Specifies the folder name to be deleted.
return value:
0: Indicates that the function successfully deletes the specified folder.
<0: Indicates that the function does not delete the specified folder.
17.6 getFoldernamelist
Grammar: getFoldernamelist (Szfoldername, ListItemsid, ListSubfolders);
Note: The getFoldernameList function is used to list all program item shortcuts and subfolders for a specified folder. This function can also be used to list all program item shortcuts and subfolders of a root folder.
parameter:
Szfoldername
Specifies the folder name being queried. You can specify a fully qualified path to SZFoldername, such as "C: // Windows // Start Menu // Programs // Accessories // Games". If SZFoldername is empty, getFoldernameList looks out the default program directory (see below). If you don't specify an absolute path to Szfoldername, getFoldernameList looks up a subfolder in the default program directory, follow the operating system:
Windows 95 and later: Start menu / program folder is located under Windows folders. Note that even if the user profile is activated, the position will not change.
Windows NT 4.0 (if you are selected by progdefgrouptype): ../ pROFILES / ALL Users / Start Menu / Programs folder under Windows folder.
Windows NT 4.0 (if you are selected by progdefgrouptype) :. ./profiles/
You can also use an InstallShield system variable:
Folder_Desktop: Find a desktop folder.
Folder_Startup: Find the launch menu folder.
Folder_StartMenu: Find the start menu folder.
Folder_Programs: Find the start menu / program folder.
Or you can use a relative path, such as:
Folder_Programs ^ "Accessories // Games"
ListItemsid
Returns a list of program item shortcut names in Szfoldername. Note that in Windows NT, if SZFoldername contains a dedicated and utility item, the list returned in this parameter will contain public or private program shortcuts, but not all included. A list identified by the ListItemsid must have been initialized by calling ListCreat.
ListSubfoldersid
A list of subfolders in Szfoldername returns a subfolder name. Note that in Windows NT, if SZFoldername contains a dedicated and utility item, the list returned in this parameter will contain public or private program shortcuts, but not all included. A list identified by the ListSubfoldersID must have been initialized by calling ListCreat. return value:
0: getFoldernameList successfully retrieves all program items and subfolders.
<0: getFoldernameList is not available to all program items and subfolder names.
annotation:
• When the function is used in a installation running under Windows NT 4.0, apply the following constraints:
If you list a specific program folder (that is, you have specified the path to the folder), the folder must match, public or dedicated to the current folder type. If the folder and the current folder type do not match, it will not be positioned and the function fails. To change the default folder type, call ProgDefGroupType.
• If you list a folder that supports dedicated and public projects and folders, such as Folder_Programs, only those program item shortcuts, and folders will be returned by the function. To change the default folder type, call ProgDefGroupType.
17.7 ProgDefgrouptype
Grammar: progDefgrouptype (ntype);
Note: The ProgDefrowType function will specify a program group to be dedicated or public under Windows NT. Call the function before calling AddFoldericon or CreateProgramFolder. The default program group type is public.
This function is only used in a Windows NT environment. It is ignored in other environments.
parameter:
NTYPE
Specify a program group type. One of the following predefined constants in this parameter location:
Personal: Specifies a private program group.
Common: Specifies a public program group.
return value:
0: Function usually returns 0.
annotation:
• If a PROGDEFROUPTYPE is called before the SDSELECTFolder running in Windows NT, the SDSELECTFolder will display the program folder (public or dedicated) based on the parameter folder (public or dedicated) that is passed to the PROGDEFROUPTYPE.
17.8 QueryProgItem
Syntax: QueryProgItem (Szfoldername, Szitemname, svcmdline, svwrkdir, sviconpath,
NviconIndex, SvshortcutKey, NVMinimizeFlag;
Description: QueryProgItem function Tests if a specified program item or subfolder name exists. If InstallShield finds the item or subfolder, QueryProgItem returns its properties. Properties include the application line, working directory, icon path, shortcut, and minimization flag.
In order to use QueryProgItem, enter information in parameter szfoldername and szitemname. InstallShield will populate the remaining parameters with the properties of the program.
When the group or folder is queried under Windows NT, first call ProgDefGroupType to determine that the group is public or dedicated. The default setting is public.
parameter:
Szfoldername
Specifies the folder name that contains the item or subfolder. You can specify a fully qualified path to SZFoldername, such as:
"C: // windows // start menu // programs // accessories // Games" If SZFoldername is empty, QueryProgItem looks for the default program directory (see below). If you don't specify an absolute path to SZFoldername, QueryProgItem looks up a subfolder in the default program directory, follow the operating system:
Windows 95 and later: The start menu / program under environment variables WINDIR.
Windows NT 4.0 (if you are selected by progdefgrouptype): Environment Variable WINDIR under the ../profiles/all users / start menu / programs directory.
Windows NT 4.0 (if you are selected by progdefgrouptype): Environment variables under WINDIR. ./Profiles/
You can also use an InstallShield system variable:
Folder_Desktop: Query items in the desktop folder.
Folder_Startup: Query items in the launch menu folder.
Folder_StartMenu: Query items in the Start menu folder.
Folder_Programs: Query items in the Start Menu / Program Folder. Or you can use a relative path, for example:
Folder_Programs ^ "Accessories // Games"
Szitemname
Specify the program item or subfolder name you want to find.
svcmdline
Returns the full path of the command line or subfolder of the project's executable.
Svwrkdir
Returns the full path to the program item work directory. (If SzItemName is a subfolder, it is not applicable.)
SviconPath
Returns the fully qualified file name of the .ico file or .exe file. (If SzItemName is a subfolder, it is not applicable.)
NviconIndex
Returns an index as a program item icon. (If SzItemName is a subfolder, it is not applicable.)
SvshortcutKey
Returns the shortcut key of the project. (If SzItemName is a subfolder, it is not applicable.)
NVMinimizeflag
(If SzItemName is a subfolder, it does not apply.) Returns one of the following constants, indicating whether an application window is minimized at the time of the first display:
NULL: Indicates that the application window is not minimized.
Run_minimized: Indicates that the application window is minimized.
return value:
IS_ITEM (0): Indicates that szitemname is a program or shortcut for Szfoldername.
IS_FOLDER (1): Indicates that SzItemName is a subfolder for Szfoldername.
<0: Indicates that the function cannot find a program item or subfolder name.
annotation:
· Different languages start menu positions. Anyway, InstallShield automatically selects the correct path.
17.9 queryshellmgr
Grammar: queryshellmgr (svshellmgrname);
Note: The queryshellmgr function gets the program case name used by Microsoft Windows. For example, if the program housing is Explorer, queryshellmgr returns "Explorer.exe" in the parameter svshellmgrname. If the housing of the target system is not Explorer, you may need to use the Launchapp function to load the housing. Creating a program folder and a program icon The installShield function is used to create a program folder and program item with a Case. Most optional housings such as Norton Desktop simulation Explorer housing. Therefore, they can create program folders and projects.
In the case where the Explorer housing is not simulated, INSTALLSHIELD cannot use the program folder and program item function to create or modify program folders and program items.
parameter:
Svshellmgrname
Returns the non-limiting name of the currently running housing management program (that is, there is no driver identity or path).
return value:
0: Indicates that the function successfully retrieves the program housing name.
<0: Indicates that the function is not able to retrieve the program housing name.
17.10 ReplaceFoldericon
Syntax: ReplaceFoldericon (SzProgramFolder, Szitemname, SznewItem, Szcmdline,
Szworkingdir, szlessonpath, nicon, szshortcutkey, nflag);
Note: The ReplaceFoldericon function replaces an icon in the specified folder. You must specify an existing folder, which can be created with the CreateProgramFolder function or it already exists on the user system.
parameter:
SZProgramfolder
Specifies a folder name that contains icons to be replaced.
Szitemname
Specifies the icon name to be replaced.
SznewItem
Specifies the icon name to display after replacement.
Szcmdline
Specify one of the following:
The fully qualified name of the executable of the interconnected file, including any command line parameters.
If SzItemName is a subfolder, it is a fully qualified path.
Szworkingdir
Specifies the directory where the application file is located. (If SzItemName is a subfolder, it is not applicable). In order to be a directory containing the program file as a working directory, pass an empty string ("") to this parameter.
SizConPath
Specifies an icon file name or a valid Windows executable of the new icon.
NICON
If you specify a Windows executable icon, specify the icon serial number. Otherwise, pass 0 to this parameter.
SzshortcutKey
Specify a string containing the shortcut sequence, the user can press them to launch the application. For example, if you want to open the application by pressing "Ctrl", "ALT" and then "1" button, deliver "Ctrl Alt 1" to this parameter. If SzItemName is a subfolder, it is not applicable).
Nflag
Specify one or more options. The following predefined constants are delivered at this parameter location. In order to deliver multiple options to this parameter, those constants are combined with bitwise or operators (|):
NULL: Indicates that there is no option.
Replace: Indicates that the existing icon is required to be replaced by the new icon.
Run_maximized: indicates that the program is maximized when the program is loaded.
Run_minimized: Indicates that the program is minimized when the program is loaded.
return value:
0: Indicates that the success is set.
<0: Indicates that the function is not available to the icon.
17.11 SELECTFOLDER
Syntax: SelectFolder (SZTITLE, SZDEFFOLDER, SVRESULTFOLDER); Description: The SelectFolder function displays a dialog that allows the end user to enter a program folder name in an editing area or select a program folder from a list. This function automatically displays all program folders in the system. A default folder name delivered to SVDeffolder is displayed in the editing area. The selected folder is returned in SvResultFolder. If the specified folder does not exist, it will not be created.
parameter:
Sztitle
Specifies the dialog title. To display the default title ("Select Program Folder"), pass the parameter to the parameter ("").
SZDeffolder
Specifies the folder name to be displayed as the default folder.
SvResultFolder
Returns the final user selected or specified folder name. If the folder does not exist, you must call CreateProgramFolder to create it; SELECTFolder does not create the folder.
return value:
Next (1): Indicates that the end user selects the next button.
Back (12): Indicates that the end user selects the Back button.
<0: Indicates that the function is successful.
17.12 ShowProgramFolder
Syntax: ShowProgramfolder (Szfolder, NCommand);
Description: The showprogramfolder function displays a program folder.
parameter:
Szfolder
Specifies the folder name to display.
Ncommand
Specify the folder status. One of the following predefined constants in this parameter location:
SW_SHOW: Displays a folder in a standard status.
SW_MAXIMIZE: Maximize folders.
SW_MINIMIZE: Minimize folders.
SW_RESTORE: Restores the folder to the original size.
return value:
This function has no return value.
