Shell Dynamic Data Exchange Interface

Shell Dynamic Data Exchange Interface


This overview describes the dynamic data exchange (DDE) interface of Program Manager (Progman.exe). Program Manager is a shell—that is, an application that enables users to group, start, and otherwise control other applications for the Microsoft® Windows® operating system.

arrowy.gifAbout Program Manager Initialization

arrowy.gifCommand-String Interface

arrowy.gifRequesting Group Information

About Program Manager Initialization

Program Manager starts automatically when the user starts Windows and runs as long as Windows is in use. When it starts, Program Manager displays one or more windows within its main window. Each window contains icons that correspond to logically related Windows-based applications. For example, the Accessories window contains icons for Windows Write, Paintbrush, Notepad, and other accessory applications.

Program Manager stores initialization and configuration information in the registry. This information is stored under the Settings, Groups, and Restrictions keys in the following section of the registry:

HKEY_CURRENT_USER\Software\Microsoft\WindowsNT\
        CurrentVersion\Program Manager

Additional information is stored in the Program Groups key in the following section of the registry:

HKEY_LOCAL_MACHINE\SOFTWARE

Settings Key

The Settings key contains information that Program Manager uses to configure its environment. The following entries appear in the Settings key.
Entry Description
MinOnRun Specifies whether to minimize Program Manager when an application is started.
AutoArrange Specifies whether Program Manager should automatically arrange icons within groups.
SaveSettings Specifies whether to save the position of the Program Manager window when Program Manager terminates.
Display.drv Specifies the file name of the display driver in use when Program Manager last terminated. When Program Manager starts, it compares this value to the file name of the display driver currently in use. If the names are different, Program Manager re-extracts the application icons.
Window Specifies the location and dimensions of the Program Manager window.
Order Specifies the order that the groups listed in the Groups key appear in the Program Manager window.
Startup Specifies the name of the startup group. Program Manager automatically starts the applications in this group whenever it starts.

Groups Key

The windows that appear in the Program Manager window correspond to group files. From the user's perspective, a group file is a collection of icons that represent logically related applications, but from the programmer's perspective, a group file is actually a collection of data. This data includes the color information for the icons (AND and XOR masks), an offset to the resource header of each icon, the ideal resolution for displaying each icon, the name of the executable (.exe) file that contains the application, and so on.

There are two types of groups: common and personal. A common group is shared among multiple users through network connections; a personal group is not shared. Program Manager stores information about personal groups under the Groups key. It stores information about common groups under the HKEY_LOCAL_MACHINE\SOFTWARE key.

The Groups key of the registry identifies the names of the group files that Program Manager displays as unique windows or icons. The groups must be numbered, but they don't need to be listed in any particular order. Program Manager never changes the number of an existing group.

Restrictions Key

The Restrictions key controls whether certain features of Program Manager are enabled or disabled. The following entries can appear in the Restrictions key.
Entry Description
NoRun Specifies whether to disable the Run command on the File menu. If this entry is set to 1, the Run command is disabled. If this entry is set to 0, the Run command is enabled. The default is 0 if no value is specified.
NoClose Specifies whether to prevent the user from closing Program Manager through the File menu, the System menu, the ALT+F4 key combination, or the Task List. If this entry is set to 1, closing is prevented. If this entry is set to 0, closing is allowed. If no value is specified, the default is 0.
EditLevel Controls the extent to which the user can modify read/write groups. (Shared read-only groups cannot be modified.) This entry can be set to one of the following values.
Value Action
0 Allows any modifications to the group. This is the default value.
1 Prevents the user from creating, deleting, or renaming groups.
2 Prevents the user from creating, deleting, or renaming groups and from creating or deleting items in a group.
3 Prevents the user from creating, deleting, or renaming groups; from creating or deleting items in a group; and from changing command lines for items in a group.
4 Prevents the user from changing any property of an item in a group; from creating, deleting, or renaming groups; from creating or deleting items in a group; and from changing command lines for items in a group.
NoFileMenu Specifies whether to disable the File menu and all of its commands. If this entry is set to 1, the File menu is disabled. If this entry is set to 0, the menu is enabled. If no value is specified, the default setting is 0.
NoSaveSettings Specifies whether to disable the Save Settings on Exit command on the Options menu. If this entry is set to 1, the Save Settings on Exit command is disabled. If this entry is set to 0, the command is enabled. If no value is specified, the default setting is 0.

Setting the value of NoRun to 1 and the value of EditLevel to 3 prevents a user from using Program Manager to run any applications not already in a program group.

Command-String Interface

Program Manager has a DDE command-string interface that allows other applications to create, display, delete, and reload groups; add items to groups; replace items in groups; delete items from groups; and close Program Manager. The following commands perform these actions:
AddItem ExitProgman
CreateGroup Reload
DeleteGroup ReplaceItem
DeleteItem ShowGroup

For example, the setup program for an application can use these commands to instruct Program Manager to install the application's icon in a group.

Multiple commands can be concatenated; each command must be contained in square brackets, and parameters must be contained in parentheses and separated by commas. Quotation marks must delimit arguments that contain spaces, brackets, or parentheses. For example, the following set of commands adds Winapp.exe to the Windows Applications group.

[CreateGroup("Windows Applications")] 
[ShowGroup("My Group",1)] 
[AddItem(winapp.exe,Win App,winapp.exe,2)] 

To use these commands, an application must first initiate a DDE conversation with Program Manager. The application and topic names for the conversation are both Progman. The application then sends the WM_DDE_EXECUTE message, specifying the appropriate command and its parameters.

Note The user can configure Windows to use a shell other than Program Manager as the default. Therefore, do not design an application that assumes Program Manager will be available for a DDE conversation.

Shell DDE Reference

The following sections describe Program Manager DDE command strings in detail. In the syntax blocks in these sections, brackets enclose optional parameters.

AddItem
AddItem(CmdLine[,
Name[,IconPath[,IconIndex[,xPos,yPos[,DefDir[,
HotKey[,fMinimize[fSeparateMemSpace] ] ] ] ] ] ])

Instructs Program Manager to add an icon to an existing group. There is a limit of 50 items per group.

CmdLine
Full command line required to run the application. This parameter is a string. At a minimum, this string is the name of the executable file for the application. It can also include the full path of the application and any parameters required by the application.
Name
Title that is displayed below the icon in the group window.
IconPath
File name for the icon to be displayed in the group window. This parameter is a string. This file can be either a Windows-based executable file or an icon file. If no value is specified for this parameter, Program Manager uses the first icon in the file specified by the CmdLine parameter if that file is an executable file. If CmdLine specifies an associated file, Program Manager uses the first icon of the associated executable file. The association is taken from the registry. If CmdLine specifies neither an executable file nor an associated executable file, Program Manager uses a default icon.
IconIndex
Index of the icon in the file identified by the IconPath parameter. The IconIndex parameter is an integer. Progman.exe contains five built-in icons that can be used for programs not written for Windows.
xPos
Horizontal position of the icon in the group window. This parameter is an integer. Both the xPos and yPos parameters must be used to specify the position of the icon. If the position is not specified, Program Manager places the icon in the next available space.
yPos
Vertical position of the icon in the group window. This parameter is an integer. Both the xPos and yPos parameters must be used to specify the position of the icon. If the position is not specified, Program Manager places the icon in the next available space.
DefDir
Name of the default (or working) directory. This parameter is a string.
HotKey
Hot (or shortcut) key that is specified by the user.
fMinimize
Specifies whether an application window is to be minimized when first displayed.
fSeparateMemSpace
Specifies whether a 16-bit application runs in a separate memory space.
CreateGroup
CreateGroup(GroupName[,CommonGroupFlag])

Instructs Program Manager to create a new group or activate the window of an existing group.

GroupName
Group to be created or activated. This parameter is a string. If a group already exists with the name specified by GroupName, CreateGroup activates the group window.
CommonGroupFlag
Specifies whether the new group is a common group or a personal group. If this parameter is 1, a common group is created; if it is 0, a personal group is created. To create a common group, the user that is currently logged on must have administrative privileges. If this parameter is 1 but the user does not have administrative privileges, the command fails. If no value is specified and if the user has administrative privileges, the default value of this parameter is 1 (common group). If no value is specified and the user does not have administrative privileges, the default value is 0 (personal group).

If the second parameter of this command specifies the path of the group file (as was required in Windows version 3.1), the parameter is ignored.

DeleteGroup
DeleteGroup(GroupName[,CommonGroupFlag])

Instructs Program Manager to delete an existing group.

GroupName
Group to be deleted.
CommonGroupFlag
Specifies whether the group is a common group or a personal group. If this parameter is 1, the group being deleted is a common group; if it is 0, the group is a personal group. If no value is specified, this parameter defaults to 1 (common group). To delete a common group, the user that is currently logged on must have administrative privileges. If this parameter is 1 but the user does not have administrative privileges, the command fails.

If the second parameter of this command specifies the path of the group file (as was required in Windows version 3.1), the parameter is ignored.

DeleteItem
DeleteItem(ItemName)

Instructs Program Manager to delete an item from the currently active group.

ItemName
Item to delete from the currently active group.
ExitProgman
ExitProgman(bSaveGroups)

Instructs Program Manager to terminate if started by another application and, optionally, save its group information.

bSaveGroups
Boolean value that, if it is nonzero, causes Program Manager to save its group information before closing. If this parameter is zero, Program Manager does not save its group information.
Reload
Reload(GroupName[,CommonGroupFlag])

Instructs Program Manager to remove and reload an existing group. An application that modifies group files can use this command to cause Program Manager to update the groups when it has finished making modifications.

GroupName
Group to be removed and reloaded. If no value is specified for this parameter, Program Manager unloads all groups and reloads the groups specified in the Groups key of the registry. The Settings and Restrictions keys are not reread.
CommonGroupFlag
Specifies whether the group is a common group or a personal group. If this parameter is 1, the group being reloaded is a common group; if it is 0, the group is a personal group. If no value is specified, this parameter defaults to 1 (common group). To reload a common group, the user that is currently logged on must have administrative privileges. If this parameter is 1 but the user does not have administrative privileges, the command fails.
ReplaceItem
ReplaceItem(ItemName)

Instructs Program Manager to delete an item and record the position of the deleted item. Program Manager then adds a new item (specified by the next AddItem command) at this recorded position.

ItemName
Item to be deleted. Its position is recorded by Program Manager.
ShowGroup
ShowGroup(GroupName,ShowCommand[,CommonGroupFlag])

Instructs Program Manager to minimize, maximize, or restore the window of an existing group.

GroupName
Group window to be minimized, maximized, or restored.
ShowCommand
Action Program Manager is to perform on the group window. This parameter is an integer. It must have one of the following values:
1 Activate and display the group window. If the window is minimized or maximized, Windows restores it to its original size and position.
2 Activate the group window and display it as an icon.
3 Activate the group window and display it as a maximized window.
4 Display the group window in its most recent size and position. The window that is currently active remains active.
5 Activate the group window and display it in its current size and position.
6 Minimize the group window.
7 Display the group window as an icon. The currently active window remains active.
8 Display the group window in its current state. The currently active window remains active.
CommonGroupFlag
Specifies whether the group is a common group or a personal group. If this parameter is 1, the group being minimized, maximized, or restored is a common group; if it is 0, the group is a personal group. If no value is specified, this parameter defaults to 1 (common group). To minimize, maximize, or restore a common group, the user that is currently logged on must have administrative privileges. If this parameter is 1 but the user does not have administrative privileges, the command fails.

Requesting Group Information

Program Manager can provide information about its groups to an application. Applications can request this information from Program Manager by using the Progman topic.

An application can obtain a list of Program Manager groups by issuing a request for the Group item. Program Manager provides the list in CF_TEXT format. The list consists of group name strings separated by carriage returns.

An application can use a group name as an item name to request information about the group. Program Manager provides this information in CF_TEXT format. The fields of group information are separated by commas. The first line of the information contains the group name (in quotation marks), the path of the group file, and the number of items in the group. Each subsequent line contains information about an item in the group, including the command line (in quotation marks), the default directory, the icon path, the position in the group, the icon index, the shortcut key (in numeric form), and the minimize flag.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.